@cursor/bdk 0.2.2 → 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/improve/extension.ts

@@ -1,69 +0,0 @@
-/**
- * Self-improvement as an extension. An agent's behaviour is source in a
- * repository, so changing how it behaves is a change to that source: a
- * one-off Cursor cloud agent does the coding on a branch and opens a pull
- * request, the agent that mounted this writes the brief and reports the
- * pull request. Durable behavior changes only after review, merge, and
- * deployment. A cloud-runtime turn may edit its ephemeral checkout while
- * preparing the pull request.
- *
- * ```ts
- * // agent/extensions/improve.ts
- * import improve from "@cursor/bdk/extensions/improve";
- *
- * export default improve({
- *   repo: "https://github.com/acme/agents",
- *   path: "agents/concierge",
- * });
- * ```
- *
- * Contributes the `<namespace>__yourself` skill; mount it as `improve` so
- * the skill reads `improve__yourself`. The coding goes through the
- * cursor-cloud-agents extension, so mount that too, with `repo` among its
- * `cloud.repos`. An agent whose own turns run on a cloud VM with the
- * repository checked out needs no second mount: the skill has it work in
- * that checkout.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { Extension } from "../../types.js";
-
-export interface ImproveOptions {
-  /** Repository that holds the agent's source. One of the cloud agents mount's `cloud.repos`. */
-  repo: string;
-  /** The agent's directory in the repository, as `agent-sdk deploy --path` names it. */
-  path: string;
-  /** Ref the deployment tracks: branches start there and pull requests target it. Defaults to `main`. */
-  ref?: string;
-  /** What a coding agent must know about this tree beyond the Agent SDK layout, one line each. */
-  notes?: string[];
-  /** Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." */
-  deploy?: string;
-}
-
-/** {@link ImproveOptions} with defaults applied. */
-export interface ImproveConfig extends ImproveOptions {
-  ref: string;
-  notes: string[];
-  deploy: string;
-}
-
-const line = z.string().trim().min(1);
-
-const improve: Extension<ImproveConfig, ImproveOptions> = defineExtension({
-  root: import.meta.dirname,
-  description:
-    "Propose changes to your own source through a branch and pull request; durable behavior changes after review and deployment.",
-  config: z.object({
-    repo: z.string().url(),
-    path: z
-      .string()
-      .regex(/^[^\s/]+(\/[^\s/]+)*$/, "Expected a repository-relative path like agents/concierge"),
-    ref: line.default("main"),
-    notes: z.array(line).default([]),
-    deploy: line.default("It takes effect at the next deploy."),
-  }),
-});
-
-export default improve;

package/src/extensions/improve/skills/yourself.ts

@@ -1,50 +0,0 @@
-import { defineSkill } from "../../../skills.js";
-import type { SkillDefinition } from "../../../types.js";
-import extension from "../extension.js";
-
-const { repo, path, ref, notes, deploy } = extension.config;
-
-const treeNotes =
-  notes.length === 0
-    ? ""
-    : `\nAbout this tree in particular; copy these into the brief verbatim:\n\n${notes.map(note => `- ${note}`).join("\n")}\n`;
-
-const yourself: SkillDefinition = defineSkill({
-  description:
-    "Change your own source (instructions, skills, tools, channels, connections, model, deployment) through a one-off Cursor cloud agent and a pull request. Use whenever the ask is about how you yourself behave, including adding or editing a skill, so the change lands in the repository instead of the tree you happen to be running from.",
-  markdown: `# Improve yourself
-
-You are the Agent SDK agent at \`${path}\` in ${repo}, deployed from \`${ref}\`. A change to how you behave is a change to that source, and it goes through the repository like any other change: a branch, a pull request, review, a deploy. Nothing about it is special except that people describe it in the second person.
-
-## What changes where
-
-Under \`${path}/agent/\`:
-
-- \`instructions.md\` is the always-on system prompt: identity, tool-choice rules, the output contract.
-- \`skills/<name>.md\` is a procedure loaded on demand; a \`<name>/SKILL.md\` directory carries sibling files. The \`description\` frontmatter is the routing rule the model sees.
-- \`tools/<name>.ts\` is typed, executable behaviour: anything that must be right every time.
-- \`channels/\`, \`mcp-connections/\`, and \`host-connections/\` are the surfaces and connectors.
-- \`agent.ts\` is the model, its parameters, and the runtime.
-- \`extensions/<ns>.ts\` mounts an extension. This skill arrives through one.
-${treeNotes}
-## The change is made on a clean checkout
-
-Durable source changes happen on a branch from a clean checkout of ${repo} at \`${ref}\`, never by mutating a deployed local-runtime copy. When your own turn runs on a cloud VM with that repository checked out, its ephemeral tree is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` instead of launching another.
-
-## The brief
-
-Whoever makes the change works from the same brief. For a cloud agent it is the whole handoff, because it cannot see this conversation:
-
-- Who and why. A change to the source of the Agent SDK agent at \`${path}\`, asked for by the person in front of you: the change in their words, and what you know about why they want it.
-- Where. Repository ${repo}, ref \`${ref}\`, directory \`${path}\`, the layout above, and the files you expect to change.
-- How. Follow the repository's own conventions (its \`AGENTS.md\` files and rules along the paths touched). Keep the diff to the change. Run the checks the repository defines for \`${path}\`. Open a pull request against \`${ref}\`; never merge it.
-- Report. The pull request URL, what changed, what was verified and how, and anything left unverified.
-
-## Report
-
-If you launched a cloud agent, give the person its URL with the full id, read its report with \`dump\` (\`get\` for status), and read the pull request before repeating its claims. Report the pull request, not that you delegated.
-
-A merged pull request changes nothing by itself. ${deploy} Never say you have already changed yourself. Editing your own source is still an edit: do it when asked, and stop at the pull request. Deploying is a separate authorization.`,
-});
-
-export default yourself;

