@cursor/july 0.1.5 → 0.1.6

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;
 
 /**