@yaag/cli 0.8.3 → 0.10.0

package/assets/types/runtime/agent/spawn-parent.d.ts

@@ -0,0 +1,11 @@
+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 declare function resolveParent(parent: unknown, agents: readonly Agent[]): string | undefined;

package/assets/types/runtime/agent/spawn-request.d.ts

@@ -8,6 +8,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;
 }
 /**

package/assets/types/runtime/ask/ask-exchange-events.d.ts

@@ -12,7 +12,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 declare class AskEvents {
     #private;
@@ -24,6 +24,12 @@ export declare class AskEvents {
     node: (snapshot: NodeSnapshot) => void;
     /** Not Ask-scoped: a fallback names the Agent only, like the spawn-time loop. */
     fallback: (fallback: ModelFallback) => void;
+    /**
+     * 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;
     /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
     end(outcome: AskEndOutcome): void;
 }

package/assets/types/runtime/cassette/cassette-schema.d.ts

@@ -31,6 +31,7 @@ export declare const CassetteSchema: Type.TObject<{
             cwd: Type.TString;
             worktree: Type.TOptional<Type.TLiteral<true>>;
             declaredExtensions: Type.TOptional<Type.TArray<Type.TString>>;
+            parent: Type.TOptional<Type.TString>;
         }>;
         model: Type.TString;
         sessionFile: Type.TOptional<Type.TString>;

package/assets/types/runtime/cassette/cassette.d.ts

@@ -72,6 +72,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. */
 export interface CassetteAsk {

package/assets/types/runtime/events.d.ts

@@ -17,6 +17,11 @@ export type { ModelErrorReason } from "./model/index.ts";
  * settled Run never writes it (ADR-0031).
  */
 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 +70,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";
     readonly agent: string;
@@ -130,6 +139,19 @@ export type LifecycleEventBody = {
     readonly attempt: number;
     /** 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/assets/types/runtime/index.d.ts

@@ -6,7 +6,7 @@ export type { ConfigEnvironment, ConfigExtension, ConfigLayerName, EffectiveConf
 export { EMPTY_EFFECTIVE_CONFIG, loadEffectiveConfig, PROJECT_CONFIG_DIR, } from "./config/index.ts";
 export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, ModelResolutionOutcome, YaagErrorCode, } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
-export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";
+export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, SpawnOrigin, StampedEventSink, } from "./events.ts";
 export type { ModelError, ModelErrorReason, ModelResolver, ModelSelection, ModelSpec, ThinkingResolver, ThinkingSpec, } from "./model/index.ts";
 export type { DecodedNode, NodeDecoder, NodePath, NodeSnapshot } from "./node/index.ts";
 export { agentAskPath, childPath, DEFAULT_NODE_DECODERS, NodeTracker, sanitizeNodeName, } from "./node/index.ts";

package/assets/types/runtime/model/model-fallback.d.ts

@@ -6,7 +6,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;
 }
 /** Where a Model Resolution loop reports each fallback it takes. */

package/assets/types/runtime/summary/index.d.ts

@@ -3,4 +3,4 @@
  * Files inside this directory import each other directly.
  */
 export { applyEvent, type EndedRunSummary, initialSummary, type RunningRunSummary, type RunOutcome, type RunState, type RunSummary, } from "./summary.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, SpawnOrigin, } from "./summary-agent.ts";

package/assets/types/runtime/summary/summary-agent.d.ts

@@ -1,19 +1,28 @@
-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";
 /** The observer-facing lifecycle state of an Agent. */
 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;
@@ -85,6 +94,8 @@ export declare function spawnAgent(current: AgentRecord | undefined, identity: {
     readonly cwd: string;
     readonly branch?: string;
     readonly sessionFile?: string;
+    readonly parent?: string;
+    readonly origin?: SpawnOrigin;
 }, at: number | null): AgentRecord;
 /**
  * Folds an Ask start into the asking arm when it is not older than the folded

package/assets/types/runtime/summary/summary-fallbacks.d.ts

@@ -22,9 +22,8 @@ type ModelFallbackEvent = Extract<LifecycleEventBody, {
  * 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 declare function applyModelFallback(agent: AgentRecord, event: ModelFallbackEvent, at: number | null): AgentRecord;
 export {};

package/assets/types/runtime/summary/summary-model.d.ts

@@ -0,0 +1,16 @@
+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 declare function applyAgentModel(agent: AgentRecord, event: AgentModelEvent): AgentRecord;
+export {};

package/assets/types/runtime/summary/summary.d.ts

@@ -2,7 +2,7 @@ import type { LifecycleEvent, LifecycleEventBody, RunOutcome } from "../events.t
 import type { TokenBreakdown } from "../transport/index.ts";
 import type { AgentInfo } from "./summary-agent.ts";
 export type { NodeState, NodeUsage, RunOutcome } from "../events.ts";
-export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, SpawnOrigin, } from "./summary-agent.ts";
 /** The observer-facing lifecycle state of a Run. */
 export type RunState = "running" | "ended";
 /** Accounting and identity facts shared by all Run observer states. */

package/assets/types/runtime/transport/fake-transport.d.ts

@@ -45,6 +45,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. */

package/assets/types/runtime/transport/transport.d.ts

@@ -162,6 +162,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/assets/types/runtime/types.d.ts

@@ -64,14 +64,23 @@ 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;
 }
 /**
  * Spawn options after Model Resolution has settled one model and thinking level.
  *
  * 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;
 }
@@ -83,6 +92,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;
 }
 /**
  * Options for one Ask (ADR-0003).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.8.3",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.8.3",
-    "@yaag/tui": "0.8.3",
+    "@yaag/runtime": "0.10.0",
+    "@yaag/tui": "0.10.0",
     "typebox": "1.3.7"
   }
 }

package/src/terminal/render.ts

@@ -24,7 +24,7 @@ function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): str
     case "run_start":
       return `[yaag] run ${event.program}`;
     case "agent_spawn":
-      return `[${event.agent}] spawned ${event.model} in ${event.cwd}`;
+      return `[${event.agent}] spawned ${event.model} in ${event.cwd}${event.parent === undefined ? "" : ` under ${event.parent}`}`;
     case "ask_start":
       return `[${event.agent}] ask #${event.index + 1}${event.replayed === true ? " (replayed)" : ""}${event.promptGist === "" ? "" : ` — ${event.promptGist}`}`;
     case "ask_activity":
@@ -41,6 +41,8 @@ function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): str
     }
     case "model_fallback":
       return `[${event.agent}] model ${event.failedModel} ${event.reason} — falling back to ${event.resolvedModel}`;
+    case "agent_model":
+      return `[${event.agent}] model \u2014 now running ${event.model}`;
     case "agent_exit":
       return `[${event.agent}] exit ${tokens(event.tokens)} ${cost(event.cost)}${event.incomplete ? " (killed mid-ask, cost incomplete)" : ""}`;
     case "run_end": {
@@ -61,6 +63,7 @@ function minimalEvent(type: LifecycleEventBody["type"]): boolean {
     type === "ask_start" ||
     type === "ask_end" ||
     type === "model_fallback" ||
+    type === "agent_model" ||
     type === "agent_exit" ||
     type === "run_end"
   );