@cursor/july 0.1.5 → 0.1.7

package/src/internal/session-engine.ts

@@ -204,8 +204,7 @@ export class SessionEngine {
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
    * records, event chunks, A/B samples/snapshots); the eval run store
-   * attaches via {@link StorageCoordinator.asEvalRunPersistence} at
-   * serve start.
+   * attaches via {@link StorageCoordinator.evalRuns} at serve start.
    */
   readonly storage: StorageCoordinator | undefined;
   /** In-flight lazy restores, deduped per channel + continuation key. */
@@ -261,18 +260,12 @@ export class SessionEngine {
             projectRoot: options.project.rootDir,
             logger: this.logger,
           });
-    // Domain-specific hooks win; the defineStorage sink is the fallback.
-    const persistSamples =
-      options.project.abConfig?.persistSamples ??
-      this.storage?.asABSamplePersistence();
     this.abCollector = new ABCollector(
       options.project.abs,
       this.logger,
       async (sessionId) => (await this.logs.get(sessionId)).snapshot(0),
-      {
-        projectRoot: options.project.rootDir,
-        persistSamples,
-      }
+      // Samples flow to the defineStorage `abs` table (no-op without one).
+      { persistSample: (sample) => this.storage?.abSample(sample) }
     );
     // Peer and Cursor-account transports are symbolic until the serve host
     // resolves them; the host-side MCP registry starts with the concrete
@@ -1592,6 +1585,7 @@ export class SessionEngine {
         return restoredSnapshot;
       }
     }
+    const abTable = this.project.storage?.abs;
     const snapshot = await buildABSnapshot({
       experiments: this.project.abs,
       agentName: this.project.name,
@@ -1602,27 +1596,13 @@ export class SessionEngine {
       logger: this.logger,
       config: {
         maxPlaygroundSessions,
-        durableSamples: abConfig?.persistSamples !== undefined,
-        durableSnapshots: abConfig?.persistSnapshots !== undefined,
+        durableSamples: abTable !== undefined,
+        durableSnapshots: abTable?.putSnapshot !== undefined,
       },
     });
-    // Side effect on the read path: playground polls GET /v1/abs ~every 4s.
-    // Authors who set persistSnapshots accept that write cadence.
-    const persistSnapshots = abConfig?.persistSnapshots;
-    if (persistSnapshots !== undefined) {
-      try {
-        await persistSnapshots.save(snapshot, {
-          projectRoot: this.project.rootDir,
-        });
-      } catch (error) {
-        this.logger(
-          `[agentkit] ab persistSnapshots.save threw: ${describeError(error)}`
-        );
-      }
-    } else {
-      // defineStorage fallback (throttled inside the coordinator).
-      this.storage?.abSnapshot(snapshot);
-    }
+    // Side effect on the read path: playground polls GET /v1/abs ~every 4s;
+    // the coordinator throttles the actual table write.
+    this.storage?.abSnapshot(snapshot);
     return snapshot;
   }
 

package/src/internal/storage-coordinator.ts

@@ -10,13 +10,13 @@
  * failures — a throwing sink is logged and its write dropped; storage
  * must never stall or fail a turn.
  *
- * Scaling shape: sessions, reminders, evals, and A/Bs all reduce to keyed
- * puts on the same queue, so one author-owned sink covers every domain,
- * and new domains are new key prefixes — not new config surface.
+ * Scaling shape: sessions and reminders reduce to keyed puts on the KV
+ * sink; eval runs and A/B metrics go to their dedicated tables
+ * (`evals` / `abs`). Everything shares one bounded, serialized queue.
  */
 
