@yaag/extension 0.9.0 → 0.10.0

package/docs/authoring.md

@@ -113,3 +113,27 @@ rules. ADR-0022 plans the human-in-the-loop verbs; they are not available yet.
 program again and replays the recorded Asks. A resume needs the program too,
 because a Cassette holds the history of a Run and never the program. See
 [Examples](examples.md#05--record-and-resume).
+
+## Lineage
+
+`parent` names the Agent a spawn belongs under. It is data only: it sets the
+Agent's place in the Run tree, so the TUI and the Run Summary draw the child
+under its parent. It opens no channel between the two Agents, and it ends no
+lifetime — every Agent still dies with the Run.
+
+`parent` takes a Handle a previous spawn in this Run returned, and it works the
+same way as an override on a definition: `ctx.spawn(reviewer, { parent })`. A
+parent that already exited stays a valid parent.
+
+An Agent cannot spawn. It can *ask* for a helper through `outputSchema`, and
+the program decides:
+
+<!-- embed: docs/examples/06-lineage.ts -->
+
+```ts
+    for (const helper of wish.helpers) {
+      if (!ALLOWED_ROLES.has(helper.role)) continue;
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+    }
+```

package/docs/examples/06-lineage.ts

@@ -0,0 +1,33 @@
+/**
+ * Mediated autonomy. The implementer reports which helpers it wants; the
+ * program is the gate that decides, spawns them, and places them in the tree
+ * under the implementer with `parent`.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+import { Type } from "typebox";
+
+const ALLOWED_ROLES = new Set(["reviewer", "summarizer"]);
+
+const Wish = Type.Object({
+  report: Type.String(),
+  helpers: Type.Array(Type.Object({ role: Type.String(), reason: Type.String() })),
+});
+
+export default defineRun({
+  name: "lineage",
+  description: "Spawns the helpers an implementer asks for, under the implementer.",
+  async run(ctx) {
+    const implementer = await ctx.spawn({ name: "implementer" });
+    const wish = await implementer.ask(
+      prompt`Report one paragraph about this repository, and the helper roles you want.`,
+      { outputSchema: Wish },
+    );
+    const reports: string[] = [];
+    for (const helper of wish.helpers) {
+      if (!ALLOWED_ROLES.has(helper.role)) continue;
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+    }
+    return [wish.report, ...reports].join("\n\n");
+  },
+});

package/docs/examples.md

@@ -100,3 +100,20 @@ holds it.
 Full file: [`examples/05-record-resume.ts`](examples/05-record-resume.ts). Run
 it with `yaag run examples/05-record-resume.ts --record run.json`, then resume
 it with `yaag run examples/05-record-resume.ts --resume run.json`.
+
+## 06 — lineage
+
+`parent` places an Agent under another Agent in the Run tree. Here the
+implementer reports the helper roles it wants, and the program decides which of
+them to spawn. The helpers become a subtree of the implementer, and no Agent
+ever spawns anything itself.
+
+<!-- embed: docs/examples/06-lineage.ts -->
+
+```ts
+      const agent = await ctx.spawn({ name: helper.role, parent: implementer });
+      reports.push(await agent.ask(prompt`Review this report: ${wish.report}`));
+```
+
+Full file: [`examples/06-lineage.ts`](examples/06-lineage.ts). Run it with
+`yaag run examples/06-lineage.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.9.0",
-    "@yaag/runtime": "0.9.0",
-    "@yaag/tui": "0.9.0",
+    "@yaag/cli": "0.10.0",
+    "@yaag/runtime": "0.10.0",
+    "@yaag/tui": "0.10.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/docs-root.ts

@@ -18,13 +18,14 @@ export const DOC_PAGES = [
   "troubleshooting.md",
 ] as const;
 
-/** The five shipped example programs, in reading order. */
+/** The shipped example programs, in reading order. */
 export const EXAMPLE_FILES = [
   "01-minimal.ts",
   "02-args.ts",
   "03-fan-out.ts",
   "04-controlled-ask.ts",
   "05-record-resume.ts",
+  "06-lineage.ts",
 ] as const;
 
 /** Absolute path of one shipped doc file, named relative to the docs root. */

package/src/record/run-summary-parse.ts

@@ -150,6 +150,10 @@ function parseAgent(value: unknown): AgentInfo | null {
     nodes,
     finishedNodesPruned: stored.finishedNodesPruned,
     modelFallbacks: fallbacks,
+    // Lineage is tolerant for the same reason as the counters: a record written
+    // before the Parent Link carries neither field.
+    parent: isNullableString(stored.parent) ? stored.parent : null,
+    origin: stored.origin === "fork" ? ("fork" as const) : ("spawn" as const),
     // Tolerant for the same reason as the Run-level counter.
     modelFallbacksPruned:
       typeof stored.modelFallbacksPruned === "number" ? stored.modelFallbacksPruned : 0,

package/src/view/run-details.ts

@@ -82,6 +82,8 @@ function normalizeAgents(value: RunSummary): RunSummary {
       finishedNodesPruned: agent.finishedNodesPruned ?? 0,
       modelFallbacks: agent.modelFallbacks ?? [],
       modelFallbacksPruned: agent.modelFallbacksPruned ?? 0,
+      parent: agent.parent ?? null,
+      origin: normalizeOrigin(agent.origin),
     };
   }
   return { ...value, agents, modelFallbacks: value.modelFallbacks ?? 0 };
@@ -166,10 +168,23 @@ function isAgentBase(value: Record<string, unknown>): boolean {
     optionalNodes(value.nodes) &&
     (value.finishedNodesPruned === undefined || natural(value.finishedNodesPruned)) &&
     optionalFallbacks(value.modelFallbacks) &&
-    (value.modelFallbacksPruned === undefined || natural(value.modelFallbacksPruned))
+    (value.modelFallbacksPruned === undefined || natural(value.modelFallbacksPruned)) &&
+    // Lineage is tolerated as absent: a details blob persisted before the
+    // Parent Link carries neither field.
+    (value.parent === undefined || nullableString(value.parent)) &&
+    (value.origin === undefined || typeof value.origin === "string")
   );
 }
 
+/**
+ * An origin a newer CLI may not have shipped yet reads as "spawn", the same way
+ * a stored Run record treats it. A value outside the contract must never drop
+ * the whole details blob and blank the Run view.
+ */
+function normalizeOrigin(value: unknown): "spawn" | "fork" {
+  return value === "fork" ? "fork" : "spawn";
+}
+
 function optionalEvent(value: unknown): value is LifecycleEvent | undefined {
   return value === undefined || isEvent(value);
 }
@@ -183,7 +198,9 @@ function isEvent(value: unknown): value is LifecycleEvent {
       return (
         strings(value.agent, value.model, value.cwd) &&
         optionalString(value.branch) &&
-        optionalString(value.sessionFile)
+        optionalString(value.sessionFile) &&
+        optionalString(value.parent) &&
+        (value.origin === undefined || typeof value.origin === "string")
       );
     case "ask_start":
       return (