@yaag/runtime 0.9.0 → 0.11.0

package/src/transport/pi-state.ts

@@ -1,6 +1,12 @@
 import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "../ask-contract/index.ts";
 import { SYSTEM_PROMPT_RECORDER_EXTENSION_PATH } from "./system-prompt-recorder.ts";
-import type { AgentStats, Frame, OpenOptions, TokenBreakdown } from "./transport.ts";
+import type {
+  AgentStats,
+  CompactionResult,
+  Frame,
+  OpenOptions,
+  TokenBreakdown,
+} from "./transport.ts";
 
 /** What the Agent reported about its own work, read from a `get_state` probe. */
 export interface AgentProgress {
@@ -23,7 +29,10 @@ export function piCommand(options: OpenOptions, toolProbeExtensionPath?: string)
   }
   appendCapabilities(cmd, options, toolProbeExtensionPath);
   if (options.sessionDir) cmd.push("--session-dir", options.sessionDir);
+  // `--session` and `--fork` are mutually exclusive in pi, and a resume is the
+  // stronger claim: it names the very session this Agent must continue.
   if (options.sessionFile) cmd.push("--session", options.sessionFile);
+  else if (options.forkSession) cmd.push("--fork", options.forkSession);
   // No --approve: Agents inherit the user's saved project-trust decision (ADR-0009).
   return cmd;
 }
@@ -154,6 +163,47 @@ export function readStats(response: Frame): AgentStats {
   return { tokens: readBreakdown("tokens" in data ? data.tokens : null), cost };
 }
 
