@cursor/bdk 0.2.6 → 0.2.8

package/dist/playground/index.html

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-CI7FAmOP.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-6BbTPnaT.css">
+    <script type="module" crossorigin src="./assets/index-MijLHTbB.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-DPKLl4C_.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/storage-backends/cursor-hosted-v2.d.ts

@@ -1,37 +1,12 @@
 /**
  * Cursor-managed durable KV for hosted **architecture v2** agents.
  *
- * Talks to the AgentSDK v2 KV proxy
- * (`POST /internal/agentsdk/kv/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves the v2 deployment from that service
- * account (factorydb `agentsdk_deployment`) and persists rows in factorydb
- * `agentsdk_kv` — v1's Bugbot-backed `/internal/agent-serve/storage/*`
- * routes cannot resolve a v2 pod credential at all.
+ * Reads return opaque version tokens. Writes support unconditional updates,
+ * create-if-absent, and compare-and-swap. Lists use stable key pagination,
+ * and this client drains every page before returning.
  *
- * The v2 wire protocol is four routes, not v1's eight:
- *
- * - `POST /internal/agentsdk/kv/get`
- *   `{ key }` → `{ found, value, version }` — reads always carry the CAS
- *   version token ({@link KvV2GetResponse}).
- * - `POST /internal/agentsdk/kv/put`
- *   `{ key, value, ifAbsent? | ifVersion? }` → `{ ok, version, current }`
- *   ({@link KvV2PutResponse}) — one write primitive: last-write-wins when
- *   unconditional (still bumps the token), atomic create-if-absent with
- *   `ifAbsent: true`, atomic compare-and-swap with `ifVersion`.
- * - `POST /internal/agentsdk/kv/delete` `{ key }` → `{ ok }`.
- * - `POST /internal/agentsdk/kv/list`
- *   `{ prefix, limit?, cursor?, keysOnly? }` → `{ entries, nextCursor }`
- *   ({@link KvV2ListResponse}) — ascending key order with keyset
- *   pagination. `list` / `listKeys` below drain every page, so the v1
- *   truncated-scan failure mode does not exist here.
- *
- * 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`
- * is rejected on v2.
+ * This backend is selected automatically for architecture v2. Authors do
+ * not import it, and `agent/storage.ts` is rejected on v2.
  */
 import type { StorageCasTable, StorageConfig, StorageEvalsTable } from "../storage.js";
 import type { JsonValue } from "../types.js";
@@ -70,12 +45,9 @@ type CursorHostedStorageV2Methods = Required<Pick<StorageConfig, "put" | "get" |
     evals: StorageEvalsTable;
 };
 /**
- * Architecture-v2 `defineStorage` methods (AgentSDK v2 KV proxy → factorydb
- * `agentsdk_kv`). Platform-selected; spread into `defineStorage({...})` by
- * framework-storage-selection.ts. No `listNewest`: v2 session records live
- * on the framework file store, so the only consumer of write-time ordering
- * never reaches this backend and the engine's `list` fallback covers the
- * rest.
+ * Architecture-v2 managed storage methods. The platform spreads these into
+ * `defineStorage({...})`. Session history uses the framework file store, so
+ * this backend does not need write-time ordering.
  */
 export declare function cursorHostedStorageV2(options?: CursorHostedStorageOptions): CursorHostedStorageV2Methods;
 export {};

