@yaag/runtime 0.6.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },

package/src/agent/agent.ts

@@ -4,11 +4,21 @@ import { exchangeAsk } from "../ask/index.ts";
 import { ReportResultTool } from "../ask-contract/index.ts";
 import { agentError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentStats, AgentTransport } from "../transport/index.ts";
 import { Connection } from "../transport/index.ts";
 import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
 import { AgentUsage } from "./agent-usage.ts";
 
+/** The mid-Ask Model Resolution one Agent's spawn handed it (ADR-0038). */
+export interface AgentModelFallback {
+  readonly resolution: ModelResolution;
+  /** The Agent-wide attempt history, shared with its spawn loop. */
+  readonly history: ModelErrorHistory;
+  /** The model candidate this Agent's spawn settled on. */
+  readonly candidate: string;
+}
+
 export interface AgentOptions {
   readonly name: string;
   readonly cwd: string;
@@ -17,6 +27,11 @@ export interface AgentOptions {
   readonly emit: EventSink;
   /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
   readonly spawnOptions: ResolvedSpawnOptions;
+  /**
+   * Mid-Ask Model Resolution for this Agent, sharing the spawn loop's history.
+   * Absent when the spawn named no candidate: there is nothing to fall back from.
+   */
+  readonly modelFallback?: AgentModelFallback;
   /** Definition-owned defaults merged below explicit per-Ask options. */
   readonly askDefaults?: AskOptions;
   /** Definition identity recorded on its Asks, outside replay identity. */
@@ -34,7 +49,6 @@ export class Agent implements Handle {
   readonly name: string;
   readonly cwd: string;
   readonly branch: string | undefined;
-  readonly model: string;
 
   readonly #transport: AgentTransport;
   readonly #connection: Connection;
@@ -45,6 +59,9 @@ export class Agent implements Handle {
   readonly #askLimitGraceMs: number | undefined;
   readonly #idleAbortSettleMs: number | undefined;
   readonly #stallProbeSettleMs: number | undefined;
+  readonly #modelFallback: AgentModelFallback | undefined;
+  #model: string;
+  #candidate: string;
   readonly #usage: AgentUsage;
   readonly #reportResultTool = new ReportResultTool();
   #busy = false;
@@ -56,7 +73,9 @@ export class Agent implements Handle {
     this.name = options.name;
     this.cwd = options.cwd;
     this.branch = options.branch;
-    this.model = options.transport.model;
+    this.#model = options.transport.model;
+    this.#modelFallback = options.modelFallback;
+    this.#candidate = options.modelFallback?.candidate ?? options.transport.model;
     this.#transport = options.transport;
     this.#emit = options.emit;
     this.#spawnOptions = options.spawnOptions;
@@ -71,6 +90,11 @@ export class Agent implements Handle {
     this.#connection = new Connection(options.transport, options.name);
   }
 
+  /** The model pi reports for this Agent now; a mid-Ask swap updates it. */
+  get model(): string {
+    return this.#model;
+  }
+
   async ask<Schema extends TSchema>(
     prompt: string,
     options: StructuredAskOptions<Schema>,
@@ -101,6 +125,18 @@ export class Agent implements Handle {
         reportResultTool: this.#reportResultTool,
         emit: this.#emit,
         usage: this.#usage,
+        modelFallback:
+          this.#modelFallback === undefined
+            ? undefined
+            : {
+                resolution: this.#modelFallback.resolution,
+                history: this.#modelFallback.history,
+                currentModel: () => this.#candidate,
+                onSwapped: (candidate: string, reportedModel: string) => {
+                  this.#candidate = candidate;
+                  this.#model = reportedModel;
+                },
+              },
         close: () => void this.close().catch(() => {}),
         askLimitGraceMs: this.#askLimitGraceMs,
         idleAbortSettleMs: this.#idleAbortSettleMs,

package/src/agent/define-agent.ts

@@ -14,10 +14,18 @@ export interface AgentConfig {
   /**
    * Model id handed to `pi --model`. Unset = pi's default. An array is an ordered
    * fallback list, a function picks the next candidate from the failures so far,
-   * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`).
+   * and any pattern may carry an inline 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` (ADR-0037).
    */
   readonly model?: ModelSpec;
-  /** Thinking budget for the Agent's turns, as a level or a resolver. */
+  /**
+   * Thinking budget for the Agent's turns, as a level or a resolver. The
+   * resolver runs again for each attempt, with the model that settled for that
+   * attempt. A resolver kept in a definition is frozen policy, so it must stay
+   * pure and synchronous (ADR-0037).
+   */
   readonly thinking?: ThinkingSpec;
   /** Allow-list of tool names. Unset = pi's default tool set. */
   readonly tools?: readonly string[];
@@ -27,6 +35,13 @@ export interface AgentConfig {
   readonly skills?: readonly string[];
   /** Deny-list of skill names, applied after `skills`. */
   readonly disallowedSkills?: readonly string[];
+  /**
+   * Load the Effective Config's `agents.extensions` for Agents of this
+   * definition. Default true. A spawn's own `SpawnOptions.configExtensions`
+   * wins over this value; spawn *overrides* stay topology-only, so the opt-out
+   * is not one of them (ADR-0019, ADR-0040).
+   */
+  readonly configExtensions?: boolean;
   /** Ask options applied to every Ask on this Agent unless overridden per call. */
   readonly askDefaults?: AskOptions;
 }
@@ -47,7 +62,9 @@ const arrayFields = ["tools", "disallowedTools", "skills", "disallowedSkills"] a
  * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
  * appear — those are topology, chosen at spawn time, not baked into a definition.
  * The config is defensively copied and deep-frozen, so later mutation of the
- * caller's arrays cannot change the definition.
+ * caller's arrays cannot change the definition. `defineAgent` also copies and
+ * freezes a model array, so a later change of the caller's array cannot change
+ * Model Resolution (ADR-0037).
  */
 export function defineAgent(config: AgentConfig): AgentDefinition {
   if (typeof config.name !== "string" || config.name.trim() === "") {

package/src/agent/spawn-extensions.ts

@@ -0,0 +1,97 @@
+import type { ConfigExtension } from "../config/index.ts";
+import { resolveExtensionPaths } from "../extension/index.ts";
+
+/** Everything one spawn needs to turn declarations into `-e` arguments. */
+export interface SpawnExtensionRequest {
+  /** Effective Config entries in merge order: global → project → run (spec rule 3). */
+  readonly configExtensions: readonly ConfigExtension[];
+  /** `SpawnOptions.extensions`, resolved against the program file as before. */
+  readonly declared?: readonly string[] | undefined;
+  /** False when the spawn or its definition opted out (spec rule 7). */
+  readonly useConfigExtensions: boolean;
+  /** Orchestration Program source path, the base of a relative spawn declaration. */
+  readonly programFile?: string | undefined;
+  /** Agent working directory, the project install root for `npm:`/`git:`. */
+  readonly projectRoot: string;
+}
+
+/** The two projections of one Agent's extensions: what launches, and what identifies. */
+export interface SpawnExtensions {
+  /** Absolute launch-ready `-e` arguments, deduplicated, in final order. */
+  readonly resolvedPaths: readonly string[];
+  /** The surviving declarations behind them, same order, unresolved (ADR-0040). */
+  readonly declared: readonly string[];
+}
+
+/**
+ * Resolves the extensions of one Agent: config-sourced first, spawn-declared
+ * last, deduplicated by resolved path with the first occurrence keeping its
+ * place. Returns undefined when nothing is declared at all, so an
+ * extension-free spawn keeps its request shape.
+ *
+ * The two bases are deliberately different: a relative *path* from a config
+ * file resolves against that file's directory, while an `npm:`/`git:`
+ * specifier still installs from the Agent working directory (`projectRoot`).
+ * An uninstalled specifier passes through verbatim and dedups by its literal
+ * string.
+ *
+ * A declaration joins `declared` only when it contributed at least one new
+ * resolved path, so the identity list describes what actually ran. Two
+ * different declarations that resolve to the same path therefore keep only the
+ * first, which is machine-dependent by nature of the resolution itself.
+ */
+export async function resolveSpawnExtensions(
+  request: SpawnExtensionRequest,
+): Promise<SpawnExtensions | undefined> {
+  const entries = request.useConfigExtensions ? request.configExtensions : [];
+  if (request.declared === undefined && entries.length === 0) return undefined;
+  const resolved: { declaration: string; paths: readonly string[] }[] = [];
+  for (const entry of entries) {
+    resolved.push({
+      declaration: entry.declaration,
+      paths: await resolveConfigEntry(entry, request.projectRoot),
+    });
+  }
+  for (const declaration of request.declared ?? []) {
+    resolved.push({
+      declaration,
+      // One declaration per call: `resolveExtensionPaths` keeps no cross-entry
+      // state, so the loop preserves its order and its error messages.
+      paths: await resolveExtensionPaths([declaration], {
+        ...(request.programFile === undefined ? {} : { programFile: request.programFile }),
+        projectRoot: request.projectRoot,
+      }),
+    });
+  }
+  const seen = new Set<string>();
+  const resolvedPaths: string[] = [];
+  const declared: string[] = [];
+  for (const { declaration, paths } of resolved) {
+    let contributed = false;
+    for (const path of paths) {
+      if (seen.has(path)) continue;
+      seen.add(path);
+      resolvedPaths.push(path);
+      contributed = true;
+    }
+    if (contributed) declared.push(declaration);
+  }
+  return { resolvedPaths, declared };
+}
+
+/** Names the declaring config file, so a bad entry points at its own source. */
+async function resolveConfigEntry(
+  entry: ConfigExtension,
+  projectRoot: string,
+): Promise<readonly string[]> {
+  try {
+    return await resolveExtensionPaths([entry.declaration], {
+      baseDirectory: entry.baseDirectory,
+      projectRoot,
+    });
+  } catch (error) {
+    throw new Error(
+      `config "${entry.file}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/agent/spawn-request.ts

@@ -0,0 +1,70 @@
+import type { ModelSelection } from "../model/index.ts";
+import type { OpenOptions } from "../transport/index.ts";
+import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+
+/** Everything one spawn needs to build its open request, before a model settles. */
+export interface OpenRequestOptions {
+  readonly name: string;
+  readonly cwd: string;
+  readonly spawnOptions: SpawnOptions;
+  readonly resolvedExtensionPaths?: readonly string[];
+  readonly declaredExtensions?: readonly string[];
+  readonly sessionDir: string | undefined;
+}
+
+/**
+ * Builds one spawn's open request from its options.
+ *
+ * A caller that has not settled a model yet passes the declared options: the
+ * request then carries a literal `model`/`thinking` and carries none for an
+ * array or resolver spec. That request is what a Cassette-backed factory peeks
+ * at, which is why the resume peek blanks model and thinking before it compares
+ * the request with the recorded spawn (ADR-0039).
+ */
+export function openRequest(options: OpenRequestOptions): OpenOptions {
+  const spawnOptions = options.spawnOptions;
+  const model = typeof spawnOptions.model === "string" ? spawnOptions.model : undefined;
+  const thinking = typeof spawnOptions.thinking === "function" ? undefined : spawnOptions.thinking;
+  return {
+    cwd: options.cwd,
+    name: options.name,
+    ...(model === undefined ? {} : { model }),
+    ...(spawnOptions.systemPrompt === undefined ? {} : { systemPrompt: spawnOptions.systemPrompt }),
+    ...(thinking === undefined ? {} : { thinking }),
+    ...(spawnOptions.appendSystemPrompt === undefined
+      ? {}
+      : { appendSystemPrompt: spawnOptions.appendSystemPrompt }),
+    ...(spawnOptions.inherit === undefined ? {} : { inherit: spawnOptions.inherit }),
+    ...(spawnOptions.tools === undefined ? {} : { tools: spawnOptions.tools }),
+    ...(spawnOptions.disallowedTools === undefined
+      ? {}
+      : { disallowedTools: spawnOptions.disallowedTools }),
+    ...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
+    ...(spawnOptions.disallowedSkills === undefined
+      ? {}
+      : { disallowedSkills: spawnOptions.disallowedSkills }),
+    ...(options.resolvedExtensionPaths === undefined
+      ? {}
+      : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+    // An empty list means the same as no list at all, so it stays absent and an
+    // extension-free spawn keeps its recorded identity.
+    ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
+      ? {}
+      : { declaredExtensions: options.declaredExtensions }),
+    ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
+    ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
+  };
+}
+
+/** Replaces the caller's `model`/`thinking` forms with one attempt's settled selection. */
+export function withSelection(
+  options: SpawnOptions,
+  selection: ModelSelection,
+): ResolvedSpawnOptions {
+  const { model: _model, thinking: _thinking, ...rest } = options;
+  return {
+    ...rest,
+    ...(selection.model === undefined ? {} : { model: selection.model }),
+    ...(selection.thinking === undefined ? {} : { thinking: selection.thinking }),
+  };
+}

package/src/agent/spawn.ts

@@ -1,8 +1,14 @@
 import { resolve } from "node:path";
+import type { ConfigExtension } from "../config/index.ts";
 import { YaagError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
-import { resolveExtensionPaths } from "../extension/index.ts";
-import { normalizeModelResolution } from "../model/index.ts";
+import {
+  ModelErrorHistory,
+  type ModelSelection,
+  normalizeModelResolution,
+  resolveModel,
+  resolveRecordedModel,
+} from "../model/index.ts";
 import type { RunContext } from "../run/index.ts";
 import type { AgentTransport, TransportFactory, TransportStartup } from "../transport/index.ts";
 import type {
@@ -15,6 +21,8 @@ import type {
 import { Agent } from "./agent.ts";
 import { uniqueAgentName } from "./agent-names.ts";
 import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
+import { resolveSpawnExtensions } from "./spawn-extensions.ts";
+import { openRequest, withSelection } from "./spawn-request.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
@@ -23,6 +31,8 @@ export interface SpawnDependencies {
   readonly emit: EventSink;
   readonly sessionDir: string | undefined;
   readonly programFile: string | undefined;
+  /** Effective Config entries, in merge order; empty when the Run has no config. */
+  readonly configExtensions: readonly ConfigExtension[];
 }
 
 /** A RunContext spawn function that can synchronously stop accepting new Agents. */
@@ -48,16 +58,79 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
     const request = resolveRequest(definitionOrOptions, overrides);
     const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
     const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
-    const spawnOptions = resolveSpawnSelection(request.spawnOptions, name);
+    const resolution = normalizeModelResolution(request.spawnOptions);
+    // One history per Agent: its spawn loop and every mid-Ask fallback loop
+    // append to it, so a resolver sees every candidate that already failed.
+    const history = new ModelErrorHistory();
     try {
-      const opened = await openTransport({
-        factory: deps.factory,
-        name,
-        cwd,
-        spawnOptions,
-        sessionDir: deps.sessionDir,
-        programFile: deps.programFile,
+      // Extension paths do not vary per candidate, so a bad path fails once, generically.
+      const extensions = await resolveSpawnExtensions({
+        configExtensions: deps.configExtensions,
+        declared: request.spawnOptions.extensions,
+        useConfigExtensions: request.spawnOptions.configExtensions !== false,
+        ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
+        projectRoot: cwd,
+      }).catch((error: unknown) => {
+        if (error instanceof YaagError) throw error;
+        throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
       });
+      // One local for both open sites, so the launch arguments and the recorded
+      // identity cannot drift apart.
+      const extensionFields =
+        extensions === undefined
+          ? {}
+          : {
+              resolvedExtensionPaths: extensions.resolvedPaths,
+              declaredExtensions: extensions.declared,
+            };
+      const attempt = async (
+        selection: ModelSelection,
+      ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
+        const settled = withSelection(request.spawnOptions, selection);
+        return {
+          opened: await openTransport({
+            factory: deps.factory,
+            name,
+            cwd,
+            spawnOptions: settled,
+            ...extensionFields,
+            sessionDir: deps.sessionDir,
+          }),
+          spawnOptions: settled,
+        };
+      };
+      // The peek must stay in the same synchronous block as the first open: a
+      // Cassette-backed factory claims Agents in open order (ADR-0013).
+      const recorded = deps.factory.recordedSpawn?.(
+        openRequest({
+          name,
+          cwd,
+          spawnOptions: request.spawnOptions,
+          ...extensionFields,
+          sessionDir: deps.sessionDir,
+        }),
+      );
+      // A Cassette-backed spawn adopts the recorded resolved selection and skips
+      // the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
+      const adopted =
+        recorded === undefined ? undefined : resolveRecordedModel({ resolution, recorded });
+      // The adopted outcome carries the attempts the recording already spent, so
+      // a later mid-Ask fallback re-resolves from that attempt index (ADR-0039).
+      for (const skipped of adopted?.skipped ?? []) {
+        history.record(skipped.reason, skipped.failedModel);
+      }
+      const { opened, spawnOptions } =
+        adopted === undefined
+          ? await resolveModel({
+              resolution,
+              agent: name,
+              history,
+              onFallback: (fallback) => {
+                deps.emit({ type: "model_fallback", agent: name, ...fallback });
+              },
+              attempt,
+            })
+          : await attempt(adopted.selection);
       const resolvedCwd = opened.startup.worktree?.cwd ?? cwd;
       const branch = opened.startup.worktree?.branch;
       const sessionFile = opened.startup.sessionFile;
@@ -68,6 +141,11 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
         transport: opened.transport,
         emit: deps.emit,
         spawnOptions,
+        // An Agent that named no candidate inherits pi's default model, so a
+        // failing Ask has nothing to fall back from and stays an Ask failure.
+        ...(spawnOptions.model === undefined
+          ? {}
+          : { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
         ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
         ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
       });
@@ -100,23 +178,6 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   };
 }
 
-/**
- * Attempt-0 shim for Model Resolution: one selection, no retry loop.
- * Ticket 02 replaces this with the fallback loop and MODEL_RESOLUTION_FAILED.
- */
-function resolveSpawnSelection(options: SpawnOptions, name: string): ResolvedSpawnOptions {
-  const selection = normalizeModelResolution(options).resolve([]);
-  if (selection === undefined) {
-    throw new YaagError("SPAWN_FAILED", `agent "${name}": no model candidate to try`, name);
-  }
-  const { model: _model, thinking: _thinking, ...rest } = options;
-  return {
-    ...rest,
-    ...(selection.model === undefined ? {} : { model: selection.model }),
-    ...(selection.thinking === undefined ? {} : { thinking: selection.thinking }),
-  };
-}
-
 type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
 
 interface SpawnRequest {
@@ -145,6 +206,9 @@ function resolveRequest(
       ...(config.tools === undefined ? {} : { tools: config.tools }),
       ...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
       ...(config.skills === undefined ? {} : { skills: config.skills }),
+      ...(config.configExtensions === undefined
+        ? {}
+        : { configExtensions: config.configExtensions }),
       ...(config.disallowedSkills === undefined
         ? {}
         : { disallowedSkills: config.disallowedSkills }),
@@ -206,8 +270,9 @@ interface OpenTransportOptions {
   readonly name: string;
   readonly cwd: string;
   readonly spawnOptions: ResolvedSpawnOptions;
+  readonly resolvedExtensionPaths?: readonly string[];
+  readonly declaredExtensions?: readonly string[];
   readonly sessionDir: string | undefined;
-  readonly programFile: string | undefined;
 }
 
 interface OpenedTransport {
@@ -218,44 +283,19 @@ interface OpenedTransport {
 async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
   const startup: TransportStartup = {};
   try {
-    const resolvedExtensionPaths =
-      options.spawnOptions.extensions === undefined
-        ? undefined
-        : await resolveExtensionPaths(options.spawnOptions.extensions, {
-            ...(options.programFile === undefined ? {} : { programFile: options.programFile }),
-            projectRoot: options.cwd,
-          });
     const transport = await options.factory.open(
-      {
-        cwd: options.cwd,
+      openRequest({
         name: options.name,
-        ...(options.spawnOptions.model === undefined ? {} : { model: options.spawnOptions.model }),
-        ...(options.spawnOptions.systemPrompt === undefined
-          ? {}
-          : { systemPrompt: options.spawnOptions.systemPrompt }),
-        ...(options.spawnOptions.thinking === undefined
-          ? {}
-          : { thinking: options.spawnOptions.thinking }),
-        ...(options.spawnOptions.appendSystemPrompt === undefined
-          ? {}
-          : { appendSystemPrompt: options.spawnOptions.appendSystemPrompt }),
-        ...(options.spawnOptions.inherit === undefined
-          ? {}
-          : { inherit: options.spawnOptions.inherit }),
-        ...(options.spawnOptions.tools === undefined ? {} : { tools: options.spawnOptions.tools }),
-        ...(options.spawnOptions.disallowedTools === undefined
-          ? {}
-          : { disallowedTools: options.spawnOptions.disallowedTools }),
-        ...(options.spawnOptions.skills === undefined
+        cwd: options.cwd,
+        spawnOptions: options.spawnOptions,
+        ...(options.resolvedExtensionPaths === undefined
           ? {}
-          : { skills: options.spawnOptions.skills }),
-        ...(options.spawnOptions.disallowedSkills === undefined
+          : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+        ...(options.declaredExtensions === undefined
           ? {}
-          : { disallowedSkills: options.spawnOptions.disallowedSkills }),
-        ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
-        ...(options.spawnOptions.worktree === true ? { worktree: true } : {}),
-        ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
-      },
+          : { declaredExtensions: options.declaredExtensions }),
+        sessionDir: options.sessionDir,
+      }),
       (report) => Object.assign(startup, report),
     );
     return { transport, startup };

package/src/ask/ask-exchange-events.ts

@@ -1,4 +1,5 @@
 import type { AgentActivity, AskOutputChannel, EventSink } from "../events.ts";
+import type { ModelFallback } from "../model/index.ts";
 import type { NodeSnapshot } from "../node/index.ts";
 import { agentAskPath, childPath } from "../node/index.ts";
 import { promptGist } from "../prompt/index.ts";
@@ -13,7 +14,10 @@ export interface AskEndOutcome {
   readonly cause?: SettlementCause;
 }
 
-/** Emits the four Ask-scoped Lifecycle Events for one exchange. */
+/**
+ * Emits the Ask-scoped Lifecycle Events for one exchange, plus the Agent-scoped
+ * `model_fallback` this exchange's fallback loop reports.
+ */
 export class AskEvents {
   readonly #emit: EventSink;
   readonly #agent: string;
@@ -57,6 +61,11 @@ export class AskEvents {
     });
   };
 
+  /** Not Ask-scoped: a fallback names the Agent only, like the spawn-time loop. */
+  fallback = (fallback: ModelFallback): void => {
+    this.#emit({ type: "model_fallback", agent: this.#agent, ...fallback });
+  };
+
   /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
   end(outcome: AskEndOutcome): void {
     const { durationMs, ok, maxFrameGapMs, cause = "normal" } = outcome;

package/src/ask/ask-exchange-options.ts

@@ -1,5 +1,6 @@
 import type { ReportResultTool } from "../ask-contract/index.ts";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentTransport, Connection, Frame } from "../transport/index.ts";
 import type { ResolvedSpawnOptions } from "../types.ts";
 import type { EffectiveAskOptions } from "./ask-hash.ts";
@@ -9,6 +10,16 @@ export interface FrameObserver {
   observe(frame: Frame): void;
 }
 
+/** Mid-Ask Model Resolution for one Agent, shared with its spawn-time loop. */
+export interface AskModelFallback {
+  readonly resolution: ModelResolution;
+  readonly history: ModelErrorHistory;
+  /** The model candidate the Agent runs right now; a failure is attributed to it. */
+  currentModel(): string;
+  /** Reports the candidate a successful swap applied, and the model pi now reports. */
+  onSwapped(candidate: string, reportedModel: string): void;
+}
+
 /** Options that connect one Ask exchange to its Agent's identity and event stream. */
 export interface AskExchangeOptions {
   readonly agent: string;
@@ -25,6 +36,8 @@ export interface AskExchangeOptions {
   readonly emit: EventSink;
   /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
   readonly usage: FrameObserver;
+  /** Mid-Ask Model Resolution; absent when this Agent's spawn named no candidate. */
+  readonly modelFallback: AskModelFallback | undefined;
   /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
   readonly close: () => void;
   /** Test-only override for the fixed duration-limit grace. */