@cursor/bdk 0.2.3 → 0.2.4

package/src/extensions/cursor-cloud-agents/extension.ts

@@ -1,131 +0,0 @@
-/**
- * Cursor cloud agents as an extension. Mount it and the agent can hand
- * coding work to Cursor cloud agents and steer a fleet of them:
- *
- * ```ts
- * // agent/extensions/cloud.ts
- * import cursorCloudAgents from "@cursor/bdk/extensions/cursor-cloud-agents";
- *
- * export default cursorCloudAgents({
- *   cloud: { repos: [{ url: "https://github.com/acme/api" }], autoCreatePR: true },
- * });
- * ```
- *
- * Contributes `cloud__launch`, `cloud__get`, `cloud__dump`, `cloud__reply`,
- * `cloud__cancel`, `cloud__list` and the `cloud__handoff` skill (the
- * namespace is the mount filename), the action vocabulary Sand's CloudAgent
- * tool uses, over the same backend calls: launches through the v1 Cloud
- * Agents API, everything else through the BackgroundComposerService RPCs,
- * all under the serve host's Cursor API key (`CURSOR_API_KEY`, key file, or
- * `login`). Each launched agent stays bound to the principal that launched
- * it, and launches go to the configured repositories. `channels` limits
- * launch, reply, and cancel to sessions on those channel ids, so a channel
- * whose input is untrusted (an alert webhook) cannot start or steer an agent.
- * The tools run on the serve host, so they need the local runtime.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { AgentCloudOptions, Extension, ModelSetting } from "../../types.js";
-
-type CloudRepo = NonNullable<AgentCloudOptions["repos"]>[number];
-
-export type CursorCloudAgentsCloudOptions = Omit<AgentCloudOptions, "repos"> & {
-  repos?: CloudRepo[] | (() => CloudRepo[]);
-};
-
-/** Mount options; every field is optional. */
-export interface CursorCloudAgentsOptions {
-  /**
-   * Launch defaults: target `repos`, `env`, `autoCreatePR`, ... in the same
-   * vocabulary as `defineAgent({ cloud })`. Configured `repos` are also the
-   * allowlist for a launch's own `repo` / `prUrl`; model-chosen targets are
-   * refused when no allowlist is configured. With none configured,
-   * `needsApproval` defaults to true so prompt-only launches park first.
-   * `repos` may be a function, called on every launch, for an allowlist that
-   * is only known at request time (a multi-tenant deployment's per-install
-   * secrets). A launch against a function allowlist always targets exactly
-   * one of its repositories, never the whole list and never none.
-   */
-  cloud?: CursorCloudAgentsCloudOptions;
-  /** Model for launched agents. The account default when omitted. */
-  model?: ModelSetting;
-  /**
-   * Park launches and follow-ups for a human approval. Defaults to `true`
-   * when no `cloud.repos` are configured (prompt-only launches still use
-   * the host key); `false` once repositories are configured. Pass an
-   * explicit boolean to override. Model-chosen `repo` / `prUrl` still
-   * require the allowlist regardless of this flag.
-   */
-  needsApproval?: boolean;
-  channels?: string[];
-  /** Cursor API key. Defaults to the serve host's own key. */
-  apiKey?: string;
-}
-
-/** {@link CursorCloudAgentsOptions} with defaults applied. */
-export interface CursorCloudAgentsConfig {
-  cloud: CursorCloudAgentsCloudOptions;
-  model?: ModelSetting;
-  needsApproval: boolean;
-  channels?: string[];
-  apiKey?: string;
-}
-
-const repo = z.object({
-  url: z.string().url(),
-  startingRef: z.string().optional(),
-  prUrl: z.string().url().optional(),
-});
-
-const repos = z.array(repo);
-
-const cloud: z.ZodType<CursorCloudAgentsCloudOptions> = z.object({
-  env: z
-    .discriminatedUnion("type", [
-      z.object({ type: z.literal("cloud"), name: z.string().optional() }),
-      z.object({ type: z.literal("pool"), name: z.string().optional() }),
-      z.object({ type: z.literal("machine"), name: z.string().optional() }),
-    ])
-    .optional(),
-  repos: z.union([repos, z.function().args().returns(repos)]).optional(),
-  workOnCurrentBranch: z.boolean().optional(),
-  autoCreatePR: z.boolean().optional(),
-  skipReviewerRequest: z.boolean().optional(),
-  envVars: z.record(z.string()).optional(),
-});
-
-const model: z.ZodType<ModelSetting> = z.union([
-  z.string().min(1),
-  z.object({
-    id: z.string().min(1),
-    params: z.array(z.object({ id: z.string(), value: z.string() })).optional(),
-  }),
-]);
-
-const config: z.ZodType<
-  CursorCloudAgentsConfig,
-  z.ZodTypeDef,
-  CursorCloudAgentsOptions | undefined
-> = z
-  .object({
-    cloud: cloud.default({}),
-    model: model.optional(),
-    needsApproval: z.boolean().optional(),
-    channels: z.array(z.string().min(1)).optional(),
-    apiKey: z.string().optional(),
-  })
-  .default({})
-  .transform(options => ({
-    ...options,
-    needsApproval: options.needsApproval ?? options.cloud.repos === undefined,
-  }));
-
-const cursorCloudAgents: Extension<CursorCloudAgentsConfig, CursorCloudAgentsOptions | undefined> =
-  defineExtension({
-    root: import.meta.dirname,
-    description: "Launch, steer, and monitor Cursor cloud agents.",
-    config,
-  });
-
-export default cursorCloudAgents;

