@yaag/extension 0.9.0 → 0.11.0

package/docs/authoring.md

@@ -113,3 +113,47 @@ 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).
+
+## Fork and compaction
+
+`handle.compact()` replaces an Agent's context with a summary of it, and
+reports the context size before and after. `handle.fork()` spawns a new Agent
+from a copy of this Agent's conversation: use it when one expensive Agent
+builds context that several cheap Agents need. Both need a settled Ask
+boundary, so a call during an Ask fails with `COMPACT_DURING_ASK` or
+`FORK_DURING_ASK`.
+
+- An Agent that exited cleanly stays forkable: build context, close the Agent,
+  then fork its final state. An Agent killed during an Ask fails `FORK_REFUSED`.
+- The fork inherits every spawn option of its source, including the concrete
+  model it settled on, but not its name. Pass any spawn option to change that.
+  The source becomes the fork's parent; pass `parent` to place it elsewhere.
+- `fork({ compact: true })` compacts the copy before you get the Handle; a
+  string becomes the compaction instructions.
+- A fork of a Worktree Agent gets its own worktree, branched from the source's
+  branch, so only committed work transfers. Forking needs a pi that supports
+  `pi --fork`. See [Examples](examples.md#07--fork-and-compaction).
+
+## 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/07-fork.ts

@@ -0,0 +1,29 @@
+/**
+ * Build context once, then work many times. The builder reads the repository;
+ * each worker forks the builder's conversation, so it starts with that context
+ * without paying to read the repository again.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+
+const TOPICS = ["error handling", "testing", "naming"] as const;
+
+export default defineRun({
+  name: "fork",
+  description: "Forks one context-building Agent into several cheap workers.",
+  async run(ctx) {
+    const builder = await ctx.spawn({ name: "builder" });
+    await builder.ask(prompt`
+      Read this repository and describe how it is organized. Report one
+      paragraph.
+    `);
+    const notes = await Promise.all(
+      TOPICS.map(async (topic) => {
+        // The fork inherits the builder's options and its whole conversation.
+        // `compact` summarizes that conversation before the worker starts.
+        const worker = await builder.fork({ name: topic.split(" ")[0], compact: true });
+        return worker.ask(prompt`From what you already read, report on ${topic}.`);
+      }),
+    );
+    return notes.join("\n\n");
+  },
+});

package/docs/examples.md

@@ -100,3 +100,35 @@ 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`.
+## 07 — fork and compaction
+
+One Agent reads the repository. Each worker forks that Agent, so it inherits
+the whole conversation instead of reading the repository again. `compact: true`
+summarizes the inherited context before the worker starts.
+
+<!-- embed: docs/examples/07-fork.ts -->
+
+```ts
+        const worker = await builder.fork({ name: topic.split(" ")[0], compact: true });
+        return worker.ask(prompt`From what you already read, report on ${topic}.`);
+```
+
+Full file: [`examples/07-fork.ts`](examples/07-fork.ts). Run it with
+`yaag run examples/07-fork.ts`.

package/docs/troubleshooting.md

@@ -103,6 +103,17 @@ Cause: `ASK_LIMIT` is a tripped soft budget (`maxTurns`, `maxToolCalls`,
 Fix: raise the budget, or add a `wrapUpPrompt`. After `ASK_LIMIT` the Handle is
 alive, so the program can ask again.
 
+## A fork or a compaction was refused
+
+Cause: `COMPACT_DURING_ASK` and `FORK_DURING_ASK` mean an Ask of that Agent was
+still in flight. Both operations need a settled Ask boundary. `FORK_REFUSED`
+means the Agent cannot be forked at all: it was killed during an Ask, so the
+end of its session is undefined, or it holds no session file, as a
+Cassette-playback Agent does. `COMPACT_FAILED` means pi refused the summary.
+
+Fix: await the Ask before you fork or compact. For `FORK_REFUSED`, fork an
+Agent that settled its last Ask, or spawn a fresh Agent instead.
+
 ## describe executes the module top level
 
 <!-- quote: @yaag/cli/src/argv.ts -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/extension",
-  "version": "0.9.0",
+  "version": "0.11.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.11.0",
+    "@yaag/runtime": "0.11.0",
+    "@yaag/tui": "0.11.0",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/docs-root.ts

@@ -18,13 +18,15 @@ 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",
+  "07-fork.ts",
 ] as const;
 
 /** Absolute path of one shipped doc file, named relative to the docs root. */

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

@@ -2,6 +2,7 @@ import type {
   AgentActivity,
   AgentInfo,
   AgentState,
+  CompactionInfo,
   ModelFallbackInfo,
   NodeInfo,
   NodeState,
@@ -58,6 +59,7 @@ interface SummaryBase {
   readonly durationMs: number;
   readonly worstFrameGapMs: number;
   readonly modelFallbacks: number;
+  readonly compactions: number;
 }
 
 function parseBase(stored: Record<string, unknown>): SummaryBase | null {
@@ -93,6 +95,7 @@ function parseBase(stored: Record<string, unknown>): SummaryBase | null {
     // Tolerant, unlike the strict fields above: a record written before the
     // fallback counter existed must still load instead of disappearing.
     modelFallbacks: typeof stored.modelFallbacks === "number" ? stored.modelFallbacks : 0,
+    compactions: typeof stored.compactions === "number" ? stored.compactions : 0,
   };
 }
 
@@ -150,9 +153,16 @@ 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,
+    // Tolerant as well: a record written before compaction carries neither field.
+    compactions: typeof stored.compactions === "number" ? stored.compactions : 0,
+    lastCompaction: parseCompaction(stored.lastCompaction),
   };
   if (state === "asking") {
     if (typeof stored.askIndex !== "number") return null;
@@ -171,6 +181,26 @@ function parseAgent(value: unknown): AgentInfo | null {
   return { ...base, state, askIndex: stored.askIndex, promptGist: stored.promptGist };
 }
 
+/** The newest compaction of one Agent, or null when the record holds none. */
+function parseCompaction(value: unknown): CompactionInfo | null {
+  const stored = asRecord(value);
+  if (stored === null) return null;
+  if (
+    !isNullableNumber(stored.tokensBefore) ||
+    !isNullableNumber(stored.tokensAfter) ||
+    !isNullableNumber(stored.cost) ||
+    !isNullableNumber(stored.at)
+  ) {
+    return null;
+  }
+  return {
+    tokensBefore: stored.tokensBefore,
+    tokensAfter: stored.tokensAfter,
+    cost: stored.cost,
+    at: stored.at,
+  };
+}
+
 function parseNodes(value: unknown): NodeInfo[] | null {
   if (!Array.isArray(value)) return null;
   const nodes: NodeInfo[] = [];

package/src/view/run-details.ts

@@ -82,9 +82,19 @@ function normalizeAgents(value: RunSummary): RunSummary {
       finishedNodesPruned: agent.finishedNodesPruned ?? 0,
       modelFallbacks: agent.modelFallbacks ?? [],
       modelFallbacksPruned: agent.modelFallbacksPruned ?? 0,
+      parent: agent.parent ?? null,
+      origin: normalizeOrigin(agent.origin),
+      // Absent in every message written before compaction shipped.
+      compactions: agent.compactions ?? 0,
+      lastCompaction: agent.lastCompaction ?? null,
     };
   }
-  return { ...value, agents, modelFallbacks: value.modelFallbacks ?? 0 };
+  return {
+    ...value,
+    agents,
+    modelFallbacks: value.modelFallbacks ?? 0,
+    compactions: value.compactions ?? 0,
+  };
 }
 
 function optionalNodes(value: unknown): boolean {
@@ -166,10 +176,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 +206,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 (