@yaag/runtime 0.6.2 → 0.8.0

package/src/transport/live-transport.ts

@@ -3,6 +3,7 @@ import { FrameQueue } from "./frame-queue.ts";
 import { decodeFrames } from "./jsonl.ts";
 import { piCommand, readModel, readSessionFile, readStats } from "./pi-state.ts";
 import { reap } from "./reap.ts";
+import { appendStderrTail, stderrDiagnostic } from "./stderr-tail.ts";
 import {
   createToolProbe,
   TOOL_PROBE_EXTENSION_PATH,
@@ -25,6 +26,8 @@ import type {
 const READY_TIMEOUT_MS = 30_000;
 /** Cost is a local read answering in ~0ms, but the kill must never block on it. */
 const STATS_TIMEOUT_MS = 2_000;
+/** How long an exit message waits for stderr, which grandchildren may hold open. */
+const STDERR_DRAIN_MS = 100;
 
 /** Agents are real `pi --mode rpc` child processes (ADR-0001). */
 export const liveTransport: TransportFactory = {
@@ -42,7 +45,11 @@ class LiveTransport implements AgentTransport {
   model = "";
 
   readonly #name: string;
-  readonly #process: Bun.Subprocess<"pipe", "pipe", "ignore">;
+  readonly #process: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  /** Last bytes pi wrote to stderr; the only classification signal a spawn gets (ADR-0037). */
+  #stderrTail = "";
+  /** Settles when stderr reaches EOF, so an exit message can wait for the diagnostic. */
+  readonly #stderrDone: Promise<void>;
   readonly #queue = new FrameQueue();
   readonly #pending = new Map<string, (frame: Frame) => void>();
   /** Both halves of tool verification, or null when the spawn promised nothing. */
@@ -60,12 +67,29 @@ class LiveTransport implements AgentTransport {
       cwd: options.cwd,
       stdin: "pipe",
       stdout: "pipe",
-      stderr: "ignore",
+      // pi prints model and startup diagnostics to stderr and exits 1 (main() →
+      // reportDiagnostics → process.exit(1)), so stderr carries the only reason
+      // yaag can classify. The reader below drains it so pi never blocks.
+      stderr: "pipe",
       // Its own process group, so the Agent sees stdin EOF rather than a signal
       // when the Orchestrator dies — EOF is the path that reaps grandchildren.
       detached: true,
     });
     void this.#read();
+    // A stream error must not surface as an unhandled rejection: the tail is a
+    // best-effort diagnostic, never a reason to fail an Agent that started.
+    this.#stderrDone = this.#readStderr().catch(() => undefined);
+  }
+
+  /** Drains stderr continuously, keeping only a bounded tail. */
+  async #readStderr(): Promise<void> {
+    const decoder = new TextDecoder();
+    for await (const chunk of readChunks(this.#process.stderr)) {
+      this.#stderrTail = appendStderrTail(
+        this.#stderrTail,
+        decoder.decode(chunk, { stream: true }),
+      );
+    }
   }
 
   /** Confirms the Agent is up and speaking the protocol, and resolves its model. */
@@ -90,6 +114,8 @@ class LiveTransport implements AgentTransport {
         // The original startup error remains the useful failure.
       }
       if (error instanceof YaagError) throw error;
+      // Only the exit path folds in stderr: a tool-contract or timeout failure
+      // must stay generic, whatever pi warned about earlier (ADR-0037).
       const message = error instanceof Error ? error.message : "agent startup failed";
       throw new YaagError("SPAWN_FAILED", message, this.#name);
     }
@@ -174,8 +200,15 @@ class LiveTransport implements AgentTransport {
         timeoutMs,
       );
     });
-    const death = this.#process.exited.then((code) => {
-      throw new YaagError("SPAWN_FAILED", `agent "${this.#name}" exited (${code})`, this.#name);
+    const death = this.#process.exited.then(async (code) => {
+      // Detached grandchildren can hold the pipe open, so the drain is bounded:
+      // an exit must reject fast, with whatever diagnostic already arrived.
+      await Promise.race([this.#stderrDone, Bun.sleep(STDERR_DRAIN_MS)]);
+      throw new YaagError(
+        "SPAWN_FAILED",
+        `agent "${this.#name}" exited (${code})${stderrDiagnostic(this.#stderrTail)}`,
+        this.#name,
+      );
     });
     return Promise.race([response, failure, death]).finally(() => clearTimeout(timer));
   }