package/src/extensions/jev/extension.ts

@@ -1,95 +0,0 @@
-/**
- * Jev decisions as an extension. Mount it and the agent can ask Jev for
- * typed boolean, choice, and score answers, then call `decide` from your
- * own channel hooks and tools before they start a turn or write.
- *
- * ```ts
- * // agent/extensions/jev.ts
- * import jev from "@cursor/bdk/extensions/jev";
- *
- * export default jev();
- * ```
- *
- * Contributes `<namespace>__evaluate` plus the `questions` and
- * `gated-write` skills (the namespace is the mount filename). Auth is
- * `TYPESAFE_API_KEY`. The default model is `jev-latest`. Custom tools
- * import `decide`, `above`, and `needsHuman` from this same module. Set
- * `harnessTools` or `skills` to false when the agent should not see those
- * contributions.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { Extension } from "../../types.js";
-import { DEFAULT_EVALUATION_MODEL } from "./lib/evaluate.js";
-
-/** Mount options; every field is optional. */
-export interface JevOptions {
-  /** TypeSafe API key. Defaults to `TYPESAFE_API_KEY`. */
-  apiKey?: string;
-  /** TypeSafe model id. Defaults to `jev-latest`. */
-  model?: string;
-  /** Mount the namespaced `evaluate` harness tool. Defaults to true. */
-  harnessTools?: boolean;
-  /** Mount the `questions` and `gated-write` skills. Defaults to true. */
-  skills?: boolean;
-}
-
-/** {@link JevOptions} with defaults applied. */
-export interface JevConfig {
-  apiKey?: string;
-  model: string;
-  harnessTools: boolean;
-  skills: boolean;
-}
-
-const config: z.ZodType<JevConfig, z.ZodTypeDef, JevOptions | undefined> = z
-  .object({
-    apiKey: z.string().min(1).optional(),
-    model: z.string().min(1).optional(),
-    harnessTools: z.boolean().default(true),
-    skills: z.boolean().default(true),
-  })
-  .default({})
-  .transform(options => ({
-    apiKey: options.apiKey,
-    model: options.model ?? DEFAULT_EVALUATION_MODEL,
-    harnessTools: options.harnessTools,
-    skills: options.skills,
-  }));
-
-const jev: Extension<JevConfig, JevOptions | undefined> = defineExtension({
-  root: import.meta.dirname,
-  description: "Ask Jev for typed choice, score, and boolean answers.",
-  config,
-  contributions: options => ({
-    tools: options.harnessTools,
-    skills: options.skills,
-  }),
-});
-
-export type {
-  AnswersFor,
-  BooleanAnswer,
-  BooleanQuestion,
-  ChoiceAnswer,
-  ChoiceQuestion,
-  EvaluateArgs,
-  EvaluateResult,
-  EvaluationAnswer,
-  EvaluationQuestion,
-  EvaluationState,
-  QuestionMap,
-  ScoreAnswer,
-  ScoreQuestion,
-} from "./lib/evaluate.js";
-export {
-  above,
-  DEFAULT_EVALUATION_MODEL,
-  DEFAULT_HUMAN_THRESHOLD,
-  decide,
-  evaluate,
-  needsHuman,
-} from "./lib/evaluate.js";
-
-export default jev;