@yaag/runtime 0.8.3 → 0.9.0

package/package.json

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

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

@@ -16,7 +16,7 @@ export interface AskEndOutcome {
 
 /**
  * Emits the Ask-scoped Lifecycle Events for one exchange, plus the Agent-scoped
- * `model_fallback` this exchange's fallback loop reports.
+ * `model_fallback` and `agent_model` this exchange's fallback loop reports.
  */
 export class AskEvents {
   readonly #emit: EventSink;
@@ -66,6 +66,15 @@ export class AskEvents {
     this.#emit({ type: "model_fallback", agent: this.#agent, ...fallback });
   };
 
+  /**
+   * The concrete model the Agent runs after a swap that landed (ADR-0041).
+   * Agent-scoped like `fallback`: the pattern side of the story stays in
+   * `model_fallback`, and this carries pi's own `provider/id`.
+   */
+  model = (model: string): void => {
+    this.#emit({ type: "agent_model", agent: this.#agent, model });
+  };
+
   /** 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.ts

@@ -112,6 +112,9 @@ class AskExchange {
           selection,
         });
         fallback.onSwapped(selection.model ?? swapped.model, swapped.model);
+        // Only a swap that landed reports a model: a refused `set_model` throws
+        // above and re-enters the loop, so the loop itself stays event-free.
+        this.#events.model(swapped.model);
       },
     });
   }

package/src/events.ts

@@ -137,6 +137,20 @@ export type LifecycleEventBody =
       /** The candidate resolution picked next. */
       readonly resolvedModel: string;
     }
+  | {
+      /**
+       * The concrete model an Agent runs from now on, reported when it changes
+       * after spawn. Today the only producer is a successful mid-Ask model swap
+       * (ADR-0038, ADR-0041): `model_fallback` names the pattern the resolver
+       * picked, this names the `provider/id` pi landed on, so `agent.model`
+       * stays concrete. Spawn needs none: `agent_spawn.model` is already
+       * concrete.
+       */
+      readonly type: "agent_model";
+      readonly agent: string;
+      /** pi's concrete `provider/id` for the model the Agent runs now. */
+      readonly model: string;
+    }
   | {
       readonly type: "agent_usage";
       readonly agent: string;

package/src/model/model-fallback.ts

@@ -7,7 +7,10 @@ export interface ModelFallback {
   readonly reason: ModelErrorReason;
   /** 0-based index of the failed attempt in the Agent's shared history. */
   readonly attempt: number;
-  /** The candidate the resolver picked next. */
+  /**
+   * The candidate the resolver picked next. It is a yaag pattern, not a
+   * concrete `provider/id`, so it is never an Agent's model (ADR-0041).
+   */
   readonly resolvedModel: string;
 }
 

package/src/summary/summary-agent.ts

@@ -12,6 +12,11 @@ export type AgentState = "idle" | "asking" | "exited";
 
 /** Identity and accounting facts that apply in every observer Agent state. */
 interface AgentInfoBase {
+  /**
+   * Always the concrete `provider/id` pi reports — from `agent_spawn` at spawn
+   * and from `agent_model` after every Model Fallback that landed (ADR-0041).
+   * A `resolvedModel` pattern never lands here.
+   */
   readonly model: string | null;
   readonly cwd: string | null;
   readonly branch: string | null;

package/src/summary/summary-fallbacks.ts

@@ -24,9 +24,8 @@ type ModelFallbackEvent = Extract<LifecycleEventBody, { readonly type: "model_fa
  * The Agent's `model` is left alone. `resolvedModel` is a yaag pattern, which
  * can be partial, and the event reports it before the swap is applied, while
  * `model` is pi's resolved `provider/id` for the model the Agent really runs.
- * `agent_spawn` is the only writer of that field: a mid-Ask swap updates the
- * Handle alone and reports no Lifecycle Event, so the Summary keeps the
- * spawn-time id.
+ * Only `agent_spawn` and `agent_model` write that field: a mid-Ask swap that
+ * lands reports the concrete model in its own `agent_model` event (ADR-0041).
  */
 export function applyModelFallback(
   agent: AgentRecord,

package/src/summary/summary-model.ts

@@ -0,0 +1,18 @@
+import type { LifecycleEventBody } from "../events.ts";
+import type { AgentRecord } from "./summary-agent.ts";
+
+type AgentModelEvent = Extract<LifecycleEventBody, { readonly type: "agent_model" }>;
+
+/**
+ * Folds the concrete model an Agent runs now (ADR-0041).
+ *
+ * The event reports pi's `provider/id` after a swap landed, so it replaces
+ * `model` and nothing else: a model change is not a lifecycle state change, and
+ * `state`, `askIndex`, `activity`, `stateChangedAt` and the bounded fallback
+ * table stay as they are. An exited Agent is skipped, because its model is
+ * frozen together with its final accounting.
+ */
+export function applyAgentModel(agent: AgentRecord, event: AgentModelEvent): AgentRecord {
+  if (agent.state === "exited") return agent;
+  return { ...agent, model: event.model };
+}

package/src/summary/summary.ts

@@ -13,6 +13,7 @@ import {
   totalsFromAgents,
 } from "./summary-agent.ts";
 import { applyModelFallback } from "./summary-fallbacks.ts";
+import { applyAgentModel } from "./summary-model.ts";
 import { applyNodeUpdate } from "./summary-nodes.ts";
 
 export type { NodeState, NodeUsage, RunOutcome } from "../events.ts";
@@ -152,6 +153,12 @@ export function applyEvent(
         event.agent,
         applyModelFallback(summary.agents[event.agent] ?? placeholderAgent(), event, at),
       );
+    case "agent_model":
+      return withAgent(
+        summary,
+        event.agent,
+        applyAgentModel(summary.agents[event.agent] ?? placeholderAgent(), event),
+      );
     case "agent_usage":
       return withAgent(summary, event.agent, setUsage(summary.agents[event.agent], event, at));
     case "ask_end":

package/src/transport/fake-transport.ts

@@ -54,6 +54,8 @@ export interface FakeTransportOptions extends FakePromptScript {
   readonly schemaCommandError?: string;
   /** The snapshot answered to `get_available_models`; defaults to this fake's own model. */
   readonly models?: readonly AvailableModel[];
+  /** The model this fake reports before any swap; defaults to a placeholder id. */
+  readonly model?: string;
   /** Makes a `set_model` command fail, as pi does for a pair it does not know. */
   readonly setModelError?: string;
   /** Makes a `set_thinking_level` command fail. */
@@ -75,7 +77,7 @@ export interface FakeTransportOptions extends FakePromptScript {
  * It never spawns or closes a real Agent process.
  */
 export class FakeTransport implements AgentTransport {
-  #model = "test/model";
+  #model: string;
 
   /** The model this fake currently reports, which a `set_model` swap updates. */
   get model(): string {
@@ -101,6 +103,7 @@ export class FakeTransport implements AgentTransport {
 
   constructor(options: FakeTransportOptions = {}) {
     this.#options = options;
+    this.#model = options.model ?? "test/model";
   }
 
   send(frame: Frame): void {