@cursor/july 0.1.39 → 0.1.41

package/src/storage-backends/cursor-hosted.ts

@@ -10,8 +10,7 @@
  * On Cursor-managed hosting the start script pins `CURSOR_API_BASE_URL` to
  * `https://api.cursor.com` (where the proxy is mounted). Locally, point
  * `CURSOR_API_BASE_URL` at a backend that mounts Agent Serve routes and use
- * a deployment SA key, or use `@cursor/july/storage/postgres-kv` /
- * `file-kv` instead.
+ * a deployment SA key, or use `@cursor/july/storage/file-kv` instead.
  *
  * ```ts
  * import { defineStorage } from "@cursor/july/storage";
@@ -27,11 +26,12 @@ import type { ABSnapshot } from "../ab.js";
 import type { EvalRunSnapshot } from "../evals.js";
 import type {
   StorageABTable,
+  StorageCasTable,
   StorageConfig,
   StorageEntry,
   StorageEvalsTable,
 } from "../storage.js";
-import type { JsonValue } from "../types.js";
+import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
 
 /**
  * Same default as {@link cursorExternalApiUrl} in the CLI credentials module,
@@ -103,10 +103,75 @@ type CursorHostedStorageMethods = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 > & {
   readonly [CURSOR_HOSTED_STORAGE]: true;
+  cas: StorageCasTable;
   evals: StorageEvalsTable;
   abs: StorageABTable;
 };
 
+// ============================================================================
+// CAS wire protocol
+// ============================================================================
+//
+// Served by the backend Agent Serve storage proxy
+// (`backend/server/src/agentServe/agentServeHostedStorage.ts`, routes in
+// `agentServeEndpoints.ts`) over `agent_serve_kv` and its `version BIGINT`
+// column. Each call is atomic server-side:
+//
+// - `POST /internal/agent-serve/storage/kv/get-with-version`
+//   `{ key }` → `{ found, value, version }` ({@link KvGetWithVersionResponse}).
+// - `POST /internal/agent-serve/storage/kv/put-if-absent`
+//   `{ key, value }` → `{ ok, version, current }` ({@link KvCasResponse});
+//   plain INSERT, unique-violation conflict returns the existing row as
+//   `current`.
+// - `POST /internal/agent-serve/storage/kv/put-if-version`
+//   `{ key, value, expectedVersion }` → `{ ok, version, current }`;
+//   one conditional `UPDATE … SET value, version = version + 1 WHERE key
+//   AND version = expected`, conflict returns the current row (or
+//   `current: null` when the row is gone).
+// - `POST /internal/agent-serve/storage/kv/list-keys`
+//   `{ prefix }` → `{ keys }` ({@link KvListKeysResponse}) in ascending
+//   key order (prefix scan on the `(deployment_id, key)` primary key).
+
+/** Wire shape of the `get-with-version` route. `null` ⇒ JSON `undefined`. */
+export interface KvGetWithVersionResponse {
+  found: boolean;
+  value: JsonValue | null;
+  version: string | null;
+}
+
+/** Wire shape of the `put-if-absent` / `put-if-version` routes. */
+export interface KvCasResponse {
+  ok: boolean;
+  /** New version on success, else `null`. */
+  version: string | null;
+  /** Entry observed on conflict; `null` when the key is absent. */
+  current: { value: JsonValue | null; version: string } | null;
+}
+
+/** Wire shape of the `list-keys` route. */
+export interface KvListKeysResponse {
+  keys: string[];
+}
+
+function toCasResult(response: KvCasResponse): KvCasResult {
+  if (response.ok) {
+    if (response.version === null) {
+      throw new Error(
+        "cursorHostedStorage: CAS success without a version token"
+      );
+    }
+    return { ok: true, version: response.version };
+  }
+  const current: KvVersionedEntry | undefined =
+    response.current === null
+      ? undefined
+      : {
+          value: response.current.value ?? null,
+          version: response.current.version,
+        };
+  return { ok: false, current };
+}
+
 function resolveApiKey(options: CursorHostedStorageOptions): string {
   const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
@@ -203,6 +268,46 @@ export function cursorHostedStorage(
       }>(options, "/internal/agent-serve/storage/kv/list", { prefix });
       return result.entries;
     },
