@yaag/runtime 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },

package/src/agent/agent-compaction.ts

@@ -0,0 +1,80 @@
+import { agentError } from "../errors.ts";
+import type { EventSink } from "../events.ts";
+import type { AgentTransport, CompactionResult, Connection } from "../transport/index.ts";
+import { readCompaction } from "../transport/index.ts";
+import type { AgentUsage } from "./agent-usage.ts";
+
+/** One compaction of one Agent's context (ADR-0043). */
+export interface CompactionExchange {
+  readonly agent: string;
+  readonly connection: Connection;
+  readonly transport: AgentTransport;
+  /** Monotonic per Agent, from 0. */
+  readonly index: number;
+  /** Settled Asks of this Agent at the compaction point. */
+  readonly afterAsks: number;
+  /** pi `customInstructions`; the text never rides the wire (ticket 09). */
+  readonly instructions?: string;
+  readonly emit: EventSink;
+  readonly usage: AgentUsage;
+}
+
+/**
+ * Compacts one Agent's context and reports what the summary call cost.
+ *
+ * Playback answers from the Cassette and emits the same event, but folds no
+ * usage: a replayed Run never reports live accounting.
+ */
+export async function compactAgent(exchange: CompactionExchange): Promise<CompactionResult> {
+  const playback = exchange.transport.beginCompaction({
+    index: exchange.index,
+    hash: compactionHash(exchange.afterAsks, exchange.instructions),
+    afterAsks: exchange.afterAsks,
+  });
+  let result: CompactionResult | undefined;
+  try {
+    result = playback === undefined ? await live(exchange) : playback.result;
+  } finally {
+    exchange.transport.finishCompaction(result);
+  }
+  if (playback === undefined && result.tokens !== null && result.cost !== null) {
+    exchange.usage.add({ tokens: result.tokens, cost: result.cost });
+  }
+  exchange.emit({
+    type: "agent_compaction",
+    agent: exchange.agent,
+    index: exchange.index,
+    tokensBefore: result.tokensBefore,
+    tokensAfter: result.tokensAfter,
+    tokens: result.tokens,
+    cost: result.cost,
+    custom: exchange.instructions !== undefined,
+  });
+  return result;
+}
+
+/** Runs the pi `compact` command and parses what it reported. */
+async function live(exchange: CompactionExchange): Promise<CompactionResult> {
+  const response = await exchange.connection.command({
+    type: "compact",
+    ...(exchange.instructions === undefined ? {} : { customInstructions: exchange.instructions }),
+  });
+  if (!response.success) {
+    throw agentError(
+      exchange.agent,
+      "COMPACT_FAILED",
+      `compaction failed: ${response.error ?? "no reason reported"}`,
+    );
+  }
+  return readCompaction({ type: "response", data: response.data });
+}
+
+/**
+ * Identity of one compaction: where it sits in the Agent's conversation, and
+ * whether the program steered it. The instruction text is hashed, never stored.
+ */
+export function compactionHash(afterAsks: number, instructions: string | undefined): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(JSON.stringify({ afterAsks, instructions: instructions ?? null }));
+  return hasher.digest("hex");
+}

package/src/agent/agent-usage.ts

