@yaag/runtime 0.6.2 → 0.7.0

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";
 
 /**
@@ -209,4 +210,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`). */
@@ -59,7 +63,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 +93,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 +120,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 +158,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 +175,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…]";