@cursor/bdk 0.2.3 → 0.2.4

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

@@ -1,80 +0,0 @@
-/**
- * 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`. A function allowlist is resolved on every
- * call and always narrows the launch to one of its repositories.
- */
-
-import { parsePrUrl } from "../../../internal/scm/pr-url.js";
-import type { AgentCloudOptions } from "../../../types.js";
-import type { CursorCloudAgentsCloudOptions } from "../extension.js";
-
-export interface LaunchTarget {
-  repo?: string;
-  ref?: string;
-  prUrl?: string;
-}
-
-export function launchRepos(
-  target: LaunchTarget,
-  cloud: CursorCloudAgentsCloudOptions,
-): AgentCloudOptions["repos"] {
-  const resolved = typeof cloud.repos === "function";
-  const allowlist = typeof cloud.repos === "function" ? cloud.repos() : cloud.repos;
-  if (resolved && allowlist?.length === 0) {
-    throw new Error("No repositories are available to cloud agents for this deployment.");
-  }
-  if (
-    !resolved &&
-    target.repo === undefined &&
-    target.ref === undefined &&
-    target.prUrl === undefined
-  ) {
-    return allowlist;
-  }
-  const pr = target.prUrl === undefined ? undefined : parsePrUrl(target.prUrl);
-  if (target.prUrl !== undefined && 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 = allowlist ?? [];
-  const url = target.repo ?? prRepo ?? (configured.length === 1 ? configured[0]?.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 = allowlist?.some(configured => repoKey(configured.url) === repoKey(url));
-  if (allowlisted !== true) {
-    throw new Error(
-      allowlist === 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: match?.url ?? url,
-      startingRef: target.ref ?? match?.startingRef,
-      prUrl: target.prUrl ?? (target.ref !== undefined ? undefined : match?.prUrl),
-    },
-  ];
-}
-
-function repoKey(url: string): string {
-  const parsed = new URL(url);
-  const path = parsed.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
-  return `${parsed.hostname}${path}`.toLowerCase();
-}

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

@@ -1,19 +0,0 @@
-/** 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 function transcriptPath(agentId: string): string {
-  return `cloud-agent-transcripts/${agentId}.jsonl`;
-}
-
-export function transcriptLines(messages: CloudAgentMessage[]): string[] {
-  return messages.map(message => JSON.stringify(message));
-}
-
-/** The text of the last assistant message, the agent's report. */
-export function lastAssistantText(messages: CloudAgentMessage[]): string | undefined {
-  return messages
-    .toReversed()
-    .find(message => message.role === "assistant" && message.text !== undefined)?.text;
-}

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

@@ -1,37 +0,0 @@
----
-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/src/extensions/cursor-cloud-agents/tools/cancel.ts

@@ -1,21 +0,0 @@
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import { cloudAgentsBackend } from "../lib/backend.js";
-import { assertWriteChannel } from "../lib/channels.js";
-import { assertOwned } from "../lib/fleet.js";
-import { agentRef } from "../lib/inputs.js";
-
-const cancel: ToolDefinition = 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,
-  async execute(input, ctx) {
-    assertWriteChannel(ctx);
-    await assertOwned(ctx, input.agent_id);
-    await cloudAgentsBackend().pause(input.agent_id);
-    return { agentId: input.agent_id, cancelled: true };
-  },
-});
-
-export default cancel;

package/src/extensions/cursor-cloud-agents/tools/dump.ts

