@yaag/runtime 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },

package/src/agent.ts

@@ -5,8 +5,9 @@ import type { EffectiveAskOptions } from "./ask-hash.ts";
 import { Connection } from "./connection.ts";
 import { agentError } from "./errors.ts";
 import type { EventSink } from "./events.ts";
+import { ReportResultTool } from "./report-result.ts";
 import type { AgentStats, AgentTransport } from "./transport.ts";
-import type { AskOptions, Handle, SpawnOptions, StructuredAskOptions } from "./types.ts";
+import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "./types.ts";
 
 export interface AgentOptions {
   readonly name: string;
@@ -15,7 +16,7 @@ export interface AgentOptions {
   readonly transport: AgentTransport;
   readonly emit: EventSink;
   /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
-  readonly spawnOptions: SpawnOptions;
+  readonly spawnOptions: ResolvedSpawnOptions;
   /** Definition-owned defaults merged below explicit per-Ask options. */
   readonly askDefaults?: AskOptions;
   /** Definition identity recorded on its Asks, outside replay identity. */
@@ -24,6 +25,8 @@ export interface AgentOptions {
   readonly askLimitGraceMs?: number;
   /** Test-only override for the bounded wait for `agent_settled` after an idle abort. */
   readonly idleAbortSettleMs?: number;
+  /** Test-only override for the bounded wait for the Stall Watchdog probe. */
+  readonly stallProbeSettleMs?: number;
 }
 
 /** One Agent as an Orchestration Program sees it. Lives above the transport seam. */
@@ -36,12 +39,14 @@ export class Agent implements Handle {
   readonly #transport: AgentTransport;
   readonly #connection: Connection;
   readonly #emit: EventSink;
-  readonly #spawnOptions: SpawnOptions;
+  readonly #spawnOptions: ResolvedSpawnOptions;
   readonly #askDefaults: AskOptions;
   readonly #definitionName: string | undefined;
   readonly #askLimitGraceMs: number | undefined;
   readonly #idleAbortSettleMs: number | undefined;
+  readonly #stallProbeSettleMs: number | undefined;
   readonly #usage: AgentUsage;
+  readonly #reportResultTool = new ReportResultTool();
   #busy = false;
   #incomplete = false;
   #askIndex = 0;
@@ -59,6 +64,7 @@ export class Agent implements Handle {
     this.#definitionName = options.definitionName;
     this.#askLimitGraceMs = options.askLimitGraceMs;
     this.#idleAbortSettleMs = options.idleAbortSettleMs;
+    this.#stallProbeSettleMs = options.stallProbeSettleMs;
     this.#usage = new AgentUsage((snapshot) =>
       this.#emit({ type: "agent_usage", agent: this.name, ...snapshot }),
     );
@@ -92,11 +98,13 @@ export class Agent implements Handle {
         ask: { ...this.#askDefaults, ...options },
         spawnOptions: this.#spawnOptions,
         definitionName: this.#definitionName,
+        reportResultTool: this.#reportResultTool,
         emit: this.#emit,
         usage: this.#usage,
         close: () => void this.close().catch(() => {}),
         askLimitGraceMs: this.#askLimitGraceMs,
         idleAbortSettleMs: this.#idleAbortSettleMs,
+        stallProbeSettleMs: this.#stallProbeSettleMs,
       });
     } finally {
       this.#busy = false;

package/src/ask-contract-identity.ts

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import { ASK_OUTPUT_EXTRACTION_POLICY } from "./ask-output.ts";
+import { ASK_OUTPUT_EXTRACTION_POLICY, type AskOutputExtractionPolicy } from "./ask-output.ts";
 
 /** A JSON value suitable for deterministic Cassette identity. */
 export type CanonicalJson =
@@ -32,11 +32,29 @@ export function canonicalizeSchema(value: unknown): CanonicalJsonObject {
   return canonicalize(value, new Set<object>()) as CanonicalJsonObject;
 }
 
-/** Builds the recorded and hashed behavioral contract for one structured Ask. */
-export function createAskOutputContract(schema: TSchema, maxSteers?: number): AskOutputContract {
+/**
+ * Builds the recorded and hashed behavioral contract for one structured Ask.
+ *
+ * `policy` is the live policy unless a Cassette recorded this Ask under an
+ * older one, in which case that Ask keeps its recorded identity and behavior.
+ * Throws a TypeError when a live Ask declares a schema that is not an object
+ * schema: the Agent reports the result as one tool call's arguments (ADR-0032),
+ * and an Ask recorded before that decision keeps whatever schema it recorded.
+ */
+export function createAskOutputContract(
+  schema: TSchema,
+  maxSteers?: number,
+  policy: AskOutputExtractionPolicy = ASK_OUTPUT_EXTRACTION_POLICY,
+): AskOutputContract {
+  const outputSchema = canonicalizeSchema(schema);
+  if (policy === ASK_OUTPUT_EXTRACTION_POLICY && outputSchema.type !== "object") {
+    throw new TypeError(
+      "outputSchema must be an object schema: the Agent reports it as one tool call's arguments",
+    );
+  }
   return {
-    outputSchema: canonicalizeSchema(schema),
-    extractionPolicy: ASK_OUTPUT_EXTRACTION_POLICY,
+    outputSchema,
+    extractionPolicy: policy,
     ...(maxSteers === undefined ? {} : { maxSteers }),
   };
 }

package/src/ask-exchange-events.ts

@@ -2,6 +2,16 @@ import type { AgentActivity, AskOutputChannel, EventSink } from "./events.ts";
 import { agentAskPath, childPath } from "./node-path.ts";
 import type { NodeSnapshot } from "./node-tracker.ts";
 import { promptGist } from "./prompt-gist.ts";
+import type { SettlementCause } from "./stall-watchdog.ts";
+
+/** What one finished Ask reports in its `ask_end` Lifecycle Event. */
+export interface AskEndOutcome {
+  readonly durationMs: number;
+  readonly ok: boolean;
+  /** Largest inter-frame silence; absent during Cassette playback. */
+  readonly maxFrameGapMs: number | undefined;
+  readonly cause?: SettlementCause;
+}
 
 /** Emits the four Ask-scoped Lifecycle Events for one exchange. */
 export class AskEvents {
@@ -47,7 +57,9 @@ export class AskEvents {
     });
   };
 
-  end(durationMs: number, ok: boolean, maxFrameGapMs: number | undefined): void {
+  /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
+  end(outcome: AskEndOutcome): void {
+    const { durationMs, ok, maxFrameGapMs, cause = "normal" } = outcome;
     this.#emit({
       type: "ask_end",
       agent: this.#agent,
@@ -55,6 +67,7 @@ export class AskEvents {
       durationMs,
       ok,
       ...(maxFrameGapMs === undefined ? {} : { maxFrameGapMs }),
+      ...(cause === "normal" ? {} : { cause }),
     });
   }
 }

package/src/ask-exchange-options.ts

@@ -1,8 +1,9 @@
 import type { EffectiveAskOptions } from "./ask-hash.ts";
 import type { Connection } from "./connection.ts";
 import type { EventSink } from "./events.ts";
+import type { ReportResultTool } from "./report-result.ts";
 import type { AgentTransport, Frame } from "./transport.ts";
-import type { SpawnOptions } from "./types.ts";
+import type { ResolvedSpawnOptions } from "./types.ts";
 
 /** A frame consumer whose lifetime exceeds one Ask; the Agent's AgentUsage satisfies it. */
 export interface FrameObserver {
@@ -17,8 +18,10 @@ export interface AskExchangeOptions {
   readonly prompt: string;
   readonly index: number;
   readonly ask: EffectiveAskOptions;
-  readonly spawnOptions: SpawnOptions;
+  readonly spawnOptions: ResolvedSpawnOptions;
   readonly definitionName: string | undefined;
+  /** The Agent's report_result activation state, which spans its Asks (ADR-0032). */
+  readonly reportResultTool: ReportResultTool;
   /** Lifecycle Event sink; the exchange emits every Ask-scoped event itself. */
   readonly emit: EventSink;
   /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
@@ -29,4 +32,6 @@ export interface AskExchangeOptions {
   readonly askLimitGraceMs: number | undefined;
   /** Test-only override for the bounded settle wait after an idle abort. */
   readonly idleAbortSettleMs: number | undefined;
+  /** Test-only override for the bounded wait for the Stall Watchdog probe. */
+  readonly stallProbeSettleMs: number | undefined;
 }

package/src/ask-exchange.ts

@@ -1,9 +1,11 @@
+import type { TSchema } from "typebox";
 import { AskActivityTracker } from "./ask-activity.ts";
-import { AskEvents } from "./ask-exchange-events.ts";
+import type { AskOutputContract } from "./ask-contract-identity.ts";
+import { type AskEndOutcome, AskEvents } from "./ask-exchange-events.ts";
 import type { AskExchangeOptions } from "./ask-exchange-options.ts";
 import { askHash, askMarkerContext, structuredOutputContract } from "./ask-hash.ts";
 import { AskLimit } from "./ask-limit.ts";
-import { resolvePlaybackAskOutput } from "./ask-output.ts";
+import { LEGACY_ASK_OUTPUT_EXTRACTION_POLICY, resolvePlaybackAskOutput } from "./ask-output.ts";
 import { AskOutputSteering } from "./ask-output-steering.ts";
 import { AskOutputTail } from "./ask-output-tail.ts";
 import { awaitAskSettlement } from "./ask-settlement.ts";
@@ -19,6 +21,15 @@ import {
 import { FrameGapTracker } from "./frame-gap.ts";
 import { IdleKillSignal, IdleWatch } from "./idle-watch.ts";
 import { NodeTracker } from "./node-tracker.ts";
+import { ReportResultCall } from "./report-result.ts";
+import { REPORT_RESULT_WRAP_UP, resolvePlaybackReportedResult } from "./report-result-output.ts";
+import { ReportResultSteering } from "./report-result-steering.ts";
+import {
+  type SettlementCause,
+  StallSignal,
+  StallWatchdog,
+  stallBudgetMs,
+} from "./stall-watchdog.ts";
 import type { AskPlayback } from "./transport.ts";
 
 export type { AskExchangeOptions } from "./ask-exchange-options.ts";
@@ -32,10 +43,14 @@ class AskExchange {
   readonly #events: AskEvents;
   #limit: AskLimit | null = null;
   #idle: IdleWatch | null = null;
+  #stall: StallWatchdog | null = null;
   #gap: FrameGapTracker | null = null;
   #activity: AskActivityTracker | null = null;
   #output: AskOutputTail | null = null;
   #nodes: NodeTracker | null = null;
+  #call: ReportResultCall | null = null;
+  #legacyExtraction = false;
+  #contract: AskOutputContract | undefined;
   #playback: AskPlayback | undefined;
   #began = false;
   #outcome: AskLimitOutcome | undefined;
@@ -45,6 +60,8 @@ class AskExchange {
   #controlFailure: Promise<never> = new Promise<never>(() => {});
   #timeoutDeadline: number | undefined;
   #maxFrameGapMs: number | undefined;
+  #cause: SettlementCause = "normal";
+  #drainStaleFrames = false;
   constructor(options: AskExchangeOptions) {
     this.#options = options;
     this.#events = new AskEvents(options.emit, options.agent, options.index);
@@ -54,19 +71,31 @@ class AskExchange {
     const startedAt = Date.now();
     try {
       const result = await this.#exchange();
-      this.#events.end(Date.now() - startedAt, true, this.#maxFrameGapMs);
+      this.#events.end(this.#endOutcome(startedAt, true));
       return result;
     } catch (error) {
-      if (this.#began) this.#events.end(Date.now() - startedAt, false, this.#maxFrameGapMs);
+      if (this.#began) this.#events.end(this.#endOutcome(startedAt, false));
       throw error;
     }
   }
 
+  #endOutcome(startedAt: number, ok: boolean): AskEndOutcome {
+    return {
+      durationMs: Date.now() - startedAt,
+      ok,
+      maxFrameGapMs: this.#maxFrameGapMs,
+      cause: this.#cause,
+    };
+  }
+
   async #exchange(): Promise<unknown> {
     try {
       this.#begin();
-      const settled = this.#armSettlement();
       this.#timeoutDeadline = this.#deadline();
+      // The schema command is answered without a turn, so settlement tracking
+      // starts after it: nothing it could emit may settle this Ask (ADR-0032).
+      await this.#deliverSchema();
+      const settled = this.#armSettlement();
       await this.#sendPrompt();
       await this.#verify(settled);
       const abortSettled =
@@ -74,7 +103,7 @@ class AskExchange {
       let result: unknown;
       let outputError: unknown;
       try {
-        result = await this.#resolveOutput(await this.#lastAssistantText());
+        result = await this.#resolveOutput();
       } catch (error) {
         if (abortSettled === undefined) throw error;
         outputError = error;
@@ -91,7 +120,12 @@ class AskExchange {
   }
 
   #begin(): void {
-    const outputContract = structuredOutputContract(this.#options.ask);
+    this.#legacyExtraction = this.#recordedLegacyPolicy();
+    const outputContract = structuredOutputContract(
+      this.#options.ask,
+      this.#legacyExtraction ? LEGACY_ASK_OUTPUT_EXTRACTION_POLICY : undefined,
+    );
+    this.#contract = outputContract;
     const identity = {
       spawnOptions: this.#options.spawnOptions,
       index: this.#options.index,
@@ -118,11 +152,16 @@ class AskExchange {
     // Nested Node is decoded from recorded Agent frames only, so playback must
     // re-derive the identical `node_update` stream (ADR-0013, spec §3).
     this.#nodes = new NodeTracker({ report: this.#events.node });
+    // Playback reads the recorded call from the Cassette instead, so its value
+    // cannot depend on how far the replayed frame stream has drained.
+    this.#call = playback === undefined ? new ReportResultCall() : null;
     this.#limit = playback === undefined ? this.#createLimit() : null;
     this.#idle = playback === undefined ? this.#createIdleWatch() : null;
+    this.#stall = playback === undefined ? this.#createStallWatchdog() : null;
     this.#observe();
     this.#limit?.start();
     this.#idle?.start();
+    this.#stall?.start();
     this.#gap?.start();
     this.#controlFailure = this.#createControlFailure();
   }
@@ -132,9 +171,35 @@ class AskExchange {
       ask: this.#options.ask,
       durationGraceMs: this.#options.askLimitGraceMs,
       command: async (frame) => (await this.#options.connection.command(frame)).success,
+      ...(this.#reportsResult() ? { wrapUpSuffix: REPORT_RESULT_WRAP_UP } : {}),
     });
   }
 
+  /** The Ask's declared output schema, or undefined when it takes final text. */
+  #outputSchema(): TSchema | undefined {
+    return "outputSchema" in this.#options.ask ? this.#options.ask.outputSchema : undefined;
+  }
+
+  /** The Ask's explicit correction bound, absent unless it declared a schema. */
+  #maxSteers(): number | undefined {
+    return "maxSteers" in this.#options.ask ? this.#options.ask.maxSteers : undefined;
+  }
+
+  /** True when this Ask settles from a report_result call rather than from text. */
+  #reportsResult(): boolean {
+    return this.#outputSchema() !== undefined && !this.#legacyExtraction;
+  }
+
+  /**
+   * True when a Cassette recorded this Ask before ADR-0032. Such an Ask keeps
+   * its recorded identity and its recorded ADR-0027 behavior, so it replays
+   * frame for frame.
+   */
+  #recordedLegacyPolicy(): boolean {
+    const recorded = this.#options.transport.recordedExtractionPolicy?.(this.#options.index);
+    return recorded === LEGACY_ASK_OUTPUT_EXTRACTION_POLICY;
+  }
+
   #createIdleWatch(): IdleWatch | null {
     if (this.#options.ask.idleMs === undefined) return null;
     return new IdleWatch({
@@ -146,28 +211,67 @@ class AskExchange {
     });
   }
 
+  #createStallWatchdog(): StallWatchdog | null {
+    const stallMs = stallBudgetMs(this.#options.ask.stallMs);
+    if (stallMs === null) return null;
+    return new StallWatchdog({
+      stallMs,
+      ...(this.#options.stallProbeSettleMs === undefined
+        ? {}
+        : { probeSettleMs: this.#options.stallProbeSettleMs }),
+      command: async (frame) => await this.#options.connection.command(frame),
+      terminal: () => this.#turn.terminal,
+      recover: () => {
+        this.#cause = "recovered";
+        // The missing `agent_settled` may still arrive: it belongs to the turn
+        // yaag just settled by hand, never to the next Ask.
+        this.#drainStaleFrames = true;
+        this.#onSettled();
+      },
+    });
+  }
+
   #observe(): void {
     this.#options.connection.observe((frame) => {
       this.#turn.observe(frame);
       this.#limit?.observe(frame);
       if (frame.type !== "agent_settled" || this.#idle?.tripped) this.#idle?.observe(frame);
+      this.#stall?.observe(frame);
       this.#gap?.observe();
       this.#activity?.observe(frame);
       this.#output?.observe(frame);
       this.#nodes?.observe(frame);
+      this.#call?.observe(frame);
       if (this.#playback === undefined) this.#options.usage.observe(frame);
-      if (this.#turn.settled) this.#onSettled();
+      // A recorded recovery has no `agent_settled`: its terminal assistant
+      // message is what the live watchdog settled on, so playback does the same.
+      if (this.#playback?.recovered === true && this.#turn.terminal) {
+        this.#cause = "recovered";
+        this.#onSettled();
+      }
+      if (this.#turn.settled) {
+        this.#stall?.settled();
+        this.#onSettled();
+      }
     });
   }
 
   #createControlFailure(): Promise<never> {
-    const controls = [this.#limit?.failed, this.#idle?.failed, this.#idle?.killed].filter(
-      (promise): promise is Promise<never> => promise !== undefined,
-    );
+    const controls = [
+      this.#limit?.failed,
+      this.#idle?.failed,
+      this.#idle?.killed,
+      this.#stall?.failed,
+    ].filter((promise): promise is Promise<never> => promise !== undefined);
     return Promise.race(controls.length === 0 ? [new Promise<never>(() => {})] : controls).catch(
       (error: unknown) => {
         if (error instanceof IdleKillSignal)
           throw askStalledError(this.#options.agent, error.outcome);
+        if (error instanceof StallSignal) {
+          this.#cause = "stalled";
+          this.#drainStaleFrames = !error.outcome.destructive;
+          throw askStalledError(this.#options.agent, error.outcome);
+        }
         throw this.#failed(error instanceof Error ? error.message : "limit control command failed");
       },
     );
@@ -175,6 +279,7 @@ class AskExchange {
 
   #armSettlement(): Promise<void> {
     this.#turn.rearm();
+    this.#stall?.rearm();
     return new Promise<void>((resolve) => {
       this.#onSettled = resolve;
     });
@@ -186,7 +291,30 @@ class AskExchange {
       : Date.now() + this.#options.ask.timeoutMs;
   }
 
+  /**
+   * Carries this Ask's schema to the Agent's report_result tool, before the
+   * prompt (ADR-0032).
+   *
+   * pi routes the command to the extension and never to the model, and the
+   * frame belongs to this same logical Ask, so the Ask's own prompt bytes and
+   * its Ask index are untouched.
+   */
+  async #deliverSchema(): Promise<void> {
+    if (this.#legacyExtraction) return;
+    const command = this.#options.reportResultTool.begin(this.#contract?.outputSchema);
+    if (command === null) return;
+    const response = await this.#options.connection.command({
+      type: "prompt",
+      message: command.message,
+    });
+    if (!response.success) {
+      throw this.#failed(response.error ?? "report_result schema command was rejected");
+    }
+    command.accepted();
+  }
+
   async #sendPrompt(): Promise<void> {
+    this.#call?.arm();
     const response = await this.#options.connection.command({
       type: "prompt",
       message: this.#options.prompt,
@@ -199,6 +327,12 @@ class AskExchange {
   }
 
   async #verify(settled: Promise<void>, ignoreAbortFailure = false): Promise<void> {
+    // A recorded Ask that never settled has no settlement frame to wait for.
+    // Waiting for one would reproduce, in replay, the exact stall this
+    // watchdog exists to end.
+    if (this.#playback?.settles === false && this.#playback.recovered !== true) {
+      throw this.#recordedOutcome();
+    }
     await awaitAskSettlement({
       settled,
       closed: this.#options.connection.closed,
@@ -218,6 +352,15 @@ class AskExchange {
     if (failure !== null && !ignoreAbortFailure) throw this.#failed(failure);
   }
 
+  /** The rejection a recorded unsettled Ask replays as. */
+  #recordedOutcome(): Error {
+    this.#outcome = this.#playback?.limit;
+    if (this.#outcome !== undefined) return askLimitError(this.#options.agent, this.#outcome);
+    this.#stalled = this.#playback?.stalled;
+    if (this.#stalled !== undefined) return askStalledError(this.#options.agent, this.#stalled);
+    return this.#failed("recorded Ask never settled");
+  }
+
   async #lastAssistantText(): Promise<string> {
     const response = await this.#options.connection.command({ type: "get_last_assistant_text" });
     const text: unknown = response.data?.text;
@@ -227,36 +370,58 @@ class AskExchange {
     return text;
   }
 
-  async #resolveOutput(text: string): Promise<unknown> {
-    if (!("outputSchema" in this.#options.ask)) return text;
+  async #resolveOutput(): Promise<unknown> {
+    const schema = this.#outputSchema();
+    if (schema === undefined) return await this.#lastAssistantText();
+    if (this.#legacyExtraction) return await this.#resolveRecordedText(schema);
     if (this.#playback !== undefined) {
-      return resolvePlaybackAskOutput(
-        this.#options.agent,
-        this.#options.ask.outputSchema,
-        text,
-        this.#playback.outcome,
-      );
+      return resolvePlaybackReportedResult({
+        agent: this.#options.agent,
+        schema,
+        reported: this.#playback.reported,
+        recordedOutcome: this.#playback.outcome,
+      });
     }
-    return new AskOutputSteering({
+    return new ReportResultSteering({
       agent: this.#options.agent,
-      schema: this.#options.ask.outputSchema,
-      maxSteers: this.#options.ask.maxSteers,
+      schema,
+      maxSteers: this.#maxSteers(),
+      reported: () => this.#call?.reported,
       beginCorrection: () => this.#limit?.enterOutputCorrection() ?? true,
       wrappingUp: () => this.#limit?.tripped ?? false,
       correct: async (message) => this.#correct(message),
       abort: async () => this.#abort(),
+    }).resolve();
+  }
+
+  /** The ADR-0027 path, reachable only for an Ask recorded under its policy. */
+  async #resolveRecordedText(schema: TSchema): Promise<unknown> {
+    const text = await this.#lastAssistantText();
+    if (this.#playback !== undefined) {
+      return resolvePlaybackAskOutput(this.#options.agent, schema, text, this.#playback.outcome);
+    }
+    return new AskOutputSteering({
+      agent: this.#options.agent,
+      schema,
+      maxSteers: this.#maxSteers(),
+      beginCorrection: () => this.#limit?.enterOutputCorrection() ?? true,
+      wrappingUp: () => this.#limit?.tripped ?? false,
+      correct: async (message) => {
+        await this.#correct(message);
+        return await this.#lastAssistantText();
+      },
+      abort: async () => this.#abort(),
     }).resolve(text);
   }
 
   // A follow-up prompt within the same logical Ask: real pi parks a post-settlement
   // steer behind queue_update and never starts a correction turn (ADR-0027 amendment).
-  async #correct(message: string): Promise<string> {
+  async #correct(message: string): Promise<void> {
     try {
       const settled = this.#armSettlement();
       const response = await this.#options.connection.command({ type: "prompt", message });
       if (!response.success) throw this.#failed(response.error ?? "correction prompt was rejected");
       await this.#verify(settled);
-      return await this.#lastAssistantText();
     } finally {
       this.#limit?.leaveOutputCorrection();
     }
@@ -276,14 +441,21 @@ class AskExchange {
 
   #cleanup(): void {
     this.#maxFrameGapMs = this.#gap?.maxGapMs;
-    this.#stalled ??= this.#idle?.result ?? undefined;
+    this.#stalled ??= this.#idle?.result ?? this.#stall?.result ?? undefined;
     this.#limit?.cleanup();
     this.#idle?.cleanup();
+    this.#stall?.cleanup();
     this.#output?.close();
     this.#options.connection.observe(null);
+    if (this.#drainStaleFrames) this.#options.connection.drainStaleTurn();
     if (!this.#began) return;
     try {
-      this.#options.transport.finishAsk(this.#outcome, this.#stalled, this.#invalidOutput);
+      this.#options.transport.finishAsk({
+        ...(this.#outcome === undefined ? {} : { limit: this.#outcome }),
+        ...(this.#stalled === undefined ? {} : { stalled: this.#stalled }),
+        ...(this.#invalidOutput === undefined ? {} : { invalidOutput: this.#invalidOutput }),
+        ...(this.#cause === "recovered" ? { recovered: true as const } : {}),
+      });
     } catch {
       // Recording must not hide the Ask outcome it was observing.
     }

package/src/ask-hash.ts

@@ -1,14 +1,15 @@
 import type { TSchema } from "typebox";
 import { type AskOutputContract, createAskOutputContract } from "./ask-contract-identity.ts";
+import type { AskOutputExtractionPolicy } from "./ask-output.ts";
 import type { AskMarkerContext } from "./transport.ts";
-import type { AskOptions, SpawnOptions, StructuredAskOptions } from "./types.ts";
+import type { AskOptions, ResolvedSpawnOptions, StructuredAskOptions } from "./types.ts";
 
 /** The combined option shape used internally after Definition defaults merge. */
 export type EffectiveAskOptions = AskOptions | StructuredAskOptions<TSchema>;
 
 /** Inputs that identify an Ask in a Cassette. */
 export interface AskHashOptions {
-  readonly spawnOptions: SpawnOptions;
+  readonly spawnOptions: ResolvedSpawnOptions;
   readonly index: number;
   readonly prompt: string;
   /** Soft-limit behavior and structured output contract, unlike timeoutMs, identify replay. */
@@ -43,6 +44,7 @@ export function askHash(options: AskHashOptions): string {
       ...(ask?.maxToolCalls === undefined ? {} : { maxToolCalls: ask.maxToolCalls }),
       ...(ask?.maxDurationMs === undefined ? {} : { maxDurationMs: ask.maxDurationMs }),
       ...(ask?.idleMs === undefined ? {} : { idleMs: ask.idleMs }),
+      ...(ask?.stallMs === undefined ? {} : { stallMs: ask.stallMs }),
       ...(ask?.wrapUpPrompt === undefined ? {} : { wrapUpPrompt: ask.wrapUpPrompt }),
       ...(outputContract === undefined ? {} : outputContract),
     }),
@@ -71,6 +73,7 @@ export function askMarkerContext({
       ...(ask?.maxToolCalls === undefined ? {} : { maxToolCalls: ask.maxToolCalls }),
       ...(ask?.maxDurationMs === undefined ? {} : { maxDurationMs: ask.maxDurationMs }),
       ...(ask?.idleMs === undefined ? {} : { idleMs: ask.idleMs }),
+      ...(ask?.stallMs === undefined ? {} : { stallMs: ask.stallMs }),
       ...(ask?.wrapUpPrompt === undefined ? {} : { wrapUpPrompt: ask.wrapUpPrompt }),
       ...(outputContract === undefined ? {} : outputContract),
     },
@@ -80,7 +83,8 @@ export function askMarkerContext({
 /** Creates structured identity only when the Ask explicitly carries a schema. */
 export function structuredOutputContract(
   ask: EffectiveAskOptions | undefined,
+  policy?: AskOutputExtractionPolicy,
 ): AskOutputContract | undefined {
   if (ask === undefined || !("outputSchema" in ask)) return undefined;
-  return createAskOutputContract(ask.outputSchema, ask.maxSteers);
+  return createAskOutputContract(ask.outputSchema, ask.maxSteers, policy);
 }