@yaag/cli 0.9.0 → 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/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;

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/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,8 +1,8 @@
-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. */
@@ -19,6 +19,10 @@ interface AgentInfoBase {
     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;
@@ -90,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.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/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.9.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.9.0",
-    "@yaag/tui": "0.9.0",
+    "@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":