@yaag/runtime 0.1.2 → 0.2.0

package/src/ask-limit.ts

@@ -1,7 +1,20 @@
 import type { AskLimitKind, AskLimitOutcome } from "./errors.ts";
+import { REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
 import type { Frame } from "./transport.ts";
 import type { AskOptions } from "./types.ts";
 
+/**
+ * True for a call to yaag's private result tool.
+ *
+ * `maxToolCalls` bounds the Agent's own work. The settling `report_result` call
+ * is yaag's mechanism, and counting it would both shrink every declared budget
+ * and let the settling call trip a wrap-up steer that pi parks for the next Ask
+ * (ADR-0032).
+ */
+function isReportResult(frame: Frame): boolean {
+  return frame.toolName === REPORT_RESULT_TOOL_NAME;
+}
+
 /** The message sent when an Ask uses its allotted soft budget. */
 export const DEFAULT_WRAP_UP_PROMPT = "Please wrap up now and provide your final answer.";
 /** Fixed time allowed to conclude after a duration limit trips. */
@@ -12,6 +25,8 @@ export interface AskLimitOptions {
   readonly command: (frame: Frame) => Promise<boolean>;
   readonly durationGraceMs?: number;
   readonly now?: () => number;
+  /** One sentence appended to the wrap-up, so a structured Ask still reports its result. */
+  readonly wrapUpSuffix?: string;
 }
 
 /**
@@ -24,6 +39,7 @@ export class AskLimit {
   readonly #ask: AskOptions;
   readonly #command: (frame: Frame) => Promise<boolean>;
   readonly #durationGraceMs: number;
+  readonly #wrapUpSuffix: string | undefined;
   readonly #now: () => number;
   readonly #failure: Promise<string>;
   #rejectFailure: (reason: string) => void = () => {};
@@ -43,6 +59,7 @@ export class AskLimit {
     this.#ask = options.ask;
     this.#command = options.command;
     this.#durationGraceMs = options.durationGraceMs ?? ASK_LIMIT_DURATION_GRACE_MS;
+    this.#wrapUpSuffix = options.wrapUpSuffix;
     this.#now = options.now ?? Date.now;
     this.#failure = new Promise<string>((_resolve, reject) => {
       this.#rejectFailure = reject;
@@ -77,16 +94,10 @@ export class AskLimit {
       }
       return;
     }
-    if (
-      frame.type === "tool_execution_start" &&
-      this.#trip === null &&
-      this.#ask.maxToolCalls !== undefined
-    ) {
-      this.#toolCalls += 1;
-      if (this.#toolCalls >= this.#ask.maxToolCalls) this.#tripLimit("toolCalls", this.#toolCalls);
-      return;
-    }
-    if (frame.type === "tool_execution_start") this.#toolCalls += 1;
+    if (frame.type !== "tool_execution_start" || isReportResult(frame)) return;
+    this.#toolCalls += 1;
+    if (this.#trip !== null || this.#ask.maxToolCalls === undefined) return;
+    if (this.#toolCalls >= this.#ask.maxToolCalls) this.#tripLimit("toolCalls", this.#toolCalls);
   }
 
   /**
@@ -146,12 +157,17 @@ export class AskLimit {
     if (this.#completed || this.#trip !== null) return;
     this.#trip = { kind, count };
     this.#turnsAtSteer = this.#turns;
-    void this.#send({ type: "steer", message: this.#ask.wrapUpPrompt ?? DEFAULT_WRAP_UP_PROMPT });
+    void this.#send({ type: "steer", message: this.#wrapUpMessage() });
     if (kind === "durationMs") {
       this.#graceTimer = setTimeout(() => this.#abort(), this.#durationGraceMs);
     }
   }
 
+  #wrapUpMessage(): string {
+    const wrapUp = this.#ask.wrapUpPrompt ?? DEFAULT_WRAP_UP_PROMPT;
+    return this.#wrapUpSuffix === undefined ? wrapUp : `${wrapUp} ${this.#wrapUpSuffix}`;
+  }
+
   #abort(): void {
     if (this.#completed || this.#aborted || this.#trip === null) return;
     void this.#sendAbort();

package/src/ask-output-steering.ts

@@ -1,13 +1,11 @@
 import type { TSchema } from "typebox";
 import {
+  DEFAULT_MAX_STEERS,
   formatAskOutputCorrection,
   invalidAskOutputError,
   validateAskOutput,
 } from "./ask-output.ts";
 
-/** The per-Ask bound when a structured Ask omits `maxSteers`. */
-export const DEFAULT_MAX_STEERS = 3;
-
 export interface AskOutputSteeringOptions {
   readonly agent: string;
   readonly schema: TSchema;

package/src/ask-output.ts

@@ -5,11 +5,24 @@ import { YaagError } from "./errors.ts";
 import type { AskInvalidOutputPlayback } from "./transport.ts";
 import { formatValidationErrors } from "./validation-errors.ts";
 
-/** Versioned extraction behavior. It becomes Cassette identity in issue 04. */
-export const ASK_OUTPUT_EXTRACTION_POLICY = "json-first-block/v1";
+/** Versioned extraction behavior, and part of Ask identity in a Cassette. */
+export const ASK_OUTPUT_EXTRACTION_POLICY = "report-result-tool/v1";
 
-/** The currently implemented extraction policy identifier. */
-export type AskOutputExtractionPolicy = typeof ASK_OUTPUT_EXTRACTION_POLICY;
+/**
+ * The pre-ADR-0032 policy: the first JSON block of the final assistant text.
+ *
+ * No live Ask selects it. It stays reachable so a Cassette recorded under it
+ * replays through the same ADR-0027 code path it was recorded from.
+ */
+export const LEGACY_ASK_OUTPUT_EXTRACTION_POLICY = "json-first-block/v1";
+
+/** The extraction policy identifiers this runtime can execute. */
+export type AskOutputExtractionPolicy =
+  | typeof ASK_OUTPUT_EXTRACTION_POLICY
+  | typeof LEGACY_ASK_OUTPUT_EXTRACTION_POLICY;
+
+/** The per-Ask bound when a structured Ask omits `maxSteers`. */
+export const DEFAULT_MAX_STEERS = 3;
 
 export type AskOutputResult =
   | { readonly ok: true; readonly value: unknown }
@@ -38,6 +51,9 @@ export function formatAskOutputCorrection(errors: readonly string[]): string {
  * A recorded invalid-output outcome rethrows deterministically (ADR-0027); otherwise
  * the text is re-validated so playback and live settlement agree. Throws the same
  * recoverable ASK_INVALID_OUTPUT error as a live Ask on validation failure.
+ *
+ * Its signature is frozen with the policy it serves: this path exists only for
+ * Cassettes recorded under `json-first-block/v1` (ADR-0032).
  */
 export function resolvePlaybackAskOutput(
   agent: string,

package/src/ask-turn.ts

@@ -19,6 +19,7 @@ export class AskTurn {
   #stopReason: string | null = null;
   #errorMessage: string | null = null;
   #settled = false;
+  #terminal = false;
 
   observe(frame: Frame): void {
     if (frame.type === "agent_settled") {
@@ -30,6 +31,7 @@ export class AskTurn {
     if (!end) return;
     this.#stopReason = end.stopReason;
     this.#errorMessage = end.errorMessage;
+    this.#terminal = true;
   }
 
   /** True once `agent_settled` has been seen — settled says nothing about success. */
@@ -37,11 +39,20 @@ export class AskTurn {
     return this.#settled;
   }
 
+  /**
+   * True once an assistant `message_end` was seen — the Agent produced a final
+   * message even if `agent_settled` never arrived. The Stall Watchdog reads it.
+   */
+  get terminal(): boolean {
+    return this.#terminal;
+  }
+
   /** Starts a new correction effort without retaining the preceding terminal state. */
   rearm(): void {
     this.#stopReason = null;
     this.#errorMessage = null;
     this.#settled = false;
+    this.#terminal = false;
   }
 
   /**

package/src/cassette-loader.ts

@@ -122,6 +122,30 @@ function upgrade(artifact: CassetteArtifact): Cassette {
   return { ...artifact, v: CASSETTE_VERSION, run: artifact.run ?? { outcome: "completed" } };
 }
 
+/**
+ * Strict replay demands a settled Run. An `interrupted` artifact stops at the
+ * last Ask boundary, so its final Ask has no recorded settlement (ADR-0031).
+ */
+export function assertReplayable(cassette: Cassette, path: string): void {
+  if (cassette.run.outcome === "interrupted") {
+    throw new Error(
+      `cannot replay interrupted cassette "${path}": the Run died before it settled; use resume instead`,
+    );
+  }
+}
+
+/**
+ * Warns once when a resume source came from a hard death. The Run continues:
+ * resume already handles an incomplete last Ask.
+ */
+export function interruptedResumeWarning(cassette: Cassette, path: string): string | null {
+  if (cassette.run.outcome !== "interrupted") return null;
+  return (
+    `resuming interrupted cassette "${path}": the Run died before it settled, ` +
+    "the recording stops at the last Ask boundary, and re-run tools can repeat their effects"
+  );
+}
+
 function message(error: unknown): string {
   return error instanceof Error ? error.message : "is invalid";
 }

package/src/cassette-replay.ts

@@ -1,5 +1,7 @@
 import type { CassetteAgent } from "./cassette.ts";
 import { FrameQueue } from "./frame-queue.ts";
+import type { ReportedResult } from "./report-result.ts";
+import { isReportResultCommandFrame, ReportResultCall } from "./report-result.ts";
 import type { AgentStats, AskMarker, AskPlayback, Frame } from "./transport.ts";
 
 /**
@@ -17,6 +19,7 @@ export class CassetteReplay {
   #receivedCursor = 0;
   #sent: readonly Frame[] = [];
   #received: readonly Frame[] = [];
+  #promptFloor = 0;
   #ids = new Map<string, string>();
 
   constructor(agent: CassetteAgent) {
@@ -38,8 +41,13 @@ export class CassetteReplay {
     if (frame.type === "get_last_assistant_text") this.#skipCorrectionHistory();
     const expected = this.#sent[this.#sentCursor];
     if (expected && expected.type === frame.type) {
+      const schemaCommand = isReportResultCommandFrame(expected);
       this.#sentCursor += 1;
       this.#rememberId(expected, frame);
+      if (schemaCommand) {
+        this.#releaseOneResponse();
+        return;
+      }
       this.#releaseFor(frame.type);
       this.#consumeControls();
       return;
@@ -64,11 +72,20 @@ export class CassetteReplay {
     this.#receivedCursor = 0;
     this.#sent = ask.sentFrames;
     this.#received = ask.receivedFrames;
+    // A schema-bearing Ask opens with the report_result schema command, so the
+    // Ask's own prompt is the second sent frame, not the first (ADR-0032).
+    const first = ask.sentFrames[0];
+    this.#promptFloor = first !== undefined && isReportResultCommandFrame(first) ? 1 : 0;
     const awaitsAbortSettlement = abortSettlementFollowsFinalText(ask);
+    const settles = ask.receivedFrames.some((frame) => frame.type === "agent_settled");
+    const reported = recordedReportedResult(ask);
     return {
+      ...(settles ? {} : { settles: false as const }),
+      ...(reported === undefined ? {} : { reported }),
       ...(ask.limit === undefined ? {} : { limit: ask.limit }),
       ...(ask.stalled === undefined ? {} : { stalled: ask.stalled }),
       ...(ask.outcome === undefined ? {} : { outcome: ask.outcome }),
+      ...(ask.recovered === true ? { recovered: true as const } : {}),
       ...(awaitsAbortSettlement ? { awaitsAbortSettlement: true as const } : {}),
     };
   }
@@ -83,14 +100,20 @@ export class CassetteReplay {
       const expected = this.#sent[this.#sentCursor];
       if (expected === undefined || !this.#isRecordedControl(expected)) return;
       this.#sentCursor += 1;
+      this.#retireId(expected);
       this.#releaseFor(expected.type);
     }
   }
 
-  /** Any non-first prompt within an Ask is a recorded correction (ADR-0027 amendment). */
+  /**
+   * Any non-first prompt within an Ask is a recorded correction (ADR-0027
+   * amendment). A recorded `get_state` is a Stall Watchdog probe: replay is
+   * never silent, so it never probes, and the recorded exchange is consumed
+   * here instead of blocking the frames that follow it (ADR-0029).
+   */
   #isRecordedControl(frame: Frame): boolean {
-    if (frame.type === "steer" || frame.type === "abort") return true;
-    return frame.type === "prompt" && this.#sentCursor > 0;
+    if (frame.type === "steer" || frame.type === "abort" || frame.type === "get_state") return true;
+    return frame.type === "prompt" && this.#sentCursor > this.#promptFloor;
   }
 
   #skipCorrectionHistory(): void {
@@ -112,6 +135,25 @@ export class CassetteReplay {
     );
   }
 
+  /**
+   * Releases exactly the schema command's own response.
+   *
+   * The schema command and the Ask's own prompt are both `prompt` commands, so
+   * the ordinary release cannot tell their responses apart and would hand out
+   * the Ask's response before the Ask has sent it (ADR-0032).
+   */
+  #releaseOneResponse(): void {
+    for (; this.#receivedCursor < this.#received.length; this.#receivedCursor += 1) {
+      const frame = this.#received[this.#receivedCursor];
+      if (frame === undefined) return;
+      this.#queue.push(this.#remapResponse(frame));
+      if (frame.type === "response") {
+        this.#receivedCursor += 1;
+        return;
+      }
+    }
+  }
+
   #releaseFor(command: string, skippedText = false): void {
     for (; this.#receivedCursor < this.#received.length; this.#receivedCursor += 1) {
       const frame = this.#received[this.#receivedCursor];
@@ -133,6 +175,16 @@ export class CassetteReplay {
     return this.#sent.slice(this.#sentCursor).some((frame) => frame.type === command);
   }
 
+  /**
+   * Renames a consumed probe's id, so its recorded response cannot answer an
+   * unrelated live command that reuses that id. Replay sends no probe and
+   * numbers its own commands from zero, so those ids do collide.
+   */
+  #retireId(expected: Frame): void {
+    if (expected.type !== "get_state" || typeof expected.id !== "string") return;
+    this.#ids.set(expected.id, `cassette-${expected.id}`);
+  }
+
   #rememberId(expected: Frame, actual: Frame): void {
     if (typeof expected.id === "string" && typeof actual.id === "string") {
       this.#ids.set(expected.id, actual.id);
@@ -151,13 +203,30 @@ export class CassetteReplay {
   }
 }
 
+/** The result the recorded Ask reported, folded from its own frames (ADR-0032). */
+function recordedReportedResult(ask: CassetteAgent["asks"][number]): ReportedResult | undefined {
+  const call = ReportResultCall.armed();
+  for (const frame of ask.receivedFrames) call.observe(frame);
+  return call.reported;
+}
+
+/**
+ * True when the recorded Ask ends with an abort that produced its own
+ * settlement, after the frame that asked the Agent for its result.
+ *
+ * That frame is the final text query of an ADR-0027 Ask, or the last prompt of
+ * a report_result Ask that recorded an invalid-output outcome. A limit abort
+ * also follows a prompt, and its settlement belongs to the Ask's own wait.
+ */
 function abortSettlementFollowsFinalText(agent: CassetteAgent["asks"][number]): boolean {
-  const finalText = agent.sentFrames.findLastIndex(
-    (frame) => frame.type === "get_last_assistant_text",
+  const structuredAbort = agent.outcome !== undefined;
+  const finalResultQuery = agent.sentFrames.findLastIndex(
+    (frame) =>
+      frame.type === "get_last_assistant_text" || (structuredAbort && frame.type === "prompt"),
   );
   if (
-    finalText === -1 ||
-    !agent.sentFrames.slice(finalText + 1).some((frame) => frame.type === "abort")
+    finalResultQuery === -1 ||
+    !agent.sentFrames.slice(finalResultQuery + 1).some((frame) => frame.type === "abort")
   ) {
     return false;
   }

package/src/cassette-schema.ts

@@ -56,6 +56,7 @@ const ContextAskSchema = Type.Object({
   maxToolCalls: Type.Optional(Type.Number()),
   maxDurationMs: Type.Optional(Type.Number()),
   idleMs: Type.Optional(Type.Number()),
+  stallMs: Type.Optional(Type.Union([Type.Number(), Type.Literal(false)])),
   wrapUpPrompt: Type.Optional(Type.String()),
   ...contractFields,
 });
@@ -86,7 +87,18 @@ const CassetteAskSchema = Type.Object({
     }),
   ),
   stalled: Type.Optional(
-    Type.Object({ idleMs: Type.Number({ exclusiveMinimum: 0 }), destructive: Type.Boolean() }),
+    Type.Object({
+      idleMs: Type.Number({ exclusiveMinimum: 0 }),
+      destructive: Type.Boolean(),
+      state: Type.Optional(
+        Type.Object({
+          working: Type.Boolean(),
+          streaming: Type.Boolean(),
+          compacting: Type.Boolean(),
+          pendingMessages: Type.Number(),
+        }),
+      ),
+    }),
   ),
   outcome: Type.Optional(
     Type.Object({
@@ -94,6 +106,7 @@ const CassetteAskSchema = Type.Object({
       steeringEfforts: Type.Integer({ minimum: 0 }),
     }),
   ),
+  recovered: Type.Optional(Type.Literal(true)),
 });
 
 const TokenBreakdownSchema = Type.Object({
@@ -121,7 +134,9 @@ const CassetteAgentSchema = Type.Object({
 
 const CassetteRunSchema = Type.Object({
   outcome: Type.Union(
-    (["completed", "failed", "stopped", "paused"] as const).map((outcome) => Type.Literal(outcome)),
+    (["completed", "failed", "stopped", "paused", "interrupted"] as const).map((outcome) =>
+      Type.Literal(outcome),
+    ),
   ),
   programFile: Type.Optional(Type.String()),
   args: Type.Optional(Type.Unknown()),

package/src/cassette.ts

@@ -3,6 +3,7 @@ import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
 import type { RunOutcome } from "./events.ts";
 import type {
   AgentStats,
+  AskCompletion,
   AskInvalidOutputPlayback,
   AskMarker,
   AskMarkerContext,
@@ -104,6 +105,8 @@ export interface CassetteAsk {
   readonly stalled?: AskStalledOutcome;
   /** Present only when the Ask surfaced ASK_INVALID_OUTPUT. */
   readonly outcome?: AskInvalidOutputPlayback;
+  /** Present only when the Stall Watchdog recovered the settlement (ADR-0029). */
+  readonly recovered?: true;
 }
 
 /** Sink consumed by recordingTransport without exposing its mutable state. */
@@ -126,11 +129,7 @@ export interface CassetteRecorder {
   sent(frame: Frame): void;
   received(frame: Frame): void;
   beginAsk(marker: AskMarker): void;
-  finishAsk(
-    outcome?: AskLimitOutcome,
-    stalled?: AskStalledOutcome,
-    invalidOutput?: AskInvalidOutputPlayback,
-  ): void;
+  finishAsk(completion: AskCompletion): void;
   closed(stats: AgentStats): void;
 }
 
@@ -147,6 +146,7 @@ interface MutableAsk {
   limit?: AskLimitOutcome;
   stalled?: AskStalledOutcome;
   outcome?: AskInvalidOutputPlayback;
+  recovered?: true;
 }
 
 interface MutableAgent {
@@ -198,11 +198,12 @@ export class CassetteCollector implements CassetteSink {
         agent.asks.push(ask);
         agent.active = ask;
       },
-      finishAsk: (outcome, stalled, invalidOutput): void => {
+      finishAsk: (completion): void => {
         if (!agent?.active) return;
-        if (outcome !== undefined) agent.active.limit = outcome;
-        if (stalled !== undefined) agent.active.stalled = stalled;
-        if (invalidOutput !== undefined) agent.active.outcome = invalidOutput;
+        if (completion.limit !== undefined) agent.active.limit = completion.limit;
+        if (completion.stalled !== undefined) agent.active.stalled = completion.stalled;
+        if (completion.invalidOutput !== undefined) agent.active.outcome = completion.invalidOutput;
+        if (completion.recovered === true) agent.active.recovered = true;
       },
       closed: (stats): void => {
         if (agent) agent.stats = stats;

package/src/checkpoint-flush.ts

@@ -0,0 +1,101 @@
+import type { CassetteRecorder, CassetteSink } from "./cassette.ts";
+import { publishCassette } from "./cassette-publish.ts";
+import {
+  ensureCheckpointDirectory,
+  type RunIdentity,
+  writeRecordingDiagnostic,
+} from "./run-checkpoint.ts";
+
+/**
+ * Publishes the Run's in-progress Checkpoint (ADR-0031).
+ *
+ * Each flush rewrites the full collected Cassette to the Run's destination with
+ * the same atomic write a settled Checkpoint uses, and states the outcome
+ * `interrupted`. Flushes never reject: a failed one writes a diagnostic, and the
+ * next Ask boundary tries again.
+ */
+export interface CheckpointFlusher {
+  /** Requests a publication; returns at once. Concurrent requests coalesce. */
+  flush(): void;
+  /** Resolves when no publication is in flight, and stops accepting new ones. */
+  quiesce(): Promise<void>;
+}
+
+export interface CheckpointFlushOptions {
+  /** Read at each flush; its current content becomes the artifact. */
+  readonly collector: CassetteSink;
+  /** Explicit `--record` destination, or undefined when the Run only checkpoints. */
+  readonly record: string | undefined;
+  /** Where the in-progress artifact lives; fixed at Run start. */
+  readonly destination: string;
+  readonly identity: RunIdentity;
+}
+
+export function createCheckpointFlusher(options: CheckpointFlushOptions): CheckpointFlusher {
+  let active: Promise<void> | null = null;
+  let requested = false;
+  let stopped = false;
+
+  const publish = async (): Promise<void> => {
+    try {
+      await ensureCheckpointDirectory(options.record, options.destination);
+      await publishCassette(
+        options.destination,
+        options.collector.cassette({ outcome: "interrupted", ...options.identity }),
+      );
+    } catch (error) {
+      // Losing this boundary costs one Ask of restorability; failing the Run
+      // would cost the whole Run (ADR-0031).
+      writeRecordingDiagnostic(error);
+    }
+  };
+
+  // Only one publication runs at a time, so two Asks settling together cannot
+  // interleave two writes onto one destination. A request that arrives during a
+  // write is folded into exactly one follow-up write.
+  const pump = async (): Promise<void> => {
+    while (requested && !stopped) {
+      requested = false;
+      await publish();
+    }
+    active = null;
+  };
+
+  return {
+    flush: (): void => {
+      if (stopped) return;
+      requested = true;
+      active ??= pump();
+    },
+    quiesce: async (): Promise<void> => {
+      stopped = true;
+      while (active !== null) await active;
+    },
+  };
+}
+
+/**
+ * Wraps a sink so every Ask boundary publishes the Checkpoint: an Agent opened,
+ * an Ask begun, an Ask finished, an Agent closed (ADR-0031).
+ */
+export function flushingSink(sink: CassetteSink, flusher: CheckpointFlusher): CassetteSink {
+  return {
+    cassette: (run) => sink.cassette(run),
+    reserve: (options): CassetteRecorder => {
+      const recorder = sink.reserve(options);
+      const boundary =
+        <Args extends unknown[]>(record: (...args: Args) => void) =>
+        (...args: Args): void => {
+          record(...args);
+          flusher.flush();
+        };
+      return {
+        ...recorder,
+        opened: boundary(recorder.opened),
+        beginAsk: boundary(recorder.beginAsk),
+        finishAsk: boundary(recorder.finishAsk),
+        closed: boundary(recorder.closed),
+      };
+    },
+  };
+}

package/src/connection.ts

@@ -24,6 +24,7 @@ export class Connection {
   readonly #pending = new Map<string, (response: CommandResponse) => void>();
   readonly #closed: Promise<void>;
   #observer: ((frame: Frame) => void) | null = null;
+  #draining = false;
   #dead = false;
   #nextId = 0;
 
@@ -48,6 +49,21 @@ export class Connection {
     this.#observer = listener;
   }
 
+  /**
+   * Drops every frame up to and including the abandoned turn's `agent_settled`.
+   *
+   * A stall leaves the Agent still working on the turn yaag gave up on. pi
+   * queues the next prompt behind that turn, so its late frames — above all
+   * its `agent_settled` — arrive after the next Ask started, and would settle
+   * that Ask with the abandoned turn's text. Draining to the settlement frame
+   * is the only boundary pi gives. A turn that never settles keeps the drain
+   * open, and the next Ask's own Stall Watchdog ends that wait with
+   * `ASK_STALLED` instead of a wrong answer.
+   */
+  drainStaleTurn(): void {
+    this.#draining = true;
+  }
+
   /**
    * Sends one command and resolves with its id-correlated response.
    * Rejects with AGENT_DIED if the Agent dies first.
@@ -94,6 +110,10 @@ export class Connection {
       this.#answerDialog(frame);
       return;
     }
+    if (this.#draining) {
+      if (frame.type === "agent_settled") this.#draining = false;
+      return;
+    }
     this.#observer?.(frame);
   }
 

package/src/define-agent.ts

@@ -1,4 +1,5 @@
-import type { AskOptions, ThinkingLevel } from "./types.ts";
+import type { ModelSpec, ThinkingSpec } from "./model-resolution.ts";
+import type { AskOptions } from "./types.ts";
 
 export type { ThinkingLevel } from "./types.ts";
 
@@ -10,10 +11,14 @@ export interface AgentConfig {
   readonly prompt?: string;
   /** Replace pi's system prompt with `prompt` instead of appending to it. */
   readonly overrideSystemPrompt?: boolean;
-  /** Model id handed to `pi --model`. Unset = pi's default. */
-  readonly model?: string;
-  /** Thinking budget for the Agent's turns. */
-  readonly thinking?: ThinkingLevel;
+  /**
+   * Model id handed to `pi --model`. Unset = pi's default. An array is an ordered
+   * fallback list, a function picks the next candidate from the failures so far,
+   * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`).
+   */
+  readonly model?: ModelSpec;
+  /** Thinking budget for the Agent's turns, as a level or a resolver. */
+  readonly thinking?: ThinkingSpec;
   /** Allow-list of tool names. Unset = pi's default tool set. */
   readonly tools?: readonly string[];
   /** Deny-list of tool names, applied after `tools`. */
@@ -58,6 +63,7 @@ export function defineAgent(config: AgentConfig): AgentDefinition {
     const value = config[field];
     if (value !== undefined) copy[field] = Object.freeze(value.slice());
   }
+  if (Array.isArray(config.model)) copy.model = Object.freeze([...config.model]);
   if (config.askDefaults !== undefined) {
     copy.askDefaults = Object.freeze({ ...config.askDefaults });
   }