@cursor/july 0.1.101 → 0.1.103

package/dist/extensions/cursor-cloud-agents/lib/backend.js

@@ -0,0 +1,286 @@
+/**
+ * The Cursor backend as the tools use it: launches go through the public
+ * v1 Cloud Agents API (the only surface that takes per-launch `envVars`),
+ * everything about an existing agent goes through the same
+ * `aiserver.v1.BackgroundComposerService` RPCs Sand's CloudAgent tool
+ * calls, so follow-ups queue, runs pause, and the full conversation is
+ * readable. Both authenticate with the host's Cursor API key; the RPCs
+ * exchange it for a session token the way the dashboard client does.
+ */
+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 { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { CursorBackendClient } from "../../../internal/cursor/backend-client.js";
+import { cursorBackendUrl, cursorExternalApiUrl, cursorWebsiteUrl, resolveApiKeySync, SIGN_IN_HINT, } from "../../../internal/cursor/credentials.js";
+import { toModelSelection } from "../../../internal/sdk-runner.js";
+import extension from "../extension.js";
+const SERVICE = "BackgroundComposerService";
+/** Launches and follow-ups from this extension carry the SDK source, like the v1 API. */
+const SOURCE = "BACKGROUND_COMPOSER_SOURCE_SDK";
+const RPC_TIMEOUT_MS = 60000;
+// The create call returns once the initial run exists, which can wait on a VM.
+const LAUNCH_TIMEOUT_MS = 300000;
+export class CloudAgentsApiError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "CloudAgentsApiError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Proto-JSON response schemas (camelCase; default-valued fields are omitted)
+// ---------------------------------------------------------------------------
+const composerSchema = z.object({
+    bcId: z.string(),
+    name: z.string().optional(),
+    status: z.string().optional(),
+    isArchived: z.boolean().optional(),
+    branchName: z.string().optional(),
+    prUrl: z.string().optional(),
+    linesAdded: z.number().optional(),
+    linesRemoved: z.number().optional(),
+    filesChanged: z.number().optional(),
+});
+const errorDetailsSchema = z.object({
+    details: z
+        .object({ title: z.string().optional(), detail: z.string().optional() })
+        .optional(),
+});
+const infoResponseSchema = z.object({
+    composer: z.object({
+        composer: composerSchema,
+        summary: z.string().optional(),
+        startError: errorDetailsSchema.optional(),
+        permanentError: errorDetailsSchema.optional(),
+    }),
+});
+const toolResultSchema = z.object({
+    toolName: z.string().optional(),
+    args: z.string().optional(),
+    rawArgs: z.string().optional(),
+    content: z.string().optional(),
+    error: z
+        .object({ clientVisibleErrorMessage: z.string().optional() })
+        .optional(),
+});
+const conversationResponseSchema = z.object({
+    conversation: z
+        .array(z.object({
+        type: z.string().optional(),
+        text: z.string().optional(),
+        thinking: z.object({ text: z.string().optional() }).optional(),
+        toolResults: z.array(toolResultSchema).optional(),
+    }))
+        .optional(),
+});
+const followupResponseSchema = z.object({ runId: z.string().optional() });
+const launchResponseSchema = z.object({
+    agent: z.object({ id: z.string(), url: z.string().optional() }),
+    run: z.object({ id: z.string(), status: z.string() }),
+});
+// ---------------------------------------------------------------------------
+export class CloudAgentsBackend {
+    constructor(apiKey, fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+        // The key is read per call: the host can sign in after the mount.
+        this.rpcClient = new CursorBackendClient({
+            backendUrl: cursorBackendUrl(),
+            apiKey: "",
+            getApiKey: apiKey,
+            fetchImpl,
+        });
+    }
+    /** `POST /v1/agents`: create the agent and start its first run in one call. */
+    launch(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { cloud } = request;
+            const body = {
+                prompt: { text: request.prompt },
+                name: request.name,
+                model: request.model === undefined
+                    ? undefined
+                    : toModelSelection(request.model),
+                env: cloud.env,
+                envVars: cloud.envVars,
+                repos: cloud.repos,
+                workOnCurrentBranch: cloud.workOnCurrentBranch,
+                autoCreatePR: cloud.autoCreatePR,
+                skipReviewerRequest: cloud.skipReviewerRequest,
+            };
+            let response;
+            try {
+                response = yield this.fetchImpl(`${cursorExternalApiUrl()}/v1/agents`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        authorization: `Bearer ${this.apiKey()}`,
+                        "x-ghost-mode": "true",
+                        "x-cursor-client-type": "agent-serve",
+                        "x-request-id": randomUUID(),
+                    },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(LAUNCH_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                throw new CloudAgentsApiError(`Cloud agent launch failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const text = yield response.text();
+            if (!response.ok) {
+                throw new CloudAgentsApiError(`Cloud agent launch failed (${response.status}): ${apiErrorMessage(text)}`, response.status);
+            }
+            const parsed = launchResponseSchema.parse(JSON.parse(text));
+            return {
+                agentId: parsed.agent.id,
+                runId: parsed.run.id,
+                status: parsed.run.status.toLowerCase(),
+                url: (_a = parsed.agent.url) !== null && _a !== void 0 ? _a : agentUrl(parsed.agent.id),
+            };
+        });
+    }
+    info(agentId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            const { composer } = infoResponseSchema.parse(yield this.rpcClient.serviceRpc(SERVICE, "GetBackgroundComposerInfo", { bcId: agentId }, RPC_TIMEOUT_MS));
+            const { composer: summary } = composer;
+            const failure = (_a = composer.permanentError) !== null && _a !== void 0 ? _a : composer.startError;
+            return {
+                agentId: summary.bcId,
+                name: (_b = summary.name) !== null && _b !== void 0 ? _b : "",
+                status: statusOf(summary.status),
+                archived: summary.isArchived === true,
+                url: agentUrl(summary.bcId),
+                branch: emptyToUndefined(summary.branchName),
+                prUrl: emptyToUndefined(summary.prUrl),
+                summary: emptyToUndefined(composer.summary),
+                error: failureMessage(failure),
+                changes: summary.filesChanged === undefined
+                    ? undefined
+                    : {
+                        filesChanged: summary.filesChanged,
+                        linesAdded: (_c = summary.linesAdded) !== null && _c !== void 0 ? _c : 0,
+                        linesRemoved: (_d = summary.linesRemoved) !== null && _d !== void 0 ? _d : 0,
+                    },
+            };
+        });
+    }
+    conversation(agentId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { conversation } = conversationResponseSchema.parse(yield this.rpcClient.serviceRpc(SERVICE, "GetBackgroundComposerConversation", { bcId: agentId }, RPC_TIMEOUT_MS));
+            return (conversation !== null && conversation !== void 0 ? conversation : []).map((message) => {
+                var _a;
+                var _b;
+                const toolCalls = ((_b = message.toolResults) !== null && _b !== void 0 ? _b : []).map((result) => { var _a; var _b, _c; return ({
+                    name: (_b = result.toolName) !== null && _b !== void 0 ? _b : "",
+                    args: parseArgs((_c = result.args) !== null && _c !== void 0 ? _c : result.rawArgs),
+                    content: result.content,
+                    error: (_a = result.error) === null || _a === void 0 ? void 0 : _a.clientVisibleErrorMessage,
+                }); });
+                return {
+                    role: message.type === "MESSAGE_TYPE_HUMAN" ? "user" : "assistant",
+                    text: emptyToUndefined(message.text),
+                    thinking: emptyToUndefined((_a = message.thinking) === null || _a === void 0 ? void 0 : _a.text),
+                    toolCalls: toolCalls.length === 0 ? undefined : toolCalls,
+                };
+            });
+        });
+    }
+    /**
+     * Queue a follow-up behind the current run, or with `interrupt` cancel the
+     * in-flight step and run it now; the backend's `synchronous` switch.
+     */
+    followUp(agentId, prompt, interrupt) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { runId } = followupResponseSchema.parse(yield this.rpcClient.serviceRpc(SERVICE, "AddAsyncFollowupBackgroundComposer", {
+                bcId: agentId,
+                synchronous: interrupt,
+                followupSource: SOURCE,
+                followupMessage: {
+                    text: prompt,
+                    type: "MESSAGE_TYPE_HUMAN",
+                    bubbleId: randomUUID(),
+                },
+            }, RPC_TIMEOUT_MS));
+            return { runId };
+        });
+    }
+    pause(agentId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rpcClient.serviceRpc(SERVICE, "PauseBackgroundComposer", { bcId: agentId, source: SOURCE }, RPC_TIMEOUT_MS);
+        });
+    }
+}
+let backend;
+/** The process-wide backend for this mount, built on first use. */
+export function cloudAgentsBackend() {
+    backend !== null && backend !== void 0 ? backend : (backend = new CloudAgentsBackend(apiKey));
+    return backend;
+}
+export function apiKey() {
+    const key = resolveApiKeySync({ apiKey: extension.config.apiKey });
+    if (key === undefined) {
+        throw new Error(`Cloud agents need a Cursor API key. ${SIGN_IN_HINT}`);
+    }
+    return key.apiKey;
+}
+export function agentUrl(agentId) {
+    return `${cursorWebsiteUrl()}/agents/${agentId}`;
+}
+function statusOf(status) {
+    switch (status) {
+        case "BACKGROUND_COMPOSER_STATUS_CREATING":
+            return "creating";
+        case "BACKGROUND_COMPOSER_STATUS_RUNNING":
+            return "running";
+        case "BACKGROUND_COMPOSER_STATUS_FINISHED":
+            return "finished";
+        case "BACKGROUND_COMPOSER_STATUS_ERROR":
+            return "error";
+        case "BACKGROUND_COMPOSER_STATUS_EXPIRED":
+            return "expired";
+        default:
+            return "unknown";
+    }
+}
+function failureMessage(failure) {
+    var _a, _b;
+    const parts = [(_a = failure === null || failure === void 0 ? void 0 : failure.details) === null || _a === void 0 ? void 0 : _a.title, (_b = failure === null || failure === void 0 ? void 0 : failure.details) === null || _b === void 0 ? void 0 : _b.detail].filter((part) => part !== undefined && part !== "");
+    return parts.length === 0 ? undefined : parts.join(": ");
+}
+function parseArgs(args) {
+    if (args === undefined || args === "") {
+        return undefined;
+    }
+    try {
+        return JSON.parse(args);
+    }
+    catch (_a) {
+        return args;
+    }
+}
+function emptyToUndefined(value) {
+    return value === undefined || value === "" ? undefined : value;
+}
+function apiErrorMessage(text) {
+    var _a, _b;
+    var _c, _d;
+    try {
+        const parsed = JSON.parse(text);
+        const code = (_c = (_a = parsed.error) === null || _a === void 0 ? void 0 : _a.code) !== null && _c !== void 0 ? _c : parsed.code;
+        const message = (_d = (_b = parsed.error) === null || _b === void 0 ? void 0 : _b.message) !== null && _d !== void 0 ? _d : parsed.message;
+        return ([code, message].filter((part) => part !== undefined).join(": ") || text);
+    }
+    catch (_e) {
+        return text;
+    }
+}

package/dist/extensions/cursor-cloud-agents/lib/inputs.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const agentRef: z.ZodObject<{
+    agent_id: z.ZodString;
+}>;
+//# sourceMappingURL=inputs.d.ts.map

package/dist/extensions/cursor-cloud-agents/lib/inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/lib/inputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;IAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAA;CAAE,CAE1D,CAAC"}

package/dist/extensions/cursor-cloud-agents/lib/inputs.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const agentRef = z.object({
+    agent_id: z.string().describe("Agent id (`bc-...`) returned by launch."),
+});

package/dist/extensions/cursor-cloud-agents/lib/transcript.d.ts

@@ -0,0 +1,8 @@
+/** A cloud agent's conversation as JSONL lines, one message per line. */
+import type { CloudAgentMessage } from "./backend.js";
+/** Workspace-relative path of a dumped transcript; the directory Sand uses too. */
+export declare function transcriptPath(agentId: string): string;
+export declare function transcriptLines(messages: CloudAgentMessage[]): string[];
+/** The text of the last assistant message, the agent's report. */
+export declare function lastAssistantText(messages: CloudAgentMessage[]): string | undefined;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/extensions/cursor-cloud-agents/lib/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/lib/transcript.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAEzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAEvE;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAAE,GAC5B,MAAM,GAAG,SAAS,CAMpB"}

package/dist/extensions/cursor-cloud-agents/lib/transcript.js

@@ -0,0 +1,15 @@
+/** A cloud agent's conversation as JSONL lines, one message per line. */
+/** Workspace-relative path of a dumped transcript; the directory Sand uses too. */
+export function transcriptPath(agentId) {
+    return `cloud-agent-transcripts/${agentId}.jsonl`;
+}
+export function transcriptLines(messages) {
+    return messages.map((message) => JSON.stringify(message));
+}
+/** The text of the last assistant message, the agent's report. */
+export function lastAssistantText(messages) {
+    var _a;
+    return (_a = messages
+        .toReversed()
+        .find((message) => message.role === "assistant" && message.text !== undefined)) === null || _a === void 0 ? void 0 : _a.text;
+}

package/dist/extensions/cursor-cloud-agents/skills/handoff.md

@@ -1,26 +1,40 @@
 ---
-description: "Delegate coding work to Cursor cloud agents: when to hand off, how to write the prompt, and how to follow up and check status."
+description: "Delegate coding work to Cursor cloud agents: when to hand off, how to write the prompt, and how to look an agent up by id, read what it did, reply, and cancel."
 ---
 
 # Cloud agent handoff
 
 Hand work to a Cursor cloud agent when it needs a repository checkout, a long run, or an isolated machine: implementing a change, running a test suite, opening a pull request. Answer questions and small reads yourself.
 
-The tools below are this extension's; they appear under its mount namespace, as `<namespace>__launch` and so on.
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__launch` and so on. Every agent is addressed by its `agent_id` (`bc-...`).
 
 ## Launch
 
-Call `launch` with a self-contained prompt: the goal, the repository or pull request, constraints (branch, files to leave alone), and what done looks like (tests pass, PR opened). Pass `ref` or `prUrl` to pick a branch or pull request; `repo` must be one of the configured repositories.
+Call `launch` with a self-contained prompt: the goal, the repository or pull request, constraints (branch, files to leave alone), and what done looks like (tests pass, PR opened). Pass `starting_ref` or `pr_url` to pick a branch or pull request; `repo` must be one of the configured repositories.
 
 The result carries `agentId` (`bc-...`) and a `url`. Report both in full. Never truncate the id.
 
-## Follow up
+## Look an agent up by id
 
-Call `follow_up` with the `agentId` to steer an agent you launched or ask for changes on its branch. A busy agent rejects the follow-up: check status and retry once its run has finished. Do not launch a second agent for follow-up work on the same branch.
+Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, or `expired`), its `branch` and pull request `prUrl` once pushed, the `changes` it made so far (files and lines), a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
 
-## Check status
+## Read what it did
 
-Call `status` with the `agentId`. The latest run carries `status` (`running`, `finished`, `error`, or `cancelled`), the final `result` text, an `error` message, and any pushed `branches` or pull requests; the agent itself reports `archived`. A run takes minutes: check when asked or when you need the result, not in a tight loop.
+To read the report or understand what was done, call `dump` with the `agent_id`. It writes the agent's whole conversation, every run, to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus the `finalMessage`. Each line is one JSON message with `role` (`user` or `assistant`) and, for assistant lines, `text`, `thinking`, and `toolCalls` (tool `name`, `args`, `content`, `error`). Read it with your file and shell tools, using the returned path:
+
+- `tail -n 1 <path>` gives the final report.
+- `grep '"toolCalls"' <path>` shows the commands and edits it made.
+- `grep '"role":"user"' <path>` shows every prompt it received, including replies.
+
+Use `dump` before summarizing an agent's work for a person, and to understand a failure before replying with a fix.
+
+## Reply
+
+Call `reply` with the `agent_id` and a prompt to steer an agent or ask for changes on its branch. The follow-up queues behind the current run and starts when it finishes; pass `interrupt: true` to stop the current step and deliver it now. Do not launch a second agent for follow-up work on the same branch.
+
+## Cancel
+
+Call `cancel` with the `agent_id` to stop the active run. The agent keeps its branch and conversation, so a `reply` can continue from where it stopped.
 
 ## Fleet
 

package/dist/extensions/cursor-cloud-agents/tools/cancel.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const cancel: ToolDefinition;
+export default cancel;
+//# sourceMappingURL=cancel.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/cancel.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD,QAAA,MAAM,MAAM,EAAE,cAUZ,CAAC;eAEY,MAAM"}

package/dist/extensions/cursor-cloud-agents/tools/cancel.js

@@ -0,0 +1,26 @@
+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 { defineTool } from "../../../tools.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+const cancel = defineTool({
+    description: "Stop a cloud agent's active run. The agent keeps its branch and conversation; reply to it to continue.",
+    effect: "write",
+    inputSchema: agentRef,
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield assertOwned(ctx, input.agent_id);
+            yield cloudAgentsBackend().pause(input.agent_id);
+            return { agentId: input.agent_id, cancelled: true };
+        });
+    },
+});
+export default cancel;

