@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/storage-coordinator.ts

@@ -1,800 +0,0 @@
-/**
- * Runtime for `defineStorage` (`agent/storage.ts`).
- *
- * The coordinator is the single funnel between the engine's hot paths and
- * the author's key-value sink. The sink is four functions (`put` / `get` /
- * `delete` / `list`); the coordinator owns everything else: it mints every
- * key from the versioned scheme ({@link storageKeys}), coalesces
- * session records and batches event chunks per turn (or debounce window),
- * serializes delivery on one bounded queue per agent, and isolates
- * failures — a throwing sink is logged and its write dropped; storage
- * must never stall or fail a turn.
- *
- * Scaling shape: sessions reduce to keyed puts on the KV sink; eval runs
- * go to their dedicated `evals` table. Reminder documents live on the
- * control plane. Everything shares one bounded, serialized queue.
- *
- * It does three unrelated jobs, declared separately as
- * {@link FrameworkSessionStore}, {@link AuthorKvStore}, and
- * {@link EvalStore} — see `storage-roles.ts` for why they differ and where
- * each is headed. The queue stays shared: it is one bounded, serialized chain
- * per agent, and splitting it would change backpressure behavior, which this
- * seam deliberately does not touch.
- */
-
-import type { EvalRunSnapshot } from "../evals.js";
-import {
-  type ResolvedStoragePolicy,
-  resolveStoragePolicy,
-  type StorageContext,
-  type StorageDefinition,
-  type StorageEntry,
-  type StorageKeys,
-  storageKeys,
-} from "../storage.js";
-import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
-import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
-import { describeError } from "./describe-error.js";
-import type { EvalRunStorage } from "./eval-run-store.js";
-import type { AuthorKvStore, EvalStore, FrameworkSessionStore } from "./storage-roles.js";
-
-/** Event types that close a unit of work — persist + storage flush point. */
-export const TURN_BOUNDARY_EVENTS: ReadonlySet<SessionEvent["type"]> = new Set([
-  "turn.completed",
-  "turn.failed",
-  "session.waiting",
-  "session.completed",
-  "session.failed",
-]);
-
-export function isTurnBoundaryEvent(type: SessionEvent["type"]): boolean {
-  return TURN_BOUNDARY_EVENTS.has(type);
-}
-
-/** Boundaries after which no further turn updates the record: write it exactly. */
-const TERMINAL_SESSION_EVENTS: ReadonlySet<SessionEvent["type"]> = new Set([
-  "session.completed",
-  "session.failed",
-]);
-
-/**
- * Max writes waiting on the delivery queue before new ones are dropped.
- * At-most-once delivery already tolerates loss; bounding the queue keeps a
- * slow sink from growing memory without limit under sustained traffic.
- */
-const MAX_PENDING_OPS = 1_000;
-
-/**
- * How long {@link StorageCoordinator.close} waits for the sink to
- * drain before giving up. Keeps a hung sink from stalling shutdown past
- * the pod grace period (where a SIGKILL would lose the flush anyway).
- */
-const CLOSE_DRAIN_TIMEOUT_MS = 10_000;
-
-/** Debounced event batching flushes early past this many buffered events. */
-const DEBOUNCE_MAX_BATCH = 200;
-
-/** Cap on the per-session acked-record dedupe cache (oldest-out). */
-const MAX_ACKED_RECORDS = 5_000;
-
-/**
- * Cap on consecutive record rewrites skipped because only volatile
- * bookkeeping changed. Bounds how stale the durable copy's `turnCount` /
- * `updatedAt` can get: a crash loses at most this many turns of counters —
- * never resume state — while a long steady-state session stops paying one
- * record put per turn.
- */
-export const MAX_VOLATILE_RECORD_SKIPS = 20;
-
-/**
- * The record minus per-turn bookkeeping. When two records agree here, a
- * restore from the older durable copy resumes identically — continuation
- * keys, channel state, parked approvals, and staged one-shot inputs are all
- * equal — and only `turnCount` / `updatedAt` (display and ordering
- * metadata) would lag.
- */
-function resumeProjectionJson(record: SessionRecord): string {
-  return JSON.stringify({ ...record, turnCount: 0, updatedAt: "" });
-}
-
-/** One queued sink call (KV put/delete or a dedicated-table write). */
-interface StorageOp {
-  /** Human-readable op label for failure logs, e.g. `put({root}/...)`. */
-  label: string;
-  run: (ctx: StorageContext) => void | Promise<void>;
-}
-
-export interface StorageCoordinatorOptions {
-  definition: StorageDefinition;
-  agentName: string;
-  projectRoot: string;
-  logger: (line: string) => void;
-  /** Defaults to the architecture-v1 key contract. */
-  keys?: StorageKeys;
-}
-
-interface SessionBuffer {
-  events: SessionEvent[];
-  /** Coalesced latest record; only the newest at flush time is written. */
-  record?: SessionRecord;
-  debounceTimer?: ReturnType<typeof setTimeout>;
-}
-
-/** Session records out of raw sink entries; rows without a usable id are dropped. */
-function sessionRecordsOf(entries: readonly StorageEntry[]): SessionRecord[] {
-  return entries
-    .map(entry => entry.value as unknown as SessionRecord)
-    .filter(
-      record => record != null && typeof record.sessionId === "string" && record.sessionId !== "",
-    );
-}
-
-export class StorageCoordinator implements FrameworkSessionStore, AuthorKvStore, EvalStore {
-  readonly policy: ResolvedStoragePolicy;
-
-  private readonly definition: StorageDefinition;
-  private readonly keys: StorageKeys;
-  private readonly agentName: string;
-  private readonly projectRoot: string;
-  private readonly logger: (line: string) => void;
-  /** Per-session pending state (events + coalesced record). */
-  private readonly buffers = new Map<string, SessionBuffer>();
-  /**
-   * Last continuation key written to the sink per session, so a token
-   * change emits a delete for the stale index entry alongside the new put.
-   */
-  private readonly continuationIndex = new Map<string, string | null>();
-  /**
-   * The last session record each session **successfully** wrote — its full
-   * serialized form, its resume projection ({@link resumeProjectionJson}),
-   * how many rewrites were skipped since, and the newest skipped record
-   * (`skippedJson`) so an exact flush (terminal boundary, shutdown,
-   * coordination) can repair bookkeeping staleness even when the buffer no
-   * longer holds a record. A flush whose record is byte-identical skips
-   * the rewrite, and one whose record differs only in volatile bookkeeping
-   * skips it too (bounded by {@link MAX_VOLATILE_RECORD_SKIPS}); the
-   * record otherwise rides every flush, changed or not. Keyed on
-   * acknowledged writes only: a failed write clears the entry, so
-   * at-most-once delivery never turns into never-delivered. Bounded;
-   * eviction only costs a redundant rewrite.
-   */
-  private readonly lastAckedRecord = new Map<
-    string,
-    { json: string; projection: string; skips: number; skippedJson?: string }
-  >();
-  /** Single delivery chain: writes reach the sink serialized, in order. */
-  private queue: Promise<void> = Promise.resolve();
-  /** Ops on the queue not yet delivered (bounded by MAX_PENDING_OPS). */
-  private pending = 0;
-  /** Ops dropped because the queue was full. */
-  private dropped = 0;
-  private closed = false;
-
-  constructor(options: StorageCoordinatorOptions) {
-    this.definition = options.definition;
-    this.keys = options.keys ?? storageKeys;
-    this.policy = resolveStoragePolicy(options.definition.policy);
-    this.agentName = options.agentName;
-    this.projectRoot = options.projectRoot;
-    this.logger = options.logger;
-  }
-
-  // ==========================================================================
-  // Sessions (writes)
-  // ==========================================================================
-
-  /** Durable session-record update (engine calls after every store save). */
-  sessionRecord(record: SessionRecord): void {
-    if (this.closed) {
-      return;
-    }
-    // Coalesced: only the newest record at flush time reaches the sink.
-    this.buffer(record.sessionId).record = record;
-  }
-
-  /** One appended session event (engine calls from its dispatch funnel). */
-  event(event: SessionEvent): void {
-    if (this.closed) {
-      return;
-    }
-    const buffer = this.buffer(event.sessionId);
-    buffer.events.push(event);
-    const events = this.policy.events;
-    if (events !== "turnEnd") {
-      // Debounce spans turn boundaries by design ("flush when the session
-      // goes quiet", not once per turn); the coalesced record rides the
-      // same debounced flush.
-      if (buffer.events.length >= DEBOUNCE_MAX_BATCH) {
-        this.flushSession(event.sessionId);
-      } else {
-        this.armDebounce(event.sessionId, buffer, events.debounceMs);
-      }
-    }
-    // Turn boundaries do NOT flush here: the boundary event's own handlers
-    // (and their record updates) haven't run yet. The engine calls
-    // eventDispatched() once dispatch settles — that's the flush point.
-  }
-
-  /**
-   * A boundary event's dispatch settled: channel/hook handlers ran and
-   * their record updates (channel state, continuation tokens) are
-   * buffered. This — not the append — is the turn-end flush point, so the
-   * persisted session record includes the boundary event's own handler
-   * mutations. Debounced batching intentionally ignores boundaries.
-   */
-  eventDispatched(event: SessionEvent): void {
-    if (this.closed || this.policy.events !== "turnEnd" || !TURN_BOUNDARY_EVENTS.has(event.type)) {
-      return;
-    }
-    this.flushSessionInternal(event.sessionId, "policy", TERMINAL_SESSION_EVENTS.has(event.type));
-  }
-
-  /** Flush everything buffered for one session (ordered: events, record). */
-  flushSession(sessionId: string, reason: StorageContext["reason"] = "policy"): void {
-    // Non-policy flushes (shutdown, coordination, restore) are drains around
-    // a lifecycle edge: write the record exactly rather than skip on a
-    // volatile-only diff.
-    this.flushSessionInternal(sessionId, reason, reason !== "policy");
-  }
-
-  private flushSessionInternal(
-    sessionId: string,
-    reason: StorageContext["reason"],
-    exactRecord: boolean,
-  ): void {
-    const buffer = this.buffers.get(sessionId);
-    const acked = this.lastAckedRecord.get(sessionId);
-    if (buffer === undefined && !(exactRecord && acked?.skippedJson !== undefined)) {
-      return;
-    }
-    this.buffers.delete(sessionId);
-    if (buffer?.debounceTimer !== undefined) {
-      clearTimeout(buffer.debounceTimer);
-    }
-    const events = buffer?.events ?? [];
-    // A terminal event can arrive through a debounce-policy timer flush,
-    // where eventDispatched never ran: detect it from the buffered events
-    // so a finished session's record is exact under either policy.
-    const exact = exactRecord || events.some(event => TERMINAL_SESSION_EVENTS.has(event.type));
-    // Exact flushes repair earlier volatile-only skips: when the buffer no
-    // longer holds a record, the newest skipped one still gets written.
-    const record =
-      buffer?.record ??
-      (exact && acked?.skippedJson !== undefined
-        ? (JSON.parse(acked.skippedJson) as SessionRecord)
-        : undefined);
-    const ops: StorageOp[] = [];
-    const puts: Array<{ key: string; value: JsonValue }> = [];
-    const first = events[0];
-    if (first !== undefined) {
-      puts.push({
-        key: this.keys.sessionEvents(this.agentName, sessionId, first.index),
-        value: events as unknown as JsonValue,
-      });
-    }
-    /** Set after the record write is acknowledged; undefined = no record write. */
-    let recordAck: { sessionId: string; json: string; projection: string } | undefined;
-    if (record !== undefined) {
-      const recordJson = JSON.stringify(record);
-      const projection = resumeProjectionJson(record);
-      if (acked?.json === recordJson) {
-        // Byte-identical to the last acknowledged write: rewriting it buys
-        // nothing. Events and continuation index still flush normally.
-      } else if (
-        !exact &&
-        acked !== undefined &&
-        acked.skips < MAX_VOLATILE_RECORD_SKIPS &&
-        acked.projection === projection
-      ) {
-        // Only turnCount/updatedAt moved since the last durable write: a
-        // restore from the stored copy resumes identically, so skip the
-        // rewrite. Terminal boundaries and non-policy drains write exactly,
-        // and the skip run is bounded so bookkeeping staleness is too. The
-        // skipped record is stashed so a later exact flush can repair it.
-        acked.skips += 1;
-        acked.skippedJson = recordJson;
-      } else {
-        puts.push({
-          key: this.keys.session(this.agentName, sessionId),
-          value: JSON.parse(recordJson) as JsonValue,
-        });
-        recordAck = { sessionId, json: recordJson, projection };
-      }
-    }
-    if (puts.length > 0) {
-      ops.push(this.putsOp(puts, recordAck));
-    }
-    if (record !== undefined) {
-      ops.push(...this.continuationOps(record));
-    }
-    if (ops.length > 0) {
-      this.enqueue(ops, reason);
-    }
-  }
-
-  /**
-   * One queued op covering every put of a flush. When the sink offers
-   * `putMany`, the whole flush is one backend round trip (on the hosted
-   * file store: one presign call instead of one per key); otherwise the
-   * puts run sequentially, exactly as before. Failures stay per-key —
-   * logged and dropped (at-most-once), never failing batch siblings.
-   */
-  private putsOp(
-    puts: Array<{ key: string; value: JsonValue }>,
-    recordAck: { sessionId: string; json: string; projection: string } | undefined,
-  ): StorageOp {
-    const recordKey =
-      recordAck === undefined ? undefined : this.keys.session(this.agentName, recordAck.sessionId);
-    const settleRecord = (failed: boolean): void => {
-      if (recordAck === undefined) {
-        return;
-      }
-      if (failed) {
-        this.lastAckedRecord.delete(recordAck.sessionId);
-        return;
-      }
-      if (this.lastAckedRecord.size >= MAX_ACKED_RECORDS) {
-        const oldest = this.lastAckedRecord.keys().next();
-        if (!oldest.done) {
-          this.lastAckedRecord.delete(oldest.value);
-        }
-      }
-      this.lastAckedRecord.set(recordAck.sessionId, {
-        json: recordAck.json,
-        projection: recordAck.projection,
-        skips: 0,
-      });
-    };
-    const putMany = this.definition.putMany?.bind(this.definition);
-    if (putMany !== undefined) {
-      return {
-        label: `putMany(${puts.map(entry => entry.key).join(", ")})`,
-        run: async ctx => {
-          const results = await putMany(puts, ctx);
-          let recordFailed = false;
-          for (const result of results) {
-            if (result.error === undefined) {
-              continue;
-            }
-            if (result.key === recordKey) {
-              recordFailed = true;
-            }
-            this.logger(
-              `[agent-sdk] storage put(${result.key}) failed: ${describeError(result.error)}`,
-            );
-          }
-          settleRecord(recordFailed);
-        },
-      };
-    }
-    return {
-      label: `put(${puts.map(entry => entry.key).join(", ")})`,
-      run: async ctx => {
-        let recordFailed = false;
-        for (const entry of puts) {
-          try {
-            await this.definition.put(entry.key, entry.value, ctx);
-          } catch (error) {
-            if (entry.key === recordKey) {
-              recordFailed = true;
-            }
-            this.logger(`[agent-sdk] storage put(${entry.key}) failed: ${describeError(error)}`);
-          }
-        }
-        settleRecord(recordFailed);
-      },
-    };
-  }
-
-  /**
-   * Index maintenance for `continuation/{channelId}/{token}` → sessionId:
-   * put the current token, delete the previous one when it changed.
-   */
-  private continuationOps(record: SessionRecord): StorageOp[] {
-    const previous = this.continuationIndex.get(record.sessionId);
-    const next = record.continuationKey;
-    if (previous === next) {
-      return [];
-    }
-    this.continuationIndex.set(record.sessionId, next);
-    const ops: StorageOp[] = [];
-    if (previous != null) {
-      ops.push(this.deleteOp(this.keys.continuation(this.agentName, record.channelId, previous)));
-    }
-    if (next != null) {
-      ops.push(
-        this.putOp(this.keys.continuation(this.agentName, record.channelId, next), {
-          sessionId: record.sessionId,
-        }),
-      );
-    }
-    return ops;
-  }
-
-  /** KV upsert op on the sink's `put`. */
-  private putOp(key: string, value: JsonValue): StorageOp {
-    return {
-      label: `put(${key})`,
-      run: ctx => this.definition.put(key, value, ctx),
-    };
-  }
-
-  /** KV delete op on the sink's `delete` (skipped when the hook is absent). */
-  private deleteOp(key: string): StorageOp {
-    return {
-      label: `delete(${key})`,
-      run: ctx => this.definition.delete?.(key, ctx),
-    };
-  }
-
-  // ==========================================================================
-  // Sessions (reads / restore)
-  // ==========================================================================
-
-  /** Whether the sink can serve the startup bulk restore (`list`). */
-  get canBulkRestore(): boolean {
-    return this.definition.list !== undefined;
-  }
-
-  /**
-   * True when the authored sink is `cursorHostedStorage` (Bugbot via the
-   * control-plane proxy). `GET /v1/sessions` prefers this durable list.
-   */
-  get isCursorHosted(): boolean {
-    return isCursorHostedStorage(this.definition);
-  }
-
-  /**
-   * Saved session records for this agent (startup restore). Errors are
-   * logged and read as "nothing saved" — a broken store must never block
-   * serve start.
-   */
-  async listSessions(): Promise<SessionRecord[]> {
-    const entries = await this.tryList(this.keys.sessionPrefix(this.agentName));
-    return entries
-      .map(entry => entry.value as unknown as SessionRecord)
-      .filter(record => record != null);
-  }
-
-  /**
-   * Session records from the sink for the sessions API. Unlike
-   * {@link listSessions}, missing `list` or a thrown sink error **propagates**
-   * so the caller can fall back to the local session store.
-   */
-  async listSessionsFromSink(): Promise<SessionRecord[]> {
-    const list = this.definition.list;
-    if (list === undefined) {
-      throw new Error("storage sink has no list");
-    }
-    const entries = await list(this.keys.sessionPrefix(this.agentName), this.context("restore"));
-    if (!Array.isArray(entries)) {
-      throw new Error("storage list returned a non-array");
-    }
-    return sessionRecordsOf(entries);
-  }
-
-  /**
-   * Newest-written session records from the sink (`GET /v1/sessions?latest=1`
-   * on a host whose local store has nothing for the caller). Same error
-   * posture as {@link listSessionsFromSink}; `undefined` when the sink
-   * cannot order by write time, so the caller falls back to the full list.
-   */
-  async listNewestSessionsFromSink(limit: number): Promise<SessionRecord[] | undefined> {
-    const listNewest = this.definition.listNewest;
-    if (listNewest === undefined) {
-      return undefined;
-    }
-    const entries = await listNewest(
-      this.keys.sessionPrefix(this.agentName),
-      limit,
-      this.context("restore"),
-    );
-    if (!Array.isArray(entries)) {
-      throw new Error("storage listNewest returned a non-array");
-    }
-    return sessionRecordsOf(entries);
-  }
-
-  /**
-   * Saved event stream for one session: chunk values concatenated in key
-   * order (chunks are keyed by their first event's index, zero-padded, so
-   * ascending key order is append order). Errors read as an empty stream.
-   */
-  async listSessionEvents(sessionId: string): Promise<SessionEvent[]> {
-    const entries = await this.tryList(this.keys.sessionEventsPrefix(this.agentName, sessionId));
-    const events: SessionEvent[] = [];
-    for (const entry of entries) {
-      if (Array.isArray(entry.value)) {
-        events.push(...(entry.value as unknown as SessionEvent[]));
-      }
-    }
-    return events;
-  }
-
-  /**
-   * One saved session by id (lazy restore for playground Open-trace /
-   * events / stream after a host replacement). Sink errors **propagate**
-   * — same posture as {@link getSessionByContinuation}. A definitive miss
-   * (no row, or a write-only sink without `get`) resolves undefined.
-   */
-  async getSessionById(sessionId: string): Promise<SessionRecord | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
-      return undefined;
-    }
-    if (typeof sessionId !== "string" || sessionId === "") {
-      return undefined;
-    }
-    const ctx = this.context("restore");
-    const record = (await get(this.keys.session(this.agentName, sessionId), ctx)) as
-      | SessionRecord
-      | null
-      | undefined;
-    if (record == null) {
-      return undefined;
-    }
-    if (record.sessionId !== sessionId) {
-      throw new Error(
-        `storage returned a session that does not match the requested id ${sessionId}`,
-      );
-    }
-    return record;
-  }
-
-  /**
-   * One saved session by channel continuation key (lazy restore). Unlike
-   * the startup reads, sink errors **propagate**: a failing store must
-   * fail the follow-up (which the caller can retry) rather than read as
-   * "unknown token" — that would mint a new session under the same
-   * continuation key and permanently shadow the real one on this host.
-   * A definitive miss (no index entry, or a write-only sink without
-   * `get`) resolves undefined.
-   */
-  async getSessionByContinuation(
-    channelId: string,
-    continuationKey: string,
-  ): Promise<SessionRecord | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
-      return undefined;
-    }
-    const ctx = this.context("restore");
-    const pointer = await get(
-      this.keys.continuation(this.agentName, channelId, continuationKey),
-      ctx,
-    );
-    if (pointer == null) {
-      return undefined;
-    }
-    const sessionId =
-      typeof pointer === "object" && !Array.isArray(pointer) ? pointer.sessionId : undefined;
-    if (typeof sessionId !== "string" || sessionId === "") {
-      throw new Error(`storage returned a malformed continuation entry for channel ${channelId}`);
-    }
-    const record = await this.getSessionById(sessionId);
-    if (record === undefined) {
-      // Index entry without its record (e.g. the record write was shed
-      // under at-most-once). The session is unrecoverable; treat as a miss
-      // so the conversation can continue rather than failing forever.
-      this.logger(
-        `[agent-sdk] storage continuation entry points at missing session ${sessionId}; treating as a miss`,
-      );
-      return undefined;
-    }
-    // The sink must answer for the exact key it was asked about — a
-    // mismatched row is a broken store, not a miss; treating it as a miss
-    // would fork the continuation token onto a new session.
-    if (record.channelId !== channelId || record.continuationKey !== continuationKey) {
-      throw new Error(
-        `storage returned a session that does not match the requested continuation (channel ${channelId})`,
-      );
-    }
-    return record;
-  }
-
-  // ==========================================================================
-  // Author KV ({@link HostContext.kv})
-  // ==========================================================================
-
-  /**
-   * Whether the sink can serve awaited author reads/writes (`get` is
-   * required — `put` is always present on {@link StorageConfig}).
-   */
-  get supportsAuthorKv(): boolean {
-    return this.definition.get !== undefined;
-  }
-
-  /**
-   * Awaited author KV read. Unlike framework session mirrors, this awaits
-   * the sink and propagates errors — handlers need read-after-write.
-   */
-  async kvGet(authorKey: string): Promise<JsonValue | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
-      throw new Error("storage get is not configured");
-    }
-    const key = this.keys.kv(this.agentName, authorKey);
-    // Preserve stored JSON `null` (distinct from a missing key).
-    return await get(key, this.context("restore"));
-  }
-
-  /**
-   * Awaited author KV write. Goes straight to the sink (not the
-   * at-most-once delivery queue) so callers observe durable success/failure.
-   */
-  async kvPut(authorKey: string, value: JsonValue): Promise<void> {
-    const key = this.keys.kv(this.agentName, authorKey);
-    await this.definition.put(key, value, this.context("policy"));
-  }
-
-  /** Awaited author KV delete. No-op when the sink omits `delete`. */
-  async kvDelete(authorKey: string): Promise<void> {
-    const key = this.keys.kv(this.agentName, authorKey);
-    await this.definition.delete?.(key, this.context("policy"));
-  }
-
-  // ==========================================================================
-  // Evals (dedicated `evals` table)
-  // ==========================================================================
-
-  /**
-   * Adapter over the sink's dedicated `evals` table for the playground
-   * eval-run store. Undefined when the table is not configured — eval
-   * history then stays in process memory.
-   */
-  evalRuns(): EvalRunStorage | undefined {
-    const table = this.definition.evals;
-    if (table === undefined) {
-      return undefined;
-    }
-    return {
-      save: (run: EvalRunSnapshot) => {
-        // Clone at enqueue time: the store mutates snapshots in place as
-        // cases finish, and delivery is async.
-        const snapshot = structuredClone(run);
-        this.enqueue(
-          [
-            {
-              label: `evals.put(${run.runId})`,
-              run: ctx => table.put(snapshot, ctx),
-            },
-          ],
-          "policy",
-        );
-      },
-      delete: (runId: string) => {
-        this.enqueue(
-          [
-            {
-              label: `evals.delete(${runId})`,
-              run: ctx => table.delete(runId, ctx),
-            },
-          ],
-          "policy",
-        );
-      },
-      list: async () => {
-        try {
-          const runs = await table.list(this.context("restore"));
-          return Array.isArray(runs) ? runs : [];
-        } catch (error) {
-          this.logger(`[agent-sdk] storage evals.list() failed: ${describeError(error)}`);
-          return [];
-        }
-      },
-    };
-  }
-
-  // ==========================================================================
-  // Delivery
-  // ==========================================================================
-
-  /**
-   * Flush all buffers and drain the queue, giving the sink at most
-   * {@link CLOSE_DRAIN_TIMEOUT_MS} — a hung sink must not stall shutdown
-   * past the pod grace period. Called from engine close.
-   */
-  async close(): Promise<void> {
-    if (!this.closed) {
-      for (const sessionId of [...this.buffers.keys()]) {
-        this.flushSession(sessionId, "shutdown");
-      }
-      // Sessions whose newest record was only ever skipped (volatile-only
-      // turns) have no buffer left; drain their stashed records too so a
-      // graceful shutdown leaves exact bookkeeping behind.
-      for (const [sessionId, acked] of this.lastAckedRecord) {
-        if (acked.skippedJson !== undefined) {
-          this.flushSessionInternal(sessionId, "shutdown", true);
-        }
-      }
-      this.closed = true;
-    }
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const drained = await Promise.race([
-      this.queue.then(() => true),
-      new Promise<boolean>(resolve => {
-        timer = setTimeout(() => resolve(false), CLOSE_DRAIN_TIMEOUT_MS);
-        timer.unref?.();
-      }),
-    ]);
-    clearTimeout(timer);
-    if (!drained) {
-      this.logger(
-        `[agent-sdk] storage shutdown drain timed out after ${CLOSE_DRAIN_TIMEOUT_MS}ms with ${this.pending} write(s) undelivered`,
-      );
-    }
-  }
-
-  /** Pending deliveries (exposed for tests and drain instrumentation). */
-  whenIdle(): Promise<void> {
-    return this.queue;
-  }
-
-  private buffer(sessionId: string): SessionBuffer {
-    let buffer = this.buffers.get(sessionId);
-    if (buffer === undefined) {
-      buffer = { events: [] };
-      this.buffers.set(sessionId, buffer);
-    }
-    return buffer;
-  }
-
-  private armDebounce(sessionId: string, buffer: SessionBuffer, debounceMs: number): void {
-    if (buffer.debounceTimer !== undefined) {
-      clearTimeout(buffer.debounceTimer);
-    }
-    buffer.debounceTimer = setTimeout(() => {
-      buffer.debounceTimer = undefined;
-      this.flushSession(sessionId);
-    }, debounceMs);
-    // Never keep the process alive just for a pending storage flush.
-    buffer.debounceTimer.unref?.();
-  }
-
-  /** `list` wrapper for the startup reads: missing hook or throw ⇒ empty. */
-  private async tryList(prefix: string): Promise<Array<{ key: string; value: JsonValue }>> {
-    const list = this.definition.list;
-    if (list === undefined) {
-      return [];
-    }
-    try {
-      const entries = await list(prefix, this.context("restore"));
-      return Array.isArray(entries) ? entries : [];
-    } catch (error) {
-      this.logger(`[agent-sdk] storage list(${prefix}) failed: ${describeError(error)}`);
-      return [];
-    }
-  }
-
-  private enqueue(ops: StorageOp[], reason: StorageContext["reason"]): void {
-    if (this.closed && reason !== "shutdown") {
-      return;
-    }
-    if (this.pending + ops.length > MAX_PENDING_OPS) {
-      this.dropped += ops.length;
-      if (this.dropped <= ops.length || this.dropped % 1_000 < ops.length) {
-        this.logger(
-          `[agent-sdk] storage queue full (${MAX_PENDING_OPS} pending writes); dropped ${this.dropped} write(s) so far — the sink is too slow for the traffic`,
-        );
-      }
-      return;
-    }
-    this.pending += ops.length;
-    const ctx = this.context(reason);
-    this.queue = this.queue.then(async () => {
-      for (const op of ops) {
-        try {
-          await op.run(ctx);
-        } catch (error) {
-          this.logger(`[agent-sdk] storage ${op.label} failed: ${describeError(error)}`);
-        } finally {
-          this.pending -= 1;
-        }
-      }
-    });
-  }
-
-  private context(reason: StorageContext["reason"]): StorageContext {
-    return { agentName: this.agentName, projectRoot: this.projectRoot, reason };
-  }
-}