@yaag/runtime 0.9.0 → 0.11.0

package/src/cassette/replay-divergence.ts

@@ -2,6 +2,7 @@ import { YaagError } from "../errors.ts";
 import type {
   AskMarker,
   AskMarkerContext,
+  CompactionMarker,
   OpenOptions,
   RecordedSpawnSelection,
 } from "../transport/index.ts";
@@ -9,7 +10,13 @@ import type { CassetteAgent, CassetteAsk, CassetteSpawn } from "./cassette.ts";
 
 /** A pure description of the first strict replay identity mismatch. */
 export interface ReplayMismatch {
-  readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
+  readonly kind:
+    | "unexpected-spawn"
+    | "spawn-options"
+    | "changed-ask"
+    | "extra-ask"
+    | "changed-compaction"
+    | "extra-compaction";
   readonly agent: string;
   readonly index?: number;
   readonly expectedHash: string;
@@ -71,6 +78,32 @@ export const replayMismatch = {
               }),
         };
   },
+
+  compaction(
+    agent: CassetteAgent,
+    cursor: number,
+    actual: CompactionMarker,
+  ): ReplayMismatch | null {
+    const expected = agent.compactions?.[cursor];
+    if (!expected) {
+      return {
+        kind: "extra-compaction",
+        agent: agent.spawn.name,
+        index: actual.index,
+        expectedHash: "<none>",
+        actualHash: actual.hash,
+      };
+    }
+    return expected.index === actual.index && expected.hash === actual.hash
+      ? null
+      : {
+          kind: "changed-compaction",
+          agent: agent.spawn.name,
+          index: actual.index,
+          expectedHash: expected.hash,
+          actualHash: actual.hash,
+        };
+  },
 };
 
 /** Where a user reads what a Divergence means and what to do about it. */
@@ -86,7 +119,8 @@ export function strictReplay(mismatch: ReplayMismatch): never {
       mismatch.agent,
     );
   }
-  const at = mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`;
+  const at =
+    compactionAt(mismatch) ?? (mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`);
   const changed =
     mismatch.kind === "spawn-options" && mismatch.changedFields !== undefined
       ? ` changed ${mismatch.changedFields.join(", ")};`
@@ -98,6 +132,14 @@ export function strictReplay(mismatch: ReplayMismatch): never {
   );
 }
 
+/** Names the compaction seam of a compaction mismatch, or nothing for other kinds. */
+function compactionAt(mismatch: ReplayMismatch): string | undefined {
+  if (mismatch.kind !== "changed-compaction" && mismatch.kind !== "extra-compaction") {
+    return undefined;
+  }
+  return `compaction #${mismatch.index}`;
+}
+
 /** The identity fields a changed spawn altered, for the Divergence report (ADR-0039). */
 function spawnChangedFields(expected: CassetteSpawn, actual: OpenOptions): readonly string[] {
   return changedAmong(SPAWN_OPEN_FIELDS, expected, actual);
@@ -145,7 +187,15 @@ const SPAWN_IDENTITY_FIELDS = [
 ] as const;
 
 /** The spawn identity fields plus the Agent name, which only an open request carries. */
-const SPAWN_OPEN_FIELDS = ["name", ...SPAWN_IDENTITY_FIELDS, "declaredExtensions"] as const;
+const SPAWN_OPEN_FIELDS = [
+  "name",
+  ...SPAWN_IDENTITY_FIELDS,
+  "declaredExtensions",
+  "parent",
+  "origin",
+  "forkOf",
+  "forkAsks",
+] as const;
 
 /** The listed fields whose canonical JSON differs between two identity records. */
 function changedAmong<Key extends string>(
@@ -216,6 +266,11 @@ function spawnHash(options: CassetteSpawn | OpenOptions): string {
       ...(options.declaredExtensions === undefined || options.declaredExtensions.length === 0
         ? {}
         : { declaredExtensions: options.declaredExtensions }),
+      ...(options.parent === undefined ? {} : { parent: options.parent }),
+      // Conditional, so a Cassette recorded before forking keeps its hash.
+      ...(options.origin === undefined ? {} : { origin: options.origin }),
+      ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
+      ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
     }),
   );
   return hasher.digest("hex");