package/dist/extensions/cursor-cloud-agents/tools/dump.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const dump: ToolDefinition;
+export default dump;
+//# sourceMappingURL=dump.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/dump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dump.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/dump.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,QAAA,MAAM,IAAI,EAAE,cAmCV,CAAC;eAEY,IAAI"}

package/dist/extensions/cursor-cloud-agents/tools/dump.js

@@ -0,0 +1,54 @@
+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, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defineTool } from "../../../tools.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+import { lastAssistantText, transcriptLines, transcriptPath, } from "../lib/transcript.js";
+const dump = defineTool({
+    description: "Write a cloud agent's full conversation to a JSONL file in your workspace so you can read what it did: one JSON message per line (prompts, assistant text, thinking, tool calls). Read the last line for the final report.",
+    effect: "read",
+    inputSchema: agentRef,
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield assertOwned(ctx, input.agent_id);
+            const backend = cloudAgentsBackend();
+            const [messages, info] = yield Promise.all([
+                backend.conversation(input.agent_id),
+                backend.info(input.agent_id),
+            ]);
+            if (messages.length === 0) {
+                return {
+                    agentId: input.agent_id,
+                    lineCount: 0,
+                    status: info.status,
+                    note: "The agent has not produced any transcript yet.",
+                };
+            }
+            // Absolute: the harness's shell does not run in the workspace directory.
+            const path = join(ctx.workspaceDir, transcriptPath(input.agent_id));
+            const jsonl = `${transcriptLines(messages).join("\n")}\n`;
+            yield mkdir(dirname(path), { recursive: true });
+            yield writeFile(path, jsonl, "utf8");
+            return {
+                agentId: input.agent_id,
+                path,
+                sizeBytes: Buffer.byteLength(jsonl),
+                lineCount: messages.length,
+                status: info.status,
+                finalMessage: lastAssistantText(messages),
+                note: `One JSON message per line. Grep it, or read the final report with \`tail -n 1 ${path}\`.`,
+            };
+        });
+    },
+});
+export default dump;