package/dist/storage-backends/cursor-hosted-v2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-hosted-v2.d.ts","sourceRoot":"","sources":["../../src/storage-backends/cursor-hosted-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,aAAa,CAAC;AAC5E,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,EAGhC,MAAM,oBAAoB,CAAC;AAI5B,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,2DAA2D;IAC3D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,oDAAoD;QACpD,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,KAAK,4BAA4B,GAAG,QAAQ,CAC1C,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IACvC,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,CAAC;AAgDF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,0BAA+B,GACvC,4BAA4B,CA2D9B"}
+{"version":3,"file":"cursor-hosted-v2.d.ts","sourceRoot":"","sources":["../../src/storage-backends/cursor-hosted-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,aAAa,CAAC;AAC5E,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,EAGhC,MAAM,oBAAoB,CAAC;AAI5B,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,2DAA2D;IAC3D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,oDAAoD;QACpD,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,KAAK,4BAA4B,GAAG,QAAQ,CAC1C,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IACvC,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,CAAC;AAgDF;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,0BAA+B,GACvC,4BAA4B,CA2D9B"}

package/dist/storage-backends/cursor-hosted-v2.js

@@ -1,37 +1,12 @@
 /**
  * Cursor-managed durable KV for hosted **architecture v2** agents.
  *
- * Talks to the AgentSDK v2 KV proxy
- * (`POST /internal/agentsdk/kv/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves the v2 deployment from that service
- * account (factorydb `agentsdk_deployment`) and persists rows in factorydb
- * `agentsdk_kv` — v1's Bugbot-backed `/internal/agent-serve/storage/*`
- * routes cannot resolve a v2 pod credential at all.
+ * Reads return opaque version tokens. Writes support unconditional updates,
+ * create-if-absent, and compare-and-swap. Lists use stable key pagination,
+ * and this client drains every page before returning.
  *
- * The v2 wire protocol is four routes, not v1's eight:
- *
- * - `POST /internal/agentsdk/kv/get`
- *   `{ key }` → `{ found, value, version }` — reads always carry the CAS
- *   version token ({@link KvV2GetResponse}).
- * - `POST /internal/agentsdk/kv/put`
- *   `{ key, value, ifAbsent? | ifVersion? }` → `{ ok, version, current }`
- *   ({@link KvV2PutResponse}) — one write primitive: last-write-wins when
- *   unconditional (still bumps the token), atomic create-if-absent with
- *   `ifAbsent: true`, atomic compare-and-swap with `ifVersion`.
- * - `POST /internal/agentsdk/kv/delete` `{ key }` → `{ ok }`.
- * - `POST /internal/agentsdk/kv/list`
- *   `{ prefix, limit?, cursor?, keysOnly? }` → `{ entries, nextCursor }`
- *   ({@link KvV2ListResponse}) — ascending key order with keyset
- *   pagination. `list` / `listKeys` below drain every page, so the v1
- *   truncated-scan failure mode does not exist here.
- *
- * 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`
- * is rejected on v2.
+ * This backend is selected automatically for architecture v2. Authors do
+ * not import it, and `agent/storage.ts` is rejected on v2.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -84,15 +59,12 @@ function listAllPages(options, body) {
     });
 }
 /**
- * Architecture-v2 `defineStorage` methods (AgentSDK v2 KV proxy → factorydb
- * `agentsdk_kv`). Platform-selected; spread into `defineStorage({...})` by
- * framework-storage-selection.ts. No `listNewest`: v2 session records live
- * on the framework file store, so the only consumer of write-time ordering
- * never reaches this backend and the engine's `list` fallback covers the
- * rest.
+ * Architecture-v2 managed storage methods. The platform spreads these into
+ * `defineStorage({...})`. Session history uses the framework file store, so
+ * this backend does not need write-time ordering.
  */
 export function cursorHostedStorageV2(options = {}) {
-    // Eval runs stay on the v1 proxy's dedicated table.
+    // Eval runs use the managed eval-storage path.
     const v1 = cursorHostedStorage(options);
     return {
         [CURSOR_HOSTED_STORAGE]: true,

package/dist/storage-backends/cursor-hosted.d.ts

@@ -1,30 +1,21 @@
 /**
  * Cursor-managed durable storage for hosted agents.
  *
- * Talks to the control-plane storage proxy
- * (`POST /internal/agent-serve/storage/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves `deployment_id` from that service
- * account — engines never receive a Bugbot DSN and cannot address another
- * deployment's rows.
- *
- * 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/bdk/internal/file-kv` instead.
- * Wiring it into a storage sink is internal-only `defineStorage`
- * territory (see `storage.ts`).
+ * Uses the control-plane storage proxy with the deployment pod credential.
+ * The proxy scopes each request to the authenticated deployment, and the
+ * engine never receives a database URL. Cursor manages its storage
+ * environment variables; do not add them to `hosting.secretNames`.
  */
 import type { StorageCasTable, StorageConfig, StorageEvalsTable } from "../storage.js";
 import type { JsonValue } from "../types.js";
 /**
- * Diagnostic / self-host deployment id. Not the hosted-storage authz
- * boundary — the proxy scopes rows from the authenticated service account.
+ * Deployment identifier for diagnostics and self-hosted compatibility.
+ * The proxy scopes managed-storage requests by pod credential.
  */
 export declare const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR: "AGENT_SERVE_DEPLOYMENT_ID";
 /**
- * Platform-managed secret / env names. User `secrets set` / DELETE cannot
- * claim these. Hosted storage talks to the HTTP proxy; engines never
- * receive a database URL.
+ * Environment variables reserved for Cursor-managed storage. Do not include
+ * these names in `hosting.secretNames`.
  */
 export declare const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR];
 export interface CursorHostedStorageOptions {
@@ -37,18 +28,16 @@ export interface CursorHostedStorageOptions {
     apiKey?: string;
     /**
      * Lazy credential, re-resolved on every call and preferred over
-     * {@link apiKey}: hosted freeze snapshots listen unsigned and bind the
-     * key file after serve start, so a value captured at construct time
-     * would be permanently absent. Used by the platform-selected v2
-     * defaults; kept separate so `apiKey` stays a plain string for authors.
+     * {@link apiKey}.
      */
     resolveApiKey?: () => string | undefined;
-    /** Injected for tests. */
+    /** Custom fetch implementation. */
     fetch?: typeof fetch;
 }
 /**
  * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
- * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
+ * Cursor-managed durable state for session listing. It survives a
+ * `defineStorage` spread.
  * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
  * (TS9010).
  */
@@ -81,8 +70,8 @@ export interface KvCasResponse {
 export interface KvListKeysResponse {
     keys: string[];
     /**
-     * Set when the scan hit the server's row cap and `keys` is incomplete.
-     * Additive: older servers omit it (treated as `false`).
+     * Set when `keys` is incomplete. Older servers may omit it, which is
+     * treated as `false`.
      */
     truncated?: boolean;
 }
@@ -93,14 +82,12 @@ export declare class StorageRpcError extends Error {
     constructor(message: string, reasonCode: string, status: number);
 }
 /**
- * One authenticated POST to the control-plane proxy. Shared with the
- * architecture-v2 backend (`cursor-hosted-v2.ts`), which speaks a different
- * route family over the same transport and credential chain.
+ * Send one authenticated request through the control-plane proxy.
  */
 export declare function storageRpc<T>(options: CursorHostedStorageOptions, path: string, body: Record<string, unknown>): Promise<T>;
 /**
- * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
- * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ * Cursor-managed durable storage methods. Requests use the control-plane
+ * proxy and deployment pod credential. Spread into `defineStorage({...})`.
  */
 export declare function cursorHostedStorage(options?: CursorHostedStorageOptions): CursorHostedStorageMethods;
 export {};

package/dist/storage-backends/cursor-hosted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/storage-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,aAAa,CAAC;AAW5E;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAAG,2BAAoC,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,CAAC,OAAO,iCAAiC,CAE9F,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAE1C,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAED,KAAK,0BAA0B,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC,CACtE,GAAG;IACF,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IACvC,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,CAAC;AA4BF,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAaD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,6BAA6B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAK9D;CACF;AAuCD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CA8CZ;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CAiH5B"}
+{"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/storage-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,aAAa,CAAC;AAQ5E;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAAG,2BAAoC,CAAC;AAEtF;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,CAAC,OAAO,iCAAiC,CAE9F,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,MAE1C,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAED,KAAK,0BAA0B,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC,CACtE,GAAG;IACF,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;IACvC,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,CAAC;AAMF,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,OAAO,EAAE;QAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAaD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,6BAA6B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAK9D;CACF;AAuCD;;GAEG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CA8CZ;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CAiH5B"}

package/dist/storage-backends/cursor-hosted.js

@@ -1,18 +1,10 @@
 /**
  * Cursor-managed durable storage for hosted agents.
  *
- * Talks to the control-plane storage proxy
- * (`POST /internal/agent-serve/storage/*`) using the engine's pod
- * `CURSOR_API_KEY`. The server resolves `deployment_id` from that service
- * account — engines never receive a Bugbot DSN and cannot address another
- * deployment's rows.
- *
- * 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/bdk/internal/file-kv` instead.
- * Wiring it into a storage sink is internal-only `defineStorage`
- * territory (see `storage.ts`).
+ * Uses the control-plane storage proxy with the deployment pod credential.
+ * The proxy scopes each request to the authenticated deployment, and the
+ * engine never receives a database URL. Cursor manages its storage
+ * environment variables; do not add them to `hosting.secretNames`.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -26,28 +18,25 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { injectActiveTraceContext } from "../otel.js";
 /**
  * Same default as {@link cursorExternalApiUrl} in the CLI credentials module,
- * inlined here so this storage entrypoint does not import CLI/zod code.
- * Hosted monorepo examples load this file from `packages/agent-serve/src`
- * while `npm install` runs in the example package — a credentials import
- * would resolve `zod` from the wrong `node_modules` tree and crash serve.
+ * kept local so this storage entrypoint does not import CLI dependencies.
  */
 const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 /**
- * Diagnostic / self-host deployment id. Not the hosted-storage authz
- * boundary — the proxy scopes rows from the authenticated service account.
+ * Deployment identifier for diagnostics and self-hosted compatibility.
+ * The proxy scopes managed-storage requests by pod credential.
  */
 export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR = "AGENT_SERVE_DEPLOYMENT_ID";
 /**
- * Platform-managed secret / env names. User `secrets set` / DELETE cannot
- * claim these. Hosted storage talks to the HTTP proxy; engines never
- * receive a database URL.
+ * Environment variables reserved for Cursor-managed storage. Do not include
+ * these names in `hosting.secretNames`.
  */
 export const CURSOR_HOSTED_STORAGE_ENV_VARS = [
     AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
 ];
 /**
  * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
- * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
+ * Cursor-managed durable state for session listing. It survives a
+ * `defineStorage` spread.
  * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
  * (TS9010).
  */
@@ -109,9 +98,7 @@ function resolveBaseUrl(options) {
     return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
 /**
- * One authenticated POST to the control-plane proxy. Shared with the
- * architecture-v2 backend (`cursor-hosted-v2.ts`), which speaks a different
- * route family over the same transport and credential chain.
+ * Send one authenticated request through the control-plane proxy.
  */
 export function storageRpc(options, path, body) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -162,8 +149,8 @@ export function storageRpc(options, path, body) {
     });
 }
 /**
- * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
- * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ * Cursor-managed durable storage methods. Requests use the control-plane
+ * proxy and deployment pod credential. Spread into `defineStorage({...})`.
  */
 export function cursorHostedStorage(options = {}) {
     return {

package/dist/storage-protocol.d.ts

@@ -1,9 +1,9 @@
 /**
  * Durable session KV contract: key families plus a tolerant SessionRecord
- * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
- * plane. Architecture v2 uses the same key shape under its AgentSDK root.
+ * decoder. Both hosted architectures use the same key shape under their
+ * versioned roots.
  *
- * Additive JSON only — unknown fields are ignored.
+ * Additive JSON only: unknown fields are ignored.
  */
 /** Legacy architecture-v1 storage root. */
 export declare const STORAGE_KEY_ROOT: "agentkit/v1";
@@ -16,39 +16,18 @@ export declare const AGENTSDK_STORAGE_KEY_ROOT: "agentsdk/v1";
  * Build the framework-owned key scheme under one versioned root. Channel ids
  * and continuation tokens are URI-encoded, and oversized segments are
  * replaced by a deterministic `sha256:…` digest.
- *
- * | Key | Value |
- * | --- | --- |
- * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
- * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
- * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
- *
- * 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.
  */
 declare function createStorageKeys(root: string): {
     readonly session: (agent: string, sessionId: string) => string;
     readonly sessionPrefix: (agent: string) => string;
     readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
     readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
-    /**
-     * One session-level hosted-execution log (v2 only). `sessionPublicId` is
-     * the factory `ses_…` so a throw that never minted a July session still
-     * lands under a stable key. Per-execution rows live inside the document.
-     */
+    /** One session-level hosted execution log. */
     readonly sessionRun: (agent: string, sessionPublicId: string) => string;
     readonly sessionRunsPrefix: (agent: string) => string;
     /**
-     * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
-     * `logId` is the factory `ses_…` after a `send`, or
-     * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
-     * before a session exists. Skip/task admissions do not write this key.
-     * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
-     * objects, and this key is flushed in snapshots, not per line.
+     * Hosted execution output, keyed by session or by workflow when no
+     * session exists.
      */
     readonly log: (agent: string, logId: string) => string;
     readonly logsPrefix: (agent: string) => string;
@@ -59,7 +38,7 @@ declare function createStorageKeys(root: string): {
      */
     readonly kv: (agent: string, key: string) => string;
     readonly kvPrefix: (agent: string) => string;
-    /** One playground eval-run snapshot (derived `evals` table). */
+    /** One playground eval-run snapshot. */
     readonly evalRun: (agent: string, runId: string) => string;
     readonly evalRunsPrefix: (agent: string) => string;
 };
@@ -71,18 +50,14 @@ export declare const agentSdkStorageKeys: StorageKeys;
 export declare function storageKeysForArchitecture(architecture: "v1" | "v2" | undefined): StorageKeys;
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.
- * Chosen so full keys stay well under common backend limits (Postgres btree
- * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
- * replaced by their SHA-256 digest, keeping every minted key bounded.
+ * Longer segments use their SHA-256 digest so every minted key stays within
+ * supported storage limits.
  */
 export declare const MAX_KEY_SEGMENT_BYTES = 256;
 /**
- * Stable start-log object id. A `send` attaches to the factory session
- * so the factory/dashboard session-runs read can see it. Admission that
- * fails before a session exists is keyed on the Temporal workflow run
- * (`wf:{workflowId}` or `wf:{workflowId}/{runId}`) so the object joins
- * the Temporal UI. A successful skip/task writes nothing — there is no
- * customer log.
+ * Stable execution-log id. Prefer the session id, then use the workflow
+ * identity for failures before a session exists. Successful work without a
+ * session writes no log.
  */
 export declare function frameworkStartLogId(args: {
     sessionPublicId?: string | null;
@@ -135,7 +110,7 @@ export declare function summarizeDurableSessionRecord(args: {
 }): DurableSessionSummary;
 /**
  * Golden persisted record: required list fields plus extras a future engine
- * might write. Both this package and the CP decoder must accept it.
+ * might write. Package and service decoders must both accept it.
  */
 export declare const GOLDEN_DURABLE_SESSION_RECORD: Record<string, unknown>;
 export {};

package/dist/storage-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-protocol.d.ts","sourceRoot":"","sources":["../src/storage-protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage-protocol.d.ts","sourceRoot":"","sources":["../src/storage-protocol.ts"],"names":[],"mappings":"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"}

package/dist/storage-protocol.js

@@ -1,9 +1,9 @@
 /**
  * Durable session KV contract: key families plus a tolerant SessionRecord
- * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
- * plane. Architecture v2 uses the same key shape under its AgentSDK root.
+ * decoder. Both hosted architectures use the same key shape under their
+ * versioned roots.
  *
- * Additive JSON only — unknown fields are ignored.
+ * Additive JSON only: unknown fields are ignored.
  */
 import { createHash } from "node:crypto";
 import { isRecord } from "./internal/is-record.js";
@@ -16,26 +16,13 @@ export const STORAGE_KEY_ROOT = "agentkit/v1";
 export const AGENTSDK_STORAGE_KEY_ROOT = "agentsdk/v1";
 /**
  * Exact session-record keys: `{agentkit|agentsdk}/v1/{agent}/session/{sessionId}`.
- * Rejects `session-events/` and the CP-owned `_cp` agent name.
+ * Rejects `session-events/` and the reserved `_cp` agent name.
  */
 const DURABLE_SESSION_RECORD_KEY_RE = /^(agentkit|agentsdk)\/v1\/([^/]+)\/session\/([^/]+)$/;
 /**
  * Build the framework-owned key scheme under one versioned root. Channel ids
  * and continuation tokens are URI-encoded, and oversized segments are
  * replaced by a deterministic `sha256:…` digest.
- *
- * | Key | Value |
- * | --- | --- |
- * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
- * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
- * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
- *
- * 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) {
     return {
@@ -43,20 +30,12 @@ function createStorageKeys(root) {
         sessionPrefix: (agent) => `${root}/${agent}/session/`,
         sessionEvents: (agent, sessionId, firstIndex) => `${root}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
         sessionEventsPrefix: (agent, sessionId) => `${root}/${agent}/session-events/${sessionId}/`,
-        /**
-         * One session-level hosted-execution log (v2 only). `sessionPublicId` is
-         * the factory `ses_…` so a throw that never minted a July session still
-         * lands under a stable key. Per-execution rows live inside the document.
-         */
+        /** One session-level hosted execution log. */
         sessionRun: (agent, sessionPublicId) => `${root}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
         sessionRunsPrefix: (agent) => `${root}/${agent}/session-runs/`,
         /**
-         * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
-         * `logId` is the factory `ses_…` after a `send`, or
-         * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
-         * before a session exists. Skip/task admissions do not write this key.
-         * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
-         * objects, and this key is flushed in snapshots, not per line.
+         * Hosted execution output, keyed by session or by workflow when no
+         * session exists.
          */
         log: (agent, logId) => `${root}/${agent}/logs/${keySegment(logId)}`,
         logsPrefix: (agent) => `${root}/${agent}/logs/`,
@@ -67,7 +46,7 @@ function createStorageKeys(root) {
          */
         kv: (agent, key) => `${root}/${agent}/kv/${keySegment(key)}`,
         kvPrefix: (agent) => `${root}/${agent}/kv/`,
-        /** One playground eval-run snapshot (derived `evals` table). */
+        /** One playground eval-run snapshot. */
         evalRun: (agent, runId) => `${root}/${agent}/eval-runs/${keySegment(runId)}`,
         evalRunsPrefix: (agent) => `${root}/${agent}/eval-runs/`,
     };
@@ -81,18 +60,14 @@ export function storageKeysForArchitecture(architecture) {
 }
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.
- * Chosen so full keys stay well under common backend limits (Postgres btree
- * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
- * replaced by their SHA-256 digest, keeping every minted key bounded.
+ * Longer segments use their SHA-256 digest so every minted key stays within
+ * supported storage limits.
  */
 export const MAX_KEY_SEGMENT_BYTES = 256;
 /**
- * Stable start-log object id. A `send` attaches to the factory session
- * so the factory/dashboard session-runs read can see it. Admission that
- * fails before a session exists is keyed on the Temporal workflow run
- * (`wf:{workflowId}` or `wf:{workflowId}/{runId}`) so the object joins
- * the Temporal UI. A successful skip/task writes nothing — there is no
- * customer log.
+ * Stable execution-log id. Prefer the session id, then use the workflow
+ * identity for failures before a session exists. Successful work without a
+ * session writes no log.
  */
 export function frameworkStartLogId(args) {
     var _a, _b, _c;
@@ -184,7 +159,7 @@ export function summarizeDurableSessionRecord(args) {
 }
 /**
  * Golden persisted record: required list fields plus extras a future engine
- * might write. Both this package and the CP decoder must accept it.
+ * might write. Package and service decoders must both accept it.
  */
 export const GOLDEN_DURABLE_SESSION_RECORD = {
     sessionId: "ses_aaaaaaaaaaaaaaaaaaaaaaaa",