package/src/cassette/replay-transport.ts

@@ -3,6 +3,8 @@ import type {
   AgentTransport,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -30,7 +32,14 @@ export function replayTransport(cassette: Cassette): TransportFactory {
       const mismatch = replayMismatch.spawn(agent, options);
       if (mismatch) strictReplay(mismatch);
       spawnCursor += 1;
-      if (agent.worktree !== undefined) observeStartup?.({ worktree: agent.worktree });
+      // The recorded session file rides along, so a replayed Agent can be
+      // forked exactly where the recording forked it (ADR-0044).
+      if (agent.worktree !== undefined || agent.sessionFile !== undefined) {
+        observeStartup?.({
+          ...(agent.worktree === undefined ? {} : { worktree: agent.worktree }),
+          ...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
+        });
+      }
       return new ReplayTransport(new CassetteReplay(agent));
     },
 
@@ -46,6 +55,7 @@ class ReplayTransport implements AgentTransport {
   readonly model: string;
   readonly #replay: CassetteReplay;
   #askCursor = 0;
+  #compactionCursor = 0;
   #closed: Promise<AgentStats> | null = null;
 
   constructor(replay: CassetteReplay) {
@@ -72,6 +82,17 @@ class ReplayTransport implements AgentTransport {
     // A completed replay does not alter the recorded Cassette.
   }
 
+  beginCompaction(marker: CompactionMarker): CompactionPlayback {
+    const mismatch = replayMismatch.compaction(this.#replay.agent, this.#compactionCursor, marker);
+    if (mismatch) strictReplay(mismatch);
+    this.#compactionCursor += 1;
+    return this.#replay.beginCompaction(marker);
+  }
+
+  finishCompaction(): void {
+    // A completed replay does not alter the recorded Cassette.
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#replay.agent.asks[index]?.extractionPolicy;
   }

package/src/cassette/resume-transport.ts

@@ -4,6 +4,9 @@ import type {
   AskCompletion,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -64,6 +67,7 @@ class ResumeTransport implements AgentTransport {
   readonly #frames = new FrameQueue();
   readonly #buffered: Frame[] = [];
   #askCursor = 0;
+  #compactionCursor = 0;
   #mode: "replay" | "activating" | "live" = "replay";
   #live: AgentTransport | null = null;
   #activation: Promise<void> | null = null;
@@ -112,6 +116,27 @@ class ResumeTransport implements AgentTransport {
     if (this.#mode === "live") this.#live?.finishAsk(completion);
   }
 
+  /**
+   * A compaction the Cassette does not hold activates live, exactly as a
+   * diverged Ask does: the recorded prefix cannot answer it (ADR-0043).
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined {
+    if (this.#mode === "live") return this.#live?.beginCompaction(marker);
+    if (this.#mode === "activating") return undefined;
+    const mismatch = replayMismatch.compaction(this.#agent, this.#compactionCursor, marker);
+    if (!mismatch) {
+      this.#compactionCursor += 1;
+      return this.#replay.beginCompaction(marker);
+    }
+    this.#mode = "activating";
+    this.#activation = this.#activate(null);
+    return undefined;
+  }
+
+  finishCompaction(result: CompactionResult | undefined): void {
+    if (this.#mode === "live") this.#live?.finishCompaction(result);
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#mode === "replay" ? this.#agent.asks[index]?.extractionPolicy : undefined;
   }
@@ -121,7 +146,7 @@ class ResumeTransport implements AgentTransport {
     return this.#closed;
   }
 
-  async #activate(marker: AskMarker): Promise<void> {
+  async #activate(marker: AskMarker | null): Promise<void> {
     // End the old source before attaching the new one, but keep the outward
     // queue open so Connection remains attached across the handoff.
     this.#replay.finish();
@@ -131,7 +156,7 @@ class ResumeTransport implements AgentTransport {
     try {
       const live = await this.#liveFactory.open(this.#continuation);
       this.#live = live;
-      live.beginAsk(marker);
+      if (marker !== null) live.beginAsk(marker);
       for (const frame of this.#buffered.splice(0)) live.send(frame);
       this.#mode = "live";
       void this.#forward(live.frames());

package/src/errors.ts

@@ -44,6 +44,10 @@ export type YaagErrorCode =
   | "ASK_TIMEOUT" // timeoutMs elapsed
   | "ASK_LIMIT" // soft Ask budget exceeded after grace
   | "ASK_STALLED" // no frame arrived within the silence budget; escalated, then kill
+  | "COMPACT_DURING_ASK" // compact() was called while an Ask was in flight
+  | "COMPACT_FAILED" // pi refused or could not summarize the context
+  | "FORK_DURING_ASK" // fork() was called while the source Ask was in flight
+  | "FORK_REFUSED" // the fork source died mid-Ask, or holds no session file
   | "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
   | "ARGS_INVALID" // arguments failed schema validation before the Run started
   | "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema

package/src/events.ts

@@ -20,6 +20,12 @@ export type { ModelErrorReason } from "./model/index.ts";
  */
 export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interrupted";
 
+/**
+ * How an Agent came to be. An absent value on an event means "spawn"; "fork"
+ * marks an Agent created from a copy of another Agent's session (ADR-0044).
+ */
+export type SpawnOrigin = "spawn" | "fork";
+
 /** The current, Ask-scoped observer projection derived from Agent frames. */
 export type AgentActivity =
   | { readonly type: "thinking" }
@@ -65,6 +71,10 @@ export type LifecycleEventBody =
        * Cassette-playback Agents and events from older CLIs.
        */
       readonly sessionFile?: string;
+      /** Resolved name of the Agent named as this Agent's parent (Parent Link). */
+      readonly parent?: string;
+      /** How the Agent came to be; absent means "spawn". */
+      readonly origin?: SpawnOrigin;
     }
   | {
       readonly type: "ask_start";
@@ -159,6 +169,31 @@ export type LifecycleEventBody =
       /** Cumulative assistant-completion cost observed so far. */
       readonly cost: number;
     }
+  | {
+      /**
+       * One compaction of an Agent's context (ADR-0043).
+       *
+       * It carries the summary call's own spend, so a Run Summary does not
+       * silently lose it. `agent_exit` stays authoritative for the Agent's
+       * total: pi's `get_session_stats` already includes compaction spend.
+       * The custom instructions never ride the wire (ticket 09); only the
+       * `custom` flag says that the program supplied some.
+       */
+      readonly type: "agent_compaction";
+      readonly agent: string;
+      /** Monotonic per Agent, from 0. */
+      readonly index: number;
+      /** Context tokens before the summary replaced the transcript; null when unknown. */
+      readonly tokensBefore: number | null;
+      /** Estimated context tokens after the summary; null when unknown. */
+      readonly tokensAfter: number | null;
+      /** The summary call's own token breakdown; null when unknown. */
+      readonly tokens: TokenBreakdown | null;
+      /** The summary call's own cost; null when unknown. */
+      readonly cost: number | null;
+      /** The program supplied custom compaction instructions. */
+      readonly custom: boolean;
+    }
   | {
       readonly type: "agent_exit";
       readonly agent: string;

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
   CassetteAgent,
   CassetteArtifact,
   CassetteAsk,
+  CassetteCompaction,
   CassetteGit,
   CassetteRun,
   CassetteSink,
@@ -47,6 +48,7 @@ export type {
   LifecycleEventBody,
   NodeState,
   NodeUsage,
+  SpawnOrigin,
   StampedEventSink,
 } from "./events.ts";
 export type {
@@ -78,6 +80,7 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   EndedRunSummary,
   ExitedAgentInfo,
   IdleAgentInfo,
@@ -95,6 +98,9 @@ export type {
   AskMarker,
   AskMarkerContext,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   DiscoveredSkill,
   Frame,
   ReapPath,
@@ -109,6 +115,7 @@ export type {
 export { readSystemPromptSidecar, reap, worktreeTransport } from "./transport/index.ts";
 export type {
   AskOptions,
+  ForkOptions,
   Handle,
   ResolvedSpawnOptions,
   SpawnOptions,

package/src/summary/index.ts

@@ -16,8 +16,10 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
   ModelFallbackInfo,
   NodeInfo,
+  SpawnOrigin,
 } from "./summary-agent.ts";

package/src/summary/summary-agent.ts

@@ -1,12 +1,21 @@
-import type { AgentActivity } from "../events.ts";
+import type { AgentActivity, SpawnOrigin } from "../events.ts";
 import type { TokenBreakdown, WorktreeResolution } from "../transport/index.ts";
 import type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 import type { NodeInfo } from "./summary-nodes.ts";
 
-export type { AgentActivity } from "../events.ts";
+export type { AgentActivity, SpawnOrigin } from "../events.ts";
 export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 export type { NodeInfo } from "./summary-nodes.ts";
 
+/** What one compaction of an Agent's context reported (ADR-0043). */
+export interface CompactionInfo {
+  readonly tokensBefore: number | null;
+  readonly tokensAfter: number | null;
+  /** The summary call's own cost, already included in `agent_exit` accounting. */
+  readonly cost: number | null;
+  readonly at: number | null;
+}
+
 /** The observer-facing lifecycle state of an Agent. */
 export type AgentState = "idle" | "asking" | "exited";
 
@@ -22,6 +31,10 @@ interface AgentInfoBase {
   readonly branch: string | null;
   /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
   readonly sessionFile: string | null;
+  /** The Agent named as this one's parent (Parent Link), or null for a root Agent. */
+  readonly parent: string | null;
+  /** How the Agent came to be; "spawn" until forking ships. */
+  readonly origin: SpawnOrigin;
   readonly activity: AgentActivity | null;
   readonly tokens: TokenBreakdown | null;
   readonly cost: number | null;
@@ -30,6 +43,10 @@ interface AgentInfoBase {
   /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
   readonly usageUpdatedAt: number | null;
   readonly askStartedAt: number | null;
+  /** Compactions of this Agent's context so far (ADR-0043). */
+  readonly compactions: number;
+  /** What the newest compaction reported, or null when the Agent compacted none. */
+  readonly lastCompaction: CompactionInfo | null;
   /** This Agent's bounded Nested Node table, in first-seen order (spec §3). */
   readonly nodes: readonly NodeInfo[];
   /** Exited Nested Nodes dropped to keep the table bounded. */
@@ -97,6 +114,10 @@ export function placeholderAgent(): IdleAgentInfo {
     cwd: null,
     branch: null,
     sessionFile: null,
+    parent: null,
+    origin: "spawn",
+    compactions: 0,
+    lastCompaction: null,
     state: "idle",
     askIndex: null,
     promptGist: null,
@@ -125,6 +146,8 @@ export function spawnAgent(
     readonly cwd: string;
     readonly branch?: string;
     readonly sessionFile?: string;
+    readonly parent?: string;
+    readonly origin?: SpawnOrigin;
   },
   at: number | null,
 ): AgentRecord {
@@ -135,6 +158,8 @@ export function spawnAgent(
       cwd: identity.cwd,
       branch: identity.branch ?? null,
       sessionFile: identity.sessionFile ?? null,
+      parent: identity.parent ?? null,
+      origin: identity.origin ?? "spawn",
       stateChangedAt: at,
     };
   }
@@ -144,6 +169,11 @@ export function spawnAgent(
     cwd: current.cwd ?? identity.cwd,
     branch: current.branch ?? identity.branch ?? null,
     sessionFile: current.sessionFile ?? identity.sessionFile ?? null,
+    // Lineage follows the rule above it: a fact already folded wins, and a late
+    // spawn only fills what is still missing. `origin` has no missing value —
+    // it defaults to "spawn" — so the spawn event is its only authority.
+    parent: current.parent ?? identity.parent ?? null,
+    origin: identity.origin ?? current.origin,
   };
 }
 
@@ -249,6 +279,29 @@ export function setUsage(
   return { ...agent, tokens: observation.tokens, cost: observation.cost, usageUpdatedAt: at };
 }
 
+/**
+ * Counts one compaction and keeps what it reported.
+ *
+ * It folds no cost: the summary call's spend reaches the Summary through
+ * `agent_usage`, and `agent_exit` stays authoritative (ADR-0043). A terminal
+ * Agent still counts a late compaction, because the count is a fact about the
+ * conversation rather than a lifecycle state.
+ */
+export function compactAgent(
+  current: AgentRecord | undefined,
+  observation: CompactionInfo,
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  const stale =
+    at !== null && agent.lastCompaction?.at !== null && at < (agent.lastCompaction?.at ?? at);
+  return {
+    ...agent,
+    compactions: agent.compactions + 1,
+    lastCompaction: stale ? agent.lastCompaction : { ...observation, at },
+  };
+}
+
 /**
  * Folds authoritative shutdown accounting into the terminal Agent state.
  *

package/src/summary/summary.ts

@@ -3,6 +3,7 @@ import type { TokenBreakdown } from "../transport/index.ts";
 import type { AgentInfo } from "./summary-agent.ts";
 import {
   type AgentRecord,
+  compactAgent,
   endAsk,
   exitAgent,
   placeholderAgent,
@@ -22,10 +23,12 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
   ModelFallbackInfo,
   NodeInfo,
+  SpawnOrigin,
 } from "./summary-agent.ts";
 
 /** The observer-facing lifecycle state of a Run. */
@@ -50,6 +53,8 @@ interface RunSummaryBase {
   readonly worstFrameGapMs: number;
   /** Run-wide Model Resolution fallbacks, pruned per-Agent entries included. */
   readonly modelFallbacks: number;
+  /** Compactions across every Agent of this Run (ADR-0043). */
+  readonly compactions: number;
 }
 
 /** A Run that has not settled; it has neither outcome nor compatibility result. */
@@ -108,6 +113,7 @@ export function initialSummary(): RunningRunSummary {
     durationMs: 0,
     worstFrameGapMs: 0,
     modelFallbacks: 0,
+    compactions: 0,
     ok: null,
   };
 }
@@ -159,6 +165,21 @@ export function applyEvent(
         event.agent,
         applyAgentModel(summary.agents[event.agent] ?? placeholderAgent(), event),
       );
+    case "agent_compaction":
+      return withAgent(
+        { ...summary, compactions: summary.compactions + 1 },
+        event.agent,
+        compactAgent(
+          summary.agents[event.agent],
+          {
+            tokensBefore: event.tokensBefore,
+            tokensAfter: event.tokensAfter,
+            cost: event.cost,
+            at,
+          },
+          at,
+        ),
+      );
     case "agent_usage":
       return withAgent(summary, event.agent, setUsage(summary.agents[event.agent], event, at));
     case "ask_end":

package/src/transport/fake-transport.ts

@@ -6,7 +6,13 @@ import {
 import type { AvailableModel } from "../model/index.ts";
 import { FrameQueue } from "./frame-queue.ts";
 import { parseFrame } from "./jsonl.ts";
-import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  CompactionMarker,
+  Frame,
+} from "./transport.ts";
 
 /**
  * Scripted frame playback for one prompt sent through a FakeTransport.
@@ -50,6 +56,10 @@ export interface FakeTransportOptions extends FakePromptScript {
   readonly steerError?: string;
   /** Makes an abort RPC response fail without embedding a limit decision in playback. */
   readonly abortError?: string;
+  /** Payload of a `compact` command response; omission answers a bare success. */
+  readonly compaction?: Record<string, unknown>;
+  /** Makes a `compact` command response fail, as pi does when it cannot summarize. */
+  readonly compactError?: string;
   /** Makes the private report_result schema command fail. */
   readonly schemaCommandError?: string;
   /** The snapshot answered to `get_available_models`; defaults to this fake's own model. */
@@ -87,6 +97,7 @@ export class FakeTransport implements AgentTransport {
   /** Everything the runtime wrote, in order. */
   readonly sent: Frame[] = [];
   readonly asks: AskMarker[] = [];
+  readonly compactions: CompactionMarker[] = [];
   readonly #queue = new FrameQueue();
   readonly #options: FakeTransportOptions;
   #closed = false;
@@ -113,6 +124,7 @@ export class FakeTransport implements AgentTransport {
     if (frame.type === "abort") void this.#answerAbort(frame);
     if (frame.type === "get_last_assistant_text") this.#answerLastText(frame);
     if (frame.type === "get_state") this.#answerState(frame);
+    if (frame.type === "compact") this.#answerCompact(frame);
     if (frame.type === "get_available_models") this.#answerAvailableModels(frame);
     if (frame.type === "set_model") this.#answerSetModel(frame);
     if (frame.type === "set_thinking_level")
@@ -133,6 +145,15 @@ export class FakeTransport implements AgentTransport {
     // This live test transport does not persist Ask outcomes.
   }
 
+  beginCompaction(marker: CompactionMarker): undefined {
+    this.compactions.push(marker);
+    return undefined;
+  }
+
+  finishCompaction(): void {
+    // This live test transport does not persist compaction outcomes.
+  }
+
   /** True once the runtime shut this Agent down. */
   get closed(): boolean {
     return this.#closed;
@@ -295,6 +316,19 @@ export class FakeTransport implements AgentTransport {
     });
   }
 
+  #answerCompact(frame: Frame): void {
+    const error = this.#options.compactError;
+    this.#queue.push({
+      type: "response",
+      command: "compact",
+      id: frame.id,
+      success: error === undefined,
+      ...(error === undefined
+        ? { data: this.#options.compaction ?? { summary: "summary" } }
+        : { error }),
+    });
+  }
+
   #answerState(frame: Frame): void {
     if (this.#options.stateSilent === true) return;
     this.#queue.push({

package/src/transport/index.ts

@@ -17,7 +17,12 @@ export { FrameGapTracker } from "./frame-gap.ts";
 export { FrameQueue } from "./frame-queue.ts";
 export { decodeFrames } from "./jsonl.ts";
 export { liveTransport } from "./live-transport.ts";
-export { type AgentProgress, piCommand, readAgentProgress } from "./pi-state.ts";
+export {
+  type AgentProgress,
+  piCommand,
+  readAgentProgress,
+  readCompaction,
+} from "./pi-state.ts";
 export { type ReapPath, type ReapTarget, reap } from "./reap.ts";
 export { type DiscoveredSkill, liveSkillProbe, type SkillProbeFactory } from "./skill-probe.ts";
 export { skillRestrictionTransport } from "./skill-restriction-transport.ts";
@@ -34,6 +39,9 @@ export type {
   AskMarker,
   AskMarkerContext,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   TokenBreakdown,

package/src/transport/live-transport.ts

@@ -140,6 +140,15 @@ class LiveTransport implements AgentTransport {
     // Live transport has no Cassette outcome to complete.
   }
 
+  beginCompaction(): undefined {
+    // Nothing to do live; a recording implementation groups frames by this.
+    return undefined;
+  }
+
+  finishCompaction(): void {
+    // Live transport has no Cassette compaction to complete.
+  }
+
   close(): Promise<AgentStats> {
     this.#closing ??= this.#shutdown();
     return this.#closing;