@yaag/cli 0.1.2 → 0.2.0

package/assets/types/runtime/agent.d.ts

@@ -1,7 +1,7 @@
 import type { Static, TSchema } from "typebox";
 import type { EventSink } from "./events.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;
     readonly cwd: string;
@@ -9,7 +9,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. */
@@ -18,6 +18,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. */
 export declare class Agent implements Handle {

package/assets/types/runtime/ask-contract-identity.d.ts

@@ -1,4 +1,5 @@
 import type { TSchema } from "typebox";
+import { type AskOutputExtractionPolicy } from "./ask-output.ts";
 /** A JSON value suitable for deterministic Cassette identity. */
 export type CanonicalJson = null | boolean | number | string | CanonicalJson[] | CanonicalJsonObject;
 /** A JSON object with recursively sorted keys. */
@@ -17,8 +18,16 @@ export interface AskOutputContract {
  * Throws when the value cannot be represented in a Cassette JSON artifact.
  */
 export declare function canonicalizeSchema(value: unknown): CanonicalJsonObject;
-/** Builds the recorded and hashed behavioral contract for one structured Ask. */
-export declare 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 declare function createAskOutputContract(schema: TSchema, maxSteers?: number, policy?: AskOutputExtractionPolicy): AskOutputContract;
 /** Validates an externally supplied canonical schema representation. */
 export declare function validateCanonicalOutputSchema(value: unknown): CanonicalJsonObject;
 /** Validates a policy identifier while allowing future versions to load and diverge at replay. */

package/assets/types/runtime/ask-exchange-events.d.ts

@@ -1,5 +1,14 @@
 import type { AgentActivity, AskOutputChannel, EventSink } from "./events.ts";
 import type { NodeSnapshot } from "./node-tracker.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 declare class AskEvents {
     #private;
@@ -9,5 +18,6 @@ export declare class AskEvents {
     output: (channel: AskOutputChannel, text: string) => void;
     /** Composes the Nested Node path from this Ask's identity, then reports it. */
     node: (snapshot: NodeSnapshot) => void;
-    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;
 }

package/assets/types/runtime/ask-exchange-options.d.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 {
     observe(frame: Frame): void;
@@ -15,8 +16,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. */
@@ -27,4 +30,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/assets/types/runtime/ask-hash.d.ts

@@ -1,12 +1,13 @@
 import type { TSchema } from "typebox";
 import { type AskOutputContract } 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. */
@@ -29,4 +30,4 @@ export declare function askHash(options: AskHashOptions): string;
  */
 export declare function askMarkerContext({ spawnOptions, prompt, ask, outputContract, }: AskHashOptions): AskMarkerContext;
 /** Creates structured identity only when the Ask explicitly carries a schema. */
-export declare function structuredOutputContract(ask: EffectiveAskOptions | undefined): AskOutputContract | undefined;
+export declare function structuredOutputContract(ask: EffectiveAskOptions | undefined, policy?: AskOutputExtractionPolicy): AskOutputContract | undefined;

package/assets/types/runtime/ask-limit.d.ts

@@ -10,6 +10,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;
 }
 /**
  * Per-Ask soft-limit controller.

package/assets/types/runtime/ask-output-steering.d.ts

@@ -1,6 +1,4 @@
 import type { TSchema } from "typebox";
-/** The per-Ask bound when a structured Ask omits `maxSteers`. */
-export declare const DEFAULT_MAX_STEERS = 3;
 export interface AskOutputSteeringOptions {
     readonly agent: string;
     readonly schema: TSchema;

package/assets/types/runtime/ask-output.d.ts

@@ -2,10 +2,19 @@ import type { TSchema } from "typebox";
 import type { AskInvalidOutputOutcome } from "./errors.ts";
 import { YaagError } from "./errors.ts";
 import type { AskInvalidOutputPlayback } from "./transport.ts";
-/** Versioned extraction behavior. It becomes Cassette identity in issue 04. */
-export declare const ASK_OUTPUT_EXTRACTION_POLICY = "json-first-block/v1";
-/** The currently implemented extraction policy identifier. */
-export type AskOutputExtractionPolicy = typeof ASK_OUTPUT_EXTRACTION_POLICY;
+/** Versioned extraction behavior, and part of Ask identity in a Cassette. */
+export declare const ASK_OUTPUT_EXTRACTION_POLICY = "report-result-tool/v1";
+/**
+ * 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 declare 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 declare const DEFAULT_MAX_STEERS = 3;
 export type AskOutputResult = {
     readonly ok: true;
     readonly value: unknown;
@@ -23,6 +32,9 @@ export declare function formatAskOutputCorrection(errors: readonly string[]): st
  * 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 declare function resolvePlaybackAskOutput(agent: string, schema: TSchema, text: string, recordedOutcome: AskInvalidOutputPlayback | undefined): unknown;
 /** Creates the recoverable error for final structured-output validation failure. */

package/assets/types/runtime/ask-turn.d.ts

@@ -14,6 +14,11 @@ export declare class AskTurn {
     observe(frame: Frame): void;
     /** True once `agent_settled` has been seen — settled says nothing about success. */
     get settled(): boolean;
+    /**
+     * 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;
     /** Starts a new correction effort without retaining the preceding terminal state. */
     rearm(): void;
     /**

package/assets/types/runtime/cassette-loader.d.ts

@@ -9,3 +9,13 @@ import { type Cassette } from "./cassette.ts";
  * Unknown fields are retained, never dropped (forward tolerance).
  */
 export declare function loadCassette(path: string): Promise<Cassette>;
+/**
+ * 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 declare function assertReplayable(cassette: Cassette, path: string): void;
+/**
+ * Warns once when a resume source came from a hard death. The Run continues:
+ * resume already handles an incomplete last Ask.
+ */
+export declare function interruptedResumeWarning(cassette: Cassette, path: string): string | null;

package/assets/types/runtime/cassette-schema.d.ts

@@ -11,7 +11,7 @@ import type { Frame } from "./transport.ts";
 export declare const CassetteSchema: Type.TObject<{
     v: Type.TUnion<[Type.TLiteral<1>, Type.TLiteral<2>]>;
     run: Type.TOptional<Type.TObject<{
-        outcome: Type.TUnion<Type.TLiteral<"completed" | "failed" | "paused" | "stopped">[]>;
+        outcome: Type.TUnion<Type.TLiteral<"completed" | "failed" | "interrupted" | "paused" | "stopped">[]>;
         programFile: Type.TOptional<Type.TString>;
         args: Type.TOptional<Type.TUnknown>;
         programHash: Type.TOptional<Type.TString>;
@@ -71,6 +71,7 @@ export declare const CassetteSchema: Type.TObject<{
                     maxToolCalls: Type.TOptional<Type.TNumber>;
                     maxDurationMs: Type.TOptional<Type.TNumber>;
                     idleMs: Type.TOptional<Type.TNumber>;
+                    stallMs: Type.TOptional<Type.TUnion<[Type.TNumber, Type.TLiteral<false>]>>;
                     wrapUpPrompt: Type.TOptional<Type.TString>;
                 }>;
             }>>;
@@ -83,11 +84,18 @@ export declare const CassetteSchema: Type.TObject<{
             stalled: Type.TOptional<Type.TObject<{
                 idleMs: Type.TNumber;
                 destructive: Type.TBoolean;
+                state: Type.TOptional<Type.TObject<{
+                    working: Type.TBoolean;
+                    streaming: Type.TBoolean;
+                    compacting: Type.TBoolean;
+                    pendingMessages: Type.TNumber;
+                }>>;
             }>>;
             outcome: Type.TOptional<Type.TObject<{
                 kind: Type.TLiteral<"invalid_output">;
                 steeringEfforts: Type.TInteger;
             }>>;
+            recovered: Type.TOptional<Type.TLiteral<true>>;
         }>>;
         stats: Type.TObject<{
             tokens: Type.TUnion<[Type.TNull, Type.TObject<{

package/assets/types/runtime/cassette.d.ts

@@ -1,7 +1,7 @@
 import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
 import type { RunOutcome } from "./events.ts";
-import type { AgentStats, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, Frame, OpenOptions, WorktreeResolution } from "./transport.ts";
+import type { AgentStats, AskCompletion, AskInvalidOutputPlayback, AskMarker, AskMarkerContext, Frame, OpenOptions, WorktreeResolution } from "./transport.ts";
 import type { ThinkingLevel } from "./types.ts";
 /** The Cassette format this runtime writes; the loader also reads version 1. */
 export declare const CASSETTE_VERSION: 2;
@@ -88,6 +88,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. */
 export interface CassetteSink {
@@ -107,7 +109,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;
 }
 /** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */

package/assets/types/runtime/checkpoint-flush.d.ts

@@ -0,0 +1,31 @@
+import type { CassetteSink } from "./cassette.ts";
+import { type RunIdentity } 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 declare function createCheckpointFlusher(options: CheckpointFlushOptions): CheckpointFlusher;
+/**
+ * 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 declare function flushingSink(sink: CassetteSink, flusher: CheckpointFlusher): CassetteSink;

package/assets/types/runtime/connection.d.ts

@@ -21,6 +21,18 @@ export declare class Connection {
     get closed(): Promise<void>;
     /** Routes non-response frames to a listener, replacing any previous one. */
     observe(listener: ((frame: Frame) => void) | null): void;
+    /**
+     * 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;
     /**
      * Sends one command and resolves with its id-correlated response.
      * Rejects with AGENT_DIED if the Agent dies first.

package/assets/types/runtime/define-agent.d.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";
 /** What `defineAgent` is given: the policy of one Agent, never its topology. */
 export interface AgentConfig {
@@ -8,10 +9,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`. */

package/assets/types/runtime/errors.d.ts

@@ -5,12 +5,16 @@ export interface AskLimitOutcome {
     readonly kind: AskLimitKind;
     readonly count: number;
 }
+import type { AgentProgress } from "./pi-state.ts";
+export type { AgentProgress } from "./pi-state.ts";
 /** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
 export interface AskStalledOutcome {
     /** The configured silence threshold that tripped. */
     readonly idleMs: number;
-    /** True when abort failed to settle the Agent and yaag killed the process. */
+    /** True when escalation failed to settle the Agent and yaag killed the process. */
     readonly destructive: boolean;
+    /** State the Stall Watchdog probe observed; absent when the probe stayed silent. */
+    readonly state?: AgentProgress;
 }
 /** Recoverable result when all structured-output correction efforts are exhausted. */
 export interface AskInvalidOutputOutcome {
@@ -34,6 +38,8 @@ export declare class YaagError extends Error {
     readonly idleMs?: number;
     /** True when an `ASK_STALLED` escalation had to kill the Agent. */
     readonly destructive?: boolean;
+    /** State observed by the Stall Watchdog probe, present only for `ASK_STALLED`. */
+    readonly state?: AgentProgress;
     /** Number of corrective output steers sent, present only for `ASK_INVALID_OUTPUT`. */
     readonly steeringEfforts?: number;
     /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */

package/assets/types/runtime/events.d.ts

@@ -6,9 +6,15 @@
  * activity, output, and usage observations. v0 renders them as stderr lines; the
  * dedicated fd arrives with the extension.
  */
+import type { SettlementCause } from "./stall-watchdog.ts";
 import type { TokenBreakdown, WorktreeResolution } from "./transport.ts";
-/** A settled Run's terminal outcome (ADR-0022). `paused` arrives with the pause slice. */
-export type RunOutcome = "completed" | "failed" | "stopped" | "paused";
+export type { SettlementCause } from "./stall-watchdog.ts";
+/**
+ * A Run's outcome (ADR-0022). `paused` arrives with the pause slice.
+ * `interrupted` is not terminal: only an in-flight Checkpoint carries it, and a
+ * settled Run never writes it (ADR-0031).
+ */
+export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interrupted";
 /** The current, Ask-scoped observer projection derived from Agent frames. */
 export type AgentActivity = {
     readonly type: "thinking";
@@ -37,6 +43,12 @@ export interface NodeUsage {
 export type LifecycleEventBody = {
     readonly type: "run_start";
     readonly program: string;
+    /**
+     * Path of the in-progress Checkpoint this Run publishes at each Ask
+     * boundary (ADR-0031). A hard death leaves this file loadable with the
+     * outcome `interrupted`, so an observer can name the resume source.
+     */
+    readonly artifact?: string;
 } | {
     readonly type: "agent_spawn";
     readonly agent: string;
@@ -95,6 +107,11 @@ export type LifecycleEventBody = {
     readonly ok: boolean;
     /** Largest inter-frame silence during this Ask; absent during Cassette playback. */
     readonly maxFrameGapMs?: number;
+    /**
+     * How the Ask settled. Absent means `normal`. `recovered` means the Stall
+     * Watchdog settled it from observed state, so its usage is an undercount.
+     */
+    readonly cause?: SettlementCause;
 } | {
     readonly type: "agent_usage";
     readonly agent: string;
@@ -124,6 +141,11 @@ export type LifecycleEventBody = {
     readonly incomplete: boolean;
     /** Largest inter-frame silence across every Ask; 0 when nothing was measured. */
     readonly worstFrameGapMs: number;
+    /**
+     * The Run failed, `--record` asked for a Checkpoint, and publication also
+     * failed. Carries the publication error text. Absent on every other path.
+     */
+    readonly checkpointLost?: string;
 };
 /**
  * A Lifecycle Event as observers see it: the body plus `at` — epoch-ms wall

package/assets/types/runtime/fake-transport.d.ts

@@ -32,10 +32,16 @@ export interface FakePromptScript {
 export interface FakeTransportOptions extends FakePromptScript {
     /** One script per Ask's initial prompt, used in order; preserves the single-script shorthand above. */
     readonly scripts?: readonly FakePromptScript[];
+    /** Payload of a `get_state` probe; omission answers with an idle, non-streaming Agent. */
+    readonly state?: Record<string, unknown>;
+    /** Makes the fake ignore every `get_state` probe, as a wedged Agent does. */
+    readonly stateSilent?: boolean;
     /** Makes a steer RPC response fail without embedding a limit decision in playback. */
     readonly steerError?: string;
     /** Makes an abort RPC response fail without embedding a limit decision in playback. */
     readonly abortError?: string;
+    /** Makes the private report_result schema command fail. */
+    readonly schemaCommandError?: string;
     readonly stats?: AgentStats;
     /** pi can answer a command after `agent_settled` — it is last among events only. */
     readonly promptResponse?: "immediate" | "after-settle";
@@ -67,9 +73,13 @@ export declare class FakeTransport implements AgentTransport {
     /** Number of times this fake actually began close work. */
     get closeCalls(): number;
     close(): Promise<AgentStats>;
+    /** Pushes one unsolicited frame, as a late or abandoned turn would emit. */
+    emit(frame: Frame): void;
     /** Simulates the process dying: the frame stream just ends. */
     die(): void;
 }
+/** The frames one accepted `report_result` call produces, for scripted Asks. */
+export declare function reportResultFrames(value: unknown, toolCallId?: string): readonly Frame[];
 /**
  * Loads and parses a named JSONL frame fixture from the runtime fixtures directory.
  *

package/assets/types/runtime/frame-queue.d.ts

@@ -9,6 +9,8 @@ import type { Frame } from "./transport.ts";
 export declare class FrameQueue {
     #private;
     push(frame: Frame): void;
+    /** Drops every buffered frame the consumer has not taken yet. */
+    discardPending(): void;
     /** Ends the stream; the consumer's iteration finishes once drained. */
     end(): void;
     frames(): AsyncGenerator<Frame>;

package/assets/types/runtime/index.d.ts

@@ -1,6 +1,6 @@
 export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette.ts";
 export { CASSETTE_VERSION } from "./cassette.ts";
-export { loadCassette } from "./cassette-loader.ts";
+export { assertReplayable, loadCassette } from "./cassette-loader.ts";
 export type { AgentConfig, AgentDefinition } from "./define-agent.ts";
 export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./define-agent.ts";
 export type { OrchestrationProgram, ProgramDefinition } from "./define-run.ts";
@@ -8,6 +8,7 @@ export { defineRun, isOrchestrationProgram, programDefinition } from "./define-r
 export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, YaagErrorCode, } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
 export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";
+export type { ModelError, ModelErrorReason, ModelResolver, ModelSelection, ModelSpec, ThinkingResolver, ThinkingSpec, } from "./model-resolution.ts";
 export type { DecodedNode, NodeDecoder } from "./node-decoder.ts";
 export { DEFAULT_NODE_DECODERS } from "./node-decoders.ts";
 export type { NodePath } from "./node-path.ts";
@@ -28,6 +29,6 @@ export type { DiscoveredSkill, SkillProbeFactory } from "./skill-probe.ts";
 export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary.ts";
 export { applyEvent, initialSummary } from "./summary.ts";
 export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, Frame, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport.ts";
-export type { AskOptions, Handle, SpawnOptions, SpawnOverrides, StructuredAskOptions, ThinkingLevel, } from "./types.ts";
+export type { AskOptions, Handle, ResolvedSpawnOptions, SpawnOptions, SpawnOverrides, StructuredAskOptions, ThinkingLevel, } from "./types.ts";
 export { AGENT_NODE_TABLE_MAX, ASK_OUTPUT_FLUSH_INTERVAL_MS, ASK_OUTPUT_MAX_BYTES, ASK_OUTPUT_TRUNCATION_MARKER, NODE_GIST_MAX_CHARS, PROMPT_GIST_MAX_CHARS, TOOL_ARGS_GIST_MAX_CHARS, } from "./wire-constants.ts";
 export { worktreeTransport } from "./worktree-transport.ts";

package/assets/types/runtime/model-resolution.d.ts

@@ -0,0 +1,45 @@
+import { type ThinkingLevel } from "./thinking-level.ts";
+/** Why one model candidate was rejected by pi. */
+export type ModelErrorReason = "not_found" | "auth" | "rate_limited";
+/** One failed Model Resolution attempt, handed back to the caller's resolver. */
+export interface ModelError {
+    readonly reason: ModelErrorReason;
+    /** The model pattern that failed, after inline-suffix stripping. */
+    readonly failedModel: string;
+    /** 0-based index of the attempt that produced this error. */
+    readonly attempt: number;
+}
+/** Picks the next model candidate, or `undefined` to give up. */
+export type ModelResolver = (errors: readonly ModelError[]) => string | undefined;
+/** Every accepted `model` form: one pattern, an ordered list, or a resolver. */
+export type ModelSpec = string | readonly string[] | ModelResolver;
+/** Picks the thinking level for a settled model, or `undefined` for pi's default. */
+export type ThinkingResolver = (selectedModel: string, errors: readonly ModelError[]) => ThinkingLevel | undefined;
+/** Every accepted `thinking` form: one level or a resolver. */
+export type ThinkingSpec = ThinkingLevel | ThinkingResolver;
+/** One attempt's settled selection; `model: undefined` inherits pi's default model. */
+export interface ModelSelection {
+    readonly model: string | undefined;
+    readonly thinking: ThinkingLevel | undefined;
+}
+/** The canonical shape the spawn loop consumes, whatever form the caller wrote. */
+export interface ModelResolution {
+    /** The next selection given the errors so far, or `undefined` when candidates run out. */
+    resolve(errors: readonly ModelError[]): ModelSelection | undefined;
+}
+/**
+ * Turns any accepted `model`/`thinking` form into one canonical resolver pair.
+ *
+ * Within one attempt the order is: model resolver → inline-suffix parse →
+ * thinking resolver, and an inline suffix wins over the `thinking` spec, which
+ * is then not consulted at all. An absent `model` inherits pi's default for
+ * attempt 0 only; a thinking *resolver* is then not called, because no model has
+ * settled, while a thinking level still applies.
+ * Array specs are copied, so later caller mutation cannot change resolution.
+ * Throws a `TypeError` when a caller resolver returns something other than a
+ * non-empty model string or a valid thinking level.
+ */
+export declare function normalizeModelResolution(spec: {
+    readonly model?: ModelSpec;
+    readonly thinking?: ThinkingSpec;
+}): ModelResolution;

package/assets/types/runtime/model-suffix.d.ts

@@ -0,0 +1,16 @@
+import { type ThinkingLevel } from "./thinking-level.ts";
+/** A model pattern split into its model part and its optional inline thinking suffix. */
+export interface ModelPattern {
+    readonly model: string;
+    readonly thinking: ThinkingLevel | undefined;
+}
+/**
+ * Splits a resolved model pattern on its inline thinking suffix.
+ *
+ * The split happens on the *last* `:` only when the tail is exactly one of pi's
+ * thinking levels and the head is non-empty, so colon-bearing model ids such as
+ * `llama3:8b` and suffix-only strings such as `:medium` survive untouched. The
+ * parser is total: it never throws, and an unusable pattern simply fails later
+ * as an ordinary model lookup failure.
+ */
+export declare function parseModelSuffix(pattern: string): ModelPattern;

package/assets/types/runtime/pi-state.d.ts

@@ -1,4 +1,13 @@
 import type { AgentStats, Frame, OpenOptions } from "./transport.ts";
+/** What the Agent reported about its own work, read from a `get_state` probe. */
+export interface AgentProgress {
+    /** True while pi streams a completion, compacts its context, or holds a queued prompt. */
+    readonly working: boolean;
+    readonly streaming: boolean;
+    readonly compacting: boolean;
+    /** Prompts pi has queued but not started. */
+    readonly pendingMessages: number;
+}
 /** The command line for one Agent. */
 export declare function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[];
 /**
@@ -6,6 +15,13 @@ export declare function piCommand(options: OpenOptions, toolProbeExtensionPath?:
  * to, not the pattern that was requested. Null when the payload has no model.
  */
 export declare function readModel(response: Frame): string | null;
+/**
+ * Reads what a `get_state` payload says about the Agent's own work.
+ *
+ * Null when the payload does not carry pi's streaming flags, which the Stall
+ * Watchdog treats as work in progress rather than as a settlement.
+ */
+export declare function readAgentProgress(data: unknown): AgentProgress | null;
 /** Returns pi's persisted session path from a startup `get_state` response, when valid. */
 export declare function readSessionFile(response: Frame): string | null;
 /**

package/assets/types/runtime/report-result-extension.d.ts

@@ -0,0 +1,44 @@
+/**
+ * yaag's private structured-result tool, loaded into every Agent at spawn.
+ *
+ * The tool stays inactive until a schema-bearing Ask delivers its output schema
+ * through the `yaag-report-result` command; the schema becomes the tool's input
+ * schema, so pi validates the arguments and the Orchestrator settles the Ask
+ * from the call instead of scraping final text (ADR-0032).
+ *
+ * Types are declared locally rather than imported from pi: this file is passed
+ * to `pi -e` as a path and must load without yaag's dependency graph.
+ */
+/** One tool result, in the shape pi's tool layer returns to the model. */
+export interface ReportResultToolResult {
+    readonly content: readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    readonly details?: {
+        readonly reportedResult: unknown;
+    };
+    readonly isError?: boolean;
+    readonly terminate?: boolean;
+}
+/** One tool definition, in the shape `pi.registerTool` accepts. */
+export interface ReportResultToolDefinition {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly promptSnippet: string;
+    readonly promptGuidelines: readonly string[];
+    readonly parameters: object;
+    execute(toolCallId: string, params: unknown): Promise<ReportResultToolResult>;
+}
+/** The part of pi's extension API this extension uses (pi docs/extensions.md). */
+export interface ReportResultAPI {
+    registerTool(definition: ReportResultToolDefinition): void;
+    registerCommand(name: string, command: {
+        readonly description: string;
+        handler(args: string): void;
+    }): void;
+    getActiveTools(): string[];
+    setActiveTools(names: readonly string[]): void;
+}
+export default function (pi: ReportResultAPI): void;