@yaag/extension 0.6.2 → 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.2",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -24,9 +24,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.6.2",
-    "@yaag/runtime": "0.6.2",
-    "@yaag/tui": "0.6.2",
+    "@yaag/cli": "0.7.0",
+    "@yaag/runtime": "0.7.0",
+    "@yaag/tui": "0.7.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

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/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":