@cursor/bdk 0.2.1

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

@@ -0,0 +1,280 @@
+/**
+ * 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/fleet.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Who launched which cloud agent. The tools authenticate with the serve
+ * host's one Cursor API key, so the host itself must keep every session's
+ * cloud agents bound to the principal that launched them: status and
+ * follow-ups only reach agents recorded here for the same principal, and
+ * the fleet listing is that principal's records, by default narrowed to the
+ * session that launched them.
+ */
+import type { ToolContext } from "../../../types.js";
+export type FleetEntry = {
+    agentId: string;
+    name?: string;
+    launchedAt: string;
+    /** The session whose turn launched the agent; absent on records older than this field. */
+    sessionId?: string;
+};
+export type FleetScope = "session" | "all";
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export declare function principalOf(ctx: ToolContext): string;
+export declare function recordLaunch(ctx: ToolContext, agentId: string, name: string | undefined): Promise<void>;
+/** Refuse agents launched by another principal, or not through the extension. */
+export declare function assertOwned(ctx: ToolContext, agentId: string): Promise<void>;
+/** The caller's launches, newest first: this session's, or every session's. */
+export declare function listFleet(ctx: ToolContext, scope?: FleetScope): Promise<FleetEntry[]>;
+//# sourceMappingURL=fleet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/lib/fleet.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC;AA2B3C,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAGpD;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,iFAAiF;AACjF,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlF;AAED,+EAA+E;AAC/E,wBAAsB,SAAS,CAC7B,GAAG,EAAE,WAAW,EAChB,KAAK,GAAE,UAAkB,GACxB,OAAO,CAAC,UAAU,EAAE,CAAC,CAIvB"}

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

@@ -0,0 +1,81 @@
+/**
+ * Who launched which cloud agent. The tools authenticate with the serve
+ * host's one Cursor API key, so the host itself must keep every session's
+ * cloud agents bound to the principal that launched them: status and
+ * follow-ups only reach agents recorded here for the same principal, and
+ * the fleet listing is that principal's records, by default narrowed to the
+ * session that launched them.
+ */
+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 { z } from "zod";
+const PREFIX = "cloud-agents";
+const fleetSchema = z.array(z.object({
+    agentId: z.string(),
+    name: z.string().optional(),
+    launchedAt: z.string(),
+    sessionId: z.string().optional(),
+}));
+const ownerSchema = z.object({ principal: z.string() });
+// `host.kv` has no compare-and-swap, and a model that launches two agents in
+// one turn calls this tool in parallel. Chain the index read-modify-write per
+// principal so neither launch overwrites the other's entry.
+const indexWrites = new Map();
+function withIndexLock(key, task) {
+    var _a;
+    const run = ((_a = indexWrites.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve()).then(task, task);
+    indexWrites.set(key, run);
+    return run.finally(() => {
+        if (indexWrites.get(key) === run) {
+            indexWrites.delete(key);
+        }
+    });
+}
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export function principalOf(ctx) {
+    const auth = ctx.session.auth;
+    return auth === null ? "anonymous" : `${auth.principalType}:${auth.principalId}`;
+}
+export function recordLaunch(ctx, agentId, name) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const principal = principalOf(ctx);
+        const entry = {
+            agentId,
+            name,
+            launchedAt: new Date().toISOString(),
+            sessionId: ctx.session.id,
+        };
+        yield ctx.host.kv.put(`${PREFIX}/agents/${agentId}`, { principal });
+        yield withIndexLock(fleetKey(principal), () => __awaiter(this, void 0, void 0, function* () {
+            const fleet = yield listFleet(ctx);
+            yield ctx.host.kv.put(fleetKey(principal), [entry, ...fleet]);
+        }));
+    });
+}
+/** Refuse agents launched by another principal, or not through the extension. */
+export function assertOwned(ctx, agentId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const owner = ownerSchema.safeParse(yield ctx.host.kv.get(`${PREFIX}/agents/${agentId}`));
+        if (!owner.success || owner.data.principal !== principalOf(ctx)) {
+            throw new Error(`Agent ${agentId} was not launched through this extension by this principal; only your own launches can be read or steered.`);
+        }
+    });
+}
+/** The caller's launches, newest first: this session's, or every session's. */
+export function listFleet(ctx_1) {
+    return __awaiter(this, arguments, void 0, function* (ctx, scope = "all") {
+        const fleet = fleetSchema.safeParse(yield ctx.host.kv.get(fleetKey(principalOf(ctx))));
+        const entries = fleet.success ? fleet.data : [];
+        return scope === "all" ? entries : entries.filter(entry => entry.sessionId === ctx.session.id);
+    });
+}
+function fleetKey(principal) {
+    return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
+}

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/repos.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Which repositories a launch may target. The model picks `repo` / `ref` /
+ * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
+ * Model-chosen targets always require that allowlist: an unbound mount
+ * (no `cloud.repos`) must not accept an arbitrary URL under the host API
+ * key, with or without `envVars`.
+ */
+import type { AgentCloudOptions } from "../../../types.js";
+export interface LaunchTarget {
+    repo?: string;
+    ref?: string;
+    prUrl?: string;
+}
+export declare function launchRepos(target: LaunchTarget, cloud: AgentCloudOptions): AgentCloudOptions["repos"];
+//# sourceMappingURL=repos.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repos.d.ts","sourceRoot":"","sources":["../../../../src/extensions/cursor-cloud-agents/lib/repos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,iBAAiB,GACvB,iBAAiB,CAAC,OAAO,CAAC,CAyC5B"}

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

