@yaag/runtime 0.1.4 → 0.2.1

package/src/errors.ts

@@ -7,12 +7,18 @@ export interface AskLimitOutcome {
   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. */
@@ -30,7 +36,7 @@ export type YaagErrorCode =
   | "AGENT_BUSY" // concurrent ask() on one Handle
   | "ASK_TIMEOUT" // timeoutMs elapsed
   | "ASK_LIMIT" // soft Ask budget exceeded after grace
-  | "ASK_STALLED" // no frame arrived within idleMs; escalated by abort, then kill
+  | "ASK_STALLED" // no frame arrived within the silence budget; escalated, then kill
   | "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
   | "ARGS_INVALID" // arguments failed schema validation before the Run started
   | "OPTIONS_CONFLICT" // incompatible Run options were supplied
@@ -54,6 +60,8 @@ export 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`. */
@@ -76,6 +84,7 @@ export class YaagError extends Error {
     if (options !== undefined && "idleMs" in options) {
       this.idleMs = options.idleMs;
       this.destructive = options.destructive;
+      if (options.state !== undefined) this.state = options.state;
     }
     if (options !== undefined && "steeringEfforts" in options) {
       this.steeringEfforts = options.steeringEfforts;

package/src/events.ts

@@ -6,10 +6,17 @@
  * 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 =
@@ -32,7 +39,16 @@ export interface NodeUsage {
 }
 
 export type LifecycleEventBody =
-  | { readonly type: "run_start"; readonly program: string }
+  | {
+      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;
@@ -96,6 +112,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";
@@ -128,6 +149,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;
     };
 
 /**

package/src/fake-transport.ts

@@ -1,6 +1,7 @@
 import { DEFAULT_WRAP_UP_PROMPT } from "./ask-limit.ts";
 import { FrameQueue } from "./frame-queue.ts";
 import { parseFrame } from "./jsonl.ts";
+import { isReportResultCommandFrame, REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
 import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
 
 /**
@@ -37,10 +38,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";
@@ -86,6 +93,7 @@ export class FakeTransport implements AgentTransport {
     if (frame.type === "steer") void this.#answerSteer(frame);
     if (frame.type === "abort") void this.#answerAbort(frame);
     if (frame.type === "get_last_assistant_text") this.#answerLastText(frame);
+    if (frame.type === "get_state") this.#answerState(frame);
   }
 
   frames(): AsyncIterable<Frame> {
@@ -127,12 +135,23 @@ export class FakeTransport implements AgentTransport {
     return this.#closing;
   }
 
+  /** Pushes one unsolicited frame, as a late or abandoned turn would emit. */
+  emit(frame: Frame): void {
+    this.#queue.push(frame);
+  }
+
   /** Simulates the process dying: the frame stream just ends. */
   die(): void {
     this.#queue.end();
   }
 
   async #answerPrompt(frame: Frame): Promise<void> {
+    // pi answers an extension command without starting a turn, so the private
+    // schema command selects no script and plays no frames (ADR-0032).
+    if (isReportResultCommandFrame(frame)) {
+      this.#answerControl(frame, this.#options.schemaCommandError);
+      return;
+    }
     const script = this.#selectPromptScript();
     const error = script.promptError ?? this.#options.promptError;
     const response = {
@@ -214,6 +233,23 @@ export class FakeTransport implements AgentTransport {
     }
   }
 
+  #answerState(frame: Frame): void {
+    if (this.#options.stateSilent === true) return;
+    this.#queue.push({
+      type: "response",
+      command: "get_state",
+      id: frame.id,
+      success: true,
+      data: this.#options.state ?? {
+        model: { provider: "test", id: "model" },
+        isStreaming: false,
+        isCompacting: false,
+        messageCount: 1,
+        pendingMessageCount: 0,
+      },
+    });
+  }
+
   #answerLastText(frame: Frame): void {
     const text = this.#currentScript?.lastText ?? this.#options.lastText;
     this.#queue.push({
@@ -226,6 +262,25 @@ export class FakeTransport implements AgentTransport {
   }
 }
 
+/** The frames one accepted `report_result` call produces, for scripted Asks. */
+export function reportResultFrames(value: unknown, toolCallId = "call-1"): readonly Frame[] {
+  return [
+    {
+      type: "tool_execution_start",
+      toolCallId,
+      toolName: REPORT_RESULT_TOOL_NAME,
+      args: value,
+    },
+    {
+      type: "tool_execution_end",
+      toolCallId,
+      toolName: REPORT_RESULT_TOOL_NAME,
+      result: { content: [], details: { reportedResult: value }, terminate: true },
+      isError: false,
+    },
+  ];
+}
+
 /**
  * Loads and parses a named JSONL frame fixture from the runtime fixtures directory.
  *

package/src/frame-queue.ts

@@ -23,6 +23,11 @@ export class FrameQueue {
     this.#buffered.push(frame);
   }
 
+  /** Drops every buffered frame the consumer has not taken yet. */
+  discardPending(): void {
+    this.#buffered = [];
+  }
+
   /** Ends the stream; the consumer's iteration finishes once drained. */
   end(): void {
     if (this.#ended) return;

package/src/index.ts

@@ -9,7 +9,7 @@ export type {
   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";
@@ -32,6 +32,15 @@ export type {
   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";
@@ -79,6 +88,7 @@ export type {
 export type {
   AskOptions,
   Handle,
+  ResolvedSpawnOptions,
   SpawnOptions,
   SpawnOverrides,
   StructuredAskOptions,

package/src/model-resolution.ts

@@ -0,0 +1,119 @@
+import { parseModelSuffix } from "./model-suffix.ts";
+import { isThinkingLevel, 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 function normalizeModelResolution(spec: {
+  readonly model?: ModelSpec;
+  readonly thinking?: ThinkingSpec;
+}): ModelResolution {
+  const model = toModelResolver(spec.model);
+  const thinking = toThinkingResolver(spec.thinking);
+  const literalThinking = typeof spec.thinking === "function" ? undefined : spec.thinking;
+  return {
+    resolve(errors: readonly ModelError[]): ModelSelection | undefined {
+      if (model === undefined) {
+        if (errors.length > 0) return undefined;
+        return { model: undefined, thinking: checkedThinking(literalThinking) };
+      }
+      const pattern = checkedModel(model(errors));
+      if (pattern === undefined) return undefined;
+      const parsed = parseModelSuffix(pattern);
+      if (parsed.thinking !== undefined) return parsed;
+      return { model: parsed.model, thinking: checkedThinking(thinking(parsed.model, errors)) };
+    },
+  };
+}
+
+function toModelResolver(spec: ModelSpec | undefined): ModelResolver | undefined {
+  if (spec === undefined) return undefined;
+  if (typeof spec === "string") {
+    return (errors) => (errors.length === 0 ? spec : undefined);
+  }
+  if (Array.isArray(spec)) {
+    const candidates: readonly string[] = [...spec];
+    return (errors) => candidates[errors.length];
+  }
+  if (typeof spec === "function") return spec;
+  throw new TypeError(`model must be a string, an array of strings, or a function: ${show(spec)}`);
+}
+
+function toThinkingResolver(spec: ThinkingSpec | undefined): ThinkingResolver {
+  if (spec === undefined) return () => undefined;
+  if (typeof spec === "function") return spec;
+  if (isThinkingLevel(spec)) return () => spec;
+  throw new TypeError(`thinking must be a pi thinking level or a function: ${show(spec)}`);
+}
+
+function checkedModel(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value === "") {
+    throw new TypeError(
+      `model resolver must return a non-empty string or undefined: ${show(value)}`,
+    );
+  }
+  return value;
+}
+
+function checkedThinking(value: unknown): ThinkingLevel | undefined {
+  if (value === undefined) return undefined;
+  if (!isThinkingLevel(value)) {
+    throw new TypeError(
+      `thinking resolver must return a pi thinking level or undefined: ${show(value)}`,
+    );
+  }
+  return value;
+}
+
+function show(value: unknown): string {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}

package/src/model-suffix.ts

@@ -0,0 +1,24 @@
+import { isThinkingLevel, 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 function parseModelSuffix(pattern: string): ModelPattern {
+  const separator = pattern.lastIndexOf(":");
+  if (separator <= 0) return { model: pattern, thinking: undefined };
+  const tail = pattern.slice(separator + 1);
+  if (!isThinkingLevel(tail)) return { model: pattern, thinking: undefined };
+  return { model: pattern.slice(0, separator), thinking: tail };
+}

package/src/pi-state.ts

@@ -1,5 +1,16 @@
+import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "./report-result.ts";
 import type { AgentStats, Frame, OpenOptions, TokenBreakdown } 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 function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[] {
   const cmd = ["pi", "--mode", "rpc"];
@@ -22,13 +33,7 @@ function appendCapabilities(
   toolProbeExtensionPath: string | undefined,
 ): void {
   const hermetic = options.inherit !== true;
-  if (options.tools === undefined) {
-    if (hermetic) cmd.push("--no-tools");
-  } else if (options.tools.length === 0) {
-    cmd.push("--no-tools");
-  } else {
-    cmd.push("--tools", options.tools.join(","));
-  }
+  appendTools(cmd, options, hermetic);
   if (options.resolvedSkillPaths === undefined) {
     if (hermetic) cmd.push("--no-skills");
   } else {
@@ -39,6 +44,10 @@ function appendCapabilities(
     cmd.push("--no-extensions", "--no-context-files", "--no-prompt-templates");
   }
   for (const path of options.resolvedExtensionPaths ?? []) cmd.push("-e", path);
+  // Every Agent carries the report-result tool, because an Ask declares its
+  // output schema long after the process started and pi loads extensions only
+  // at startup (ADR-0032).
+  cmd.push("-e", REPORT_RESULT_EXTENSION_PATH);
   if (
     options.tools !== undefined &&
     options.tools.length > 0 &&
@@ -47,10 +56,34 @@ function appendCapabilities(
     cmd.push("-e", toolProbeExtensionPath);
   }
   if (options.disallowedTools !== undefined) {
-    cmd.push("--exclude-tools", options.disallowedTools.join(","));
+    // The private tool is never a program's to deny: excluding it would fail
+    // every schema-bearing Ask with "agent did not call report_result". A
+    // denylist of only that name leaves nothing to exclude.
+    const denied = options.disallowedTools.filter((name) => name !== REPORT_RESULT_TOOL_NAME);
+    // An explicit empty denylist still emits its empty flag, as it always has.
+    const emitsExcludeTools = denied.length > 0 || options.disallowedTools.length === 0;
+    if (emitsExcludeTools) cmd.push("--exclude-tools", denied.join(","));
   }
 }
 
+/**
+ * Expresses the tool baseline as an allowlist that keeps `report_result`.
+ *
+ * `--no-tools` strips extension tools as well, and refuses a tool registered
+ * afterwards, so "no tools" becomes an allowlist of exactly yaag's own tool
+ * (e2e/report-result-spike.test.ts). The tool stays inactive until a
+ * schema-bearing Ask activates it, so the Agent's effective capability is
+ * unchanged.
+ */
+function appendTools(cmd: string[], options: OpenOptions, hermetic: boolean): void {
+  if (options.tools === undefined) {
+    if (hermetic) cmd.push("--tools", REPORT_RESULT_TOOL_NAME);
+    return;
+  }
+  const allowed = [...new Set([...options.tools, REPORT_RESULT_TOOL_NAME])];
+  cmd.push("--tools", allowed.join(","));
+}
+
 /**
  * `provider/id` from a `get_state` response — what the Agent actually resolved
  * to, not the pattern that was requested. Null when the payload has no model.
@@ -66,6 +99,28 @@ export function readModel(response: Frame): string | null {
   return provider ? `${provider}/${model.id}` : model.id;
 }
 
+/**
+ * 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 function readAgentProgress(data: unknown): AgentProgress | null {
+  if (typeof data !== "object" || data === null) return null;
+  const record: Record<string, unknown> = { ...data };
+  if (typeof record.isStreaming !== "boolean") return null;
+  const streaming = record.isStreaming;
+  const compacting = record.isCompacting === true;
+  const pendingMessages =
+    typeof record.pendingMessageCount === "number" ? record.pendingMessageCount : 0;
+  return {
+    working: streaming || compacting || pendingMessages > 0,
+    streaming,
+    compacting,
+    pendingMessages,
+  };
+}
+
 /** Returns pi's persisted session path from a startup `get_state` response, when valid. */
 export function readSessionFile(response: Frame): string | null {
   const data: unknown = response.data;

package/src/recording-transport.ts

@@ -1,9 +1,9 @@
 import type { CassetteSink } from "./cassette.ts";
-import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
 import { readGitFacts } from "./git-facts.ts";
 import type {
   AgentStats,
   AgentTransport,
+  AskCompletion,
   AskMarker,
   AskPlayback,
   Frame,
@@ -75,13 +75,13 @@ class RecordingTransport implements AgentTransport {
     return this.#inner.beginAsk(marker);
   }
 
-  finishAsk(
-    outcome?: AskLimitOutcome,
-    stalled?: AskStalledOutcome,
-    invalidOutput?: import("./transport.ts").AskInvalidOutputPlayback,
-  ): void {
-    this.#recorder.finishAsk(outcome, stalled, invalidOutput);
-    this.#inner.finishAsk(outcome, stalled, invalidOutput);
+  finishAsk(completion: AskCompletion): void {
+    this.#recorder.finishAsk(completion);
+    this.#inner.finishAsk(completion);
+  }
+
+  recordedExtractionPolicy(index: number): string | undefined {
+    return this.#inner.recordedExtractionPolicy?.(index);
   }
 
   close(): Promise<AgentStats> {

package/src/replay-divergence.ts

@@ -114,6 +114,7 @@ function changedFields(expected: AskMarkerContext, actual: AskMarkerContext): re
     "maxToolCalls",
     "maxDurationMs",
     "idleMs",
+    "stallMs",
     "wrapUpPrompt",
     "outputSchema",
     "maxSteers",

package/src/replay-transport.ts

@@ -65,6 +65,10 @@ class ReplayTransport implements AgentTransport {
     // A completed replay does not alter the recorded Cassette.
   }
 
+  recordedExtractionPolicy(index: number): string | undefined {
+    return this.#replay.agent.asks[index]?.extractionPolicy;
+  }
+
   close(): Promise<AgentStats> {
     this.#closed ??= Promise.resolve(this.#replay.stats).finally(() => this.#replay.finish());
     return this.#closed;