package/src/transport/stderr-tail.ts

@@ -0,0 +1,32 @@
+/** Bound on the kept stderr tail, so a chatty Agent cannot grow the buffer. */
+export const STDERR_TAIL_BYTES = 4_096;
+/** Bound on the diagnostic folded into a failure message, so it stays readable. */
+export const STDERR_MESSAGE_CHARS = 300;
+
+/**
+ * Lines pi prints that are warnings, not the reason a process died.
+ * `No models match pattern "<p>"` is the dangerous one: it classifies as
+ * `not_found` (ADR-0037), so an unfiltered tail would turn an unrelated startup
+ * failure of the same Agent into a Model Resolution trigger.
+ */
+const WARNINGS: readonly RegExp[] = [/no models match pattern/i, /^\s*warn(ing)?\b/i];
+
+/** Appends one chunk to a stderr tail, keeping only the last bounded window. */
+export function appendStderrTail(tail: string, chunk: string): string {
+  return (tail + chunk).slice(-STDERR_TAIL_BYTES);
+}
+
+/**
+ * The exit diagnostic of a stderr tail as a message suffix, or "" when pi
+ * printed nothing fatal. Warning lines are dropped, the rest is collapsed to one
+ * line and capped, so a failure message stays readable.
+ */
+export function stderrDiagnostic(tail: string): string {
+  const lines = tail
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && !WARNINGS.some((pattern) => pattern.test(line)));
+  const text = lines.join(" ").replace(/\s+/g, " ").trim();
+  if (text === "") return "";
+  return `: ${text.length > STDERR_MESSAGE_CHARS ? text.slice(-STDERR_MESSAGE_CHARS) : text}`;
+}

package/src/transport/transport.ts

@@ -1,5 +1,6 @@
 import type { CanonicalJsonObject, ReportedResult } from "../ask-contract/index.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
+import type { RecordedSpawnSelection } from "../model/index.ts";
 import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "../types.ts";
 
 /**
@@ -185,6 +186,11 @@ export interface OpenOptions {
   readonly resolvedSkillPaths?: readonly string[];
   /** Absolute launch-ready extension paths resolved above the seam, emitted as repeated `-e` flags. */
   readonly resolvedExtensionPaths?: readonly string[];
+  /**
+   * Declared extensions in final concatenation order, unresolved (ADR-0040).
+   * Spawn identity only: it never becomes argv, and it is absent when empty.
+   */
+  readonly declaredExtensions?: readonly string[];
   /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
   readonly sessionDir?: string;
   /** Resumes an existing pi session, translated to `--session <path>`. */
@@ -209,4 +215,14 @@ export type TransportStartupObserver = (startup: TransportStartup) => void;
 /** How the layer above obtains transports. Swapped wholesale for replay. */
 export interface TransportFactory {
   open(options: OpenOptions, observeStartup?: TransportStartupObserver): Promise<AgentTransport>;
+
+  /**
+   * The resolved selection this factory recorded for the Agent it would open
+   * next, so a Cassette-backed spawn adopts the recorded outcome instead of
+   * re-running Model Resolution (ADR-0037, ADR-0038, ADR-0039).
+   *
+   * A pure peek: it must not advance the factory's spawn cursor. Live factories
+   * record nothing and omit it.
+   */
+  recordedSpawn?(options: OpenOptions): RecordedSpawnSelection | undefined;
 }

package/src/types.ts

