@yaag/extension 0.6.1 → 0.7.0

package/README.md

@@ -138,6 +138,8 @@ export default defineRun({
   run: async (ctx) => {
     const agent = await ctx.spawn({
       name: "reviewer",
+      model: ["anthropic/claude-opus-4:medium", "anthropic/claude-haiku-4"],
+      thinking: (model) => (model.includes("haiku") ? "low" : "high"),
       tools: ["read", "grep"],
       disallowedTools: ["yaag_run"],
       skills: ["review"],
@@ -173,6 +175,14 @@ is recoverable and the Handle can be asked again. `wrapUpPrompt` replaces the
 default steering message. This is intentionally different from `timeoutMs`, the
 destructive fallback that rejects with `ASK_TIMEOUT` and closes the Agent.
 
+`model` takes one pattern, an ordered list, or a function of the failures so
+far; `thinking` takes a level or a function of the settled model. A pattern can
+end with a thinking suffix (`"opus-5:medium"`), and the suffix wins over
+`thinking`. The fallback rules — trigger classes, retry, termination — are
+stated on the types in `<program dir>/.yaag/types/runtime/index.d.ts` and in
+the root [`README.md`](../../README.md#models-and-fallback); the sequences are
+in [`../../docs/architecture.md`](../../docs/architecture.md) §4 and §6.
+
 The tool call:
 
 ```json
@@ -231,3 +241,6 @@ Provided commands: `/yaag-status`, `/yaag-setup-workspace [dir]`.
 - [`../../docs/architecture.md`](../../docs/architecture.md) — the diagrams
 - [`../../docs/adr/`](../../docs/adr) — why it is built this way
 - [ADR-0018: foreign workspaces use CLI aliases and vendored types](../../docs/adr/0018-foreign-workspaces-use-cli-aliases-and-vendored-types.md) — workspace setup and foreign-program support
+- [ADR-0037: model resolution triggers are read from pi's stderr diagnostic](../../docs/adr/0037-model-resolution-triggers-are-read-from-pis-stderr-diagnostic.md) — which failures start a fallback
+- [ADR-0038: a mid-Ask model swap is a yaag-side match, then `set_model`](../../docs/adr/0038-a-mid-ask-model-swap-is-a-yaag-side-match-then-set-model.md) — how a live Agent changes model
+- [ADR-0039: replay adopts the recorded resolved model](../../docs/adr/0039-replay-adopts-the-recorded-resolved-model.md) — why a replay skips the resolution loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.6.1",
-    "@yaag/runtime": "0.6.1",
-    "@yaag/tui": "0.6.1",
+    "@yaag/cli": "0.7.0",
+    "@yaag/runtime": "0.7.0",
+    "@yaag/tui": "0.7.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/record/run-registry.ts

@@ -1,8 +1,9 @@
-import type { EndedRunSummary, RunSummary } from "@yaag/runtime";
+import type { RunSummary, RunOutcome as SummaryOutcome } from "@yaag/runtime";
 import type { ProcessIdentity, RunOutcome } from "../process/index.ts";
 import { pickInlineResumeSource } from "./resume-source.ts";
 import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
 import { restoreRecords } from "./run-restore.ts";
+import { failedSummary, settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
 
 export type { RunLaunch } from "./run-record.ts";
@@ -148,8 +149,30 @@ export class RunRegistry {
   }
 
   /**
-   * `restoreRecords` already settled every stale `live` record, so this check
-   * can never adopt a Run as live (ADR-0036).
+   * Persists the settled form of a Run read back from disk, and refreshes the
+   * retained entry so the next snapshot of this session shows the verdict.
+   *
+   * Only a `restored` Run settles here: a live Run settles through its own
+   * outcome, and a finished Run is history (ADR-0036), so either is refused
+   * rather than written over. A Run this session never listed stays unlisted —
+   * it is written, but not adopted.
+   */
+  async settleRestored(record: RunRecord, outcome: SummaryOutcome): Promise<RestoredRun> {
+    const known = this.#runs.get(record.id);
+    if (known !== undefined && known.state !== "restored")
+      throw new Error(`RunRegistry: Run ${record.id} is ${known.state}, not a restored Run`);
+    const settled = settledRecord({ record, outcome, now: this.#now() });
+    this.#records.set(settled.id, settled);
+    if (known !== undefined)
+      this.#runs.set(settled.id, { state: "restored", run: restored(settled) });
+    await this.#store?.save(settled);
+    return restored(settled);
+  }
+
+  /**
+   * `restoreRecords` already settled every stale `live` record, and every
+   * `orphaned` record whose process is gone, so this check can never adopt a
+   * Run as live (ADR-0036).
    */
   #adoptable(record: RunRecord): boolean {
     if (record.state === "orphaned" || record.state === "interrupted") return true;
@@ -228,7 +251,10 @@ export class RunRegistry {
   reject(id: string, reason: unknown): void {
     const record = this.#runs.get(id);
     if (record === undefined || record.state !== "live") return;
-    this.#settle(id, failedSummary(record.run.summary), { kind: "rejected", reason });
+    this.#settle(id, failedSummary(record.run.summary, this.#now().getTime()), {
+      kind: "rejected",
+      reason,
+    });
   }
 
   /**
@@ -310,9 +336,3 @@ function persistedOutcome(outcome: RunSettlement): RunRecord["outcome"] {
 function errorMessage(reason: unknown): string {
   return reason instanceof Error ? reason.message : String(reason);
 }
-
-function failedSummary(summary: RunSummary): EndedRunSummary {
-  if (summary.runState === "ended")
-    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
-  return { ...summary, runState: "ended", outcome: "failed", ok: false, endedAt: null };
-}

package/src/record/run-restore.ts

@@ -1,5 +1,6 @@
 import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RunRecord } from "./run-record.ts";
+import { settledRecord } from "./run-settle-record.ts";
 import type { RunStore } from "./run-store.ts";
 
 /** Decides whether the process a record names is still running. */
@@ -19,6 +20,11 @@ export interface RestoreOptions {
  * gone: its child is dead and the Run is `interrupted`, or its child still runs
  * without an owner and the Run is `orphaned`. Both re-writes are persisted, so
  * the verdict survives this session too (ticket 02).
+ *
+ * An `orphaned` record is probed again: its child can have ended since the
+ * session that orphaned it, and a dead one settles to `interrupted` with an end
+ * instant and an ended Summary. An orphan that still runs is left as it is, so
+ * a session start does not rewrite every record.
  */
 export async function restoreRecords(options: RestoreOptions): Promise<readonly RunRecord[]> {
   const isAlive = options.isAlive ?? isProcessAlive;
@@ -33,11 +39,12 @@ async function settleStale(
   now: () => Date,
   store: RunStore,
 ): Promise<RunRecord> {
-  if (record.state !== "live") return record;
+  if (record.state !== "live" && record.state !== "orphaned") return record;
   const alive = record.process !== null && isAlive(record.process);
+  if (alive && record.state === "orphaned") return record;
   const settled: RunRecord = alive
     ? { ...record, state: "orphaned" }
-    : { ...record, state: "interrupted", endedAt: now().toISOString() };
+    : settledRecord({ record, outcome: "interrupted", now: now() });
   await store.save(settled);
   return settled;
 }

package/src/record/run-settle-record.ts

@@ -0,0 +1,67 @@
+import type { EndedRunSummary, RunOutcome, RunSummary } from "@yaag/runtime";
+import type { RunRecord } from "./run-record.ts";
+
+/**
+ * Marks a folded Summary ended, keeping every accounting fact it holds.
+ *
+ * An already-ended fold is history and is returned unchanged: a Run keeps the
+ * first outcome observed for it, the invariant the registry keeps when it
+ * retains a settlement. `endedAt` stays null because it is the `run_end.at`
+ * event fact and no such event was seen.
+ */
+export function endedSummary(
+  summary: RunSummary,
+  outcome: RunOutcome,
+  endedAtMs: number,
+): EndedRunSummary {
+  if (summary.runState === "ended") return summary;
+  return {
+    ...summary,
+    runState: "ended",
+    outcome,
+    ok: outcome === "completed",
+    endedAt: null,
+    durationMs: durationOf(summary, endedAtMs),
+  };
+}
+
+/**
+ * The fold never synthesizes a duration from a clock (architecture §8), so the
+ * wall-clock value is supplied here, once, by the caller that settles the Run.
+ * Without it a settled Run reads `0s` instead of how long it really ran.
+ */
+function durationOf(summary: RunSummary, endedAtMs: number): number {
+  if (summary.durationMs !== 0) return summary.durationMs;
+  if (summary.startedAt === null) return 0;
+  return Math.max(0, endedAtMs - summary.startedAt);
+}
+
+/** Marks a fold ended as failed, for a Run whose child rejected. */
+export function failedSummary(summary: RunSummary, endedAtMs: number): EndedRunSummary {
+  if (summary.runState === "ended")
+    return summary.ok ? { ...summary, outcome: "failed", ok: false } : summary;
+  return endedSummary(summary, "failed", endedAtMs);
+}
+
+/**
+ * The settled form of a record no process is attached to any more.
+ *
+ * The persisted state is `interrupted`: no new state member is added, so an
+ * older yaag still reads the record. The verdict lives in the Summary fold —
+ * `stopped` when yaag_stop killed the group, `interrupted` when the process was
+ * already gone. The persisted outcome stays null, because the Run gave no exit
+ * code and no rejection reason.
+ */
+export function settledRecord(options: {
+  readonly record: RunRecord;
+  readonly outcome: RunOutcome;
+  readonly now: Date;
+}): RunRecord {
+  const { record, outcome, now } = options;
+  return {
+    ...record,
+    state: "interrupted",
+    endedAt: now.toISOString(),
+    summary: endedSummary(record.summary, outcome, now.getTime()),
+  };
+}

package/src/record/run-summary-parse.ts

@@ -2,6 +2,7 @@ import type {
   AgentActivity,
   AgentInfo,
   AgentState,
+  ModelFallbackInfo,
   NodeInfo,
   NodeState,
   RunOutcome,
@@ -56,6 +57,7 @@ interface SummaryBase {
   readonly incomplete: boolean;
   readonly durationMs: number;
   readonly worstFrameGapMs: number;
+  readonly modelFallbacks: number;
 }
 
 function parseBase(stored: Record<string, unknown>): SummaryBase | null {
@@ -88,6 +90,9 @@ function parseBase(stored: Record<string, unknown>): SummaryBase | null {
     incomplete: stored.incomplete,
     durationMs: stored.durationMs,
     worstFrameGapMs: stored.worstFrameGapMs,
+    // Tolerant, unlike the strict fields above: a record written before the
+    // fallback counter existed must still load instead of disappearing.
+    modelFallbacks: typeof stored.modelFallbacks === "number" ? stored.modelFallbacks : 0,
   };
 }
 
@@ -110,7 +115,9 @@ function parseAgent(value: unknown): AgentInfo | null {
   const nodes = parseNodes(stored.nodes);
   const tokens = parseTokens(stored.tokens);
   const activity = parseActivity(stored.activity);
+  const fallbacks = parseFallbacks(stored.modelFallbacks);
   if (
+    fallbacks === null ||
     nodes === null ||
     tokens === undefined ||
     activity === undefined ||
@@ -142,6 +149,10 @@ function parseAgent(value: unknown): AgentInfo | null {
     askStartedAt: stored.askStartedAt,
     nodes,
     finishedNodesPruned: stored.finishedNodesPruned,
+    modelFallbacks: fallbacks,
+    // Tolerant for the same reason as the Run-level counter.
+    modelFallbacksPruned:
+      typeof stored.modelFallbacksPruned === "number" ? stored.modelFallbacksPruned : 0,
   };
   if (state === "asking") {
     if (typeof stored.askIndex !== "number") return null;
@@ -189,6 +200,37 @@ function parseNodes(value: unknown): NodeInfo[] | null {
   return nodes;
 }
 
+/**
+ * The per-Agent fallback table: `[]` when a record predates it, `null` when the
+ * stored value is malformed.
+ */
+function parseFallbacks(value: unknown): ModelFallbackInfo[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+  const fallbacks: ModelFallbackInfo[] = [];
+  for (const entry of value) {
+    const stored = asRecord(entry);
+    if (
+      stored === null ||
+      typeof stored.failedModel !== "string" ||
+      typeof stored.resolvedModel !== "string" ||
+      typeof stored.attempt !== "number" ||
+      !isReason(stored.reason) ||
+      !isNullableNumber(stored.at)
+    ) {
+      return null;
+    }
+    fallbacks.push({
+      failedModel: stored.failedModel,
+      resolvedModel: stored.resolvedModel,
+      attempt: stored.attempt,
+      reason: stored.reason,
+      at: stored.at,
+    });
+  }
+  return fallbacks;
+}
+
 /**
  * `undefined` means the stored value is malformed or missing; a stored `null`
  * is an Agent or Node whose usage was never reported.
@@ -250,6 +292,10 @@ function isAgentState(value: unknown): value is AgentState {
   return value === "idle" || value === "asking" || value === "exited";
 }
 
+function isReason(value: unknown): value is ModelFallbackInfo["reason"] {
+  return value === "not_found" || value === "auth" || value === "rate_limited";
+}
+
 function isNodeState(value: unknown): value is NodeState {
   return value === "running" || value === "exited" || value === "failed";
 }

package/src/tool/describe-tool.ts

@@ -20,6 +20,12 @@ const DESCRIPTION = [
   "handle.ask supports maxTurns, maxToolCalls, maxDurationMs, and wrapUpPrompt as recoverable",
   "ASK_LIMIT controls. These differ from timeoutMs, the destructive Agent-killing fallback.",
   "",
+  "model takes one pattern, an ordered list of patterns, or a function of the failures so far;",
+  "thinking takes a level or a function of the settled model. A pattern can end with a thinking",
+  'suffix ("opus-5:medium"), which wins over thinking. yaag falls back only on not_found, auth,',
+  "and rate_limited, at spawn and inside an Ask. Exhausted candidates fail with",
+  "MODEL_RESOLUTION_FAILED.",
+  "",
   "Describing imports the program and executes its module top level. Programs should keep",
   "module top level side-effect free; use this only for reviewed, user-authored files.",
 ].join("\n");

package/src/tool/stop-tool.ts

@@ -1,7 +1,7 @@
 import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RunSummary } from "@yaag/runtime";
 import { Type } from "typebox";
-import { isProcessAlive } from "../process/index.ts";
+import { isProcessAlive, type ProcessIdentity } from "../process/index.ts";
 import type { RestoredRun, RunRegistry } from "../record/index.ts";
 import { toUsage } from "../view/index.ts";
 
@@ -21,9 +21,22 @@ const DESCRIPTION = [
   "it spent before it stopped.",
   "",
   "An orphaned Run left behind by an earlier Host Session is stopped too: its",
-  "process group is killed, and the report holds its last persisted Summary.",
+  "process group is killed, its record is settled, and the report holds its last",
+  "persisted Summary. If its process already ended, the record is settled too and",
+  "the report says the Run was no longer running.",
 ].join("\n");
 
+/** Seams the tests replace, so no test kills a real process group. */
+export interface StopToolOptions {
+  readonly isAlive?: (identity: ProcessIdentity) => boolean;
+  readonly kill?: (pid: number) => void;
+}
+
+interface StopDeps {
+  readonly isAlive: (identity: ProcessIdentity) => boolean;
+  readonly kill: (pid: number) => void;
+}
+
 /** What a stopped Run got through and what it cost, from the fold (ADR-0006). */
 export function stopReport(id: string, summary: RunSummary): string {
   const agents = Object.keys(summary.agents).length;
@@ -71,18 +84,28 @@ function agentStateReport(agent: RunSummary["agents"][string]): string {
  * pipes belong to a dead Host Session — so the process group is killed outright
  * (ADR-0008). The pid is re-probed first, because a record can name a pid that
  * a different process has since inherited (ticket 02).
+ *
+ * The record is settled either way: a process that already ended is not an
+ * error, it only means the verdict is `interrupted` instead of `stopped`.
  */
-function stopOrphan(run: RestoredRun): AgentToolResult<StopDetails> {
+async function stopOrphan(
+  run: RestoredRun,
+  registry: RunRegistry,
+  deps: StopDeps,
+): Promise<AgentToolResult<StopDetails>> {
   const { record } = run;
   if (record.state !== "orphaned" || record.process === null)
     throw new Error(`yaag_stop: Run ${record.id} has already finished`);
-  if (!isProcessAlive(record.process))
-    throw new Error(`yaag_stop: Run ${record.id} is no longer running`);
-  killGroup(record.process.pid);
+  const alive = deps.isAlive(record.process);
+  if (alive) deps.kill(record.process.pid);
+  const settled = await registry.settleRestored(record, alive ? "stopped" : "interrupted");
+  const note = alive
+    ? ""
+    : `Run ${record.id} was no longer running; its record is settled as interrupted.\n`;
   return {
-    content: [{ type: "text", text: stopReport(record.id, record.summary) }],
-    details: { summary: record.summary },
-    usage: toUsage(record.summary),
+    content: [{ type: "text", text: `${note}${stopReport(record.id, settled.summary)}` }],
+    details: { summary: settled.summary },
+    usage: toUsage(settled.summary),
   };
 }
 
@@ -111,7 +134,12 @@ function toError(reason: unknown): Error {
  */
 export function createStopTool(
   registry: RunRegistry,
+  options: StopToolOptions = {},
 ): ToolDefinition<typeof parameters, StopDetails> {
+  const deps: StopDeps = {
+    isAlive: options.isAlive ?? isProcessAlive,
+    kill: options.kill ?? killGroup,
+  };
   return {
     name: "yaag_stop",
     label: "Stop Run",
@@ -123,7 +151,7 @@ export function createStopTool(
         case "unknown":
           throw new Error(`yaag_stop: no Run with id ${params.id}`);
         case "restored":
-          return stopOrphan(status.run);
+          return await stopOrphan(status.run, registry, deps);
         case "finished":
           throw new Error(`yaag_stop: Run ${params.id} has already finished`);
         case "live": {

package/src/tool/system-prompt-append.ts

@@ -24,7 +24,7 @@ export function yaagPromptBlock(directories: readonly string[]): string {
     "});",
     "```",
     "",
-    "Full authoring surface (defineAgent, args schemas, ask limits, worktrees):",
+    "Full authoring surface (defineAgent, args schemas, ask limits, worktrees, model fallback):",
     "read `<program dir>/.yaag/types/runtime/index.d.ts`.",
   ].join("\n");
 }

package/src/view/run-details.ts

@@ -2,6 +2,7 @@ import type {
   AgentActivity,
   AgentInfo,
   LifecycleEvent,
+  ModelFallbackInfo,
   NodeInfo,
   RunSummary,
   TokenBreakdown,
@@ -58,7 +59,8 @@ function isSummaryBase(value: Record<string, unknown>): boolean {
     nullableTokens(value.tokens) &&
     typeof value.incomplete === "boolean" &&
     natural(value.durationMs) &&
-    natural(value.worstFrameGapMs)
+    natural(value.worstFrameGapMs) &&
+    (value.modelFallbacks === undefined || natural(value.modelFallbacks))
   );
 }
 
@@ -78,9 +80,11 @@ function normalizeAgents(value: RunSummary): RunSummary {
       ...agent,
       nodes: agent.nodes ?? [],
       finishedNodesPruned: agent.finishedNodesPruned ?? 0,
+      modelFallbacks: agent.modelFallbacks ?? [],
+      modelFallbacksPruned: agent.modelFallbacksPruned ?? 0,
     };
   }
-  return { ...value, agents };
+  return { ...value, agents, modelFallbacks: value.modelFallbacks ?? 0 };
 }
 
 function optionalNodes(value: unknown): boolean {
@@ -103,6 +107,24 @@ function isNodeState(value: unknown): boolean {
   return value === "running" || value === "exited" || value === "failed";
 }
 
+function optionalFallbacks(value: unknown): boolean {
+  return value === undefined || (Array.isArray(value) && value.every(isFallback));
+}
+
+function isFallback(value: unknown): value is ModelFallbackInfo {
+  return (
+    isRecord(value) &&
+    strings(value.failedModel, value.resolvedModel) &&
+    isReason(value.reason) &&
+    natural(value.attempt) &&
+    nullableNumber(value.at)
+  );
+}
+
+function isReason(value: unknown): boolean {
+  return value === "not_found" || value === "auth" || value === "rate_limited";
+}
+
 function optionalNodeUsage(value: unknown): boolean {
   if (value === undefined) return true;
   if (!isRecord(value)) return false;
@@ -142,7 +164,9 @@ function isAgentBase(value: Record<string, unknown>): boolean {
     nullableNumber(value.usageUpdatedAt) &&
     nullableNumber(value.askStartedAt) &&
     optionalNodes(value.nodes) &&
-    (value.finishedNodesPruned === undefined || natural(value.finishedNodesPruned))
+    (value.finishedNodesPruned === undefined || natural(value.finishedNodesPruned)) &&
+    optionalFallbacks(value.modelFallbacks) &&
+    (value.modelFallbacksPruned === undefined || natural(value.modelFallbacksPruned))
   );
 }
 
@@ -191,6 +215,12 @@ function isEvent(value: unknown): value is LifecycleEvent {
         typeof value.ok === "boolean" &&
         (value.maxFrameGapMs === undefined || natural(value.maxFrameGapMs))
       );
+    case "model_fallback":
+      return (
+        strings(value.agent, value.failedModel, value.resolvedModel) &&
+        natural(value.attempt) &&
+        isReason(value.reason)
+      );
     case "agent_usage":
       return strings(value.agent) && isTokens(value.tokens) && number(value.cost);
     case "agent_exit":