@cursor/july 0.1.47 → 0.1.49

package/src/storage.ts

@@ -9,9 +9,12 @@
  * The sink is a plain key-value store — put/get/delete/list, no schema —
  * plus a conditional-write group ({@link StorageConfig.cas}, the substrate
  * for framework coordination; optional for plain storage, required by
- * coordination features) and two optional dedicated tables
- * ({@link StorageConfig.evals} and {@link StorageConfig.abs}) for
- * eval-run and A/B history:
+ * coordination features). Implementing that small KV core is enough for
+ * FULL functionality: eval-run and A/B history are derived over the core
+ * when the optional dedicated tables ({@link StorageConfig.evals} and
+ * {@link StorageConfig.abs}) are not authored — those groups exist as
+ * backend-native optimizations (a real table, an analytics pipeline),
+ * not as required-or-lose-history hooks:
  *
  * ```ts
  * import { defineStorage } from "@anysphere/agent-serve/storage";
@@ -207,13 +210,20 @@ export interface StorageConfig {
   /** Timing knobs; see {@link StoragePolicy}. */
   policy?: StoragePolicy;
   /**
-   * Dedicated eval-runs table. Omit it and playground eval history stays
-   * in process memory (lost on restart).
+   * Dedicated eval-runs table — a backend-native optimization, not a
+   * requirement. When omitted, `defineStorage` derives the table over the
+   * KV core (one key per run under `agentkit/v1/{agent}/eval-runs/`),
+   * which needs core `put`, `delete`, and `list`; only when the core
+   * lacks `delete` or `list` does playground eval history stay 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).
+   * Dedicated A/B table — a backend-native optimization, not a
+   * requirement. When omitted, `defineStorage` derives it over the KV
+   * core: `putSample` and `putSnapshot` need only core `put` (always
+   * present), `getSnapshot` additionally needs core `get`. Session event
+   * logs remain the assignment/fold source of truth either way.
    */
   abs?: StorageABTable;
   /**
@@ -249,7 +259,8 @@ export interface StorageConfig {
   /**
    * All entries under a key prefix, in ascending key order. Optional —
    * required for the **startup bulk restore** (sessions + event streams)
-   * and playground eval history.
+   * and, together with `delete`, for the derived eval-runs table
+   * (playground eval history).
    */
   list?(
     prefix: string,
@@ -326,7 +337,91 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
   }
   // Validate eagerly so a bad policy fails at discovery, not first flush.
   resolveStoragePolicy(config.policy);
-  return brandDefinition("storage", config);
+  // A backend that implements only the KV core gets full functionality:
+  // the dedicated tables are backend-native optimizations, derived over
+  // the core when absent. Authored groups always win.
+  const derivedEvals =
+    config.evals === undefined ? deriveEvalsTable(config) : undefined;
+  const derivedAbs =
+    config.abs === undefined ? deriveAbsTable(config) : undefined;
+  return brandDefinition("storage", {
+    ...config,
+    ...(derivedEvals === undefined ? {} : { evals: derivedEvals }),
+    ...(derivedAbs === undefined ? {} : { abs: derivedAbs }),
+  });
+}
+
+/**
+ * Eval-runs table over the KV core: one key per run under
+ * {@link storageKeys.evalRun}, hydrate via prefix `list`, prune via
+ * `delete`. Requires core `put` + `delete` + `list`; without `delete` or
+ * `list` there is no derivation (pruning or hydration would silently not
+ * work) and eval history stays in process memory.
+ */
+function deriveEvalsTable(
+  config: StorageConfig
+): StorageEvalsTable | undefined {
+  if (config.delete === undefined || config.list === undefined) {
+    return undefined;
+  }
+  return {
+    put: (run, ctx) =>
+      config.put(
+        storageKeys.evalRun(ctx.agentName, run.runId),
+        run as unknown as JsonValue,
+        ctx
+      ),
+    delete: (runId, ctx) =>
+      config.delete?.(storageKeys.evalRun(ctx.agentName, runId), ctx),
+    list: async (ctx) => {
+      const entries =
+        (await config.list?.(storageKeys.evalRunsPrefix(ctx.agentName), ctx)) ??
+        [];
+      return entries.map((entry) => entry.value as unknown as EvalRunSnapshot);
+    },
+  };
+}
+
+/**
+ * A/B table over the KV core. Each sample lands as its own key (identity
+ * = experiment + sessionId + at, matching the dedicated table's row
+ * uniqueness): appending to one array value would need read-modify-write
+ * — lost updates under concurrent writers without CAS, and unbounded
+ * value growth — while a key per sample keeps `putSample` a blind put
+ * with real append-only semantics. The aggregate snapshot lives at one
+ * fixed key via plain `put` (last-write-wins is correct for "latest").
+ * Requires only core `put`; `getSnapshot` is included when core `get`
+ * exists.
+ */
+function deriveAbsTable(config: StorageConfig): StorageABTable {
+  const get = config.get;
+  return {
+    putSample: (sample, ctx) =>
+      config.put(
+        storageKeys.abSample(
+          ctx.agentName,
+          sample.experiment,
+          sample.sessionId,
+          sample.at
+        ),
+        sample as unknown as JsonValue,
+        ctx
+      ),
+    putSnapshot: (snapshot, ctx) =>
+      config.put(
+        storageKeys.abSnapshot(ctx.agentName),
+        snapshot as unknown as JsonValue,
+        ctx
+      ),
+    ...(get === undefined
+      ? {}
+      : {
+          getSnapshot: async (ctx: StorageContext) => {
+            const value = await get(storageKeys.abSnapshot(ctx.agentName), ctx);
+            return (value ?? undefined) as ABSnapshot | undefined;
+          },
+        }),
+  };
 }
 
 // ============================================================================
@@ -357,9 +452,14 @@ 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}/kv/{key}` | Author JSON via {@link HostContext.kv} |
+ * | `agentkit/v1/{agent}/eval-runs/{runId}` | `EvalRunSnapshot` (derived `evals` table) |
+ * | `agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` | `ABMetricSample` (derived `abs` table, append-only) |
+ * | `agentkit/v1/{agent}/ab-snapshot` | `ABSnapshot` (derived `abs` table, LWW) |
  *
- * Eval-run and A/B history do not flow through this KV scheme — they have
- * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
+ * The `eval-runs` / `ab-samples` / `ab-snapshot` families are minted only
+ * by the tables `defineStorage` derives over the KV core; a backend that
+ * authors dedicated {@link StorageConfig.evals} / {@link StorageConfig.abs}
+ * groups never sees them.
  */
 export const storageKeys = {
   session: (agent: string, sessionId: string): string =>
@@ -387,6 +487,25 @@ export const storageKeys = {
   kv: (agent: string, key: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
   kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
+  /** One playground eval-run snapshot (derived `evals` table). */
+  evalRun: (agent: string, runId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/${keySegment(runId)}`,
+  evalRunsPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-runs/`,
+  /**
+   * One A/B metric sample (derived `abs` table); the segments mirror the
+   * dedicated table's row identity (experiment + sessionId + at).
+   */
+  abSample: (
+    agent: string,
+    experiment: string,
+    sessionId: string,
+    at: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
+  /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
+  abSnapshot: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
 } as const;
 
 /**