@@ -12,7 +12,10 @@ export interface SpawnOptions {
    *
    * An array is an ordered fallback list and a function picks the next candidate
    * from the failures so far. Any resolved pattern may carry an inline thinking
-   * suffix (`"opus-5:medium"`), which wins over `thinking`.
+   * suffix (`"opus-5:medium"`), which wins over `thinking`. Each attempt settles
+   * the model first, then the thinking level for that model. yaag starts a new
+   * attempt only when pi reports `not_found`, `auth`, or `rate_limited`. See
+   * `ModelSpec` and `ModelResolver` for the termination rules (ADR-0037).
    */
   readonly model?: ModelSpec;
   /** Replaces the default system prompt (`pi --system-prompt`). */
@@ -20,7 +23,8 @@ export interface SpawnOptions {
   /**
    * Sets pi's thinking level; omission preserves pi's default. A function picks
    * the level from the settled model, and is not consulted for a model pattern
-   * that carries an inline thinking suffix.
+   * that carries an inline thinking suffix. The resolver runs again for each
+   * attempt, with the model that settled for that attempt (ADR-0037).
    */
   readonly thinking?: ThinkingSpec;
   /** Appends text to pi's system prompt (`pi --append-system-prompt`). */
@@ -34,6 +38,11 @@ export interface SpawnOptions {
    * resolve from the Orchestration Program file; each becomes `pi -e <path>`.
    */
   readonly extensions?: readonly string[];
+  /**
+   * Load the Effective Config's `agents.extensions` for this Agent. Default
+   * true; false spawns with only the extensions this call declares (ADR-0040).
+   */
+  readonly configExtensions?: boolean;
   /**
    * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
    * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;
@@ -59,7 +68,12 @@ export interface SpawnOptions {
   readonly worktree?: boolean;
 }
 
-/** Spawn options after Model Resolution has settled one model and thinking level. */
+/**
+ * Spawn options after Model Resolution has settled one model and thinking level.
+ *
+ * This is the settled shape, and it is what the Cassette identity hashes
+ * (ADR-0039).
+ */
 export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
   readonly model?: string;
   readonly thinking?: ThinkingLevel;
@@ -84,6 +98,11 @@ export interface SpawnOverrides {
  * Agent, permits one further turn (or a fixed duration grace), then aborts and
  * rejects with `ASK_LIMIT` if it has not settled. This leaves the Handle alive.
  * `timeoutMs` is independent: it kills the Agent and rejects with `ASK_TIMEOUT`.
+ *
+ * A model failure inside an Ask starts Model Fallback and retries the Ask
+ * (ADR-0038). Each attempt gets fresh soft limits, a fresh Stall Watchdog and a
+ * fresh output collector. `timeoutMs` is the exception: it is the hard ceiling
+ * of the whole Ask, and every attempt shares one deadline.
  */
 export interface AskOptions {
   /** Reject and kill the Agent if it has not settled in time. Unset = no bound. */
@@ -106,7 +125,10 @@ export interface AskOptions {
    * live Ask by default (ADR-0029). On expiry yaag probes the Agent and either
    * recovers a missed settlement or rejects with `ASK_STALLED`. Omission uses
    * the 10-minute default. `false`, and any value that is not above zero,
-   * disable the watchdog for this Ask.
+   * disable the watchdog for this Ask. `ASK_STALLED` is a generic failure: it
+   * never starts Model Fallback. If the silence budget ends the Ask before pi
+   * reports a model failure, the Ask fails `ASK_STALLED` and no swap happens
+   * (ADR-0029).
    */
   readonly stallMs?: number | false;
   /** Per-Ask replacement for the runtime's wrap-up steering message. */
@@ -141,7 +163,10 @@ export interface Handle {
   readonly cwd: string;
   /** Fresh branch for a worktree Agent; undefined for ordinary Agents. */
   readonly branch: string | undefined;
-  /** Model id as reported by the Agent's own `get_state` — not the requested pattern. */
+  /**
+   * Model id as reported by the Agent's own `get_state` — not the requested
+   * pattern. A mid-Ask model swap updates it (ADR-0038).
+   */
   readonly model: string;
 
   /**
@@ -155,6 +180,9 @@ export interface Handle {
    * (default 3) and then rejects recoverably with `ASK_INVALID_OUTPUT` after an
    * abort settlement; a reported value the schema rejects fails the same way
    * without a correction. These recoverable outcomes leave the Handle reusable.
+   * A retry after a Model Fallback discards the result the failed attempt
+   * reported, and arms the collector again, so a stale result cannot settle the
+   * retried Ask (ADR-0032, ADR-0038).
    * A concurrent call rejects with `AGENT_BUSY`.
    */
   ask<Schema extends TSchema>(

package/src/wire-constants.ts

@@ -20,5 +20,8 @@ export const NODE_GIST_MAX_CHARS = 120;
 /** Maximum Nested Nodes the Summary keeps per Agent; past it, exited nodes prune oldest-first. */
 export const AGENT_NODE_TABLE_MAX = 64;
 
+/** Maximum Model Resolution fallbacks the Summary keeps per Agent; past it, the oldest prune. */
+export const AGENT_MODEL_FALLBACK_MAX = 16;
+
 /** Prefix marking that the oldest pending Ask output was dropped to fit the wire cap. */
 export const ASK_OUTPUT_TRUNCATION_MARKER = "[…output truncated…]";