@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/headless.js

@@ -24,6 +24,7 @@ import { projectGoal } from './goal_contract.js';
  */
 import { randomUUID } from 'node:crypto';
 import { writeFile } from 'fs/promises';
+import { existsSync, truncateSync } from 'node:fs';
 import { configStore } from './config.js';
 import { formatTaskHandoffContext, projectTaskHandoff } from './session_handoff_contract.js';
 import { RouterConfigurationError } from './router_auth.js';
@@ -32,9 +33,11 @@ import { ContextOverflowError, isContextOverflowMessage } from './agent/agent.js
 import { dumpContextOverflow } from './agent/contextDump.js';
 import { registerToolCallbacks } from './app/tool_callbacks.js';
 import { createAgentWithConfig } from './app/agent_runner.js';
+import { awaitStartupGitSnapshot, prefetchStartupGitSnapshot } from './runtime_info.js';
 import { mergeToolCheckpointMessages } from './agent/runtime/tool_checkpoints.js';
 import { clearWorkerExecutor } from './worker/index.js';
 import { commands, refreshPluginCommands } from './agent/commands/index.js';
+import { isCommandRefusal, refusalEvent } from './agent/commands/command_refusal.js';
 import { goalManager, goalPinTask, detectGoalCompletion, detectGoalBlocked, goalBlockedReason, goalFinalNote, turnProducedText, turnToolOutcomes, shouldAccountFinalTurn, snapshotGoalForTurn } from './agent/commands/goal.js';
 import { createModeContext } from './agent/commands/mode_commands.js';
 import { allocatePlanArtifact, findPlanContent, readPlanArtifactSafely, } from './agent/commands/plan.js';
@@ -50,12 +53,17 @@ import { rename as renameFile } from 'fs/promises';
 import { buildModelsController, buildSkillsController, buildShellController, buildStubShellController, buildAutoSelectWidgets, routeUserInput, getPlanModeCommandDenial } from './app/command_context.js';
 import { isToolAllowed } from './app/modes.js';
 import { SessionManager } from './app/session_manager.js';
+import { interruptedTurnMarker } from './app/session_messages.js';
 import { LocalWorkspaceCoordinator } from './workspace_collision.js';
 import { HeadlessPaneManager } from './ui/ratatui/headless_pane_manager.js';
+import { modelHandoffSummarizer } from './utils/compaction.js';
 import { setPaneToolsTuiProcess, clearPaneToolsTuiProcess, setBusTransport, clearBusTransport, getBackgroundRegistry, clearBackgroundRegistry, resetAskUserTurnFlag, setTodoUpdateCallback } from './agent/tools/index.js';
 import { PaneRelayServer, generateRelaySocketPath } from './ui/ratatui/pane_relay.js';
 import { writePaneResponseSync } from './utils/pane_response.js';
 import { terminateActiveShellChildren } from './utils/shell.js';
+import { reserveModelRouteCredentials } from './utils/subprocess_env.js';
+import { OutputSchemaContract, OutputSchemaError } from './headless_output_schema.js';
+import { TrajectoryJsonlWriter, TrajectoryUnavailableError } from './headless_trajectory.js';
 // The simulation subsystem (world state, runner, and their zod/nunjucks/graph
 // dependency trees) is loaded lazily: most headless runs never start a
 // simulation, and the import is only needed at end-of-run checks.
@@ -68,6 +76,10 @@ import { HookLifecycle } from './hooks/lifecycle.js';
 import { runtimePluginRegistry } from './plugin/runtime_registry.js';
 import { getWorkflowRegistry } from './workflows/registry_handle.js';
 import { workflowsEnabled, workflowNaturalLanguageTriggerEnabled } from './workflows/config.js';