+/**
+ * What a `compact` response reports (ADR-0043).
+ *
+ * A missing field becomes null rather than 0, so "unknown" and "free" stay
+ * distinguishable: a custom compaction handler may answer without usage.
+ */
+export function readCompaction(response: Frame): CompactionResult {
+  const data: unknown = response.data;
+  if (typeof data !== "object" || data === null) {
+    return { tokensBefore: null, tokensAfter: null, tokens: null, cost: null };
+  }
+  const record: Record<string, unknown> = { ...data };
+  const usage: unknown = record.usage;
+  const usageRecord: Record<string, unknown> =
+    typeof usage === "object" && usage !== null ? { ...usage } : {};
+  const cost: unknown = usageRecord.cost;
+  return {
+    tokensBefore: typeof record.tokensBefore === "number" ? record.tokensBefore : null,
+    tokensAfter:
+      typeof record.estimatedTokensAfter === "number" ? record.estimatedTokensAfter : null,
+    tokens: readCompactionTokens(usageRecord),
+    cost:
+      typeof cost === "object" &&
+      cost !== null &&
+      typeof (cost as { total?: unknown }).total === "number"
+        ? (cost as { total: number }).total
+        : null,
+  };
+}
+
+/** The summary call's own token breakdown, or null when pi reported none. */
+function readCompactionTokens(usage: Record<string, unknown>): TokenBreakdown | null {
+  return readBreakdown({
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    total: usage.totalTokens,
+  });
+}
+
 function readBreakdown(tokens: unknown): TokenBreakdown | null {
   if (typeof tokens !== "object" || tokens === null) return null;
   const record: Record<string, unknown> = { ...tokens };

package/src/transport/transport.ts

@@ -31,6 +31,23 @@ export interface AgentStats {
   readonly cost: number | null;
 }
 
+/**
+ * What one compaction of an Agent's context reported (ADR-0043).
+ *
+ * Every field is null when pi reported nothing for it: a custom compaction
+ * handler may answer without usage, and "unknown" must stay distinct from 0.
+ */
+export interface CompactionResult {
+  /** Context tokens before the summary replaced the transcript. */
+  readonly tokensBefore: number | null;
+  /** Estimated context tokens after the summary replaced the transcript. */
+  readonly tokensAfter: number | null;
+  /** Token breakdown of the summary call itself. */
+  readonly tokens: TokenBreakdown | null;
+  /** Cost of the summary call itself. */
+  readonly cost: number | null;
+}
+
 /** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
 export interface AskMarkerContext {
   readonly prompt: string;
@@ -93,6 +110,27 @@ export interface AskCompletion {
   readonly recovered?: true;
 }
 
+/**
+ * Opaque marker naming one compaction of an Agent's context.
+ *
+ * A compaction sits between two Asks, so it cannot ride the Agent-level frame
+ * streams: a Cassette replay switches those cursors to an Ask and never
+ * switches back. The marker gives the exchange its own recorded streams.
+ */
+export interface CompactionMarker {
+  /** Monotonic per Agent, from 0. */
+  readonly index: number;
+  /** sha256 of the settled-Ask count and the custom instructions, when given. */
+  readonly hash: string;
+  /** Settled Asks of this Agent at the compaction point. */
+  readonly afterAsks: number;
+}
+
+/** Presence identifies Cassette playback of one compaction. */
+export interface CompactionPlayback {
+  readonly result: CompactionResult;
+}
+
 /** Presence identifies Cassette playback, including recorded successful Asks. */
 export interface AskPlayback {
   /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
@@ -143,6 +181,15 @@ export interface AgentTransport {
   /** Reports surfaced live outcomes; replay ignores completion. */
   finishAsk(completion: AskCompletion): void;
 
+  /**
+   * Begins one compaction. Live transports return undefined; replay transports
+   * return the recorded result.
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined;
+
+  /** Ends the compaction exchange, so later frames belong to the Agent again. */
+  finishCompaction(result: CompactionResult | undefined): void;
+
   /**
    * The extraction policy recorded for the Ask at `index`, when a Cassette
    * backs it. An Ask recorded under an older policy keeps that policy, so its
@@ -191,10 +238,31 @@ 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>`. */
   readonly sessionFile?: string;
+  /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
+  readonly origin?: "fork";
+  /** Name of the Agent this one was forked from. Spawn identity; never argv. */
+  readonly forkOf?: string;
+  /** Settled Asks of the fork source at the fork point. Spawn identity. */
+  readonly forkAsks?: number;
+  /**
+   * The fork source's session file, translated to `pi --fork <path>`.
+   * Never spawn identity: the path is machine-specific.
+   */
+  readonly forkSession?: string;
+  /**
+   * The fork source's worktree, so the fork branches from it instead of from a
+   * clean base tree. Never spawn identity.
+   */
+  readonly worktreeFrom?: WorktreeResolution;
 }
 
 /** Nondeterministic worktree identity resolved below the transport seam. */

package/src/transport/worktree-transport.ts

@@ -28,9 +28,17 @@ export function worktreeTransport(inner: TransportFactory): TransportFactory {
       observeStartup?: TransportStartupObserver,
     ): Promise<AgentTransport> {
       if (options.worktree !== true) return inner.open(options, observeStartup);
-      const root = await repositoryRoot(options.cwd, options.name);
-      await requireClean(root, options.name);
-      const resolution = await addWorktree({ root, name: options.name });
+      const from = options.worktreeFrom;
+      const root = await repositoryRoot(from?.cwd ?? options.cwd, options.name);
+      // A fork branches from what its source already committed, so the source's
+      // dirty files stay behind and no clean check applies (ADR-0044).
+      if (from === undefined) await requireClean(root, options.name);
+      const resolution = await addWorktree({
+        root,
+        name: options.name,
+        namingRoot: await namingRoot(root),
+        startPoint: from?.branch ?? "HEAD",
+      });
       const { worktree: _worktree, ...innerOptions } = options;
       let reported = false;
       const transport = await inner.open(
@@ -69,18 +77,43 @@ async function requireClean(cwd: string, name: string): Promise<void> {
   }
 }
 
-async function addWorktree(options: { readonly root: string; readonly name: string }): Promise<{
+/**
+ * The repository the worktree directory is named after.
+ *
+ * For a worktree it is the main repository, not the worktree itself, so a fork
+ * of a Worktree Agent does not nest `repo-worktrees/a1-worktrees/a2`.
+ */
+async function namingRoot(root: string): Promise<string> {
+  const result = await git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  const common = result.stdout.trim();
+  if (result.code !== 0 || common === "" || !common.endsWith("/.git")) return root;
+  return common.slice(0, -"/.git".length);
+}
+
+async function addWorktree(options: {
+  readonly root: string;
+  readonly name: string;
+  readonly namingRoot: string;
+  readonly startPoint: string;
+}): Promise<{
   readonly cwd: string;
   readonly branch: string;
 }> {
-  const parent = join(dirname(options.root), `${basename(options.root)}-worktrees`);
+  const parent = join(dirname(options.namingRoot), `${basename(options.namingRoot)}-worktrees`);
   await mkdir(parent, { recursive: true });
   for (let suffix = 1; ; suffix += 1) {
     const leaf = suffix === 1 ? options.name : `${options.name}-${suffix}`;
     const branch = `yaag/${leaf}`;
     const cwd = join(parent, leaf);
     if (await candidateTaken(options.root, branch, cwd)) continue;
-    const result = await git(options.root, ["worktree", "add", "-b", branch, cwd, "HEAD"]);
+    const result = await git(options.root, [
+      "worktree",
+      "add",
+      "-b",
+      branch,
+      cwd,
+      options.startPoint,
+    ]);
     if (result.code === 0) return { cwd, branch };
     if (isCollision(result)) continue;
     throw new Error(`git worktree add failed: ${result.stderr.trim() || result.stdout.trim()}`);

package/src/types.ts

@@ -1,7 +1,9 @@
 import type { Static, TSchema } from "typebox";
 import type { ModelSpec, ThinkingLevel, ThinkingSpec } from "./model/index.ts";
+import type { CompactionResult } from "./transport/index.ts";
 
 export type { ThinkingLevel } from "./model/index.ts";
+export type { CompactionResult } from "./transport/index.ts";
 
 /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
 export interface SpawnOptions {
@@ -66,6 +68,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,12 +80,35 @@ 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;
 }
 
+/**
+ * What a fork may change about the Agent it copies (ADR-0044).
+ *
+ * A fork inherits the source's resolved spawn options verbatim: model,
+ * thinking, tools, skills, system prompt, extensions and Ask defaults. `name`
+ * is the exception — the child always gets a fresh auto-name unless this object
+ * names one. The fork source becomes the child's default `parent`.
+ *
+ * The inherited model is the concrete one the source settled on, so the child
+ * never re-runs the source's fallback list; `fork({ model })` is the way out.
+ * A fork of a Worktree Agent gets its own fresh worktree, branched from the
+ * source's branch, so only committed state transfers. The child re-runs the
+ * ADR-0026 Tool Contract probe against its own effective options.
+ */
+export interface ForkOptions extends SpawnOptions {
+  /** true = pi's default compaction; a string = pi custom instructions. */
+  readonly compact?: boolean | string;
+}
+
 /** Topology-only fields that may change when spawning an Agent Definition. */
 export interface SpawnOverrides {
   /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
@@ -87,6 +117,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;
 }
 
 /**
@@ -190,4 +222,25 @@ export interface Handle {
     options: StructuredAskOptions<Schema>,
   ): Promise<Static<Schema>>;
   ask(prompt: string, options?: AskOptions): Promise<string>;
+
+  /**
+   * Spawns a new Agent from a copy of this Agent's session (ADR-0044).
+   *
+   * The fork point is a settled Ask boundary: a call while an Ask is in flight
+   * rejects with `FORK_DURING_ASK`. An Agent that died mid-Ask, or that holds
+   * no session file, rejects with `FORK_REFUSED`. An Agent that exited cleanly
+   * stays forkable, so a program can build context, let the Agent exit, then
+   * fork its final state many times.
+   */
+  fork(overrides?: ForkOptions): Promise<Handle>;
+
+  /**
+   * Replaces this Agent's context with a summary of it (ADR-0043).
+   *
+   * `instructions` becomes pi's `customInstructions`. A call while an Ask is in
+   * flight rejects with `COMPACT_DURING_ASK`; a refusal from pi rejects with
+   * `COMPACT_FAILED`. The result reports what the summary call cost; each field
+   * is null when pi reported nothing for it.
+   */
+  compact(instructions?: string): Promise<CompactionResult>;
 }