npm - @cursor/july - Versions diffs - 0.1.8 → 0.1.9 - Mend

@cursor/july 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/dist/playground/index.html CHANGED Viewed

@@ -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-Bpr4Th4M.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-7GJIUFQj.css">
+    <script type="module" crossorigin src="./assets/index-C0-QEG4O.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-z3JY9O2x.css">
   </head>
   <body>
     <div id="root"></div>

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

@@ -0,0 +1,65 @@
+/**
+ * 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/july/storage/postgres-kv` /
+ * `file-kv` instead.
+ *
+ * ```ts
+ * import { defineStorage } from "@cursor/july/storage";
+ * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+ *
+ * export default defineStorage({
+ *   ...cursorHostedStorage(),
+ * });
+ * ```
+ */
+import type { StorageABTable, StorageConfig, StorageEvalsTable } from "../storage.js";
+/**
+ * Reserved so user `secrets set` cannot smuggle a Bugbot DSN into the pod.
+ * Not injected by Cursor hosting (storage is HTTP-proxied).
+ */
+export declare const AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR: "BUGBOTDB_URL";
+/**
+ * Diagnostic / self-host deployment id. Not the hosted-storage authz
+ * boundary — the proxy scopes rows from the authenticated service account.
+ */
+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.
+ */
+export declare const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [
+    typeof AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+    typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR
+];
+export interface CursorHostedStorageOptions {
+    /**
+     * Control-plane base URL (default: `CURSOR_API_BASE_URL`, else
+     * `https://api.cursor.com`).
+     */
+    baseUrl?: string;
+    /** Bearer credential (default: `CURSOR_API_KEY`). */
+    apiKey?: string;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+type CursorHostedStorageMethods = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> & {
+    evals: StorageEvalsTable;
+    abs: StorageABTable;
+};
+/**
+ * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
+ * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ */
+export declare function cursorHostedStorage(options?: CursorHostedStorageOptions): CursorHostedStorageMethods;
+export {};
+//# sourceMappingURL=cursor-hosted.d.ts.map

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

@@ -0,0 +1 @@

+ {"version":3,"file":"cursor-hosted.d.ts","sourceRoot":"","sources":["../../src/storage-backends/cursor-hosted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAYvB;;;GAGG;AACH,eAAO,MAAM,+CAA+C,EAC1D,cAAuB,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAC5C,2BAAoC,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS;IACpD,OAAO,+CAA+C;IACtD,OAAO,iCAAiC;CAIzC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,KAAK,0BAA0B,GAAG,QAAQ,CACxC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,cAAc,CAAC;CACrB,CAAC;AA8DF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,0BAA+B,GACvC,0BAA0B,CA0F5B"}

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

@@ -0,0 +1,203 @@
+/**
+ * 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/july/storage/postgres-kv` /
+ * `file-kv` instead.
+ *
+ * ```ts
+ * import { defineStorage } from "@cursor/july/storage";
+ * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+ *
+ * export default defineStorage({
+ *   ...cursorHostedStorage(),
+ * });
+ * ```
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * 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.
+ */
+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";
+/**
+ * Diagnostic / self-host deployment id. Not the hosted-storage authz
+ * boundary — the proxy scopes rows from the authenticated service account.
+ */
+export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR = "AGENT_SERVE_DEPLOYMENT_ID";
+/**
+ * Platform-managed secret / env names. User `secrets set` / DELETE cannot
+ * claim these.
+ */
+export const CURSOR_HOSTED_STORAGE_ENV_VARS = [
+    AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+    AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+];
+function resolveApiKey(options) {
+    var _a;
+    var _b;
+    const key = (_a = ((_b = options.apiKey) !== null && _b !== void 0 ? _b : process.env.CURSOR_API_KEY)) === null || _a === void 0 ? void 0 : _a.trim();
+    if (key === undefined || key === "") {
+        throw new Error("cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)");
+    }
+    return key;
+}
+function resolveBaseUrl(options) {
+    var _a, _b;
+    const raw = ((_b = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : process.env.CURSOR_API_BASE_URL) !== null && _b !== void 0 ? _b : DEFAULT_CURSOR_EXTERNAL_API_URL).trim();
+    return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+function storageRpc(options, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = resolveBaseUrl(options);
+        const apiKey = resolveApiKey(options);
+        const fetchImpl = (_a = options.fetch) !== null && _a !== void 0 ? _a : globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("cursorHostedStorage requires fetch");
+        }
+        const response = yield fetchImpl(`${baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        const text = yield response.text();
+        let parsed;
+        try {
+            parsed = text.length === 0 ? {} : JSON.parse(text);
+        }
+        catch (_b) {
+            throw new Error(`cursorHostedStorage ${path} returned non-JSON (${response.status})`);
+        }
+        if (!response.ok) {
+            const error = parsed !== null &&
+                typeof parsed === "object" &&
+                "error" in parsed &&
+                typeof parsed.error === "string"
+                ? parsed.error
+                : `HTTP ${response.status}`;
+            throw new Error(`cursorHostedStorage ${path}: ${error}`);
+        }
+        return parsed;
+    });
+}
+/**
+ * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
+ * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ */
+export function cursorHostedStorage(options = {}) {
+    return {
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield storageRpc(options, "/internal/agent-serve/storage/kv/put", {
+                    key,
+                    value,
+                });
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const result = yield storageRpc(options, "/internal/agent-serve/storage/kv/get", { key });
+                if (!result.found) {
+                    return undefined;
+                }
+                return (_a = result.value) !== null && _a !== void 0 ? _a : undefined;
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield storageRpc(options, "/internal/agent-serve/storage/kv/delete", {
+                    key,
+                });
+            });
+        },
+        list(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const result = yield storageRpc(options, "/internal/agent-serve/storage/kv/list", { prefix });
+                return result.entries;
+            });
+        },
+        evals: {
+            put(run, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield storageRpc(options, "/internal/agent-serve/storage/evals/put", {
+                        agentName: ctx.agentName,
+                        run,
+                    });
+                });
+            },
+            delete(runId, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield storageRpc(options, "/internal/agent-serve/storage/evals/delete", {
+                        agentName: ctx.agentName,
+                        runId,
+                    });
+                });
+            },
+            list(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const result = yield storageRpc(options, "/internal/agent-serve/storage/evals/list", { agentName: ctx.agentName });
+                    return result.runs;
+                });
+            },
+        },
+        abs: {
+            putSample(sample, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield storageRpc(options, "/internal/agent-serve/storage/abs/put-sample", {
+                        agentName: ctx.agentName,
+                        sample,
+                    });
+                });
+            },
+            putSnapshot(snapshot, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield storageRpc(options, "/internal/agent-serve/storage/abs/put-snapshot", {
+                        agentName: ctx.agentName,
+                        snapshot,
+                    });
+                });
+            },
+            getSnapshot(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const result = yield storageRpc(options, "/internal/agent-serve/storage/abs/get-snapshot", {
+                        agentName: ctx.agentName,
+                    });
+                    if (!result.found) {
+                        return undefined;
+                    }
+                    return (_a = result.snapshot) !== null && _a !== void 0 ? _a : undefined;
+                });
+            },
+        },
+    };
+}

package/dist/storage-backends/postgres-kv.d.ts CHANGED Viewed

@@ -9,6 +9,11 @@
  *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
  *     PRIMARY KEY (deployment_id, agent, kind, ref)
  *
+ * For Cursor-managed hosting prefer `cursorHostedStorage` from
+ * `@cursor/july/storage/cursor-hosted` — same tables via a control-plane
+ * HTTP proxy (no pod-visible DSN). Use this helper when you supply
+ * `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` yourself (self-host).
+ *
  * `postgresStorage` implements the whole `defineStorage` surface as plain
  * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
  * table (sessions, event chunks, continuations, reminders), the `evals`

package/dist/storage-backends/postgres-kv.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"postgres-kv.d.ts","sourceRoot":"","sources":["../../src/storage-backends/postgres-kv.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG~~;AAIH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,MAAM,uBAAuB,GAAG,KAAK,MAAM,CAAC,EAAE;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD,KAAK,iBAAiB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,EAAE,uBAAuB,CAAC;IAC9B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,KAAK,sBAAsB,GAAG,QAAQ,CACpC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,cAAc,CAAC;CACrB,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAYpE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CA4HxB"}
1	+ {"version":3,"file":"postgres-kv.d.ts","sourceRoot":"","sources":["../../src/storage-backends/postgres-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,MAAM,uBAAuB,GAAG,KAAK,MAAM,CAAC,EAAE;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD,KAAK,iBAAiB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,EAAE,uBAAuB,CAAC;IAC9B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,KAAK,sBAAsB,GAAG,QAAQ,CACpC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,cAAc,CAAC;CACrB,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAYpE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CA4HxB"}

package/dist/storage-backends/postgres-kv.js CHANGED Viewed

@@ -9,6 +9,11 @@
  *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
  *     PRIMARY KEY (deployment_id, agent, kind, ref)
  *
+ * For Cursor-managed hosting prefer `cursorHostedStorage` from
+ * `@cursor/july/storage/cursor-hosted` — same tables via a control-plane
+ * HTTP proxy (no pod-visible DSN). Use this helper when you supply
+ * `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` yourself (self-host).
+ *
  * `postgresStorage` implements the whole `defineStorage` surface as plain
  * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
  * table (sessions, event chunks, continuations, reminders), the `evals`

package/docs/.vitepress/cache/deps/package.json ADDED Viewed

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/docs/deployment.md CHANGED Viewed

@@ -127,9 +127,13 @@ shell arguments.
 ### Choose durable storage
 Hosted filesystem state can reset during a deploy or runtime
-replacement. Use [`defineStorage`](./storage.md) to preserve supported
-records across deployments. Self-host with a persistent `--state-root`
-when the complete filesystem must survive.
+replacement. Prefer
+[`cursorHostedStorage`](./storage.md) (`@cursor/july/storage/cursor-hosted`)
+so durable records land in Cursor's Bugbot `agent_serve_*` tables through
+a control-plane HTTP proxy (pod credential auth — no database URL in the
+engine). Do not put `BUGBOTDB_URL` or `AGENT_SERVE_DEPLOYMENT_ID` in
+`hosting.secretNames`. Self-host with your own `defineStorage` backend or
+a persistent `--state-root` when the complete filesystem must survive.
 ### Use the hosted agent

package/docs/example-agents/approval-buddy.md CHANGED Viewed

@@ -69,7 +69,7 @@ approving the PR.
 | Server tools | [`agent/tools/`](../../examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
 | Deterministic policy | [`agent/lib/approve.ts`](../../examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](../../examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
 | Review subagents | [`agent/subagents/`](../../examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
-| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events through a custom durable adapter. |
+| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage` (Bugbot `agent_serve_*`). |
 | Evals and unit tests | [`evals/`](../../examples/approval-buddy/evals/), [`agent/lib/`](../../examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
 There are no authored skills, MCP connections, schedules, reminders, hooks,

package/docs/example-agents/index.md CHANGED Viewed

@@ -72,7 +72,7 @@ Several examples need more:
 - GitHub examples require access to the target repository. Codebase wiki and
   Codeowners review call the host `gh` CLI for PR data; the codeowners
   fixtures run without network.
-- Approval Buddy and Security Reviewer define custom durable session storage.
+- Example agents use `cursorHostedStorage` (`agent/storage.ts`) for Cursor-hosted session storage (control-plane proxy).
 - Remote PR coordinator starts remote agent sessions and needs access to its
   workflow backend.

package/docs/example-agents/security-reviewer.md CHANGED Viewed

@@ -71,7 +71,7 @@ status from the finding count even when the review posting result says
 | Progress channel | [`agent/channels/asr-progress.ts`](../../examples/security-reviewer/agent/channels/asr-progress.ts) | Serve live reviewer and triage state by `runId`. |
 | Playground renderer | [`agent/playground/tools/run_reviewers.tsx`](../../examples/security-reviewer/agent/playground/tools/run_reviewers.tsx) | Replace the generic tool chip with live module rows. |
 | SDK review pipeline | [`agent/lib/asr/`](../../examples/security-reviewer/agent/lib/asr/), [`review-stages.ts`](../../examples/security-reviewer/agent/lib/review-stages.ts) | Select modules, call model workers, triage, deduplicate, and write artifacts. |
-| Storage | [`agent/storage.ts`](../../examples/security-reviewer/agent/storage.ts) | Persist framework sessions through a custom adapter with lazy restore. |
+| Storage | [`agent/storage.ts`](../../examples/security-reviewer/agent/storage.ts) | Persist framework sessions with `cursorHostedStorage` (lazy restore). |
 | A/B | [`agent/ab.ts`](../../examples/security-reviewer/agent/ab.ts), [`agent/ab.config.ts`](../../examples/security-reviewer/agent/ab.config.ts) | Compare all-severity versus high-only GitHub comments. |
 | Eval | [`evals/`](../../examples/security-reviewer/evals/) | Check stage-tool presence against a pinned sample. |
@@ -190,10 +190,10 @@ findings, accounting, and audit events.
 ## Separate session storage from review artifacts
-`defineStorage` sends agentkit session and event records to a custom durable
-store. Security Reviewer sets `restore: "off"` so startup doesn't load old
-review sessions in bulk. A continuation lookup can still fetch a needed
-session.
+`defineStorage` + `cursorHostedStorage` sends agentkit session and event records
+to Cursor-hosted Bugbot storage through the control-plane proxy. Security
+Reviewer sets `restore: "off"` so startup doesn't load old review sessions in
+bulk. A continuation lookup can still fetch a needed session.
 The staged review files are separate from session storage. Session-store
 durability doesn't preserve those files. All stages for one `runId` must see

package/docs/storage.md CHANGED Viewed

@@ -113,13 +113,27 @@ propagate errors — unlike session mirrors, which are at-most-once.
 Without `agent/storage.ts`, `host.kv` falls back to files under
 `--state-root/kv`. That is fine for local dogfood; it does **not**
-survive replacing the host. For prod, author `defineStorage` (for example
-`@cursor/july/storage/postgres-kv`) so both sessions and author KV share
-the durable backend.
+survive replacing the host. For Cursor-managed hosting, prefer
+`@cursor/july/storage/cursor-hosted` so sessions and author KV share the
+platform Bugbot tables through a control-plane HTTP proxy (authenticated
+as the deployment pod credential — engines never receive a database URL).
+For self-hosted Postgres you own, use `@cursor/july/storage/postgres-kv`
+and supply `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` yourself.
+```ts
+// agent/storage.ts — Cursor-managed hosting
+import { defineStorage } from "@cursor/july/storage";
+import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+export default defineStorage({
+  ...cursorHostedStorage(),
+});
+```
 Built-in helpers:
 | Import | Backend |
 | --- | --- |
 | `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
-| `@cursor/july/storage/postgres-kv` | `agent_serve_*` tables (`BUGBOTDB_URL`) |
+| `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
+| `@cursor/july/storage/postgres-kv` | Same tables; you supply `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -138,6 +138,13 @@
       "import": "./dist/storage-backends/postgres-kv.js",
       "default": "./dist/storage-backends/postgres-kv.js"
     },
+    "./storage/cursor-hosted": {
+      "anysphere-source": "./src/storage-backends/cursor-hosted.ts",
+      "bun": "./src/storage-backends/cursor-hosted.ts",
+      "types": "./dist/storage-backends/cursor-hosted.d.ts",
+      "import": "./dist/storage-backends/cursor-hosted.js",
+      "default": "./dist/storage-backends/cursor-hosted.js"
+    },
     "./package.json": {
       "anysphere-source": "./package.json",
       "bun": "./package.json",

package/src/internal/cli-deploy.ts CHANGED Viewed

@@ -40,9 +40,11 @@ import {
 } from "./discovery.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import {
+  isReservedSecretName,
   isValidCursorEventRepo,
   validateSettableSecretName,
 } from "./hosting.js";
+import { deployProgressLabel, sanitizeCustomerError } from "./logs-client.js";
 import { stderrPalette } from "./terminal-style.js";
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
@@ -554,6 +556,24 @@ async function deployOne(
     );
     return 1;
   }
+  // Repo-backed fields without a resolvable https origin become a static
+  // deploy body the control plane rejects. Fail here with a fix hint —
+  // common when origin is an unrecognized SSH shape (pass --repo).
+  if (
+    gitRepoUrl === undefined &&
+    (gitRef !== undefined ||
+      agentPath !== undefined ||
+      (options.cursorEventsRepos !== undefined &&
+        options.cursorEventsRepos.length > 0) ||
+      (options.allowDomains !== undefined && options.allowDomains.length > 0))
+  ) {
+    ctx.err(
+      `Could not resolve an https:// git repository URL for this deploy.\n` +
+        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n` +
+        `  Or omit --ref/--path/--cursor-events-repo/--allow-domain for a static engine.\n`
+    );
+    return 1;
+  }
   for (const repo of options.cursorEventsRepos ?? []) {
     if (!isValidCursorEventRepo(repo)) {
       ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
@@ -659,13 +679,11 @@ async function deployOne(
   }
   if (detail.status !== "running") {
-    ctx.err(
-      `Deployment ${slug} ended ${detail.status}${
-        detail.lastError === null || detail.lastError === undefined
-          ? ""
-          : `: ${detail.lastError}`
-      }\n`
-    );
+    const errorDetail =
+      detail.lastError === null || detail.lastError === undefined
+        ? ""
+        : `: ${sanitizeCustomerError(detail.lastError)}`;
+    ctx.err(`Deployment ${slug} ended ${detail.status}${errorDetail}\n`);
     return 1;
   }
   ctx.out(
@@ -709,7 +727,11 @@ function warnMissingSecrets(
     return;
   }
   const setNames = new Set(set ?? []);
-  const missing = declared.filter((name) => !setNames.has(name));
+  // Platform-managed names (CURSOR_*, hosted storage) are injected by the
+  // control plane and never appear in secrets list — do not warn on them.
+  const missing = declared.filter(
+    (name) => !setNames.has(name) && !isReservedSecretName(name)
+  );
   if (missing.length === 0) {
     return;
   }
@@ -793,11 +815,23 @@ export async function cmdDeploymentStatus(
   const lines = [
     `${detail.slug} (team ${detail.teamId})`,
     `  status:      ${detail.status}`,
+  ];
+  if (detail.progress !== undefined) {
+    lines.push(`  progress:    ${detail.progress}`);
+  }
+  if (
+    detail.statusMessage !== null &&
+    detail.statusMessage !== undefined &&
+    detail.statusMessage.trim() !== ""
+  ) {
+    lines.push(`  step:        ${detail.statusMessage}`);
+  }
+  lines.push(
     `  generation:  ${detail.generation}`,
     `  kind:        ${detail.deploymentKind}`,
     `  alias:       ${aliasUrl}`,
-    `  playground:  ${aliasUrl}/playground`,
-  ];
+    `  playground:  ${aliasUrl}/playground`
+  );
   if (detail.gitRepoUrl !== null && detail.gitRepoUrl !== undefined) {
     lines.push(`  repo:        ${detail.gitRepoUrl} @ ${detail.gitRef ?? ""}`);
   }
@@ -835,7 +869,7 @@ export async function cmdDeploymentStatus(
     );
   }
   if (detail.lastError !== null && detail.lastError !== undefined) {
-    lines.push(`  last error:  ${detail.lastError}`);
+    lines.push(`  last error:  ${sanitizeCustomerError(detail.lastError)}`);
   }
   if (detail.desiredUpdatedAt !== undefined) {
     lines.push(`  updated:     ${detail.desiredUpdatedAt}`);
@@ -1229,7 +1263,9 @@ function createLineReader(
 /**
  * Poll deployment status every `pollIntervalMs` until it lands in
  * `terminal` (single-line progress on a TTY, one line per transition
- * otherwise). Throws DeployApiError on request failures or timeout.
+ * otherwise). Prefers customer `statusMessage` / `progress` over raw
+ * status so create → checkout → start is visible. Throws DeployApiError
+ * on request failures or timeout.
  */
 async function pollUntil(
   ctx: DeployCliContext,
@@ -1238,21 +1274,22 @@ async function pollUntil(
 ): Promise<DeploymentDetail> {
   const startedAt = Date.now();
   const tty = process.stderr.isTTY === true;
-  let lastStatus: DeploymentStatus | undefined;
+  let lastLabel: string | undefined;
   let sawProgress = false;
-  const report = (status: DeploymentStatus): void => {
+  const report = (detail: DeploymentDetail): void => {
     if (ctx.json) {
       return;
     }
+    const label = deployProgressLabel(detail);
     const elapsed = Math.round((Date.now() - startedAt) / 1000);
     if (tty) {
-      ctx.err(`\r\x1b[2K${slug}: ${status} (${elapsed}s)`);
+      ctx.err(`\r\x1b[2K${slug}: ${label} (${elapsed}s)`);
       sawProgress = true;
-    } else if (status !== lastStatus) {
-      ctx.err(`${slug}: ${status}\n`);
+    } else if (label !== lastLabel) {
+      ctx.err(`${slug}: ${label}\n`);
     }
-    lastStatus = status;
+    lastLabel = label;
   };
   const finishProgressLine = (): void => {
     if (tty && sawProgress) {
@@ -1267,15 +1304,16 @@ async function pollUntil(
         finishProgressLine();
         throw error;
       });
-    report(detail.status);
+    report(detail);
     if (terminal.has(detail.status)) {
       finishProgressLine();
       return detail;
     }
     if (Date.now() - startedAt >= ctx.timeoutMs) {
       finishProgressLine();
+      const last = deployProgressLabel(detail);
       throw new DeployApiError(
-        `Timed out after ${Math.round(ctx.timeoutMs / 1000)}s waiting for ${slug} (last status: ${detail.status}). It may still converge — check \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.`,
+        `Timed out after ${Math.round(ctx.timeoutMs / 1000)}s waiting for ${slug} (last: ${last}). It may still converge — check \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.`,
         0
       );
     }

package/src/internal/deploy-client.ts CHANGED Viewed

@@ -31,7 +31,9 @@ export type DeploymentStatus =
 export type DeploymentProgress =
   | "queued"
   | "preparing"
+  | "creating"
   | "building"
+  | "starting"
   | "finalizing"
   | "running"
   | "failed"
@@ -135,6 +137,12 @@ export interface Deployment {
    * backends; older responses omit it.
    */
   progress?: DeploymentProgress;
+  /**
+   * Live step while the deploy converges (e.g. "Checking out source…").
+   * Null when running / stopped or when only a failure is on the row.
+   * Present on newer backends; older responses omit it.
+   */
+  statusMessage?: string | null;
   generation: number;
   observedGeneration?: number | null;
   engineGeneration?: number | null;
@@ -218,7 +226,9 @@ const deploymentSchema = z.object({
     .enum([
       "queued",
       "preparing",
+      "creating",
       "building",
+      "starting",
       "finalizing",
       "running",
       "failed",
@@ -227,6 +237,7 @@ const deploymentSchema = z.object({
       "degraded",
     ])
     .optional(),
+  statusMessage: z.string().nullable().optional(),
   generation: z.number(),
   observedGeneration: z.number().nullable().optional(),
   engineGeneration: z.number().nullable().optional(),