+/** Exit status when the only failure was a final message that never satisfied --output-schema. */
+export const HEADLESS_EXIT_OUTPUT_SCHEMA = 3;
+/** Exit status for an unusable --output-schema or --trajectory-jsonl, before any inference. */
+export const HEADLESS_EXIT_USAGE = 2;
 export function classifyPaneChildLine(line) {
     const trimmed = line.trim();
     // A control command is ONLY a BARE {"__ztc_cmd":...} line — the parent's
@@ -348,6 +360,7 @@ export class HeadlessApp {
     sessionManager;
     workspaceCoordinator = null;
     taskHandoff = null;
+    loadedHostScaffold;
     restoredHandoffCorrections = [];
     paneManager = null;
     askUserAutoAnswered = false;
@@ -367,6 +380,13 @@ export class HeadlessApp {
     batchEventUnsub = null;
     batchFailed = false;
     hadHeadlessError = false;
+    fatalTurnReached = false;
+    outputSchema;
+    trajectory;
+    /** Prompts whose final message never satisfied --output-schema. */
+    outputSchemaFailures = 0;
+    /** 1-based index of the agent prompt in flight; groups trajectory records. */
+    promptTurn = 0;
     /**
      * The AbortController of the agent turn currently in flight, or null between
      * turns. A pane child's SIGUSR2 handler (and the post-turn `cancel` stdin
@@ -397,7 +417,9 @@ export class HeadlessApp {
     lastEmittedVerb = null;
     lastEmittedWaiting = null;
     hookLifecycle;
-    constructor(options) {
+    constructor(options, sinks = {}) {
+        this.outputSchema = sinks.outputSchema ?? null;
+        this.trajectory = sinks.trajectory ?? null;
         this.options = {
             autoAccept: true, // Default to auto-accept in headless mode
             // No default iteration cap: a user-level headless agent runs until the
@@ -432,11 +454,13 @@ export class HeadlessApp {
             // /context), not the char/4 estimate. 0 before the first turn -> estimate.
             getContextTokens: () => this.lastContextTokens,
             getContextWindow: () => this.lastContextWindow,
+            getHandoffSummarizer: (signal, messages) => this.buildHandoffSummarizer(signal, messages),
             // Persist the active safety/runtime identity alongside the conversation.
             // Without mode + artifact, a resumed headless plan silently becomes a
             // normal full-tool agent even though its transcript says it is planning.
             getRuntimeState: () => ({
                 environment: this.environmentRecord ? { id: this.environmentRecord.id, name: this.environmentRecord.name } : null,
+                hostScaffold: this.agent?.hostScaffoldMessages(),
                 evidence: this.agent?.getEvidenceSnapshot(),
                 usage: this.agent?.getUsageSessionId() === this.sessionId ? this.agent.getUsageSnapshot() : undefined,
                 diagnostics: this.agent?.getDiagnosticSessionId() === this.sessionId
@@ -478,6 +502,23 @@ export class HeadlessApp {
             getApprovalRequester: () => (request) => this.requestHookApproval(request),
         });
     }
+    buildHandoffSummarizer(signal, messages) {
+        const agent = this.agent;
+        if (!agent)
+            return undefined;
+        const context = agent.getHandoffContext(messages ?? this.messages);
+        return modelHandoffSummarizer(context.backend, context.model, {
+            request: context,
+            signal,
+            onFallback: reason => {
+                if (!signal?.aborted)
+                    this.output({ type: 'status', timestamp: new Date().toISOString(),
+                        data: { status: 'compaction_fallback', message: `Model handoff failed: ${reason}. Using a local summary.` } });
+            },
+            system: context.system,
+            tools: context.tools,
+        });
+    }
     outputPromptComplete() {
         this.output({
             type: 'complete',
@@ -664,8 +705,18 @@ export class HeadlessApp {
                         });
                     }
                     break;
+                case 'stream_reset':
+                    if (this.options.json) {
+                        this.output({
+                            type: 'stream_reset',
+                            timestamp: new Date().toISOString(),
+                            data: {},
+                        });
+                    }
+                    break;
                 case 'tool_start':
                     this.emitHeadlessStatus();
+                    this.recordTrajectory({ type: 'tool_call', tool: event.tool, toolCallId: event.toolCallId, args: event.args });
                     this.output({
                         type: 'tool_call',
                         timestamp: new Date().toISOString(),
@@ -676,6 +727,8 @@ export class HeadlessApp {
                     if (event.tool === 'write_file') {
                         this.hookLifecycle.onToolWrite();
                     }
+                    this.recordTrajectory({ type: 'tool_result', tool: event.tool, toolCallId: event.toolCallId, success: true,
+                        result: event.result });
                     // success:true so a mirror child pane resolves the chip as ✓ (matches
                     // the overseer's publishToolResult(tool, result, true)); without it the
                     // reducer reads undefined and paints every chip ✗.
@@ -700,6 +753,8 @@ export class HeadlessApp {
                     // Resolve the chip FIRST — a tool_result with success:false — so it
                     // flips to ✗ instead of hanging on "..."; then the human-facing error
                     // line (kept for --json consumers / logs) renders after.
+                    this.recordTrajectory({ type: 'tool_result', tool: event.tool, toolCallId: event.toolCallId, success: false,
+                        result: `Error: ${event.error}` });
                     this.output({
                         type: 'tool_result',
                         timestamp: new Date().toISOString(),
@@ -1103,6 +1158,9 @@ export class HeadlessApp {
      * Initialize the app
      */
     async init() {
+        // Scan git in the background while startup loads config, plugins and
+        // modes; the agent's runtime-context prompt reads the result below.
+        prefetchStartupGitSnapshot(this.shellCwd);
         // Load the persisted profile before reading any credential signal.
         // `runHeadless` is a public entry point, so it cannot assume its caller ran
         // the CLI loader (headless_cli.ts does; direct library callers may not).
@@ -1110,9 +1168,12 @@ export class HeadlessApp {
         // whose real credential (for example a Codex subscription auth.json) is on
         // disk. `load()` is idempotent, so the CLI path is unaffected.
         await configStore.load();
+        // A headless run executes model-chosen commands with no human reviewing
+        // them, so tool children never inherit the run's inference credentials.
+        this.reserveRouteCredentials();
         // Hosted native Messages supplies its own scoped transport bearer. The
         // backend factory validates it; provider-key discovery must not gate it.
-        if (!configStore.get().nativeAnthropicMessagesRouter && !configStore.hasApiKey() && !configStore.isAuthenticated()) {
+        if (configStore.getProvider() !== 'bedrock' && !configStore.get().nativeAnthropicMessagesRouter && !configStore.hasApiKey() && !configStore.isAuthenticated()) {
             this.output({
                 type: 'error',
                 timestamp: new Date().toISOString(),
@@ -1424,6 +1485,7 @@ export class HeadlessApp {
         }
         catch { /* Offline startup keeps the account-scoped cached catalog. */ }
         // Create agent
+        await awaitStartupGitSnapshot(this.shellCwd);
         this.agent = this.createAgent();
         if (!this.agent) {
             this.output({
@@ -1577,7 +1639,12 @@ export class HeadlessApp {
      * Create the agent
      */
     commandJobsUnsubscribe;
+    /** Reservation is additive and idempotent; profile reloads may name a new apiKeyEnv. */
+    reserveRouteCredentials() {
+        reserveModelRouteCredentials(configStore.get().apiKeyEnv ?? {});
+    }
     createAgent(options = {}) {
+        this.reserveRouteCredentials();
         const diagnostics = this.sessionManager.getDiagnostics();
         this.sessionManager.recordHostDiagnostic('runtime', {
             renderer: 'headless', rendererVersion: null, nativeCapabilities: null, source: 'host_launch',
@@ -1598,6 +1665,7 @@ export class HeadlessApp {
             environmentContext: this.environmentRecord ? describeEnvironmentForAgent(this.environmentRecord) : undefined,
             autoContinue: true, // Always auto-continue in headless mode
             maxConsecutiveAutoContinues: configStore.getMaxConsecutiveAutoContinues(),
+            completionCheck: true,
             maxIterations: isEvolveMode ? 200 : (this.options.maxIterations ?? Infinity),
             pinTaskHeader: this.options.pinTaskHeader,
             mode: this.currentMode,
@@ -1614,6 +1682,7 @@ export class HeadlessApp {
             hookApprovalRequester: (request) => this.requestHookApproval(request),
             toolResponseStore: this.sessionToolResponseStore,
             onLocalFileChange: async (paths, cwd) => {
+                this.recordTrajectory({ type: 'file_change', paths, cwd });
                 await this.workspaceCoordinator?.recordObservedPaths(paths, cwd);
             },
             toolCheckpoint: async (checkpoint) => {
@@ -1626,10 +1695,12 @@ export class HeadlessApp {
                 this.messages.splice(0, this.messages.length, ...merged);
                 await this.sessionManager.save({ required: true });
             },
+            onMidTurnCompact: ({ signal, messages }) => this.sessionManager.compactHistory(30, 5, signal, messages),
         });
         if (agent) {
             agent.restoreDiagnosticSnapshot(diagnostics);
             agent.restoreUsageSnapshot(this.sessionManager.getUsageSnapshot());
+            agent.setHostScaffoldMessages(this.loadedHostScaffold);
             agent.setTaskHandoff(this.taskHandoff);
             this.agentBindFailure = null;
             const bind = this.bindAgentStore(agent);
@@ -2141,7 +2212,7 @@ export class HeadlessApp {
      * Run a single prompt through the agent
      */
     async runPrompt(prompt, opts = {}) {
-        if (routeUserInput(prompt).type === 'command') {
+        if (process.env.ZTC_DISABLE_SLASH_COMMANDS !== '1' && routeUserInput(prompt).type === 'command') {
             await this.runPromptAdmitted(prompt, opts);
             return;
         }
@@ -2157,11 +2228,13 @@ export class HeadlessApp {
     }
     async runPromptAdmitted(prompt, opts = {}) {
         // Route input: slash command or regular message
-        const route = routeUserInput(prompt);
+        const route = process.env.ZTC_DISABLE_SLASH_COMMANDS === '1' ? { type: 'message' } : routeUserInput(prompt);
         if (route.type === 'command') {
             const output = await this.executeCommand(route.cmd, route.args);
             await this.saveCurrentSession();
-            if (output && (output.startsWith('Unknown command') || output.startsWith('Command /'))) {
+            if (isCommandRefusal(output)) {
+                this.hadHeadlessError = true;
+                this.output(refusalEvent(output));
                 this.output({
                     type: 'message',
                     timestamp: new Date().toISOString(),
@@ -2182,7 +2255,9 @@ export class HeadlessApp {
             this.output({ type: 'error', timestamp: new Date().toISOString(), data: { message: 'Shell commands (!cmd) not supported in headless mode' } });
             return;
         }
-        const triggeredWorkflow = this.workflowToolAvailableInCurrentMode()
+        this.promptTurn += 1;
+        // A schema-bound prompt always takes the validated agent path below.
+        const triggeredWorkflow = !this.outputSchema && this.workflowToolAvailableInCurrentMode()
             && workflowsEnabled(configStore.get()) && workflowNaturalLanguageTriggerEnabled(configStore.get())
             ? await this.buildTriggeredWorkflow(prompt)
             : null;
@@ -2190,11 +2265,14 @@ export class HeadlessApp {
             await this.runTriggeredWorkflowPrompt(prompt, triggeredWorkflow);
             return;
         }
-        // Add user message
+        // Add user message. A schema-bound prompt carries its output contract, so
+        // the model sees the schema on the first attempt, not only on repair.
+        if (this.outputSchema)
+            this.clearSchemaOutputFile();
         const userMsg = {
             id: `msg_${randomUUID()}`,
             role: 'user',
-            content: prompt,
+            content: this.outputSchema ? `${prompt}\n\n${this.outputSchema.promptContract()}` : prompt,
             timestamp: new Date(),
         };
         this.messages.push(userMsg);
@@ -2225,6 +2303,8 @@ export class HeadlessApp {
         await this.maybeAutoCompact();
         let maxRetries = 2;
         const maxAskUserRounds = 20;
+        // --output-schema allows exactly one repair turn per prompt.
+        let schemaRepairUsed = false;
         let askUserRounds = 0;
         let attempt = 0;
         while (attempt <= maxRetries) {
@@ -2283,7 +2363,8 @@ export class HeadlessApp {
                         timestamp: new Date(),
                         // Reasoning models expect their trace replayed with the assistant
                         // message on later turns; dropping it strips the history.
-                        ...(response.reasoning ? { metadata: { reasoningContent: response.reasoning } } : {}),
+                        metadata: { ...(response.reasoning ? { reasoningContent: response.reasoning } : {}),
+                            ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: response.nativeModel ?? configStore.get().model } : {}) },
                     };
                     this.messages.push(assistantMsg);
                     this.lastResponse = response.content; // Track for --output
@@ -2314,8 +2395,10 @@ export class HeadlessApp {
                 await this.saveCurrentSession();
                 // Check if we should auto-compact after the run
                 await this.maybeAutoCompact();
-                // Save to output file if specified
-                await this.writeFinalOutputFile(this.lastResponse ?? response.content);
+                // Save to output file if specified (schema-bound output is written
+                // only after validation, below).
+                if (!this.outputSchema)
+                    await this.writeFinalOutputFile(this.lastResponse ?? response.content);
                 const selfAppliedPlanTransition = response.toolCalls.some((toolCall) => toolCall.name === 'plan_mode'
                     && toolCall.status === 'complete') && this.currentMode === 'plan'
                     && (this.agentBuiltForMode !== 'plan'
@@ -2347,6 +2430,25 @@ export class HeadlessApp {
                     });
                     continue;
                 }
+                if (this.outputSchema) {
+                    const verdict = this.outputSchema.validateMessage(response.content);
+                    if (!verdict.ok && !schemaRepairUsed) {
+                        schemaRepairUsed = true;
+                        this.messages.push({
+                            id: `msg_${randomUUID()}`,
+                            role: 'user',
+                            content: this.outputSchema.repairPrompt(verdict.errors),
+                            timestamp: new Date(),
+                        });
+                        this.output({
+                            type: 'status',
+                            timestamp: new Date().toISOString(),
+                            data: { status: 'output_schema_repair', errors: verdict.errors },
+                        });
+                        continue;
+                    }
+                    await this.settleSchemaOutput(verdict, schemaRepairUsed);
+                }
                 // Success - exit retry loop
                 break;
             }
@@ -2359,6 +2461,7 @@ export class HeadlessApp {
                 if (this.runCancelledByUser) {
                     this.runCancelledByUser = false;
                     this.goalTurnCancelled = true;
+                    this.messages.push(interruptedTurnMarker());
                     await this.saveCurrentSession();
                     break;
                 }
@@ -2599,7 +2702,8 @@ export class HeadlessApp {
                         timestamp: new Date(),
                         // Reasoning models expect their trace replayed with the assistant
                         // message on later turns; dropping it strips the history.
-                        ...(response.reasoning ? { metadata: { reasoningContent: response.reasoning } } : {}),
+                        metadata: { ...(response.reasoning ? { reasoningContent: response.reasoning } : {}),
+                            ...(response.responseItems ? { openaiResponseItems: response.responseItems, openaiResponseModel: response.nativeModel ?? configStore.get().model } : {}) },
                     };
                     this.messages.push(assistantMsg);
                     this.lastResponse = response.content;
@@ -2657,6 +2761,7 @@ export class HeadlessApp {
             if (this.runCancelledByUser) {
                 this.runCancelledByUser = false;
                 this.goalTurnCancelled = true;
+                this.messages.push(interruptedTurnMarker());
                 await this.saveCurrentSession();
             }
             else {
@@ -2790,7 +2895,48 @@ export class HeadlessApp {
         });
     }
     getExitCode() {
-        return this.batchFailed || this.hadHeadlessError ? 1 : 0;
+        if (this.batchFailed || this.hadHeadlessError)
+            return 1;
+        return this.outputSchemaFailures > 0 ? HEADLESS_EXIT_OUTPUT_SCHEMA : 0;
+    }
+    recordTrajectory(event) {
+        if (!this.trajectory)
+            return;
+        try {
+            this.trajectory.record(this.sessionId, this.promptTurn, event);
+        }
+        catch (error) {
+            if (!(error instanceof TrajectoryUnavailableError))
+                throw error;
+            this.trajectory = null;
+            this.hadHeadlessError = true;
+            this.output({ type: 'error', timestamp: new Date().toISOString(),
+                data: { error: error.code, message: error.message } });
+        }
+    }
+    /**
+     * Under --output-schema the --output file only ever holds validated JSON for
+     * the prompt in flight: it is emptied when a prompt starts (never created)
+     * and filled only once that prompt's final message validates.
+     */
+    clearSchemaOutputFile() {
+        const path = this.options.outputFile;
+        if (path && existsSync(path))
+            truncateSync(path, 0);
+    }
+    async settleSchemaOutput(verdict, repaired) {
+        if (verdict.ok) {
+            if (this.options.outputFile)
+                await writeFile(this.options.outputFile, `${verdict.json}\n`, 'utf-8');
+            this.output({ type: 'status', timestamp: new Date().toISOString(),
+                data: { status: 'output_schema_valid', repaired, ...(this.options.outputFile ? { path: this.options.outputFile } : {}) } });
+            return;
+        }
+        this.outputSchemaFailures += 1;
+        const message = `Final message did not satisfy --output-schema${repaired ? ' after one repair turn' : ''}: `
+            + verdict.errors.slice(0, 3).join('; ');
+        this.output({ type: 'error', timestamp: new Date().toISOString(),
+            data: { error: 'output_schema_validation_failed', message, errors: verdict.errors, repair_attempted: repaired } });
     }
     /**
      * Shut down background agents and batch orchestrator gracefully before exiting.
@@ -2952,6 +3098,8 @@ export class HeadlessApp {
                 data: { status: 'ready', session_id: this.sessionId, mode: this.currentMode }
             });
             for (const input of parsedInputs) {
+                if (this.fatalTurnReached)
+                    break;
                 if (input.prompt && this.validateJsonInputMode(input.mode)) {
                     await this.runInteractivePrompt(input.prompt);
                     this.outputPromptComplete();
@@ -2986,6 +3134,8 @@ export class HeadlessApp {
                 }
                 else {
                     // TTY, JSON protocol, and pane children process one line at a time.
+                    // Their caller sends the next line after a failed turn, so a failure
+                    // ends only that turn; a batch read up front stops at it instead.
                     const budget = { records: 0, aggregateBytes: 0 };
                     for await (const line of inputLines) {
                         const trimmed = line.text.trim();
@@ -3223,6 +3373,8 @@ export class HeadlessApp {
         this.sessionLabels = { ...session.metadata.labels, manual_title: this.sessionName };
         this.messages = session.messages;
         this.taskHandoff = session.task_handoff ? projectTaskHandoff(session.task_handoff) : null;
+        this.loadedHostScaffold = session.host_scaffold;
+        this.agent?.setHostScaffoldMessages(session.host_scaffold);
         this.restoredHandoffCorrections = session.task_handoff?.corrections.map(correction => ({
             ...correction, deliveryState: correction.deliveryState === 'pending' ? 'unknown' : correction.deliveryState,
         })) ?? [];
@@ -3300,6 +3452,8 @@ export class HeadlessApp {
         await this.runPrompt(prompt);
         await this.accountGoalFinalTurnAfterPrompt();
         await this.runGoalLoopIfArmed();
+        if (this.hadHeadlessError)
+            this.fatalTurnReached = true;
     }
     /**
      * Drive an autonomous /goal to a terminal state in headless mode. No-op unless
@@ -3478,6 +3632,42 @@ export class HeadlessApp {
         process.exit(this.getExitCode());
     }
 }
+/**
+ * Load --output-schema and open --trajectory-jsonl before any stdin is read or
+ * inference runs. Returns null after reporting a typed error.
+ */
+function openHeadlessSinks(options) {
+    const report = (error) => {
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify({ type: 'error', timestamp: new Date().toISOString(),
+                data: { error: error.code, message: error.message } })}\n`);
+        }
+        else {
+            process.stderr.write(`${error.message}\n`);
+        }
+    };
+    let outputSchema;
+    try {
+        if (options.outputSchemaFile)
+            outputSchema = OutputSchemaContract.fromFile(resolve(options.outputSchemaFile));
+    }
+    catch (error) {
+        if (!(error instanceof OutputSchemaError))
+            throw error;
+        report(error);
+        return null;
+    }
+    try {
+        const trajectory = options.trajectoryJsonl ? TrajectoryJsonlWriter.open(resolve(options.trajectoryJsonl)) : undefined;
+        return { outputSchema, trajectory };
+    }
+    catch (error) {
+        if (!(error instanceof TrajectoryUnavailableError))
+            throw error;
+        report(error);
+        return null;
+    }
+}
 /**
  * Main entry point for headless mode
  */
@@ -3510,6 +3700,11 @@ export async function runHeadless(options, initialPrompt) {
             return;
         }
     }
+    const sinks = openHeadlessSinks(options);
+    if (!sinks) {
+        process.exitCode = HEADLESS_EXIT_USAGE;
+        return;
+    }
     const deferJsonStdinStartup = !!options.json
         && !options.jsonStream
         && !initialPrompt
@@ -3552,7 +3747,7 @@ export async function runHeadless(options, initialPrompt) {
         ...options,
         deferJsonStdinStartup,
         jsonInputLines,
-    });
+    }, sinks);
     let initialized;
     try {
         initialized = await app.init();

package/dist/headless_cli.js

@@ -23,6 +23,10 @@ Server-host options:
   --max-iterations <n>      Bound one agent turn
   --timeout <ms>            Bound one agent operation
   --cwd <path>              Set the agent working directory
+  --output <path>           Write each prompt's final answer to a file
+  --output-schema <file>    Require each prompt's final answer to be JSON valid
+                            against this schema (one repair turn; exit 3 on failure)
+  --trajectory-jsonl <path> Append tool_call/tool_result/file_change records as JSONL
   --quiet                   Suppress non-protocol output
 
 Interactive, TUI, audio, simulation-control-plane, and document-generation
@@ -112,6 +116,8 @@ async function main() {
         timeout: options.timeout,
         verbose: options.verbose,
         outputFile: options.outputFile,
+        outputSchemaFile: options.outputSchemaFile,
+        trajectoryJsonl: options.trajectoryJsonl,
         pinTaskHeader: options.pinTaskHeader,
     };
     await runHeadless(headlessOptions, options.prompt);

package/dist/headless_cli_args.d.ts

@@ -17,6 +17,10 @@ export interface HeadlessCliOptions {
     prompt?: string;
     cwd?: string;
     outputFile?: string;
+    /** JSON Schema the final assistant message of each prompt must satisfy. */
+    outputSchemaFile?: string;
+    /** Tool-call/tool-result/file-change trajectory sink (JSONL). Not --json-stream, which is input. */
+    trajectoryJsonl?: string;
     maxIterations?: number;
     timeout?: number;
 }

package/dist/headless_cli_args.js

@@ -35,6 +35,8 @@ export function parseHeadlessCliArgs(args) {
         ['--prompt', (value) => { options.prompt = value; return undefined; }],
         ['--cwd', (value) => { options.cwd = value; return undefined; }],
         ['--output', (value) => { options.outputFile = value; return undefined; }],
+        ['--output-schema', (value) => { options.outputSchemaFile = value; return undefined; }],
+        ['--trajectory-jsonl', (value) => { options.trajectoryJsonl = value; return undefined; }],
         ['--max-iterations', (value) => {
                 const parsed = Number(value);
                 if (!Number.isSafeInteger(parsed) || parsed <= 0)

package/dist/headless_output_schema.d.ts

@@ -0,0 +1,46 @@
+export declare const OUTPUT_SCHEMA_LIMITS: Readonly<{
+    schemaBytes: number;
+    depth: 64;
+    reportedErrors: 20;
+    /** Schema-node visits per validation; bounds anyOf/oneOf/$ref fan-out. */
+    validationSteps: 200000;
+}>;
+export type OutputSchemaErrorCode = 'output_schema_invalid' | 'output_schema_validation_failed';
+export declare class OutputSchemaError extends Error {
+    readonly code: OutputSchemaErrorCode;
+    readonly errors: readonly string[];
+    constructor(code: OutputSchemaErrorCode, message: string, errors?: readonly string[]);
+}
+export type OutputSchemaVerdict = {
+    ok: true;
+    value: unknown;
+    json: string;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare class OutputSchemaContract {
+    private readonly root;
+    private readonly patterns;
+    /** JSON pointers of every position compile() checked as a schema. */
+    private readonly schemaPointers;
+    private readonly refSites;
+    private readonly refTargets;
+    private steps;
+    private constructor();
+    /** Read, bound and compile a schema file; every failure is `output_schema_invalid`. */
+    static fromFile(path: string): OutputSchemaContract;
+    static fromSchema(schema: unknown): OutputSchemaContract;
+    /** Text appended to each schema-bound prompt so the model knows the contract up front. */
+    promptContract(): string;
+    repairPrompt(errors: readonly string[]): string;
+    validateMessage(text: string | null | undefined): OutputSchemaVerdict;
+    private compile;
+    private compileOther;
+    private matches;
+    private check;
+    private checkString;
+    private checkNumber;
+    private checkArray;
+    private checkObject;
+}