-import type { ABMetricSample, ABSamplePersistence } from "../ab.js";
-import type { EvalRunPersistence, EvalRunSnapshot } from "../evals.js";
+import type { ABMetricSample } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
 import {
   type ResolvedStoragePolicy,
   resolveStoragePolicy,
@@ -27,6 +27,7 @@ import {
 import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
+import type { EvalRunStorage } from "./eval-run-store.js";
 import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
 
 /** Event types that close a unit of work — flush point for turn-end batching. */
@@ -62,10 +63,12 @@ const DEBOUNCE_MAX_BATCH = 200;
  */
 const AB_SNAPSHOT_MIN_INTERVAL_MS = 60_000;
 
-/** One queued sink call. */
-type StorageOp =
-  | { op: "put"; key: string; value: JsonValue }
-  | { op: "delete"; key: string };
+/** One queued sink call (KV put/delete or a dedicated-table write). */
+interface StorageOp {
+  /** Human-readable op label for failure logs, e.g. `put(agentkit/v1/...)`. */
+  label: string;
+  run: (ctx: StorageContext) => void | Promise<void>;
+}
 
 export interface StorageCoordinatorOptions {
   definition: StorageDefinition;
@@ -182,18 +185,20 @@ export class StorageCoordinator {
     const ops: StorageOp[] = [];
     const first = buffer.events[0];
     if (first !== undefined) {
-      ops.push({
-        op: "put",
-        key: storageKeys.sessionEvents(this.agentName, sessionId, first.index),
-        value: buffer.events as unknown as JsonValue,
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.sessionEvents(this.agentName, sessionId, first.index),
+          buffer.events as unknown as JsonValue
+        )
+      );
     }
     if (buffer.record !== undefined) {
-      ops.push({
-        op: "put",
-        key: storageKeys.session(this.agentName, sessionId),
-        value: buffer.record as unknown as JsonValue,
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.session(this.agentName, sessionId),
+          buffer.record as unknown as JsonValue
+        )
+      );
       ops.push(...this.continuationOps(buffer.record));
     }
     if (ops.length > 0) {
@@ -214,25 +219,39 @@ export class StorageCoordinator {
     this.continuationIndex.set(record.sessionId, next);
     const ops: StorageOp[] = [];
     if (previous != null) {
-      ops.push({
-        op: "delete",
-        key: storageKeys.continuation(
-          this.agentName,
-          record.channelId,
-          previous
-        ),
-      });
+      ops.push(
+        this.deleteOp(
+          storageKeys.continuation(this.agentName, record.channelId, previous)
+        )
+      );
     }
     if (next != null) {
-      ops.push({
-        op: "put",
-        key: storageKeys.continuation(this.agentName, record.channelId, next),
-        value: { sessionId: record.sessionId },
-      });
+      ops.push(
+        this.putOp(
+          storageKeys.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)
   // ==========================================================================
@@ -351,11 +370,10 @@ export class StorageCoordinator {
     }
     this.enqueue(
       [
-        {
-          op: "put",
-          key: storageKeys.reminder(this.agentName, record.id),
-          value: record as unknown as JsonValue,
-        },
+        this.putOp(
+          storageKeys.reminder(this.agentName, record.id),
+          record as unknown as JsonValue
+        ),
       ],
       "policy"
     );
@@ -375,31 +393,29 @@ export class StorageCoordinator {
   }
 
   // ==========================================================================
-  // Evals
+  // Evals (dedicated `evals` table)
   // ==========================================================================
 
   /**
-   * Adapter for {@link EvalRunPersistence} so the playground eval store
-   * can fall back to this sink when `evals.config.ts` sets no
-   * `persistRuns`.
+   * 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.
    */
-  asEvalRunPersistence(): EvalRunPersistence {
+  evalRuns(): EvalRunStorage | undefined {
+    const table = this.definition.evals;
+    if (table === undefined) {
+      return undefined;
+    }
     return {
-      load: async () => {
-        const entries = await this.tryList(
-          storageKeys.evalRunPrefix(this.agentName)
-        );
-        return entries
-          .map((entry) => entry.value as unknown as EvalRunSnapshot)
-          .filter((run) => run != null);
-      },
       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(
           [
             {
-              op: "put",
-              key: storageKeys.evalRun(this.agentName, run.runId),
-              value: run as unknown as JsonValue,
+              label: `evals.put(${run.runId})`,
+              run: (ctx) => table.put(snapshot, ctx),
             },
           ],
           "policy"
@@ -409,86 +425,82 @@ export class StorageCoordinator {
         this.enqueue(
           [
             {
-              op: "delete",
-              key: storageKeys.evalRun(this.agentName, runId),
+              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(
+            `[agentkit] storage evals.list() failed: ${describeError(error)}`
+          );
+          return [];
+        }
+      },
     };
   }
 
   // ==========================================================================
-  // A/Bs
+  // A/Bs (dedicated `abs` table)
   // ==========================================================================
 
-  /**
-   * Adapter for {@link ABSamplePersistence} so the AB collector can fall
-   * back to this sink when `ab.config.ts` sets no `persistSamples`.
-   */
-  asABSamplePersistence(): ABSamplePersistence {
-    return {
-      save: (sample: ABMetricSample) => {
-        this.enqueue(
-          [
-            {
-              op: "put",
-              key: storageKeys.abSample(
-                this.agentName,
-                sample.sessionId,
-                sample.at
-              ),
-              value: sample as unknown as JsonValue,
-            },
-          ],
-          "policy"
-        );
-      },
-    };
+  /** Append one metric sample to the `abs` table (no-op without it). */
+  abSample(sample: ABMetricSample): void {
+    const table = this.definition.abs;
+    if (this.closed || table === undefined) {
+      return;
+    }
+    this.enqueue(
+      [
+        {
+          label: `abs.putSample(${sample.sessionId})`,
+          run: (ctx) => table.putSample(sample, ctx),
+        },
+      ],
+      "policy"
+    );
   }
 
   /**
    * Refresh the persisted aggregate A/B snapshot, throttled to once per
    * {@link AB_SNAPSHOT_MIN_INTERVAL_MS} (the playground recomputes the
-   * fold on every `GET /v1/abs` poll).
+   * fold on every `GET /v1/abs` poll). No-op without `abs.putSnapshot`.
    */
   abSnapshot(snapshot: ABSnapshot): void {
+    const putSnapshot = this.definition.abs?.putSnapshot;
     const now = Date.now();
     if (
       this.closed ||
+      putSnapshot === undefined ||
       now - this.lastAbSnapshotAt < AB_SNAPSHOT_MIN_INTERVAL_MS
     ) {
       return;
     }
     this.lastAbSnapshotAt = now;
     this.enqueue(
-      [
-        {
-          op: "put",
-          key: storageKeys.abSnapshot(this.agentName),
-          value: snapshot as unknown as JsonValue,
-        },
-      ],
+      [{ label: "abs.putSnapshot", run: (ctx) => putSnapshot(snapshot, ctx) }],
       "policy"
     );
   }
 
   /** Latest persisted aggregate A/B snapshot; errors read as absent. */
   async getLatestAbSnapshot(): Promise<ABSnapshot | undefined> {
-    const get = this.definition.get;
-    if (get === undefined) {
+    const getSnapshot = this.definition.abs?.getSnapshot;
+    if (getSnapshot === undefined) {
       return undefined;
     }
     try {
-      const value = await get(
-        storageKeys.abSnapshot(this.agentName),
-        this.context("restore")
-      );
-      return value == null ? undefined : (value as unknown as ABSnapshot);
+      const value = await getSnapshot(this.context("restore"));
+      return value ?? undefined;
     } catch (error) {
       this.logger(
-        `[agentkit] storage get(ab-snapshot) failed: ${describeError(error)}`
+        `[agentkit] storage abs.getSnapshot() failed: ${describeError(error)}`
       );
       return undefined;
     }
@@ -593,14 +605,10 @@ export class StorageCoordinator {
     this.queue = this.queue.then(async () => {
       for (const op of ops) {
         try {
-          if (op.op === "put") {
-            await this.definition.put(op.key, op.value, ctx);
-          } else {
-            await this.definition.delete?.(op.key, ctx);
-          }
+          await op.run(ctx);
         } catch (error) {
           this.logger(
-            `[agentkit] storage ${op.op}(${op.key}) failed: ${describeError(error)}`
+            `[agentkit] storage ${op.label} failed: ${describeError(error)}`
           );
         } finally {
           this.pending -= 1;

package/src/storage.ts

@@ -4,10 +4,11 @@
  * Author `agent/storage.ts` with {@link defineStorage} to mirror the
  * framework's durable state into storage you own (a database, S3, a data
  * pipeline, …). Without it, state lives under `--state-root` on local disk
- * only (and eval/A/B history follows the narrower `persistRuns` /
- * `persistSamples` / `persistSnapshots` hooks).
+ * only, and eval/A/B history stays in process memory.
  *
- * The sink is a plain key-value store — four functions, no schema:
+ * The sink is a plain key-value store — four functions, no schema — plus
+ * two optional dedicated tables ({@link StorageConfig.evals} and
+ * {@link StorageConfig.abs}) for eval-run and A/B history:
  *
  * ```ts
  * import { defineStorage } from "@anysphere/agent-serve/storage";
@@ -17,6 +18,8 @@
  *   get: (key) => db.get(key),
  *   delete: (key) => db.delete(key),
  *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
+ *   evals: { put: ..., delete: ..., list: ... }, // eval-runs table
+ *   abs: { putSample: ... },                     // A/B table
  * });
  * ```
  *
@@ -41,6 +44,9 @@
  */
 
 import { createHash } from "node:crypto";
+import type { ABMetricSample } from "./ab.js";
+import type { EvalRunSnapshot } from "./evals.js";
+import type { ABSnapshot } from "./internal/ab-snapshot.js";
 import { brandDefinition } from "./internal/brand.js";
 import type { JsonValue } from "./types.js";
 
@@ -110,11 +116,54 @@ export interface StorageRestorePolicy {
   maxTotalBytes?: number;
 }
 
+/**
+ * Dedicated table for playground eval batches, keyed by `runId`. The
+ * framework saves a full {@link EvalRunSnapshot} as a batch starts,
+ * progresses, and finishes; prunes runs past the playground history
+ * window; and lists everything back at serve start.
+ */
+export interface StorageEvalsTable {
+  /** Upsert one run snapshot under `run.runId` (last write wins). */
+  put(run: EvalRunSnapshot, ctx: StorageContext): void | Promise<void>;
+  /** Remove a run pruned out of the playground history window. */
+  delete(runId: string, ctx: StorageContext): void | Promise<void>;
+  /** All saved runs (any order). Called once when the serve process hydrates. */
+  list(ctx: StorageContext): EvalRunSnapshot[] | Promise<EvalRunSnapshot[]>;
+}
+
+/**
+ * Dedicated table for live A/B metrics: one row per cumulative metric
+ * sample (unique per `experiment` + `sessionId` + `at` — one boundary
+ * event emits a sample per enrolled experiment), plus — optionally — the latest
+ * aggregate snapshot so a replacement host with no local sessions can
+ * still serve the A/Bs surface.
+ */
+export interface StorageABTable {
+  /** Append one cumulative metric sample (turn complete/fail). */
+  putSample(sample: ABMetricSample, ctx: StorageContext): void | Promise<void>;
+  /** Upsert the latest aggregate snapshot (framework-throttled). Optional. */
+  putSnapshot?(snapshot: ABSnapshot, ctx: StorageContext): void | Promise<void>;
+  /** Latest saved aggregate snapshot (replacement-host backfill). Optional. */
+  getSnapshot?(
+    ctx: StorageContext
+  ): ABSnapshot | undefined | null | Promise<ABSnapshot | undefined | null>;
+}
+
 export interface StorageConfig {
   /** Optional label surfaced on `GET /v1/info` diagnostics. */
   name?: string;
   /** Timing knobs; see {@link StoragePolicy}. */
   policy?: StoragePolicy;
+  /**
+   * Dedicated eval-runs table. Omit it and playground eval history stays
+   * in process memory (lost on restart).
+   */
+  evals?: StorageEvalsTable;
+  /**
+   * Dedicated A/B table. Omit it and metric samples are not exported
+   * (session event logs remain the assignment/fold source of truth).
+   */
+  abs?: StorageABTable;
   /**
    * Store one value under a key (upsert, last-write-wins). Called on the
    * framework's schedule — never concurrently, always in order. Keep it
@@ -168,6 +217,30 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
       );
     }
   }
+  if (config.evals !== undefined) {
+    for (const hook of ["put", "delete", "list"] as const) {
+      if (typeof config.evals[hook] !== "function") {
+        throw new Error(
+          `defineStorage: evals.${hook} must be a function when the evals table is set`
+        );
+      }
+    }
+  }
+  if (config.abs !== undefined) {
+    if (typeof config.abs.putSample !== "function") {
+      throw new Error(
+        "defineStorage: abs.putSample must be a function when the abs table is set"
+      );
+    }
+    for (const hook of ["putSnapshot", "getSnapshot"] as const) {
+      const value = config.abs[hook];
+      if (value !== undefined && typeof value !== "function") {
+        throw new Error(
+          `defineStorage: abs.${hook} must be a function when set`
+        );
+      }
+    }
+  }
   // Validate eagerly so a bad policy fails at discovery, not first flush.
   resolveStoragePolicy(config.policy);
   return brandDefinition("storage", config);
@@ -201,9 +274,9 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
- * | `agentkit/v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
- * | `agentkit/v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
- * | `agentkit/v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
+ *
+ * Eval-run and A/B history do not flow through this KV scheme — they have
+ * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
  */
 export const storageKeys = {
   session: (agent: string, sessionId: string): string =>
@@ -228,14 +301,6 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
   reminderPrefix: (agent: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
-  evalRun: (agent: string, runId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-run/${runId}`,
-  evalRunPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/eval-run/`,
-  abSample: (agent: string, sessionId: string, at: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-sample/${sessionId}/${at}`,
-  abSnapshot: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
 } as const;
 
 /**