@cursor/july 0.1.1

package/dist/internal/sdk-runner.js

@@ -0,0 +1,221 @@
+/**
+ * Executes turns on the Cursor harness through `@cursor/sdk`.
+ * Each framework session maps 1:1 to an SDK agent. Local agents use the
+ * session id as the SDK agent id and materialize a workspace for project
+ * settings; cloud agents use Cursor cloud (`bc-…` ids) with optional
+ * `cloud` options from `defineAgent`.
+ */
+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());
+    });
+};
+import { mkdir } from "node:fs/promises";
+import { Agent, JsonlLocalAgentStore, } from "@cursor/sdk";
+import { DEFAULT_MODEL, } from "../types.js";
+export class CursorSdkRunner {
+    constructor(options = {}) {
+        this.options = options;
+        this.agents = new Map();
+        this.stores = new Map();
+    }
+    runTurn(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const agent = yield this.getAgent(request);
+                const run = yield agent.send(request.prompt, Object.assign({ onDelta: (_a) => __awaiter(this, [_a], void 0, function* ({ update }) {
+                        try {
+                            yield request.onUpdate(update);
+                        }
+                        catch (_b) {
+                            // Stream mapping must never reject into the SDK transport.
+                        }
+                    }) }, (request.runtime === "local"
+                    ? {
+                        local: Object.assign({ customTools: request.customTools }, (request.forceExpireActiveRun === true
+                            ? { force: true }
+                            : {})),
+                    }
+                    : {})));
+                // A follow-up can preempt this turn: cancelling tears down execution and
+                // marks the SDK run terminal so the next send is admitted cleanly. The
+                // signal may already be aborted if the preempt landed while send() was
+                // still creating the run.
+                const signal = request.signal;
+                const onAbort = () => {
+                    void run.cancel().catch(() => { });
+                };
+                if (signal !== undefined) {
+                    if (signal.aborted) {
+                        onAbort();
+                    }
+                    else {
+                        signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                }
+                // Cloud + envVars: server mints the real `bc-…` id during createAgent
+                // inside the first send. Bind only after that so we never persist/print
+                // the provisional client-seeded id.
+                if (request.onSdkAgentId !== undefined) {
+                    yield request.onSdkAgentId(agent.agentId);
+                }
+                try {
+                    const result = yield run.wait();
+                    return toTurnOutcome(result);
+                }
+                finally {
+                    signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+                }
+            }
+            catch (error) {
+                // Drop the cached agent so a dead Connect/HTTP2 session cannot poison
+                // the next turn (terminal/shell overflow often kills the transport).
+                this.agents.delete(request.sessionId);
+                throw error;
+            }
+        });
+    }
+    dispose() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const agents = yield Promise.allSettled([...this.agents.values()]);
+            this.agents.clear();
+            for (const settled of agents) {
+                if (settled.status === "fulfilled") {
+                    settled.value.close();
+                }
+            }
+        });
+    }
+    getAgent(request) {
+        let agentPromise = this.agents.get(request.sessionId);
+        if (agentPromise === undefined) {
+            agentPromise = this.openAgent(request).catch((error) => {
+                this.agents.delete(request.sessionId);
+                throw error;
+            });
+            this.agents.set(request.sessionId, agentPromise);
+        }
+        return agentPromise;
+    }
+    openAgent(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const apiKey = (_a = this.options.apiKey) !== null && _a !== void 0 ? _a : process.env.CURSOR_API_KEY;
+            if (apiKey === undefined || apiKey.trim() === "") {
+                throw new Error("The Cursor SDK runner requires a Cursor credential: run `agent-serve login`, set CURSOR_API_KEY, or pass serve({ apiKey }).");
+            }
+            const model = (_b = request.model) !== null && _b !== void 0 ? _b : DEFAULT_MODEL;
+            const subagents = toAgentDefinitions(request.subagents);
+            const shared = Object.assign(Object.assign({ model: toModelSelection(model), apiKey }, (Object.keys(request.mcpServers).length > 0
+                ? { mcpServers: request.mcpServers }
+                : {})), (subagents === undefined ? {} : { agents: subagents }));
+            if (request.runtime === "cloud") {
+                return this.openCloudAgent(request, shared);
+            }
+            return this.openLocalAgent(request, shared);
+        });
+    }
+    openLocalAgent(request, shared) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const store = (_a = this.options.store) !== null && _a !== void 0 ? _a : (yield this.getStore(request.runnerStateDir));
+            const options = Object.assign(Object.assign({}, shared), { local: {
+                    cwd: request.workspaceDir,
+                    settingSources: ["project"],
+                    store,
+                } });
+            if (request.isFirstTurn || request.sdkAgentId === undefined) {
+                return Agent.create(Object.assign(Object.assign({}, options), { agentId: (_b = request.sdkAgentId) !== null && _b !== void 0 ? _b : request.sessionId }));
+            }
+            return Agent.resume((_c = request.sdkAgentId) !== null && _c !== void 0 ? _c : request.sessionId, options);
+        });
+    }
+    openCloudAgent(request, shared) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const cloud = toCloudAgentOptions(request.cloud);
+            const hasEnvVars = cloud.envVars !== undefined && Object.keys(cloud.envVars).length > 0;
+            const options = Object.assign(Object.assign({}, shared), { cloud });
+            const sdkAgentId = (_a = request.sdkAgentId) === null || _a === void 0 ? void 0 : _a.trim();
+            if (sdkAgentId !== undefined && sdkAgentId !== "") {
+                // A server-minted `bc-…` id always resumes — including on the first
+                // framework turn of a session seeded via SendMessageOptions.sdkAgentId
+                // (PR→bcId affinity across session-store resets). Any persisted id
+                // resumes on later turns.
+                if (isServerMintedCloudAgentId(sdkAgentId) || !request.isFirstTurn) {
+                    return Agent.resume(sdkAgentId, options);
+                }
+                if (!hasEnvVars) {
+                    // Client-seeded (non bc-…) id on a brand new session: forward it to
+                    // create so the server adopts it. With envVars the server must mint
+                    // the id, so the seed cannot be honored and create() runs below.
+                    return Agent.create(Object.assign(Object.assign({}, options), { agentId: sdkAgentId }));
+                }
+            }
+            if (request.isFirstTurn) {
+                return Agent.create(options);
+            }
+            throw new Error(`Cloud session ${request.sessionId} is missing sdkAgentId; cannot resume.`);
+        });
+    }
+    getStore(stateDir) {
+        let storePromise = this.stores.get(stateDir);
+        if (storePromise === undefined) {
+            storePromise = mkdir(stateDir, { recursive: true }).then(() => new JsonlLocalAgentStore(stateDir));
+            this.stores.set(stateDir, storePromise);
+        }
+        return storePromise;
+    }
+}
+/** Cloud agent ids minted by the server are `bc-…`; those always resume. */
+export function isServerMintedCloudAgentId(id) {
+    return id.startsWith("bc-");
+}
+export function toModelSelection(model) {
+    if (typeof model === "string") {
+        return { id: model };
+    }
+    return Object.assign({ id: model.id }, (model.params === undefined ? {} : { params: model.params }));
+}
+function toCloudAgentOptions(cloud) {
+    if (cloud === undefined) {
+        return {};
+    }
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (cloud.env === undefined ? {} : { env: cloud.env })), (cloud.repos === undefined ? {} : { repos: cloud.repos })), (cloud.workOnCurrentBranch === undefined
+        ? {}
+        : { workOnCurrentBranch: cloud.workOnCurrentBranch })), (cloud.autoCreatePR === undefined
+        ? {}
+        : { autoCreatePR: cloud.autoCreatePR })), (cloud.skipReviewerRequest === undefined
+        ? {}
+        : { skipReviewerRequest: cloud.skipReviewerRequest })), (cloud.envVars === undefined ? {} : { envVars: cloud.envVars }));
+}
+function toAgentDefinitions(subagents) {
+    if (subagents.length === 0) {
+        return undefined;
+    }
+    const definitions = {};
+    for (const subagent of subagents) {
+        definitions[subagent.name] = {
+            description: subagent.description,
+            prompt: subagent.prompt,
+            model: subagent.model === undefined
+                ? "inherit"
+                : toModelSelection(subagent.model),
+        };
+    }
+    return definitions;
+}
+function toTurnOutcome(result) {
+    const usage = result.usage === undefined
+        ? undefined
+        : Object.assign({ inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens, cacheReadTokens: result.usage.cacheReadTokens, cacheWriteTokens: result.usage.cacheWriteTokens }, (result.usage.reasoningTokens === undefined
+            ? {}
+            : { reasoningTokens: result.usage.reasoningTokens }));
+    return Object.assign(Object.assign(Object.assign({ status: result.status }, (result.result === undefined ? {} : { result: result.result })), (result.status === "error"
+        ? { errorMessage: "The Cursor agent run failed" }
+        : {})), (usage === undefined ? {} : { usage }));
+}

