@cursor/bdk 0.2.1

package/src/internal/storage-coordinator.ts

@@ -0,0 +1,800 @@
+/**
+ * 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 };
+  }
+}