@yaag/runtime 0.9.0 → 0.11.0

package/src/agent/spawn.ts

@@ -1,28 +1,13 @@
-import { resolve } from "node:path";
 import type { ConfigExtension } from "../config/index.ts";
 import { YaagError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
-import {
-  ModelErrorHistory,
-  type ModelSelection,
-  normalizeModelResolution,
-  resolveModel,
-  resolveRecordedModel,
-} from "../model/index.ts";
 import type { RunContext } from "../run/index.ts";
-import type { AgentTransport, TransportFactory, TransportStartup } from "../transport/index.ts";
-import type {
-  AskOptions,
-  Handle,
-  ResolvedSpawnOptions,
-  SpawnOptions,
-  SpawnOverrides,
-} from "../types.ts";
-import { Agent } from "./agent.ts";
-import { uniqueAgentName } from "./agent-names.ts";
+import type { TransportFactory } from "../transport/index.ts";
+import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
+import type { Agent } from "./agent.ts";
 import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
-import { resolveSpawnExtensions } from "./spawn-extensions.ts";
-import { openRequest, withSelection } from "./spawn-request.ts";
+import { type ForkSpawner, forkRequest } from "./fork.ts";
+import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
@@ -50,125 +35,30 @@ export interface SpawnGate {
 export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   const taken = new Set<string>();
   let closed = false;
+  // Declared before use: every Agent this gate opens is handed the same fork
+  // spawner, so a fork is gated and named exactly like a spawn.
+  const forkSpawner: ForkSpawner = async (source, overrides) => {
+    if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
+    const request = forkRequest(source, overrides);
+    const handle = await openAgent(context, {
+      spawnOptions: request.spawnOptions,
+      parent: request.parent,
+      askDefaults: undefined,
+      definitionName: undefined,
+      fork: request.fork,
+    });
+    if (request.compact !== undefined && request.compact !== false) {
+      await handle.compact(typeof request.compact === "string" ? request.compact : undefined);
+    }
+    return handle;
+  };
+  const context: OpenAgentContext = { ...deps, taken, forkSpawner };
   const spawn: RunContext["spawn"] = async (
     definitionOrOptions: SpawnOptions | AgentDefinition = {},
     overrides?: SpawnOverrides,
   ): Promise<Handle> => {
     if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
-    const request = resolveRequest(definitionOrOptions, overrides);
-    const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
-    const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
-    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 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,
-            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,
-          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 } }),
-        ...(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 }),
-      });
-      return agent;
-    } catch (error) {
-      if (request.definitionName !== undefined && isSpawnFailure(error)) {
-        throw new YaagError(
-          "SPAWN_FAILED",
-          `definition "${request.definitionName}": ${error.message}`,
-          name,
-        );
-      }
-      throw error;
-    }
+    return openAgent(context, resolveRequest(definitionOrOptions, overrides));
   };
   return {
     spawn,
@@ -178,23 +68,26 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   };
 }
 
-type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
+/** Topology overrides after validation; `parent` stays raw for `resolveParent`. */
+type SpawnTopology = Omit<SpawnOverrides, "parent">;
+
+type MutableSpawnOverrides = { -readonly [Key in keyof SpawnTopology]: SpawnTopology[Key] };
 
