@cursor/july 0.1.108 → 0.1.111

package/src/kv/memory-kv.ts

@@ -1,9 +1,11 @@
 /**
- * In-memory {@link HostKvCasApi} — the test/dev implementation of the
- * interface module (`@cursor/july/kv`), exported at
- * `@cursor/july/kv/memory`.
+ * In-memory {@link HostKvCasApi} — the test/dev implementation of
+ * `@cursor/july/kv`.
  *
- * The memory KV *is* the dev shim: tests and local runs exercise the
+ * Internal only: SDK tests and Cursor factory code. Not a public Agent
+ * SDK export.
+ *
+ * The memory KV *is* the test shim: tests and local runs exercise the
  * CAS contract, not a mock of an RPC. Values are deep-copied on both write and
  * read so callers can never observe (or cause) shared-reference mutation.
  */
@@ -74,7 +76,7 @@ export function createMemoryKv(): HostKvCasApi {
     },
 
     async listKeys(prefix): Promise<string[]> {
-      return [...entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+      return [...entries.keys()].filter(key => key.startsWith(prefix)).sort();
     },
   };
 }
@@ -89,10 +91,10 @@ export function createMemoryKv(): HostKvCasApi {
 export function memoryCasTable(): StorageCasTable {
   const kv = createMemoryKv();
   return {
-    getWithVersion: (key) => kv.getWithVersion(key),
+    getWithVersion: key => kv.getWithVersion(key),
     putIfAbsent: (key, value) => kv.putIfAbsent(key, value),
     putIfVersion: (key, value, expectedVersion) =>
       kv.putIfVersion(key, value, expectedVersion),
-    listKeys: (prefix) => kv.listKeys(prefix),
+    listKeys: prefix => kv.listKeys(prefix),
   };
 }

package/src/kv.ts

@@ -8,13 +8,10 @@
  * stores of unknown provenance — a `defineStorage` backend declares CAS
  * through its `cas` group instead, so it never needs probing.
  *
- * Implementations live elsewhere:
- *
- * - `@cursor/july/kv/memory` — `createMemoryKv`, the test/dev shim.
- * - The storage backends implement the same operations as the `cas`
- *   group on `defineStorage` (see `StorageCasTable` in
- *   `@cursor/july/storage`): `fileKv` (single-process) and
- *   `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
+ * Implementations live on the storage backends: they implement the same
+ * operations as the `cas` group on the internal-only `defineStorage`
+ * (its `StorageCasTable` member): `fileKv` (single-process) and
+ * `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
  */
 
 export type {

package/src/otel-public.ts

@@ -0,0 +1,24 @@
+/**
+ * Public `@cursor/july/otel` surface: types and W3C `traceparent`
+ * helpers. `defineOtel` is `@cursor/july/internal/otel`.
+ */
+
+export type {
+  OtelConfig,
+  OtelConfigFactory,
+  OtelDefinition,
+  OtelExporterConfig,
+  OtelLogOptions,
+  OtelMetricOptions,
+  OtelSignal,
+  OtelTraceOptions,
+} from "./otel.js";
+export {
+  activeTraceparent,
+  BACKEND_TRACEPARENT_HEADER,
+  formatTraceparent,
+  injectActiveTraceContext,
+  installOutboundFetchInstrumentation,
+  instrumentedFetch,
+  TRACEPARENT_HEADER,
+} from "./otel.js";

package/src/otel.ts

@@ -3,7 +3,7 @@
  * or set `OTEL_EXPORTER_OTLP_ENDPOINT` (standard OTel env).
  *
  * ```ts
- * import { defineOtel } from "@cursor/july/otel";
+ * import { defineOtel } from "@cursor/july/internal/otel";
  *
  * export default defineOtel({
  *   serviceName: "cursor",
@@ -13,6 +13,8 @@
  * // Hosted v2: re-read env on flush after deployment secrets bind.
  * export default defineOtel(() => resolveMyOtelConfig());
  * ```
+ *
+ * Internal only: Cursor factory agents. Not a public Agent SDK export.
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -107,7 +109,10 @@ export const OTEL_CONFIG_RESOLVE: symbol = Symbol.for(
   "anysphere.july.otel.configResolve"
 );
 
-/** Author OpenTelemetry export under `agent/otel.ts`. */
+/**
+ * Author OpenTelemetry export under `agent/otel.ts`.
+ * Import from `@cursor/july/internal/otel`, not `@cursor/july`.
+ */
 export function defineOtel(
   config: OtelConfig | OtelConfigFactory = {}
 ): OtelDefinition {

package/src/prompt.ts

@@ -61,7 +61,7 @@ function dedentLines(
   if (!Number.isFinite(minIndent)) {
     minIndent = 0;
   }
-  return lines.map((line) => (line.trim() === "" ? "" : line.slice(minIndent)));
+  return lines.map(line => (line.trim() === "" ? "" : line.slice(minIndent)));
 }
 
 export type PromptTag = {

package/src/result.ts

@@ -2,8 +2,10 @@
  * `defineResult` — authored at `agent/result.ts`.
  *
  * After the model finishes, `commit` runs on the serving host with the
- * full assistant text. Throw to fail the turn. Parse `ctx.text` however
- * the agent needs.
+ * full assistant text. Throw to fail the turn. Call `ctx.reject(message)`
+ * when the model can still fix the output; the host re-runs the same
+ * turn with that message (two repairs). Parse `ctx.text` however the
+ * agent needs.
  *
  * ```ts
  * import { defineResult } from "@cursor/july/result";
@@ -13,7 +15,11 @@
  *     if (ctx.session.purpose === "eval") {
  *       return;
  *     }
- *     await applyDecision(parseDecision(ctx.text), ctx.host);
+ *     const parsed = parseDecision(ctx.text);
+ *     if (parsed === undefined) {
+ *       ctx.reject("End the turn with a decision document.");
+ *     }
+ *     await applyDecision(parsed, ctx.host);
  *   },
  * });
  * ```
@@ -22,11 +28,7 @@
 import { brandDefinition } from "./internal/brand.js";
 import type { ResultConfig, ResultDefinition } from "./types.js";
 
-export type {
-  ResultConfig,
-  ResultContext,
-  ResultDefinition,
-} from "./types.js";
+export type { ResultConfig, ResultContext, ResultDefinition } from "./types.js";
 
 export function defineResult(config: ResultConfig): ResultDefinition {
   if (typeof config.commit !== "function") {

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

@@ -25,9 +25,9 @@
  *   pagination. `list` / `listKeys` below drain every page, so the v1
  *   truncated-scan failure mode does not exist here.
  *
- * Eval runs and A/B samples still ride the v1 storage proxy's dedicated
- * tables (`evals` / `abs` below); moving them to factorydb is a separate
- * follow-up from the KV cutover.
+ * Eval runs still ride the v1 storage proxy's dedicated table (`evals`
+ * below); moving them to factorydb is a separate follow-up from the KV
+ * cutover.
  *
  * This backend is platform-selected for architecture v2
  * (framework-storage-selection.ts) — authors never import it; `agent/storage.ts`
@@ -35,7 +35,6 @@
  */
 
 import type {
-  StorageABTable,
   StorageCasTable,
   StorageConfig,
   StorageEntry,
@@ -85,7 +84,6 @@ type CursorHostedStorageV2Methods = Required<
   readonly [CURSOR_HOSTED_STORAGE]: true;
   cas: StorageCasTable;
   evals: StorageEvalsTable;
-  abs: StorageABTable;
 };
 
 function toCasResult(response: KvV2PutResponse): KvCasResult {
@@ -149,7 +147,7 @@ async function listAllPages(
 export function cursorHostedStorageV2(
   options: CursorHostedStorageOptions = {}
 ): CursorHostedStorageV2Methods {
-  // Eval runs and A/B samples stay on the v1 proxy's dedicated tables.
+  // Eval runs stay on the v1 proxy's dedicated table.
   const v1 = cursorHostedStorage(options);
   return {
     [CURSOR_HOSTED_STORAGE]: true,
@@ -172,7 +170,7 @@ export function cursorHostedStorageV2(
     },
     async list(prefix): Promise<StorageEntry[]> {
       const entries = await listAllPages(options, { prefix });
-      return entries.map((entry) => ({
+      return entries.map(entry => ({
         key: entry.key,
         value: entry.value ?? null,
       }));
@@ -210,10 +208,9 @@ export function cursorHostedStorageV2(
           prefix,
           keysOnly: true,
         });
-        return entries.map((entry) => entry.key);
+        return entries.map(entry => entry.key);
       },
     },
     evals: v1.evals,
-    abs: v1.abs,
   };
 }

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

@@ -10,23 +10,14 @@
  * 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/file-kv` instead.
- *
- * ```ts
- * import { defineStorage } from "@cursor/july/storage";
- * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
- *
- * export default defineStorage({
- *   ...cursorHostedStorage(),
- * });
- * ```
+ * a deployment SA key, or use `@cursor/july/internal/file-kv` instead.
+ * Wiring it into a storage sink is internal-only `defineStorage`
+ * territory (see `storage.ts`).
  */
 
-import type { ABSnapshot } from "../ab.js";
 import type { EvalRunSnapshot } from "../evals.js";
 import { injectActiveTraceContext } from "../otel.js";
 import type {
-  StorageABTable,
   StorageCasTable,
   StorageConfig,
   StorageEntry,
@@ -43,13 +34,6 @@ import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
  */
 const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 
-/**
- * Reserved so user `secrets set` cannot smuggle a Bugbot DSN into the pod.
- * Not injected by Cursor hosting (storage is HTTP-proxied).
- */
-export const AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR =
-  "BUGBOTDB_URL" as const;
-
 /**
  * Diagnostic / self-host deployment id. Not the hosted-storage authz
  * boundary — the proxy scopes rows from the authenticated service account.
@@ -59,15 +43,12 @@ export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR =
 
 /**
  * Platform-managed secret / env names. User `secrets set` / DELETE cannot
- * claim these.
+ * claim these. Hosted storage talks to the HTTP proxy; engines never
+ * receive a database URL.
  */
 export const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [
-  typeof AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
   typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
-] = [
-  AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
-  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
-];
+] = [AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR];
 
 export interface CursorHostedStorageOptions {
   /**
@@ -114,7 +95,6 @@ type CursorHostedStorageMethods = Required<
   readonly [CURSOR_HOSTED_STORAGE]: true;
   cas: StorageCasTable;
   evals: StorageEvalsTable;
-  abs: StorageABTable;
 };
 
 // ============================================================================
@@ -417,39 +397,5 @@ export function cursorHostedStorage(
         return result.runs;
       },
     },
-    abs: {
-      async putSample(sample, ctx): Promise<void> {
-        await storageRpc(
-          options,
-          "/internal/agent-serve/storage/abs/put-sample",
-          {
-            agentName: ctx.agentName,
-            sample,
-          }
-        );
-      },
-      async putSnapshot(snapshot, ctx): Promise<void> {
-        await storageRpc(
-          options,
-          "/internal/agent-serve/storage/abs/put-snapshot",
-          {
-            agentName: ctx.agentName,
-            snapshot,
-          }
-        );
-      },
-      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
-        const result = await storageRpc<{
-          found: boolean;
-          snapshot: ABSnapshot | null;
-        }>(options, "/internal/agent-serve/storage/abs/get-snapshot", {
-          agentName: ctx.agentName,
-        });
-        if (!result.found) {
-          return undefined;
-        }
-        return result.snapshot ?? undefined;
-      },
-    },
   };
 }

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

@@ -1,19 +1,17 @@
 /**
- * File-backed `defineStorage` helper: a file-per-key KV store plus
- * file-backed `evals` / `abs` tables.
+ * File-backed `defineStorage` helper: a file-per-key KV store plus a
+ * file-backed `evals` table.
  *
  * 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), 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
- * key scheme, but the evals/abs tables have no such scheme — the agent
- * subdirectory keeps agents sharing one storage `dir` from mixing or
- * overwriting each other's history. Swap this for a real backend
- * (Postgres, S3, …) in production; the contracts are identical.
+ * and eval runs as `eval-runs/<agent>/<runId>.json`. KV keys carry the
+ * agent name inside the framework key scheme, but the evals table has no
+ * such scheme — the agent subdirectory keeps agents sharing one storage
+ * `dir` from mixing or overwriting each other's history. Swap this for a
+ * real backend (Postgres, S3, …) in production; the contracts are
+ * identical.
  *
  * Layout notes:
  * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
@@ -29,7 +27,6 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import {
-  appendFile,
   mkdir,
   readdir,
   readFile,
@@ -38,10 +35,8 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import type { ABSnapshot } from "../ab.js";
 import type { EvalRunSnapshot } from "../evals.js";
 import type {
-  StorageABTable,
   StorageCasTable,
   StorageConfig,
   StorageContext,
@@ -63,7 +58,6 @@ type FileKvMethods = Required<
 > & {
   cas: StorageCasTable;
   evals: StorageEvalsTable;
-  abs: StorageABTable;
 };
 
 /** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
@@ -72,12 +66,10 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
     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).
+  // The evals table is scoped per agent (KV keys already carry the agent
+  // name via the framework key scheme).
   const evalRunsDir = (ctx: StorageContext): string =>
     join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
-  const abDir = (ctx: StorageContext): string =>
-    join(resolveDir(ctx), "ab", encodeURIComponent(ctx.agentName));
   const filePath = (ctx: StorageContext, key: string): string =>
     join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
   const readRaw = async (
@@ -153,9 +145,9 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
         throw error;
       }
       const keys = names
-        .filter((name) => name.endsWith(".json"))
-        .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
-        .filter((key) => key.startsWith(prefix))
+        .filter(name => name.endsWith(".json"))
+        .map(name => decodeURIComponent(name.slice(0, -".json".length)))
+        .filter(key => key.startsWith(prefix))
         .sort();
       const entries: StorageEntry[] = [];
       for (const key of keys) {
@@ -223,9 +215,9 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
           throw error;
         }
         return names
-          .filter((name) => name.endsWith(".json"))
-          .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
-          .filter((key) => key.startsWith(prefix))
+          .filter(name => name.endsWith(".json"))
+          .map(name => decodeURIComponent(name.slice(0, -".json".length)))
+          .filter(key => key.startsWith(prefix))
           .sort();
       },
     },
@@ -256,7 +248,7 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
           throw error;
         }
         const runs: EvalRunSnapshot[] = [];
-        for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+        for (const name of names.filter(n => n.endsWith(".json")).sort()) {
           // One unreadable/corrupt file must not wipe the whole history:
           // hydrate treats a throwing list() as "nothing saved".
           try {
@@ -270,39 +262,6 @@ export function fileKv(options?: FileKvOptions): FileKvMethods {
         return runs;
       },
     },
-
-    // A/B metrics: append-only sample log + latest aggregate snapshot,
-    // both under ab/<agent>/.
-    abs: {
-      async putSample(sample, ctx): Promise<void> {
-        const dir = abDir(ctx);
-        await mkdir(dir, { recursive: true });
-        await appendFile(
-          join(dir, "samples.ndjson"),
-          `${JSON.stringify(sample)}\n`,
-          "utf8"
-        );
-      },
-      async putSnapshot(snapshot, ctx): Promise<void> {
-        await writeJsonAtomic({
-          dir: abDir(ctx),
-          fileName: "snapshot.json",
-          value: snapshot,
-        });
-      },
-      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
-        try {
-          return JSON.parse(
-            await readFile(join(abDir(ctx), "snapshot.json"), "utf8")
-          ) as ABSnapshot;
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-            return undefined;
-          }
-          throw error;
-        }
-      },
-    },
   };
 }
 

package/src/storage-protocol.ts

@@ -39,10 +39,9 @@ const DURABLE_SESSION_RECORD_KEY_RE =
  * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
- * 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 `StorageConfig.evals` / `StorageConfig.abs` groups never
- * sees them.
+ * The `eval-runs` family is minted only by the table `defineStorage`
+ * derives over the KV core; a backend that authors a dedicated
+ * `StorageConfig.evals` group never sees it.
  */
 function createStorageKeys(root: string) {
   return {
@@ -94,19 +93,6 @@ function createStorageKeys(root: string) {
     evalRun: (agent: string, runId: string): string =>
       `${root}/${agent}/eval-runs/${keySegment(runId)}`,
     evalRunsPrefix: (agent: string): string => `${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 =>
-      `${root}/${agent}/ab-samples/${keySegment(experiment)}/${keySegment(sessionId)}/${keySegment(at)}`,
-    /** Latest aggregate A/B snapshot (derived `abs` table, LWW). */
-    abSnapshot: (agent: string): string => `${root}/${agent}/ab-snapshot`,
   } as const;
 }