@@ -0,0 +1,53 @@
+/**
+ * Which repositories a launch may target. The model picks `repo` / `ref` /
+ * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
+ * Model-chosen targets always require that allowlist: an unbound mount
+ * (no `cloud.repos`) must not accept an arbitrary URL under the host API
+ * key, with or without `envVars`.
+ */
+import { parsePrUrl } from "../../../internal/scm/pr-url.js";
+export function launchRepos(target, cloud) {
+    var _a, _b;
+    var _c, _d, _e, _f, _g, _h;
+    if (target.repo === undefined && target.ref === undefined && target.prUrl === undefined) {
+        return cloud.repos;
+    }
+    const pr = target.prUrl === undefined ? undefined : parsePrUrl(target.prUrl);
+    if (target.prUrl !== undefined && (pr === null || pr === void 0 ? void 0 : pr.provider) !== "github") {
+        throw new Error(`prUrl must be a GitHub pull request URL: ${target.prUrl}`);
+    }
+    const prRepo = pr === undefined ? undefined : `https://github.com/${pr.owner}/${pr.repo}`;
+    // A lone `ref` needs exactly one configured repository to apply to.
+    const configured = (_c = cloud.repos) !== null && _c !== void 0 ? _c : [];
+    const url = (_e = (_d = target.repo) !== null && _d !== void 0 ? _d : prRepo) !== null && _e !== void 0 ? _e : (configured.length === 1 ? (_a = configured[0]) === null || _a === void 0 ? void 0 : _a.url : undefined);
+    if (url === undefined) {
+        throw new Error(configured.length > 1
+            ? "`repo` is required: this extension configures several repositories."
+            : "`repo` is required: this extension has no configured default repository.");
+    }
+    if (prRepo !== undefined && repoKey(prRepo) !== repoKey(url)) {
+        throw new Error(`prUrl ${target.prUrl} is not a pull request of ${url}.`);
+    }
+    const allowlisted = (_b = cloud.repos) === null || _b === void 0 ? void 0 : _b.some(configured => repoKey(configured.url) === repoKey(url));
+    if (allowlisted !== true) {
+        throw new Error(cloud.repos === undefined
+            ? `Configure cloud.repos before launching against a model-chosen repository (${url}).`
+            : `${url} is not one of this extension's configured repositories.`);
+    }
+    // Keep the matching allowlist entry's branch / PR defaults when the model
+    // only names the repository (handoff always passes `repo`). An explicit
+    // `ref` clears an inherited `prUrl` so branch and PR targets do not mix.
+    const match = configured.find(configuredRepo => repoKey(configuredRepo.url) === repoKey(url));
+    return [
+        {
+            url: (_f = match === null || match === void 0 ? void 0 : match.url) !== null && _f !== void 0 ? _f : url,
+            startingRef: (_g = target.ref) !== null && _g !== void 0 ? _g : match === null || match === void 0 ? void 0 : match.startingRef,
+            prUrl: (_h = target.prUrl) !== null && _h !== void 0 ? _h : (target.ref !== undefined ? undefined : match === null || match === void 0 ? void 0 : match.prUrl),
+        },
+    ];
+}
+function repoKey(url) {
+    const parsed = new URL(url);
+    const path = parsed.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
+    return `${parsed.hostname}${path}`.toLowerCase();
+}

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,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,SAAS,CAInF"}

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

@@ -0,0 +1,37 @@
+---
+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. 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 `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.
+
+## Look an agent up by id
+
+Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, `expired`, or `unknown`), its `branch` and pull request `prUrl` once pushed, change counts, 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`.
+
+## Read what it did
+
+To read the report or understand what was done, call `dump` with the `agent_id`. Once a transcript exists, it writes the agent's whole conversation to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus `finalMessage`. Before any transcript exists, either value may be absent; wait for output instead of inventing a report.
+
+Use `finalMessage` as the agent's report. Read the returned transcript path when you need its prompts, reasoning, or tool calls, then inspect the resulting branch or pull request before claiming exact code changes. The transcript is evidence of what the agent did, not a canonical diff.
+
+## 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
+
+`list` returns the agents launched in this session, newest first; pass `scope: "all"` to include your launches from other sessions. Launch one agent per independent task and give each a descriptive `name`. Agents launched by others are out of reach.

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;AAMxD,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;