package/src/extensions/cursor-cloud-agents/lib/backend.ts

@@ -1,386 +0,0 @@
-/**
- * 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.
- */
-
-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 type { AgentCloudOptions, ModelSetting } from "../../../types.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 = 60_000;
-// The create call returns once the initial run exists, which can wait on a VM.
-const LAUNCH_TIMEOUT_MS = 300_000;
-
-export class CloudAgentsApiError extends Error {
-  constructor(
-    message: string,
-    readonly status?: number,
-  ) {
-    super(message);
-    this.name = "CloudAgentsApiError";
-  }
-}
-
-export type CloudAgentStatus =
-  | "creating"
-  | "running"
-  | "finished"
-  | "error"
-  | "expired"
-  | "unknown";
-
-// Type aliases, not interfaces: these flow into tool results.
-export type CloudAgentInfo = {
-  agentId: string;
-  name: string;
-  status: CloudAgentStatus;
-  archived: boolean;
-  url: string;
-  branch?: string;
-  prUrl?: string;
-  summary?: string;
-  error?: string;
-  changes?: { filesChanged: number; linesAdded: number; linesRemoved: number };
-};
-
-export type CloudAgentToolCall = {
-  name: string;
-  args: unknown;
-  content?: string;
-  error?: string;
-};
-
-export type CloudAgentMessage = {
-  role: "user" | "assistant";
-  text?: string;
-  thinking?: string;
-  toolCalls?: CloudAgentToolCall[];
-};
-
-export type CloudAgentLaunch = {
-  agentId: string;
-  runId: string;
-  status: string;
-  url: string;
-};
-
-export type LaunchRequest = {
-  prompt: string;
-  name?: string;
-  cloud: AgentCloudOptions;
-  model?: ModelSetting;
-};
-
-// ---------------------------------------------------------------------------
-// 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 {
-  private readonly rpcClient: CursorBackendClient;
-
-  constructor(
-    private readonly apiKey: () => string,
-    private readonly fetchImpl: typeof fetch = fetch,
-  ) {
-    // 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. */
-  async launch(request: LaunchRequest): Promise<CloudAgentLaunch> {
-    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: Response;
-    try {
-      response = await 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 = await 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: parsed.agent.url ?? agentUrl(parsed.agent.id),
-    };
-  }
-
-  async info(agentId: string): Promise<CloudAgentInfo> {
-    const { composer } = infoResponseSchema.parse(
-      await this.rpcClient.serviceRpc(
-        SERVICE,
-        "GetBackgroundComposerInfo",
-        { bcId: agentId },
-        RPC_TIMEOUT_MS,
-      ),
-    );
-    const { composer: summary } = composer;
-    const failure = composer.permanentError ?? composer.startError;
-    return {
-      agentId: summary.bcId,
-      name: summary.name ?? "",
-      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: summary.linesAdded ?? 0,
-              linesRemoved: summary.linesRemoved ?? 0,
-            },
-    };
-  }
-
-  async conversation(agentId: string): Promise<CloudAgentMessage[]> {
-    const { conversation } = conversationResponseSchema.parse(
-      await this.rpcClient.serviceRpc(
-        SERVICE,
-        "GetBackgroundComposerConversation",
-        { bcId: agentId },
-        RPC_TIMEOUT_MS,
-      ),
-    );
-    return (conversation ?? []).map(message => {
-      const toolCalls = (message.toolResults ?? []).map(result => ({
-        name: result.toolName ?? "",
-        args: parseArgs(result.args ?? result.rawArgs),
-        content: result.content,
-        error: result.error?.clientVisibleErrorMessage,
-      }));
-      return {
-        role: message.type === "MESSAGE_TYPE_HUMAN" ? "user" : "assistant",
-        text: emptyToUndefined(message.text),
-        thinking: emptyToUndefined(message.thinking?.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.
-   */
-  async followUp(
-    agentId: string,
-    prompt: string,
-    interrupt: boolean,
-  ): Promise<{ runId: string | undefined }> {
-    const { runId } = followupResponseSchema.parse(
-      await 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 };
-  }
-
-  async pause(agentId: string): Promise<void> {
-    await this.rpcClient.serviceRpc(
-      SERVICE,
-      "PauseBackgroundComposer",
-      { bcId: agentId, source: SOURCE },
-      RPC_TIMEOUT_MS,
-    );
-  }
-}
-
-let backend: CloudAgentsBackend | undefined;
-
-/** The process-wide backend for this mount, built on first use. */
-export function cloudAgentsBackend(): CloudAgentsBackend {
-  backend ??= new CloudAgentsBackend(apiKey);
-  return backend;
-}
-
-export function apiKey(): string {
-  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: string): string {
-  return `${cursorWebsiteUrl()}/agents/${agentId}`;
-}
-
-function statusOf(status: string | undefined): CloudAgentStatus {
-  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: z.infer<typeof errorDetailsSchema> | undefined,
-): string | undefined {
-  const parts = [failure?.details?.title, failure?.details?.detail].filter(
-    (part): part is string => part !== undefined && part !== "",
-  );
-  return parts.length === 0 ? undefined : parts.join(": ");
-}
-
-function parseArgs(args: string | undefined): unknown {
-  if (args === undefined || args === "") {
-    return undefined;
-  }
-  try {
-    return JSON.parse(args) as unknown;
-  } catch {
-    return args;
-  }
-}
-
-function emptyToUndefined(value: string | undefined): string | undefined {
-  return value === undefined || value === "" ? undefined : value;
-}
-
-function apiErrorMessage(text: string): string {
-  try {
-    const parsed = JSON.parse(text) as {
-      error?: { code?: string; message?: string };
-      code?: string;
-      message?: string;
-    };
-    const code = parsed.error?.code ?? parsed.code;
-    const message = parsed.error?.message ?? parsed.message;
-    return [code, message].filter(part => part !== undefined).join(": ") || text;
-  } catch {
-    return text;
-  }
-}

package/src/extensions/cursor-cloud-agents/lib/channels.ts

@@ -1,11 +0,0 @@
-import type { ToolContext } from "../../../types.js";
-import extension from "../extension.js";
-
-export function assertWriteChannel(ctx: ToolContext): void {
-  const { channels } = extension.config;
-  if (channels !== undefined && !channels.includes(ctx.session.channelId)) {
-    throw new Error(
-      `Cloud agents cannot be launched or steered from the "${ctx.session.channelId}" channel.`,
-    );
-  }
-}

package/src/extensions/cursor-cloud-agents/lib/fleet.ts

@@ -1,98 +0,0 @@
-/**
- * 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 { z } from "zod";
-import type { ToolContext } from "../../../types.js";
-
-const PREFIX = "cloud-agents";
-
-// Type alias, not an interface: fleet entries flow into tool results.
-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";
-
-const fleetSchema: z.ZodType<FleetEntry[]> = 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<string, Promise<void>>();
-
-function withIndexLock(key: string, task: () => Promise<void>): Promise<void> {
-  const run = (indexWrites.get(key) ?? 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: ToolContext): string {
-  const auth = ctx.session.auth;
-  return auth === null ? "anonymous" : `${auth.principalType}:${auth.principalId}`;
-}
-
-export async function recordLaunch(
-  ctx: ToolContext,
-  agentId: string,
-  name: string | undefined,
-): Promise<void> {
-  const principal = principalOf(ctx);
-  const entry: FleetEntry = {
-    agentId,
-    name,
-    launchedAt: new Date().toISOString(),
-    sessionId: ctx.session.id,
-  };
-  await ctx.host.kv.put(`${PREFIX}/agents/${agentId}`, { principal });
-  await withIndexLock(fleetKey(principal), async () => {
-    const fleet = await listFleet(ctx);
-    await ctx.host.kv.put(fleetKey(principal), [entry, ...fleet]);
-  });
-}
-
-/** Refuse agents launched by another principal, or not through the extension. */
-export async function assertOwned(ctx: ToolContext, agentId: string): Promise<void> {
-  const owner = ownerSchema.safeParse(await 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 async function listFleet(
-  ctx: ToolContext,
-  scope: FleetScope = "all",
-): Promise<FleetEntry[]> {
-  const fleet = fleetSchema.safeParse(await 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: string): string {
-  return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
-}

package/src/extensions/cursor-cloud-agents/lib/inputs.ts

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