@yaag/extension 0.10.0 → 0.11.0

package/docs/authoring.md

@@ -114,6 +114,26 @@ 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

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

@@ -117,3 +117,18 @@ ever spawns anything itself.
 
 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.10.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.10.0",
-    "@yaag/runtime": "0.10.0",
-    "@yaag/tui": "0.10.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

@@ -26,6 +26,7 @@ export const EXAMPLE_FILES = [
   "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,
   };
 }
 
@@ -157,6 +160,9 @@ function parseAgent(value: unknown): AgentInfo | null {
     // 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;
@@ -175,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

@@ -84,9 +84,17 @@ function normalizeAgents(value: RunSummary): RunSummary {
       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 {