package/dist/extensions/cursor-cloud-agents/tools/get.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const get: ToolDefinition;
+export default get;
+//# sourceMappingURL=get.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/get.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD,QAAA,MAAM,GAAG,EAAE,cAST,CAAC;eAEY,GAAG"}

package/dist/extensions/cursor-cloud-agents/tools/get.js

@@ -0,0 +1,25 @@
+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 { defineTool } from "../../../tools.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+const get = defineTool({
+    description: "Look up a cloud agent you launched by id: its status, branch, pull request, changed-file counts, summary, and any error. Use dump to read everything it did.",
+    effect: "read",
+    inputSchema: agentRef,
+    execute(input, ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield assertOwned(ctx, input.agent_id);
+            return cloudAgentsBackend().info(input.agent_id);
+        });
+    },
+});
+export default get;

package/dist/extensions/cursor-cloud-agents/tools/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/launch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,QAAA,MAAM,MAAM,EAAE,cAwEZ,CAAC;eAEY,MAAM"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/launch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,QAAA,MAAM,MAAM,EAAE,cAqDZ,CAAC;eAEY,MAAM"}

package/dist/extensions/cursor-cloud-agents/tools/launch.js

@@ -7,15 +7,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Agent } from "@cursor/sdk";
 import { z } from "zod";
 import { defineTool } from "../../../tools.js";
 import extension from "../extension.js";
