@yaag/runtime 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.9.0",
+  "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/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";

package/src/index.ts

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

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";
 
@@ -22,6 +22,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;
@@ -97,6 +101,8 @@ export function placeholderAgent(): IdleAgentInfo {
     cwd: null,
     branch: null,
     sessionFile: null,
+    parent: null,
+    origin: "spawn",
     state: "idle",
     askIndex: null,
     promptGist: null,
@@ -125,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 {
@@ -135,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,
     };
   }
@@ -144,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.ts

@@ -26,6 +26,7 @@ export type {
   IdleAgentInfo,
   ModelFallbackInfo,
   NodeInfo,
+  SpawnOrigin,
 } from "./summary-agent.ts";
 
 /** The observer-facing lifecycle state of a Run. */

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;
 }
 
 /**