98 lines
3.3 KiB
TypeScript
98 lines
3.3 KiB
TypeScript
/**
|
|
* headless-types.ts — shared types for the machine orchestrator surface.
|
|
*
|
|
* Purpose: provide a single source of truth for the structured result type
|
|
* emitted by the `sf headless` machine surface and the output format discriminator,
|
|
* so headless.ts, consumers, and tests agree on shape without circular deps.
|
|
*
|
|
* Consumer: headless.ts (machine orchestrator), external CI scripts parsing batch JSON.
|
|
*/
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Notification Metadata
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Optional structured metadata that can be attached to a notify() call to
|
|
* allow classification without brittle string matching.
|
|
*
|
|
* When present, headless-events.ts checks these fields first and falls back
|
|
* to the legacy text heuristics only for untagged (metadata-absent) events.
|
|
*
|
|
* Consumer: headless-events.ts classifiers, notification-store.ts dedup.
|
|
*/
|
|
export interface NotificationMetadata {
|
|
/** Semantic kind of this notification. */
|
|
kind?: "notice" | "approval_request" | "progress" | "terminal";
|
|
/** Whether this notification halts the workflow and requires user action. */
|
|
blocking?: boolean;
|
|
/** Stable key for deduplication — collapses repeated notices of the same type. */
|
|
dedupe_key?: string;
|
|
/** Emission source label (extension name, "workflow", etc.). */
|
|
source?: string;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Output Format
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Discriminates the three machine-surface output formats.
|
|
*
|
|
* Purpose: let callers declare the encoding of session results
|
|
* (human-readable text, single JSON blob, or streaming JSONL) without coupling
|
|
* output format to surface, protocol, run control, or permission profile.
|
|
*
|
|
* Consumer: parseHeadlessArgs in headless.ts when handling --output-format.
|
|
*/
|
|
export type OutputFormat = "text" | "json" | "stream-json";
|
|
|
|
/**
|
|
* Set of supported output-format string values.
|
|
*
|
|
* Purpose: guard against typos in CLI arguments and provide a fast
|
|
* membership test without repeating the literal list.
|
|
*
|
|
* Consumer: parseHeadlessArgs validation and unit tests.
|
|
*/
|
|
export const VALID_OUTPUT_FORMATS: ReadonlySet<string> = new Set([
|
|
"text",
|
|
"json",
|
|
"stream-json",
|
|
]);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Structured JSON Result
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Shape of the single JSON object written to stdout when --output-format json
|
|
* is used in batch (non-streaming) mode.
|
|
*
|
|
* Purpose: give non-interactive callers (CI pipelines, test harnesses,
|
|
* parent processes) a machine-readable contract for session outcome,
|
|
* cost, and metadata without scraping stderr.
|
|
*
|
|
* Consumer: emitBatchJsonResult in headless.ts; live-regression tests.
|
|
*/
|
|
export interface HeadlessJsonResult {
|
|
schemaVersion: 1;
|
|
status: "success" | "error" | "blocked" | "cancelled" | "timeout";
|
|
exitCode: number;
|
|
sessionId?: string;
|
|
duration: number;
|
|
cost: {
|
|
total: number;
|
|
input_tokens: number;
|
|
output_tokens: number;
|
|
cache_read_tokens: number;
|
|
cache_write_tokens: number;
|
|
};
|
|
toolCalls: number;
|
|
events: number;
|
|
milestone?: string;
|
|
phase?: string;
|
|
nextAction?: string;
|
|
artifacts?: string[];
|
|
commits?: string[];
|
|
}
|