-interface SpawnRequest {
-  readonly spawnOptions: SpawnOptions;
-  readonly askDefaults: AskOptions | undefined;
-  /** Definition identity stays separate from a topology-overridden Agent name. */
-  readonly definitionName: string | undefined;
+/** One validated override object: checked topology plus the unchecked Parent Link. */
+interface ValidatedOverrides {
+  readonly topology: SpawnTopology;
+  readonly parent: unknown;
 }
 
 function resolveRequest(
   definitionOrOptions: SpawnOptions | AgentDefinition,
   overrides: SpawnOverrides | undefined,
-): SpawnRequest {
+): OpenAgentRequest {
   if (!isAgentDefinition(definitionOrOptions)) {
-    return { spawnOptions: definitionOrOptions, askDefaults: undefined, definitionName: undefined };
+    const { parent, ...spawnOptions } = definitionOrOptions;
+    return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
   }
-  const topology = validateOverrides(overrides);
+  const { topology, parent } = validateOverrides(overrides);
   const config = agentDefinitionConfig(definitionOrOptions);
   return {
     spawnOptions: {
@@ -218,27 +111,32 @@ function resolveRequest(
           ? { systemPrompt: config.prompt }
           : { appendSystemPrompt: config.prompt }),
     },
+    parent,
     askDefaults: config.askDefaults,
     definitionName: config.name,
   };
 }
 
-function validateOverrides(overrides: unknown): SpawnOverrides {
-  if (overrides === undefined) return {};
+function validateOverrides(overrides: unknown): ValidatedOverrides {
+  if (overrides === undefined) return { topology: {}, parent: undefined };
   if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
     throw new TypeError(
       "spawn overrides must be an object: definitions own policy and spawn overrides own topology",
     );
   }
   for (const key of Object.keys(overrides)) {
-    if (key !== "name" && key !== "cwd" && key !== "worktree") {
+    if (key !== "name" && key !== "cwd" && key !== "worktree" && key !== "parent") {
       throw new TypeError(
         `spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
       );
     }
   }
   const topology: MutableSpawnOverrides = {};
+  // `parent` is never narrowed here: `resolveParent` owns that check, so the
+  // error text stays in one place and no unchecked value becomes a Handle.
+  let parent: unknown;
   for (const [key, value] of Object.entries(overrides)) {
+    if (key === "parent") parent = value;
     if (key === "name") {
       if (value !== undefined && typeof value !== "string") {
         throw new TypeError('spawn override "name" must be a string when present');
@@ -258,49 +156,5 @@ function validateOverrides(overrides: unknown): SpawnOverrides {
       topology.worktree = value;
     }
   }
-  return topology;
-}
-
-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 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 }),
-        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);
-  }
+  return { topology, parent };
 }

package/src/cassette/cassette-replay.ts

@@ -1,6 +1,13 @@
 import type { ReportedResult } from "../ask-contract/index.ts";
 import { isReportResultCommandFrame, ReportResultCall } from "../ask-contract/index.ts";
-import type { AgentStats, AskMarker, AskPlayback, Frame } from "../transport/index.ts";
+import type {
+  AgentStats,
+  AskMarker,
+  AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  Frame,
+} from "../transport/index.ts";
 import { FrameQueue } from "../transport/index.ts";
 import type { CassetteAgent } from "./cassette.ts";
 
@@ -92,6 +99,31 @@ export class CassetteReplay {
     };
   }
 
+  /**
+   * Moves playback to a compaction its caller has already identity-checked.
+   *
+   * A compaction lives between two Asks, and `beginAsk` never switches the
+   * cursors back to the Agent-level streams, so the recorded compaction owns
+   * its own streams (ADR-0043).
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback {
+    const compaction = this.#agent.compactions?.[marker.index];
+    if (!compaction) throw new Error("unreachable replay compaction cursor");
+    this.#sentCursor = 0;
+    this.#receivedCursor = 0;
+    this.#sent = compaction.sentFrames;
+    this.#received = compaction.receivedFrames;
+    this.#openAttempt(0);
+    return {
+      result: compaction.result ?? {
+        tokensBefore: null,
+        tokensAfter: null,
+        tokens: null,
+        cost: null,
+      },
+    };
+  }
+
   /** Ends the stream cleanly, allowing a caller to switch to another source. */
   finish(): void {
     this.#queue.end();

package/src/cassette/cassette-schema.ts

@@ -38,6 +38,10 @@ const CassetteSpawnSchema = Type.Object({
   ...spawnPolicyFields,
   worktree: Type.Optional(Type.Literal(true)),
   declaredExtensions: Type.Optional(StringArray),
+  parent: Type.Optional(Type.String()),
+  origin: Type.Optional(Type.Literal("fork")),
+  forkOf: Type.Optional(Type.String()),
+  forkAsks: Type.Optional(Type.Number()),
 });
 
 const ContextSpawnSchema = Type.Object({
@@ -118,6 +122,22 @@ const TokenBreakdownSchema = Type.Object({
   total: Type.Number(),
 });
 
+const CompactionResultSchema = Type.Object({
+  tokensBefore: Type.Union([Type.Null(), Type.Number()]),
+  tokensAfter: Type.Union([Type.Null(), Type.Number()]),
+  tokens: Type.Union([Type.Null(), TokenBreakdownSchema]),
+  cost: Type.Union([Type.Null(), Type.Number()]),
+});
+
+const CassetteCompactionSchema = Type.Object({
+  index: Type.Number(),
+  hash: Type.String(),
+  afterAsks: Type.Number(),
+  result: Type.Optional(CompactionResultSchema),
+  sentFrames: Type.Array(FrameSchema),
+  receivedFrames: Type.Array(FrameSchema),
+});
+
 const CassetteAgentSchema = Type.Object({
   spawn: CassetteSpawnSchema,
   model: Type.String(),
@@ -127,6 +147,7 @@ const CassetteAgentSchema = Type.Object({
   sentFrames: Type.Array(FrameSchema),
   receivedFrames: Type.Array(FrameSchema),
   asks: Type.Array(CassetteAskSchema),
+  compactions: Type.Optional(Type.Array(CassetteCompactionSchema)),
   stats: Type.Object({
     tokens: Type.Union([Type.Null(), TokenBreakdownSchema]),
     cost: Type.Union([Type.Null(), Type.Number()]),

package/src/cassette/cassette.ts

@@ -7,6 +7,8 @@ import type {
   AskInvalidOutputPlayback,
   AskMarker,
   AskMarkerContext,
+  CompactionMarker,
+  CompactionResult,
   Frame,
   OpenOptions,
   WorktreeResolution,
@@ -60,9 +62,23 @@ export interface CassetteAgent {
   readonly sentFrames: readonly Frame[];
   readonly receivedFrames: readonly Frame[];
   readonly asks: readonly CassetteAsk[];
+  /** Compactions between this Agent's Asks; absent for an Agent that compacted none. */
+  readonly compactions?: readonly CassetteCompaction[];
   readonly stats: AgentStats;
 }
 
+/** The frames attributed to one compaction marker (ADR-0043). */
+export interface CassetteCompaction {
+  readonly index: number;
+  readonly hash: string;
+  /** Settled Asks of this Agent at the compaction point. */
+  readonly afterAsks: number;
+  /** What the recorded compaction reported; absent when the exchange failed. */
+  readonly result?: CompactionResult;
+  readonly sentFrames: readonly Frame[];
+  readonly receivedFrames: readonly Frame[];
+}
+
 /** Behavioural identity supplied when opening a recorded Agent. */
 export interface CassetteSpawn {
   readonly name: string;
@@ -88,6 +104,17 @@ export interface CassetteSpawn {
    * across machines (ADR-0040). Absent when the Agent ran no extension.
    */
   readonly declaredExtensions?: readonly string[];
+  /**
+   * Resolved name of the Agent named as this Agent's parent (Parent Link).
+   * Part of spawn identity; absent for a root Agent and for older Cassettes.
+   */
+  readonly parent?: 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. */
+  readonly forkOf?: string;
+  /** Settled Asks of the fork source at the fork point. Spawn identity. */
+  readonly forkAsks?: number;
 }
 
 /** The frames attributed to one Ask marker. */
@@ -137,6 +164,8 @@ export interface CassetteRecorder {
   received(frame: Frame): void;
   beginAsk(marker: AskMarker): void;
   finishAsk(completion: AskCompletion): void;
+  beginCompaction(marker: CompactionMarker): void;
+  finishCompaction(result: CompactionResult | undefined): void;
   closed(stats: AgentStats): void;
 }
 
@@ -156,6 +185,15 @@ interface MutableAsk {
   recovered?: true;
 }
 
+interface MutableCompaction {
+  readonly index: number;
+  readonly hash: string;
+  readonly afterAsks: number;
+  readonly sentFrames: Frame[];
+  readonly receivedFrames: Frame[];
+  result?: CompactionResult;
+}
+
 interface MutableAgent {
   readonly spawn: CassetteSpawn;
   readonly model: string;
@@ -165,8 +203,10 @@ interface MutableAgent {
   readonly sentFrames: Frame[];
   readonly receivedFrames: Frame[];
   readonly asks: MutableAsk[];
+  readonly compactions: MutableCompaction[];
   stats: AgentStats;
-  active: MutableAsk | null;
+  /** The slot later frames belong to: one Ask, one compaction, or the Agent. */
+  active: MutableAsk | MutableCompaction | null;
 }
 
 /** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */
@@ -189,6 +229,7 @@ export class CassetteCollector implements CassetteSink {
           sentFrames: [],
           receivedFrames: [],
           asks: [],
+          compactions: [],
           stats: { tokens: null, cost: null },
           active: null,
         };
@@ -206,11 +247,24 @@ export class CassetteCollector implements CassetteSink {
         agent.active = ask;
       },
       finishAsk: (completion): void => {
-        if (!agent?.active) return;
-        if (completion.limit !== undefined) agent.active.limit = completion.limit;
-        if (completion.stalled !== undefined) agent.active.stalled = completion.stalled;
-        if (completion.invalidOutput !== undefined) agent.active.outcome = completion.invalidOutput;
-        if (completion.recovered === true) agent.active.recovered = true;
+        const ask = activeAsk(agent);
+        if (!ask) return;
+        if (completion.limit !== undefined) ask.limit = completion.limit;
+        if (completion.stalled !== undefined) ask.stalled = completion.stalled;
+        if (completion.invalidOutput !== undefined) ask.outcome = completion.invalidOutput;
+        if (completion.recovered === true) ask.recovered = true;
+      },
+      beginCompaction: (marker): void => {
+        if (!agent) return;
+        const compaction = { ...marker, sentFrames: [], receivedFrames: [] };
+        agent.compactions.push(compaction);
+        agent.active = compaction;
+      },
+      finishCompaction: (result): void => {
+        const compaction = agent?.compactions.at(-1);
+        if (compaction !== undefined && result !== undefined) compaction.result = result;
+        // Later frames belong to the Agent again, not to the compaction.
+        if (agent) agent.active = null;
       },
       closed: (stats): void => {
         if (agent) agent.stats = stats;
@@ -234,6 +288,7 @@ export class CassetteCollector implements CassetteSink {
             sentFrames,
             receivedFrames,
             asks,
+            compactions,
             stats,
           }) => ({
             spawn,
@@ -244,6 +299,9 @@ export class CassetteCollector implements CassetteSink {
             sentFrames,
             receivedFrames,
             asks,
+            // Absent for an Agent that compacted nothing, so every Cassette
+            // recorded before ADR-0043 keeps its byte-identical shape.
+            ...(compactions.length === 0 ? {} : { compactions }),
             stats,
           }),
         ),
@@ -272,10 +330,21 @@ function spawnIdentity(options: OpenOptions): CassetteSpawn {
     ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
       ? {}
       : { 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.worktree === true ? { worktree: true } : {}),
   };
 }
 
+/** The Ask that later frames belong to, or nothing when a compaction owns them. */
+function activeAsk(agent: MutableAgent | null): MutableAsk | null {
+  const active = agent?.active;
+  if (!active || "afterAsks" in active) return null;
+  return active;
+}
+
 function append(
   agent: MutableAgent | null,
   direction: "sentFrames" | "receivedFrames",

package/src/cassette/index.ts

@@ -10,6 +10,7 @@ export {
   type CassetteArtifact,
   type CassetteAsk,
   CassetteCollector,
+  type CassetteCompaction,
   type CassetteGit,
   type CassetteRun,
   type CassetteSink,

package/src/cassette/recording-transport.ts

@@ -4,6 +4,9 @@ import type {
   AskCompletion,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -87,6 +90,16 @@ class RecordingTransport implements AgentTransport {
     this.#inner.finishAsk(completion);
   }
 
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined {
+    this.#recorder.beginCompaction(marker);
+    return this.#inner.beginCompaction(marker);
+  }
+
+  finishCompaction(result: CompactionResult | undefined): void {
+    this.#recorder.finishCompaction(result);
+    this.#inner.finishCompaction(result);
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#inner.recordedExtractionPolicy?.(index);
   }