@@ -23,6 +23,17 @@ export class AgentUsage {
   observe(frame: Frame): void {
     const usage = usageFromFrame(frame);
     if (usage === null) return;
+    this.add(usage);
+  }
+
+  /**
+   * Folds one completion yaag observed outside the frame stream, and reports.
+   *
+   * A compaction's summary call is the only such completion today: pi answers
+   * it on the `compact` response instead of an assistant `message_end`, so the
+   * live accounting would lose that spend (ADR-0043).
+   */
+  add(usage: AgentUsageSnapshot): void {
     this.#tokens = {
       input: this.#tokens.input + usage.tokens.input,
       output: this.#tokens.output + usage.tokens.output,

package/src/agent/agent.ts

@@ -5,10 +5,23 @@ import { ReportResultTool } from "../ask-contract/index.ts";
 import { agentError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
 import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
-import type { AgentStats, AgentTransport } from "../transport/index.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  CompactionResult,
+  WorktreeResolution,
+} from "../transport/index.ts";
 import { Connection } from "../transport/index.ts";
-import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
+import type {
+  AskOptions,
+  ForkOptions,
+  Handle,
+  ResolvedSpawnOptions,
+  StructuredAskOptions,
+} from "../types.ts";
+import { compactAgent } from "./agent-compaction.ts";
 import { AgentUsage } from "./agent-usage.ts";
+import type { ForkSpawner } from "./fork.ts";
 
 /** The mid-Ask Model Resolution one Agent's spawn handed it (ADR-0038). */
 export interface AgentModelFallback {
@@ -32,6 +45,10 @@ export interface AgentOptions {
    * Absent when the spawn named no candidate: there is nothing to fall back from.
    */
   readonly modelFallback?: AgentModelFallback;
+  /** pi's session file for this Agent; a fork copies it. Absent during playback. */
+  readonly sessionFile?: string;
+  /** Opens a fork of this Agent through the Run's spawn gate (ADR-0044). */
+  readonly fork?: ForkSpawner;
   /** Definition-owned defaults merged below explicit per-Ask options. */
   readonly askDefaults?: AskOptions;
   /** Definition identity recorded on its Asks, outside replay identity. */
@@ -64,9 +81,13 @@ export class Agent implements Handle {
   #candidate: string;
   readonly #usage: AgentUsage;
   readonly #reportResultTool = new ReportResultTool();
+  readonly #sessionFile: string | undefined;
+  readonly #fork: ForkSpawner | undefined;
   #busy = false;
   #incomplete = false;
   #askIndex = 0;
+  #settledAsks = 0;
+  #compactionIndex = 0;
   #closing: Promise<AgentStats> | null = null;
 
   constructor(options: AgentOptions) {
@@ -81,6 +102,8 @@ export class Agent implements Handle {
     this.#spawnOptions = options.spawnOptions;
     this.#askDefaults = options.askDefaults ?? {};
     this.#definitionName = options.definitionName;
+    this.#sessionFile = options.sessionFile;
+    this.#fork = options.fork;
     this.#askLimitGraceMs = options.askLimitGraceMs;
     this.#idleAbortSettleMs = options.idleAbortSettleMs;
     this.#stallProbeSettleMs = options.stallProbeSettleMs;
@@ -144,9 +167,78 @@ export class Agent implements Handle {
       });
     } finally {
       this.#busy = false;
+      // A failed Ask settles the conversation as much as a successful one: the
+      // fork point is the boundary, not the outcome.
+      this.#settledAsks += 1;
     }
   }
 
+  /** Replaces this Agent's context with a summary of it (ADR-0043). */
+  compact(instructions?: string): Promise<CompactionResult> {
+    if (this.#connection.dead)
+      return Promise.reject(agentError(this.name, "AGENT_DIED", "agent is no longer running"));
+    if (this.#busy) {
+      return Promise.reject(
+        agentError(this.name, "COMPACT_DURING_ASK", "an Ask is in flight — compact between Asks"),
+      );
+    }
+    return compactAgent({
+      agent: this.name,
+      connection: this.#connection,
+      transport: this.#transport,
+      index: this.#compactionIndex++,
+      afterAsks: this.#settledAsks,
+      ...(instructions === undefined ? {} : { instructions }),
+      emit: this.#emit,
+      usage: this.#usage,
+    });
+  }
+
+  /** Spawns a new Agent from a copy of this Agent's session (ADR-0044). */
+  fork(overrides?: ForkOptions): Promise<Handle> {
+    const spawner = this.#fork;
+    if (spawner === undefined) {
+      return Promise.reject(
+        agentError(this.name, "FORK_REFUSED", "this Agent's Run cannot open a fork"),
+      );
+    }
+    if (this.#busy) {
+      return Promise.reject(
+        agentError(this.name, "FORK_DURING_ASK", "an Ask is in flight — fork between Asks"),
+      );
+    }
+    if (this.#incomplete) {
+      return Promise.reject(
+        agentError(
+          this.name,
+          "FORK_REFUSED",
+          "the Agent died mid-Ask, so the tail of its session is undefined",
+        ),
+      );
+    }
+    const sessionFile = this.#sessionFile;
+    if (sessionFile === undefined) {
+      return Promise.reject(
+        agentError(this.name, "FORK_REFUSED", "the Agent holds no session file to fork"),
+      );
+    }
+    return spawner(
+      {
+        name: this.name,
+        spawnOptions: this.#spawnOptions,
+        sessionFile,
+        worktree: this.#worktree(),
+        settledAsks: this.#settledAsks,
+        handle: this,
+      },
+      overrides,
+    );
+  }
+
+  #worktree(): WorktreeResolution | undefined {
+    return this.branch === undefined ? undefined : { cwd: this.cwd, branch: this.branch };
+  }
+
   /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */
   get incomplete(): boolean {
     return this.#incomplete;

package/src/agent/fork.ts

@@ -0,0 +1,74 @@
+import type { WorktreeResolution } from "../transport/index.ts";
+import type { ForkOptions, Handle, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+
+/** What one Agent hands the spawn gate when it is forked (ADR-0044). */
+export interface ForkSource {
+  readonly name: string;
+  /** The options the source settled on; the verbatim inheritance base. */
+  readonly spawnOptions: ResolvedSpawnOptions;
+  /** pi's session file for the source; a fork without one is refused. */
+  readonly sessionFile: string | undefined;
+  readonly worktree: WorktreeResolution | undefined;
+  /** Settled Asks of the source at the fork point. */
+  readonly settledAsks: number;
+  /** The source Handle itself, which becomes the fork's default Parent Link. */
+  readonly handle: Handle;
+}
+
+/** Opens one fork. The spawn gate owns it, so a fork walks the normal spawn path. */
+export type ForkSpawner = (source: ForkSource, overrides?: ForkOptions) => Promise<Handle>;
+
+/** Spawn identity and launch facts that only a fork carries. */
+export interface ForkIdentity {
+  readonly forkOf: string;
+  readonly forkAsks: number;
+  /** The session pi copies with `--fork`; machine-specific, never identity. */
+  readonly forkSession: string;
+  readonly worktreeFrom?: WorktreeResolution;
+}
+
+/** One fork request: what to spawn, whose child it is, and whether to compact it. */
+export interface ForkRequest {
+  /** Inherited options with the overrides applied; never carries `name`. */
+  readonly spawnOptions: SpawnOptions;
+  /** The raw Parent Link, defaulting to the fork source. */
+  readonly parent: unknown;
+  readonly fork: ForkIdentity;
+  readonly compact: boolean | string | undefined;
+}
+
+/**
+ * Merges a fork source with explicit overrides into one spawn request.
+ *
+ * Inheritance is verbatim, with two deliberate exceptions: `name` is dropped,
+ * so the child gets a fresh auto-name unless the overrides give it one, and
+ * `compact` never reaches the spawn options, because it is a fork verb rather
+ * than a property of the Agent.
+ */
+export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRequest {
+  if (source.sessionFile === undefined) {
+    throw new Error("a fork source must hold a session file");
+  }
+  const { name: _name, ...inherited } = source.spawnOptions;
+  const { compact, parent, ...explicit } = overrides ?? {};
+  return {
+    spawnOptions: { ...inherited, ...stripUndefined(explicit) },
+    parent: parent ?? source.handle,
+    fork: {
+      forkOf: source.name,
+      forkAsks: source.settledAsks,
+      forkSession: source.sessionFile,
+      ...(source.worktree === undefined ? {} : { worktreeFrom: source.worktree }),
+    },
+    compact,
+  };
+}
+
+/**
+ * Drops explicitly undefined overrides, so `fork({ model: undefined })` keeps
+ * the inherited value instead of erasing it.
+ */
+function stripUndefined(options: Omit<ForkOptions, "compact" | "parent">): SpawnOptions {
+  const entries = Object.entries(options).filter(([, value]) => value !== undefined);
+  return Object.fromEntries(entries) as SpawnOptions;
+}

package/src/agent/index.ts

@@ -10,4 +10,5 @@ export {
   defineAgent,
   isAgentDefinition,
 } from "./define-agent.ts";
+export { type ForkSource, type ForkSpawner, forkRequest } from "./fork.ts";
 export { makeSpawn } from "./spawn.ts";

package/src/agent/spawn-open.ts

@@ -0,0 +1,249 @@
+import { resolve } from "node:path";
+import { YaagError } from "../errors.ts";
+import {
+  ModelErrorHistory,
+  type ModelSelection,
+  normalizeModelResolution,
+  resolveModel,
+  resolveRecordedModel,
+} from "../model/index.ts";
+import type {
+  AgentTransport,
+  TransportFactory,
+  TransportStartup,
+  WorktreeResolution,
+} from "../transport/index.ts";
+import type { AskOptions, Handle, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+import { Agent } from "./agent.ts";
+import { uniqueAgentName } from "./agent-names.ts";
+import type { ForkIdentity, ForkSpawner } from "./fork.ts";
+import type { SpawnDependencies } from "./spawn.ts";
+import { resolveSpawnExtensions } from "./spawn-extensions.ts";
+import { resolveParent } from "./spawn-parent.ts";
+import { openRequest, withSelection } from "./spawn-request.ts";
+
+/** One request the open path serves: a plain spawn, or a fork of another Agent. */
+export interface OpenAgentRequest {
+  /** 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;
+  /** Present only for a fork; adds `origin: "fork"` and the `--fork` source. */
+  readonly fork?: ForkIdentity;
+}
+
+/** What the open path needs beyond the Run's spawn dependencies. */
+export interface OpenAgentContext extends SpawnDependencies {
+  /** Agent names already allocated in this Run. */
+  readonly taken: Set<string>;
+  /** How an opened Agent forks itself later. */
+  readonly forkSpawner: ForkSpawner;
+}
+
+/**
+ * Opens one Agent: resolves extensions and a model, starts its transport, and
+ * emits `agent_spawn`.
+ *
+ * A fork walks this very path, so the Tool Contract probe, Model Resolution,
+ * the worktree wrapper and the Cassette identity cannot drift between a spawn
+ * and a fork (ADR-0044).
+ */
+export async function openAgent(
+  deps: OpenAgentContext,
+  request: OpenAgentRequest,
+): Promise<Handle> {
+  const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
+  const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, deps.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.
+  const history = new ModelErrorHistory();
+  try {
+    // Extension paths do not vary per candidate, so a bad path fails once, generically.
+    const extensions = await resolveSpawnExtensions({
+      configExtensions: deps.configExtensions,
+      declared: request.spawnOptions.extensions,
+      useConfigExtensions: request.spawnOptions.configExtensions !== false,
+      ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
+      projectRoot: cwd,
+    }).catch((error: unknown) => {
+      if (error instanceof YaagError) throw error;
+      throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
+    });
+    // One local for both open sites, so the launch arguments and the recorded
+    // identity cannot drift apart.
+    const extensionFields =
+      extensions === undefined
+        ? {}
+        : {
+            resolvedExtensionPaths: extensions.resolvedPaths,
+            declaredExtensions: extensions.declared,
+          };
+    const forkFields =
+      request.fork === undefined
+        ? {}
+        : {
+            origin: "fork" as const,
+            forkOf: request.fork.forkOf,
+            forkAsks: request.fork.forkAsks,
+            forkSession: request.fork.forkSession,
+            ...(request.fork.worktreeFrom === undefined
+              ? {}
+              : { worktreeFrom: request.fork.worktreeFrom }),
+          };
+    const attempt = async (
+      selection: ModelSelection,
+    ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
+      const settled = withSelection(request.spawnOptions, selection);
+      return {
+        opened: await openTransport({
+          factory: deps.factory,
+          name,
+          cwd,
+          spawnOptions: settled,
+          ...extensionFields,
+          ...forkFields,
+          ...(parent === undefined ? {} : { parent }),
+          sessionDir: deps.sessionDir,
+        }),
+        spawnOptions: settled,
+      };
+    };
+    // The peek must stay in the same synchronous block as the first open: a
+    // Cassette-backed factory claims Agents in open order (ADR-0013).
+    const recorded = deps.factory.recordedSpawn?.(
+      openRequest({
+        name,
+        cwd,
+        spawnOptions: request.spawnOptions,
+        ...extensionFields,
+        ...forkFields,
+        ...(parent === undefined ? {} : { parent }),
+        sessionDir: deps.sessionDir,
+      }),
+    );
+    // A Cassette-backed spawn adopts the recorded resolved selection and skips
+    // the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
+    const adopted =
+      recorded === undefined ? undefined : resolveRecordedModel({ resolution, recorded });
+    // The adopted outcome carries the attempts the recording already spent, so
+    // a later mid-Ask fallback re-resolves from that attempt index (ADR-0039).
+    for (const skipped of adopted?.skipped ?? []) {
+      history.record(skipped.reason, skipped.failedModel);
+    }
+    const { opened, spawnOptions } =
+      adopted === undefined
+        ? await resolveModel({
+            resolution,
+            agent: name,
+            history,
+            onFallback: (fallback) => {
+              deps.emit({ type: "model_fallback", agent: name, ...fallback });
+            },
+            attempt,
+          })
+        : await attempt(adopted.selection);
+    const resolvedCwd = opened.startup.worktree?.cwd ?? cwd;
+    const branch = opened.startup.worktree?.branch;
+    const sessionFile = opened.startup.sessionFile;
+    const agent = new Agent({
+      name,
+      cwd: resolvedCwd,
+      branch,
+      transport: opened.transport,
+      emit: deps.emit,
+      spawnOptions,
+      // An Agent that named no candidate inherits pi's default model, so a
+      // failing Ask has nothing to fall back from and stays an Ask failure.
+      ...(spawnOptions.model === undefined
+        ? {}
+        : { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
+      ...(sessionFile === undefined ? {} : { sessionFile }),
+      fork: deps.forkSpawner,
+      ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
+      ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
+    });
+    deps.agents.push(agent);
+    deps.emit({
+      type: "agent_spawn",
+      agent: name,
+      model: agent.model,
+      cwd: resolvedCwd,
+      ...(branch === undefined ? {} : { branch }),
+      ...(sessionFile === undefined ? {} : { sessionFile }),
+      ...(parent === undefined ? {} : { parent }),
+      ...(request.fork === undefined ? {} : { origin: "fork" as const }),
+    });
+    return agent;
+  } catch (error) {
+    if (request.definitionName !== undefined && isSpawnFailure(error)) {
+      throw new YaagError(
+        "SPAWN_FAILED",
+        `definition "${request.definitionName}": ${error.message}`,
+        name,
+      );
+    }
+    throw error;
+  }
+}
+
+function isSpawnFailure(error: unknown): error is YaagError {
+  return error instanceof YaagError && error.code === "SPAWN_FAILED";
+}
+
+interface OpenTransportOptions {
+  readonly factory: TransportFactory;
+  readonly name: string;
+  readonly cwd: string;
+  readonly spawnOptions: ResolvedSpawnOptions;
+  readonly resolvedExtensionPaths?: readonly string[];
+  readonly declaredExtensions?: readonly string[];
+  readonly parent?: string;
+  readonly origin?: "fork";
+  readonly forkOf?: string;
+  readonly forkAsks?: number;
+  readonly forkSession?: string;
+  readonly worktreeFrom?: WorktreeResolution;
+  readonly sessionDir: string | undefined;
+}
+
+interface OpenedTransport {
+  readonly transport: AgentTransport;
+  readonly startup: TransportStartup;
+}
+
+async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
+  const startup: TransportStartup = {};
+  try {
+    const transport = await options.factory.open(
+      openRequest({
+        name: options.name,
+        cwd: options.cwd,
+        spawnOptions: options.spawnOptions,
+        ...(options.resolvedExtensionPaths === undefined
+          ? {}
+          : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+        ...(options.declaredExtensions === undefined
+          ? {}
+          : { declaredExtensions: options.declaredExtensions }),
+        ...(options.parent === undefined ? {} : { parent: options.parent }),
+        ...(options.origin === undefined ? {} : { origin: options.origin }),
+        ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
+        ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
+        ...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
+        ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
+        sessionDir: options.sessionDir,
+      }),
+      (report) => Object.assign(startup, report),
+    );
+    return { transport, startup };
+  } catch (error) {
+    if (error instanceof YaagError) throw error;
+    throw new YaagError("SPAWN_FAILED", `agent "${options.name}": ${String(error)}`, options.name);
+  }
+}

package/src/agent/spawn-request.ts

@@ -1,5 +1,5 @@
 import type { ModelSelection } from "../model/index.ts";
-import type { OpenOptions } from "../transport/index.ts";
+import type { OpenOptions, WorktreeResolution } from "../transport/index.ts";
 import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
 
 /** Everything one spawn needs to build its open request, before a model settles. */
@@ -11,6 +11,12 @@ export interface OpenRequestOptions {
   readonly declaredExtensions?: readonly string[];
   /** Resolved parent Agent name (Parent Link); spawn identity only, never argv. */
   readonly parent?: string;
+  /** Fork facts (ADR-0044); the first three are spawn identity, the rest are not. */
+  readonly origin?: "fork";
+  readonly forkOf?: string;
+  readonly forkAsks?: number;
+  readonly forkSession?: string;
+  readonly worktreeFrom?: WorktreeResolution;
   readonly sessionDir: string | undefined;
 }
 
@@ -54,6 +60,11 @@ export function openRequest(options: OpenRequestOptions): OpenOptions {
       ? {}
       : { declaredExtensions: options.declaredExtensions }),
     ...(options.parent === undefined ? {} : { parent: options.parent }),
+    ...(options.origin === undefined ? {} : { origin: options.origin }),
+    ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
+    ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
+    ...(options.forkSession === undefined ? {} : { forkSession: options.forkSession }),
+    ...(options.worktreeFrom === undefined ? {} : { worktreeFrom: options.worktreeFrom }),
     ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
     ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
   };