+    // Conditional writes over the same proxy (server routes: see the CAS
+    // wire-protocol block above). The proxy scopes rows from the service
+    // account, so ctx is not part of the wire contract.
+    cas: {
+      async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
+        const result = await storageRpc<KvGetWithVersionResponse>(
+          options,
+          "/internal/agent-serve/storage/kv/get-with-version",
+          { key }
+        );
+        if (!result.found || result.version === null) {
+          return undefined;
+        }
+        return { value: result.value ?? null, version: result.version };
+      },
+      async putIfAbsent(key, value): Promise<KvCasResult> {
+        const result = await storageRpc<KvCasResponse>(
+          options,
+          "/internal/agent-serve/storage/kv/put-if-absent",
+          { key, value }
+        );
+        return toCasResult(result);
+      },
+      async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
+        const result = await storageRpc<KvCasResponse>(
+          options,
+          "/internal/agent-serve/storage/kv/put-if-version",
+          { key, value, expectedVersion }
+        );
+        return toCasResult(result);
+      },
+      async listKeys(prefix): Promise<string[]> {
+        const result = await storageRpc<KvListKeysResponse>(
+          options,
+          "/internal/agent-serve/storage/kv/list-keys",
+          { prefix }
+        );
+        return result.keys;
+      },
+    },
     evals: {
       async put(run, ctx): Promise<void> {
         await storageRpc(options, "/internal/agent-serve/storage/evals/put", {

package/src/storage-backends/file-kv.ts

@@ -4,7 +4,9 @@
  *
  * Implements the whole `defineStorage` surface with zero external
  * dependencies: the four KV methods against a flat directory of JSON files
- * (one file per key, filename = URI-encoded key), eval runs as
+ * (one file per key, filename = URI-encoded key), the `cas`
+ * group (single-process conditional writes — see the `cas` member below),
+ * eval runs as
  * `eval-runs/<agent>/<runId>.json`, and A/B metrics as
  * `ab/<agent>/samples.ndjson` (append-only) plus `ab/<agent>/snapshot.json`
  * (latest aggregate). KV keys carry the agent name inside the framework
@@ -25,7 +27,7 @@
  *   throw correctly fails the follow-up instead of forking the session.
  */
 
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   appendFile,
   mkdir,
@@ -35,17 +37,18 @@ import {
   rm,
   writeFile,
 } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import type { ABSnapshot } from "../ab.js";
 import type { EvalRunSnapshot } from "../evals.js";
 import type {
   StorageABTable,
+  StorageCasTable,
   StorageConfig,
   StorageContext,
   StorageEntry,
   StorageEvalsTable,
 } from "../storage.js";
-import type { JsonValue } from "../types.js";
+import type { JsonValue, KvVersionedEntry } from "../types.js";
 
 export interface FileKvOptions {
   /**
@@ -58,14 +61,17 @@ export interface FileKvOptions {
 type FileKvMethods = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 > & {
+  cas: StorageCasTable;
   evals: StorageEvalsTable;
   abs: StorageABTable;
 };
 
 /** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
 export function fileKv(options?: FileKvOptions): FileKvMethods {
-  const resolveDir = (ctx: StorageContext): string =>
-    join(ctx.projectRoot, options?.dir ?? ".agent-serve/kv");
+  const resolveDir = (ctx: StorageContext): string => {
+    const dir = options?.dir ?? ".agent-serve/kv";
+    return isAbsolute(dir) ? dir : join(ctx.projectRoot, dir);
+  };
   // The evals/abs tables are scoped per agent (KV keys already carry the
   // agent name via the framework key scheme).
   const evalRunsDir = (ctx: StorageContext): string =>
@@ -74,14 +80,12 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
     join(resolveDir(ctx), "ab", encodeURIComponent(ctx.agentName));
   const filePath = (ctx: StorageContext, key: string): string =>
     join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
-  const readKey = async (
+  const readRaw = async (
     ctx: StorageContext,
     key: string
-  ): Promise<JsonValue | undefined> => {
+  ): Promise<string | undefined> => {
     try {
-      return JSON.parse(
-        await readFile(filePath(ctx, key), "utf8")
-      ) as JsonValue;
+      return await readFile(filePath(ctx, key), "utf8");
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
         return undefined; // definitive miss — key was never written
@@ -89,6 +93,37 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
       throw error; // real failure: let lazy restore fail the follow-up
     }
   };
+  const readKey = async (
+    ctx: StorageContext,
+    key: string
+  ): Promise<JsonValue | undefined> => {
+    const text = await readRaw(ctx, key);
+    return text === undefined ? undefined : (JSON.parse(text) as JsonValue);
+  };
+  const readVersioned = async (
+    ctx: StorageContext,
+    key: string
+  ): Promise<KvVersionedEntry | undefined> => {
+    const text = await readRaw(ctx, key);
+    if (text === undefined) {
+      return undefined;
+    }
+    return { value: JSON.parse(text) as JsonValue, version: versionOf(text) };
+  };
+
+  // In-process mutex: CAS check-then-write pairs queue on one promise
+  // chain so they cannot interleave with each other. Plain `put` stays
+  // outside the chain on purpose — it is unconditional LWW and always
+  // wins the key, like a SQL upsert would win the row.
+  let casChain: Promise<unknown> = Promise.resolve();
+  const locked = <T>(task: () => Promise<T>): Promise<T> => {
+    const result = casChain.then(task, task);
+    casChain = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  };
 
   return {
     async put(key, value, ctx): Promise<void> {
@@ -132,6 +167,69 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
       return entries;
     },
 
+    // Conditional writes over the same raw value files — no on-disk format
+    // change, so data written before the CAS group existed stays readable
+    // and plain `put` stays byte-identical. The version token is a content
+    // hash of the stored JSON text: it changes whenever the value does,
+    // and the in-process mutex makes read-check-write atomic, so a token
+    // can never go stale between the check and the rename. The one caveat
+    // of hash versions — ABA when a value returns to identical bytes — is
+    // moot for coordination values that carry a monotonic counter. CAS
+    // correctness is **single-process only**: two pods sharing this
+    // directory would race between read and rename, so a file store is
+    // only safe for single-instance deployments.
+    cas: {
+      getWithVersion: (key, ctx): Promise<KvVersionedEntry | undefined> =>
+        readVersioned(ctx, key),
+
+      putIfAbsent: (key, value, ctx) =>
+        locked(async () => {
+          const current = await readVersioned(ctx, key);
+          if (current !== undefined) {
+            return { ok: false, current };
+          }
+          const text = JSON.stringify(value);
+          await writeTextAtomic({
+            dir: resolveDir(ctx),
+            fileName: `${encodeURIComponent(key)}.json`,
+            text,
+          });
+          return { ok: true, version: versionOf(text) };
+        }),
+
+      putIfVersion: (key, value, expectedVersion, ctx) =>
+        locked(async () => {
+          const current = await readVersioned(ctx, key);
+          if (current === undefined || current.version !== expectedVersion) {
+            return { ok: false, current };
+          }
+          const text = JSON.stringify(value);
+          await writeTextAtomic({
+            dir: resolveDir(ctx),
+            fileName: `${encodeURIComponent(key)}.json`,
+            text,
+          });
+          return { ok: true, version: versionOf(text) };
+        }),
+
+      async listKeys(prefix, ctx): Promise<string[]> {
+        let names: string[];
+        try {
+          names = await readdir(resolveDir(ctx));
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return [];
+          }
+          throw error;
+        }
+        return names
+          .filter((name) => name.endsWith(".json"))
+          .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
+          .filter((key) => key.startsWith(prefix))
+          .sort();
+      },
+    },
+
     // Playground eval batches: one JSON file per run under eval-runs/<agent>/.
     evals: {
       async put(run, ctx): Promise<void> {
@@ -208,14 +306,32 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
   };
 }
 
+/** Content-hash version token for a stored JSON text. */
+function versionOf(text: string): string {
+  return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+
 /** tmp + rename write so concurrent readers never see a torn file. */
 async function writeJsonAtomic(args: {
   dir: string;
   fileName: string;
   value: unknown;
+}): Promise<void> {
+  await writeTextAtomic({
+    dir: args.dir,
+    fileName: args.fileName,
+    text: JSON.stringify(args.value),
+  });
+}
+
+/** tmp + rename write of exact text (CAS hashes the same bytes it wrote). */
+async function writeTextAtomic(args: {
+  dir: string;
+  fileName: string;
+  text: string;
 }): Promise<void> {
   await mkdir(args.dir, { recursive: true });
   const tmp = join(args.dir, `.tmp-${randomUUID()}`);
-  await writeFile(tmp, JSON.stringify(args.value), "utf8");
+  await writeFile(tmp, args.text, "utf8");
   await rename(tmp, join(args.dir, args.fileName));
 }

package/src/storage.ts

@@ -6,9 +6,12 @@
  * pipeline, …). Without it, state lives under `--state-root` on local disk
  * only, and eval/A/B history stays in process memory.
  *
- * 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:
+ * 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:
  *
  * ```ts
  * import { defineStorage } from "@anysphere/agent-serve/storage";
@@ -18,6 +21,7 @@
  *   get: (key) => db.get(key),
  *   delete: (key) => db.delete(key),
  *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
+ *   cas: { getWithVersion: ..., putIfAbsent: ..., putIfVersion: ..., listKeys: ... },
  *   evals: { put: ..., delete: ..., list: ... }, // eval-runs table
  *   abs: { putSample: ... },                     // A/B table
  * });
@@ -50,7 +54,7 @@ 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";
+import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
 
 // ============================================================================
 // Sink interface
@@ -73,8 +77,10 @@ export interface StorageContext {
    * - `"policy"` — a flush trigger fired (turn end, debounce, change)
    * - `"shutdown"` — the serve process is draining; last chance to write
    * - `"restore"` — serve start or a lazy restore; reads rebuilding state
+   * - `"coordination"` — framework coordination driving
+   *   {@link StorageCasTable} (conditional writes)
    */
-  reason: "policy" | "shutdown" | "restore";
+  reason: "policy" | "shutdown" | "restore" | "coordination";
 }
 
 export interface StoragePolicy {
@@ -151,6 +157,50 @@ export interface StorageABTable {
   ): ABSnapshot | undefined | null | Promise<ABSnapshot | undefined | null>;
 }
 
+/**
+ * Conditional writes (CAS) — the coordination tier of the storage backend
+ * contract. Plain storage works without it, so existing backends keep
+ * working across a platform upgrade; framework coordination (the upcoming
+ * session ledger — see `@cursor/july/kv` for the backend-agnostic
+ * interface) requires it and fails at startup, with an actionable
+ * message, when the backend lacks it. The built-in backends all include
+ * it, so implementing this group yourself only comes up for BYO storage.
+ *
+ * Grouped under {@link StorageConfig.cas} rather than as loose methods —
+ * matching the `evals` / `abs` table groups — so `defineStorage`
+ * validates the whole group at once: there is no meaningful
+ * half-implementation.
+ *
+ * Version tokens are opaque per-key strings that change on every
+ * successful write (counter, UUID, content hash — whatever is cheap for
+ * the backend). See {@link KvVersionedEntry} / {@link KvCasResult}.
+ */
+export interface StorageCasTable {
+  /** Read one value with its version token. Miss → `undefined`. */
+  getWithVersion(
+    key: string,
+    ctx: StorageContext
+  ): Promise<KvVersionedEntry | undefined> | KvVersionedEntry | undefined;
+  /** Create the key only when absent. Conflict returns the existing entry. */
+  putIfAbsent(
+    key: string,
+    value: JsonValue,
+    ctx: StorageContext
+  ): Promise<KvCasResult> | KvCasResult;
+  /**
+   * Replace the value only when the key still carries `expectedVersion`.
+   * Conflict (version moved, or key deleted) returns the current entry.
+   */
+  putIfVersion(
+    key: string,
+    value: JsonValue,
+    expectedVersion: string,
+    ctx: StorageContext
+  ): Promise<KvCasResult> | KvCasResult;
+  /** All keys under a prefix, in ascending key order. */
+  listKeys(prefix: string, ctx: StorageContext): Promise<string[]> | string[];
+}
+
 export interface StorageConfig {
   /** Optional label surfaced on `GET /v1/info` diagnostics. */
   name?: string;
@@ -166,6 +216,14 @@ export interface StorageConfig {
    * (session event logs remain the assignment/fold source of truth).
    */
   abs?: StorageABTable;
+  /**
+   * Conditional writes (CAS). Optional for plain storage — existing
+   * backends keep working without it — but required by coordination
+   * features (the session ledger), which fail fast when it is absent.
+   * The built-in backends (`fileKv`, `cursorHostedStorage`) both include
+   * it. See {@link StorageCasTable}.
+   */
+  cas?: StorageCasTable;
   /**
    * Store one value under a key (upsert, last-write-wins). Called on the
    * framework's schedule — never concurrently, always in order. Keep it
@@ -228,6 +286,29 @@ export function defineStorage(config: StorageConfig): StorageDefinition {
       }
     }
   }
+  if (config.cas !== undefined) {
+    const casHooks = [
+      "getWithVersion",
+      "putIfAbsent",
+      "putIfVersion",
+      "listKeys",
+    ] as const;
+    const cas = config.cas;
+    // A partial group is a bug, not a legacy config: half-implemented CAS
+    // would pass the capability probe and corrupt coordination.
+    const missingCasHooks = casHooks.filter(
+      (hook) => typeof cas[hook] !== "function"
+    );
+    if (missingCasHooks.length > 0) {
+      throw new Error(
+        `defineStorage: ${missingCasHooks
+          .map((hook) => `cas.${hook}`)
+          .join(
+            ", "
+          )} must be ${missingCasHooks.length === 1 ? "a function" : "functions"} when the cas group is set`
+      );
+    }
+  }
   if (config.abs !== undefined) {
     if (typeof config.abs.putSample !== "function") {
       throw new Error(
@@ -321,8 +402,11 @@ export const MAX_KEY_SEGMENT_BYTES = 256;
  * digest of the raw value when the encoding exceeds
  * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
  * write path and the continuation-lookup path always agree.
+ *
+ * Exported for the session ledger, which builds its `session/` and
+ * `ledger/` keys with the same encoding rules.
  */
-function keySegment(raw: string): string {
+export function keySegment(raw: string): string {
   const encoded = encodeURIComponent(raw);
   if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
     return encoded;