@@ -1,47 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.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: ToolDefinition = 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,
-  async execute(input, ctx) {
-    await assertOwned(ctx, input.agent_id);
-    const backend = cloudAgentsBackend();
-    const [messages, info] = await 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`;
-    await mkdir(dirname(path), { recursive: true });
-    await 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/src/extensions/cursor-cloud-agents/tools/get.ts

@@ -1,18 +0,0 @@
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import { cloudAgentsBackend } from "../lib/backend.js";
-import { assertOwned } from "../lib/fleet.js";
-import { agentRef } from "../lib/inputs.js";
-
-const get: ToolDefinition = 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,
-  async execute(input, ctx) {
-    await assertOwned(ctx, input.agent_id);
-    return cloudAgentsBackend().info(input.agent_id);
-  },
-});
-
-export default get;

package/src/extensions/cursor-cloud-agents/tools/launch.ts

@@ -1,62 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import extension from "../extension.js";
-import { cloudAgentsBackend } from "../lib/backend.js";
-import { assertWriteChannel } from "../lib/channels.js";
-import { recordLaunch } from "../lib/fleet.js";
-import { launchRepos } from "../lib/repos.js";
-
-const launch: ToolDefinition = defineTool({
-  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({
-    prompt: z
-      .string()
-      .min(1)
-      .describe("Self-contained task: goal, constraints, and what done looks like."),
-    repo: z
-      .string()
-      .url()
-      .optional()
-      .describe(
-        "Repository clone URL (GitHub or Origin), one of the configured repositories. Defaults to the configured repository when there is exactly one.",
-      ),
-    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()
-      .describe("Work on this pull request's branch instead of a new one."),
-    name: z
-      .string()
-      .max(100)
-      .optional()
-      .describe("Display name; derived from the prompt when omitted."),
-  }),
-  async execute(input, ctx) {
-    assertWriteChannel(ctx);
-    const { cloud, model } = extension.config;
-    const launched = await cloudAgentsBackend().launch({
-      prompt: input.prompt,
-      name: input.name,
-      model,
-      cloud: {
-        ...cloud,
-        repos: launchRepos(
-          { repo: input.repo, ref: input.starting_ref, prUrl: input.pr_url },
-          cloud,
-        ),
-      },
-    });
-    await recordLaunch(ctx, launched.agentId, input.name);
-    return launched;
-  },
-});
-
-export default launch;

package/src/extensions/cursor-cloud-agents/tools/list.ts

@@ -1,31 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import { agentUrl } from "../lib/backend.js";
-import { listFleet } from "../lib/fleet.js";
-
-const list: ToolDefinition = defineTool({
-  description:
-    'List the cloud agents launched in this session, newest first. Pass scope "all" for every agent you launched, in any session.',
-  effect: "read",
-  inputSchema: z.object({
-    scope: z
-      .enum(["session", "all"])
-      .default("session")
-      .describe(
-        "session: agents this session launched; all: every agent launched by you, in any session.",
-      ),
-    limit: z.number().int().min(1).max(100).default(20),
-  }),
-  async execute(input, ctx) {
-    const fleet = await listFleet(ctx, input.scope);
-    return {
-      sessionId: ctx.session.id,
-      agents: fleet
-        .slice(0, input.limit)
-        .map(entry => ({ ...entry, url: agentUrl(entry.agentId) })),
-    };
-  },
-});
-
-export default list;

package/src/extensions/cursor-cloud-agents/tools/reply.ts

@@ -1,36 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import extension from "../extension.js";
-import { cloudAgentsBackend } from "../lib/backend.js";
-import { assertWriteChannel } from "../lib/channels.js";
-import { assertOwned } from "../lib/fleet.js";
-import { agentRef } from "../lib/inputs.js";
-
-const reply: ToolDefinition = defineTool({
-  description:
-    "Send a follow-up prompt to a cloud agent you launched. It queues behind the current run; pass interrupt to stop that run's current step and deliver it now.",
-  effect: "write",
-  needsApproval: () => extension.config.needsApproval,
-  inputSchema: agentRef.extend({
-    prompt: z.string().min(1).describe("The follow-up instruction."),
-    interrupt: z
-      .boolean()
-      .default(false)
-      .describe(
-        "Deliver now, cancelling the in-flight step, instead of waiting for the current run to finish.",
-      ),
-  }),
-  async execute(input, ctx) {
-    assertWriteChannel(ctx);
-    await assertOwned(ctx, input.agent_id);
-    const { runId } = await cloudAgentsBackend().followUp(
-      input.agent_id,
-      input.prompt,
-      input.interrupt,
-    );
-    return { agentId: input.agent_id, runId, queued: !input.interrupt };
-  },
-});
-
-export default reply;

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

@@ -1,132 +0,0 @@
-/**
- * Your Grok Bot agents as an extension. Mount it and the agent can talk to
- * the Grok Bot agents of the host's account: send a message, read the
- * reply, keep waiting on a long turn, interrupt one.
- *
- * ```ts
- * // agent/extensions/grokbot.ts
- * import cursorGrokBotAgents from "@cursor/bdk/extensions/cursor-grokbot-agents";
- *
- * export default cursorGrokBotAgents({
- *   agents: [
- *     { name: "Plan Keeper", description: "Keeps or moves outdoor plans." },
- *   ],
- * });
- * ```
- *
- * Contributes `grokbot__ask`, `grokbot__check`, `grokbot__interrupt`,
- * `grokbot__list` and the `grokbot__consult` skill (the namespace is the
- * mount filename), over the same public `/v0/grokbot` session API the
- * grokbot runtime uses, under the serve host's Cursor API key
- * (`CURSOR_API_KEY`, key file, or `login`). Agents are addressed by name and
- * resolved on the account the key belongs to; a message lands in that
- * account's own conversation with the agent, and the reply is what the agent
- * sends back during that turn. The tools run on the serve host, so they
- * need the local runtime.
- *
- * This is the other direction from `defineAgent({ runtime: "grokbot" })`:
- * the runtime runs *this* agent's turns on the hosted Grok Bot harness; the
- * extension keeps the agent where it is and lets it talk to *other* Grok
- * Bot agents.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { Extension } from "../../types.js";
-
-/**
- * A Grok Bot agent the model may address, by the name shown in the app.
- * Type alias, not an interface: `list` returns these.
- */
-export type ConfiguredGrokBotAgent = {
-  name: string;
-  /** What the agent is for; shown to the model by `list`. */
-  description?: string;
-};
-
-/** Mount options; every field is optional. */
-export interface CursorGrokBotAgentsOptions {
-  /**
-   * The Grok Bot agents the model may talk to, by name. This is the
-   * allowlist for a call's own `agent`: names outside it are refused, and a
-   * lone configured agent is the default when a call names none. Without
-   * it, any name goes through and `needsApproval` defaults to true, since
-   * an unknown name creates an agent of that name on the account.
-   */
-  agents?: Array<string | ConfiguredGrokBotAgent>;
-  /**
-   * Park messages for a human approval. Defaults to `true` when no `agents`
-   * are configured; `false` once they are. Pass an explicit boolean to
-   * override. Configured names still bound the model's choice regardless.
-   */
-  needsApproval?: boolean;
-  /** Cursor API key. Defaults to the serve host's own key. */
-  apiKey?: string;
-  /**
-   * How often to read the agent's transcript while waiting for a reply, in
-   * milliseconds. Defaults to 750.
-   */
-  pollIntervalMs?: number;
-}
-
-/** {@link CursorGrokBotAgentsOptions} with defaults applied. */
-export interface CursorGrokBotAgentsConfig {
-  agents?: ConfiguredGrokBotAgent[];
-  needsApproval: boolean;
-  apiKey?: string;
-  pollIntervalMs: number;
-}
-
-/** The backend's session name limit. */
-export const AGENT_NAME_MAX_LENGTH = 255;
-const DEFAULT_POLL_INTERVAL_MS = 750;
-
-const agentName = z
-  .string()
-  .trim()
-  .min(1, "Grok Bot agent names must not be empty.")
-  .max(AGENT_NAME_MAX_LENGTH);
-
-const configuredAgent: z.ZodType<
-  ConfiguredGrokBotAgent,
-  z.ZodTypeDef,
-  string | ConfiguredGrokBotAgent
-> = z
-  .union([agentName, z.object({ name: agentName, description: z.string().optional() })])
-  .transform(agent => (typeof agent === "string" ? { name: agent } : agent));
-
-const agents = z
-  .array(configuredAgent)
-  .min(1, "agents must name at least one Grok Bot agent; omit it to allow any.")
-  .refine(
-    list => new Set(list.map(agent => agent.name.toLowerCase())).size === list.length,
-    "agents must not repeat a name (names match case-insensitively).",
-  );
-
-const config: z.ZodType<
-  CursorGrokBotAgentsConfig,
-  z.ZodTypeDef,
-  CursorGrokBotAgentsOptions | undefined
-> = z
-  .object({
-    agents: agents.optional(),
-    needsApproval: z.boolean().optional(),
-    apiKey: z.string().optional(),
-    pollIntervalMs: z.number().int().min(1).default(DEFAULT_POLL_INTERVAL_MS),
-  })
-  .default({})
-  .transform(options => ({
-    ...options,
-    needsApproval: options.needsApproval ?? options.agents === undefined,
-  }));
-
-const cursorGrokBotAgents: Extension<
-  CursorGrokBotAgentsConfig,
-  CursorGrokBotAgentsOptions | undefined
-> = defineExtension({
-  root: import.meta.dirname,
-  description: "Talk to your Grok Bot agents and read their replies.",
-  config,
-});
-
-export default cursorGrokBotAgents;

package/src/extensions/cursor-grokbot-agents/lib/agents.ts

@@ -1,42 +0,0 @@
-/**
- * Which Grok Bot agent a call addresses. The model names one per call, but
- * the author's `agents` are the allowlist: with them configured, a name
- * outside the list is refused (the backend would create an agent of that
- * name), and a lone configured agent stands in when the call names none.
- * Matching is case-insensitive and resolves to the configured spelling,
- * since the backend looks names up exactly.
- */
-
-import type { ConfiguredGrokBotAgent } from "../extension.js";
-
-export function resolveAgentName(
-  requested: string | undefined,
-  configured: ConfiguredGrokBotAgent[] | undefined,
-): string {
-  const name = requested?.trim();
-  if (configured === undefined) {
-    if (name === undefined || name === "") {
-      throw new Error("`agent` is required: this extension has no configured Grok Bot agents.");
-    }
-    return name;
-  }
-  const names = configured.map(agent => `"${agent.name}"`).join(", ");
-  if (name === undefined || name === "") {
-    const only = configured.length === 1 ? configured[0] : undefined;
-    if (only === undefined) {
-      throw new Error(
-        `\`agent\` is required: this extension configures several Grok Bot agents (${names}).`,
-      );
-    }
-    return only.name;
-  }
-  const match =
-    configured.find(agent => agent.name === name) ??
-    configured.find(agent => agent.name.toLowerCase() === name.toLowerCase());
-  if (match === undefined) {
-    throw new Error(
-      `"${name}" is not one of this extension's configured Grok Bot agents (${names}).`,
-    );
-  }
-  return match.name;
-}