package/dist/internal/server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The HTTP host: a plain node:http server that adapts requests to the Fetch
+ * API, resolves route auth, and dispatches to the built-in HTTP channel
+ * routes, custom channel routes (under `/v1/channels/<id>`), and the
+ * server-level health / info / dev-dispatch routes.
+ */
+import type { AgentProject, AgentServeHandle, ServeOptions } from "../types.js";
+import { type AgentRunner } from "./sdk-runner.js";
+/** One agent to serve: its slug (empty for single-agent mode) and project. */
+export interface AgentMount {
+    slug: string;
+    project: AgentProject;
+}
+/** Internal-only options for {@link startServer} (not on public `serve`). */
+export interface StartServerInternalOptions {
+    /** Test seam: replace the Cursor SDK runner (integration tests). */
+    runner?: AgentRunner;
+}
+/**
+ * Start an HTTP server hosting one or more agents. A single agent with an
+ * empty slug serves at `/v1/*` and `/playground`; multiple agents each serve
+ * under `/<slug>/v1/*` and `/<slug>/playground`, with an index at `/`.
+ */
+export declare function startServer(mounts: AgentMount[], options?: ServeOptions & StartServerInternalOptions): Promise<AgentServeHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/internal/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/internal/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAOhB,YAAY,EACb,MAAM,aAAa,CAAC;AAkFrB,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,iBAAiB,CAAC;AAapE,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;CACvB;AAYD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,YAAY,GAAG,0BAA+B,GACtD,OAAO,CAAC,gBAAgB,CAAC,CAmf3B"}