-import { agentUrl, agentView, apiKey, modelSelection } from "../lib/cloud.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
 import { recordLaunch } from "../lib/fleet.js";
 import { launchRepos } from "../lib/repos.js";
 const launch = defineTool({
-    description: "Launch a Cursor cloud agent on a repository with a self-contained task. Returns the agent id and URL; check progress with the status tool.",
+    description: "Launch a Cursor cloud agent on a repository with a self-contained task. Returns the agent id and URL; check on it with get, read what it did with dump.",
     effect: "write",
     needsApproval: () => extension.config.needsApproval,
     inputSchema: z.object({
@@ -28,8 +27,11 @@ const launch = defineTool({
             .url()
             .optional()
             .describe("GitHub repository URL, one of the configured repositories. Defaults to the configured repository."),
-        ref: z.string().optional().describe("Starting branch or commit."),
-        prUrl: z
+        starting_ref: z
+            .string()
+            .optional()
+            .describe("Branch or commit to start from; defaults to the configured or default branch."),
+        pr_url: z
             .string()
             .url()
             .optional()
@@ -42,41 +44,15 @@ const launch = defineTool({
     }),
     execute(input, ctx) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { cloud } = extension.config;
-            const key = apiKey();
-            const agent = yield Agent.create({
-                apiKey: key,
-                model: modelSelection(),
+            const { cloud, model } = extension.config;
+            const launched = yield cloudAgentsBackend().launch({
+                prompt: input.prompt,
                 name: input.name,
-                cloud: Object.assign(Object.assign({}, cloud), { repos: launchRepos(input, cloud) }),
+                model,
+                cloud: Object.assign(Object.assign({}, cloud), { repos: launchRepos({ repo: input.repo, ref: input.starting_ref, prUrl: input.pr_url }, cloud) }),
             });
-            try {
-                const run = yield agent.send(input.prompt);
-                yield recordLaunch(ctx, agent.agentId, input.name);
-                return {
-                    agentId: agent.agentId,
-                    runId: run.id,
-                    status: run.status,
-                    url: agentUrl(agent.agentId),
-                };
-            }
-            catch (error) {
-                // The API can fail after the agent exists (slow admission,
-                // post-create checks). The SDK seeded the id unless envVars made
-                // the server mint it, so read the agent back and keep the handle;
-                // envVars launches have no id to read back and surface the error.
-                const info = cloud.envVars === undefined
-                    ? yield Agent.get(agent.agentId, { apiKey: key }).catch(() => undefined)
-                    : undefined;
-                if (info === undefined) {
-                    throw error;
-                }
-                yield recordLaunch(ctx, info.agentId, input.name);
-                return Object.assign(Object.assign({}, agentView(info)), { launchError: error instanceof Error ? error.message : String(error) });
-            }
-            finally {
-                agent.close();
-            }
+            yield recordLaunch(ctx, launched.agentId, input.name);
+            return launched;
         });
     },
 });

package/dist/extensions/cursor-cloud-agents/tools/list.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { z } from "zod";
 import { defineTool } from "../../../tools.js";
-import { agentUrl } from "../lib/cloud.js";
+import { agentUrl } from "../lib/backend.js";
 import { listFleet } from "../lib/fleet.js";
 const list = defineTool({
     description: 'List the cloud agents launched in this session, newest first. Pass scope "all" for every agent you launched, in any session.',

package/dist/extensions/cursor-cloud-agents/tools/reply.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "../../../types.js";
+declare const reply: ToolDefinition;
+export default reply;
+//# sourceMappingURL=reply.d.ts.map

package/dist/extensions/cursor-cloud-agents/tools/reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/tools/reply.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,QAAA,MAAM,KAAK,EAAE,cAuBX,CAAC;eAEY,KAAK"}