@yaag/runtime 0.8.3 → 0.10.0

package/package.json

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

package/src/agent/spawn-parent.ts

@@ -0,0 +1,21 @@
+import type { Agent } from "./agent.ts";
+
+/**
+ * Resolves a Parent Link to the parent Agent's name.
+ *
+ * Only a Handle this Run already spawned is accepted, which is what makes a
+ * lineage cycle impossible by construction: a Handle exists only after its own
+ * spawn resolved. Liveness is deliberately not checked — a cleanly exited Agent
+ * remains a valid parent, because the link states tree position, not a
+ * dependency on a live process.
+ */
+export function resolveParent(parent: unknown, agents: readonly Agent[]): string | undefined {
+  if (parent === undefined) return undefined;
+  const known = agents.find((agent) => agent === parent);
+  if (known === undefined) {
+    throw new TypeError(
+      'spawn option "parent" must be a Handle returned by ctx.spawn() in this Run',
+    );
+  }
+  return known.name;
+}

package/src/agent/spawn-request.ts

@@ -9,6 +9,8 @@ export interface OpenRequestOptions {
   readonly spawnOptions: SpawnOptions;
   readonly resolvedExtensionPaths?: readonly string[];
   readonly declaredExtensions?: readonly string[];
+  /** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
+  readonly parent?: string;
   readonly sessionDir: string | undefined;
 }
 
@@ -51,6 +53,7 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
     ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
       ? {}
       : { declaredExtensions: options.declaredExtensions }),
+    ...(options.parent === undefined ? {} : { parent: options.parent }),
     ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
     ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
   };
@@ -61,7 +64,8 @@ export function withSelection(
   options: SpawnOptions,
   selection: ModelSelection,
 ): ResolvedSpawnOptions {
-  const { model: _model, thinking: _thinking, ...rest } = options;
+  // `parent` is dropped here as well: a Handle must never reach recorded options.
+  const { model: _model, thinking: _thinking, parent: _parent, ...rest } = options;
   return {
     ...rest,
     ...(selection.model === undefined ? {} : { model: selection.model }),

package/src/agent/spawn.ts

@@ -22,6 +22,7 @@ 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 { resolveParent } from "./spawn-parent.ts";
 import { openRequest, withSelection } from "./spawn-request.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
@@ -58,6 +59,8 @@ 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);
+    // Resolved before any transport work, so a bad Parent Link costs nothing.
+    const parent = resolveParent(request.parent, deps.agents);
     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.
@@ -94,6 +97,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
             cwd,
             spawnOptions: settled,
             ...extensionFields,
+            ...(parent === undefined ? {} : { parent }),
             sessionDir: deps.sessionDir,
           }),
           spawnOptions: settled,
@@ -107,6 +111,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
           cwd,
           spawnOptions: request.spawnOptions,
           ...extensionFields,
+          ...(parent === undefined ? {} : { parent }),
           sessionDir: deps.sessionDir,
         }),
       );
@@ -157,6 +162,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
         cwd: resolvedCwd,
         ...(branch === undefined ? {} : { branch }),
         ...(sessionFile === undefined ? {} : { sessionFile }),
+        ...(parent === undefined ? {} : { parent }),
       });
       return agent;
     } catch (error) {
@@ -178,10 +184,22 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   };
 }
 
-type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
+/** Topology overrides after validation; `parent` stays raw for `resolveParent`. */
+type SpawnTopology = Omit<SpawnOverrides, "parent">;
+
+type MutableSpawnOverrides = { -readonly [Key in keyof SpawnTopology]: SpawnTopology[Key] };
+
+/** One validated override object: checked topology plus the unchecked Parent Link. */
+interface ValidatedOverrides {
+  readonly topology: SpawnTopology;
+  readonly parent: unknown;
+}
 
 interface SpawnRequest {
+  /** Never carries `parent`: a Handle must not reach the recorded options. */
   readonly spawnOptions: SpawnOptions;
+  /** The raw Parent Link option, validated by `resolveParent`. */
+  readonly parent: unknown;
   readonly askDefaults: AskOptions | undefined;
   /** Definition identity stays separate from a topology-overridden Agent name. */
   readonly definitionName: string | undefined;
@@ -192,9 +210,10 @@ function resolveRequest(
   overrides: SpawnOverrides | undefined,
 ): SpawnRequest {
   if (!isAgentDefinition(definitionOrOptions)) {
-    return { spawnOptions: definitionOrOptions, askDefaults: undefined, definitionName: undefined };
+    const { parent, ...spawnOptions } = definitionOrOptions;
+    return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
   }
-  const topology = validateOverrides(overrides);
+  const { topology, parent } = validateOverrides(overrides);
   const config = agentDefinitionConfig(definitionOrOptions);
   return {
     spawnOptions: {
@@ -218,27 +237,32 @@ function resolveRequest(
           ? { systemPrompt: config.prompt }
           : { appendSystemPrompt: config.prompt }),
     },
+    parent,
     askDefaults: config.askDefaults,
     definitionName: config.name,
   };
 }
 
-function validateOverrides(overrides: unknown): SpawnOverrides {
-  if (overrides === undefined) return {};
+function validateOverrides(overrides: unknown): ValidatedOverrides {
+  if (overrides === undefined) return { topology: {}, parent: undefined };
   if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
     throw new TypeError(
       "spawn overrides must be an object: definitions own policy and spawn overrides own topology",
     );
   }
   for (const key of Object.keys(overrides)) {
-    if (key !== "name" && key !== "cwd" && key !== "worktree") {
+    if (key !== "name" && key !== "cwd" && key !== "worktree" && key !== "parent") {
       throw new TypeError(
         `spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
       );
     }
   }
   const topology: MutableSpawnOverrides = {};
+  // `parent` is never narrowed here: `resolveParent` owns that check, so the
+  // error text stays in one place and no unchecked value becomes a Handle.
+  let parent: unknown;
   for (const [key, value] of Object.entries(overrides)) {
+    if (key === "parent") parent = value;
     if (key === "name") {
       if (value !== undefined && typeof value !== "string") {
         throw new TypeError('spawn override "name" must be a string when present');
@@ -258,7 +282,7 @@ function validateOverrides(overrides: unknown): SpawnOverrides {
       topology.worktree = value;
     }
   }
-  return topology;
+  return { topology, parent };
 }
 
 function isSpawnFailure(error: unknown): error is YaagError {
@@ -272,6 +296,7 @@ interface OpenTransportOptions {
   readonly spawnOptions: ResolvedSpawnOptions;
   readonly resolvedExtensionPaths?: readonly string[];
   readonly declaredExtensions?: readonly string[];
+  readonly parent?: string;
   readonly sessionDir: string | undefined;
 }
 
@@ -294,6 +319,7 @@ async function openTransport(options: OpenTransportOptions): Promise<OpenedTrans
         ...(options.declaredExtensions === undefined
           ? {}
           : { declaredExtensions: options.declaredExtensions }),
+        ...(options.parent === undefined ? {} : { parent: options.parent }),
         sessionDir: options.sessionDir,
       }),
       (report) => Object.assign(startup, report),

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/cassette/cassette-schema.ts

@@ -38,6 +38,7 @@ const CassetteSpawnSchema = Type.Object({
   ...spawnPolicyFields,
   worktree: Type.Optional(Type.Literal(true)),
   declaredExtensions: Type.Optional(StringArray),
+  parent: Type.Optional(Type.String()),
 });
 
 const ContextSpawnSchema = Type.Object({

package/src/cassette/cassette.ts

@@ -88,6 +88,11 @@ export interface CassetteSpawn {
    * across machines (ADR-0040). Absent when the Agent ran no extension.
    */
   readonly declaredExtensions?: readonly string[];
+  /**
+   * Resolved name of the Agent named as this Agent's parent (Parent Link).
+   * Part of spawn identity; absent for a root Agent and for older Cassettes.
+   */
+  readonly parent?: string;
 }
 
 /** The frames attributed to one Ask marker. */
@@ -272,6 +277,7 @@ function spawnIdentity(options: OpenOptions): CassetteSpawn {
     ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
       ? {}
       : { declaredExtensions: [...options.declaredExtensions] }),
+    ...(options.parent === undefined ? {} : { parent: options.parent }),
     ...(options.worktree === true ? { worktree: true } : {}),
   };
 }

package/src/cassette/replay-divergence.ts

@@ -145,7 +145,12 @@ const SPAWN_IDENTITY_FIELDS = [
 ] as const;
 
 /** The spawn identity fields plus the Agent name, which only an open request carries. */
-const SPAWN_OPEN_FIELDS = ["name", ...SPAWN_IDENTITY_FIELDS, "declaredExtensions"] as const;
+const SPAWN_OPEN_FIELDS = [
+  "name",
+  ...SPAWN_IDENTITY_FIELDS,
+  "declaredExtensions",
+  "parent",
+] as const;
 
 /** The listed fields whose canonical JSON differs between two identity records. */
 function changedAmong<Key extends string>(
@@ -216,6 +221,7 @@ function spawnHash(options: CassetteSpawn | OpenOptions): string {
       ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
         ? {}
         : { declaredExtensions: options.declaredExtensions }),
+      ...(options.parent === undefined ? {} : { parent: options.parent }),
     }),
   );
   return hasher.digest("hex");

package/src/events.ts

@@ -20,6 +20,12 @@ export type { ModelErrorReason } from "./model/index.ts";
  */
 export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interrupted";
 
+/**
+ * How an Agent came to be. An absent value on an event means "spawn"; "fork"
+ * arrives with the forking spec.
+ */
+export type SpawnOrigin = "spawn" | "fork";
+
 /** The current, Ask-scoped observer projection derived from Agent frames. */
 export type AgentActivity =
   | { readonly type: "thinking" }
@@ -65,6 +71,10 @@ export type LifecycleEventBody =
        * Cassette-playback Agents and events from older CLIs.
        */
       readonly sessionFile?: string;
+      /** Resolved name of the Agent named as this Agent's parent (Parent Link). */
+      readonly parent?: string;
+      /** How the Agent came to be; absent means "spawn". */
+      readonly origin?: SpawnOrigin;
     }
   | {
       readonly type: "ask_start";
@@ -137,6 +147,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/index.ts

@@ -47,6 +47,7 @@ export type {
   LifecycleEventBody,
   NodeState,
   NodeUsage,
+  SpawnOrigin,
   StampedEventSink,
 } from "./events.ts";
 export type {

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/index.ts

@@ -20,4 +20,5 @@ export type {
   IdleAgentInfo,
   ModelFallbackInfo,
   NodeInfo,
+  SpawnOrigin,
 } from "./summary-agent.ts";

package/src/summary/summary-agent.ts

@@ -1,9 +1,9 @@
-import type { AgentActivity } from "../events.ts";
+import type { AgentActivity, SpawnOrigin } from "../events.ts";
 import type { TokenBreakdown, WorktreeResolution } from "../transport/index.ts";
 import type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 import type { NodeInfo } from "./summary-nodes.ts";
 
-export type { AgentActivity } from "../events.ts";
+export type { AgentActivity, SpawnOrigin } from "../events.ts";
 export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 export type { NodeInfo } from "./summary-nodes.ts";
 
@@ -12,11 +12,20 @@ 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;
   /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
   readonly sessionFile: string | null;
+  /** The Agent named as this one's parent (Parent Link), or null for a root Agent. */
+  readonly parent: string | null;
+  /** How the Agent came to be; "spawn" until forking ships. */
+  readonly origin: SpawnOrigin;
   readonly activity: AgentActivity | null;
   readonly tokens: TokenBreakdown | null;
   readonly cost: number | null;
@@ -92,6 +101,8 @@ export function placeholderAgent(): IdleAgentInfo {
     cwd: null,
     branch: null,
     sessionFile: null,
+    parent: null,
+    origin: "spawn",
     state: "idle",
     askIndex: null,
     promptGist: null,
@@ -120,6 +131,8 @@ export function spawnAgent(
     readonly cwd: string;
     readonly branch?: string;
     readonly sessionFile?: string;
+    readonly parent?: string;
+    readonly origin?: SpawnOrigin;
   },
   at: number | null,
 ): AgentRecord {
@@ -130,6 +143,8 @@ export function spawnAgent(
       cwd: identity.cwd,
       branch: identity.branch ?? null,
       sessionFile: identity.sessionFile ?? null,
+      parent: identity.parent ?? null,
+      origin: identity.origin ?? "spawn",
       stateChangedAt: at,
     };
   }
@@ -139,6 +154,11 @@ export function spawnAgent(
     cwd: current.cwd ?? identity.cwd,
     branch: current.branch ?? identity.branch ?? null,
     sessionFile: current.sessionFile ?? identity.sessionFile ?? null,
+    // Lineage follows the rule above it: a fact already folded wins, and a late
+    // spawn only fills what is still missing. `origin` has no missing value —
+    // it defaults to "spawn" — so the spawn event is its only authority.
+    parent: current.parent ?? identity.parent ?? null,
+    origin: identity.origin ?? current.origin,
   };
 }
 

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";
@@ -25,6 +26,7 @@ export type {
   IdleAgentInfo,
   ModelFallbackInfo,
   NodeInfo,
+  SpawnOrigin,
 } from "./summary-agent.ts";
 
 /** The observer-facing lifecycle state of a Run. */
@@ -152,6 +154,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 {

package/src/transport/transport.ts

@@ -191,6 +191,11 @@ export interface OpenOptions {
    * Spawn identity only: it never becomes argv, and it is absent when empty.
    */
   readonly declaredExtensions?: readonly string[];
+  /**
+   * Resolved name of the Agent named as this Agent's parent (Parent Link).
+   * Spawn identity only: it never becomes argv.
+   */
+  readonly parent?: string;
   /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
   readonly sessionDir?: string;
   /** Resumes an existing pi session, translated to `--session <path>`. */

package/src/types.ts

@@ -66,6 +66,11 @@ export interface SpawnOptions {
   readonly name?: string;
   /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
   readonly worktree?: boolean;
+  /**
+   * Names this Agent's parent in the Run tree (Parent Link). Data only: it is
+   * no conversation channel and no lifetime rule.
+   */
+  readonly parent?: Handle;
 }
 
 /**
@@ -73,8 +78,12 @@ export interface SpawnOptions {
  *
  * This is the settled shape, and it is what the Cassette identity hashes
  * (ADR-0039).
+ *
+ * `parent` is omitted on purpose: a Handle must never reach this shape, because
+ * an Ask records these options into the Cassette. Spawn resolves the Parent
+ * Link to a name, which travels in `OpenOptions` and stays out of Ask identity.
  */
-export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
+export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking" | "parent"> {
   readonly model?: string;
   readonly thinking?: ThinkingLevel;
 }
@@ -87,6 +96,8 @@ export interface SpawnOverrides {
   readonly cwd?: string;
   /** Request a fresh Git worktree. */
   readonly worktree?: boolean;
+  /** Names this Agent's parent in the Run tree (Parent Link). Data only. */
+  readonly parent?: Handle;
 }
 
 /**