@cursor/bdk 0.2.1

package/src/internal/terminal-style.ts

@@ -0,0 +1,133 @@
+/**
+ * Tiny ANSI helpers for CLI progress output. Respects `NO_COLOR` and
+ * only enables when the target stream is a TTY.
+ */
+
+import { clearScreenDown, cursorTo } from "node:readline";
+
+export interface TerminalPalette {
+  dim: (s: string) => string;
+  bold: (s: string) => string;
+  cyan: (s: string) => string;
+  green: (s: string) => string;
+  red: (s: string) => string;
+  magenta: (s: string) => string;
+  yellow: (s: string) => string;
+}
+
+const IDENTITY = (s: string): string => s;
+const ESC = "\u001b";
+const BEL = "\u0007";
+const ANSI_CSI = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+/** OSC 8 hyperlinks: `ESC ] 8 ; params ; uri BEL` (or ST). */
+const OSC_8 = new RegExp(`${ESC}\\]8;[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "g");
+
+const PLAIN: TerminalPalette = {
+  dim: IDENTITY,
+  bold: IDENTITY,
+  cyan: IDENTITY,
+  green: IDENTITY,
+  red: IDENTITY,
+  magenta: IDENTITY,
+  yellow: IDENTITY,
+};
+
+export function colorEnabledFor(stream: NodeJS.WriteStream = process.stdout): boolean {
+  return stream.isTTY === true && process.env.NO_COLOR === undefined;
+}
+
+export function makePalette(enabled: boolean): TerminalPalette {
+  if (!enabled) {
+    return PLAIN;
+  }
+  const wrap =
+    (code: string) =>
+    (s: string): string =>
+      `\u001b[${code}m${s}\u001b[0m`;
+  return {
+    dim: (s: string) => (hasAnsiStyling(s) ? s : wrap("2")(s)),
+    bold: wrap("1"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    red: wrap("31"),
+    magenta: wrap("35"),
+    yellow: wrap("33"),
+  };
+}
+
+/** Palette for human-facing stdout (init summaries, next steps). */
+export function stdoutPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stdout));
+}
+
+/** Palette for human-facing stderr (login progress, warnings). */
+export function stderrPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stderr));
+}
+
+/** Visible column count, ignoring CSI color/style and OSC 8 hyperlinks. */
+export function visibleWidth(text: string): number {
+  return text.replace(OSC_8, "").replace(ANSI_CSI, "").length;
+}
+
+/** True when `text` already carries CSI styling or OSC 8 (do not wrap again). */
+export function hasAnsiStyling(text: string): boolean {
+  return text.includes("\u001b[") || text.includes("\u001b]");
+}
+
+/**
+ * Clickable terminal hyperlink (OSC 8). The URI is the click target; `label`
+ * is what the user sees. `visibleWidth` ignores the OSC wrapper.
+ */
+export function terminalHyperlink(
+  url: string,
+  label: string,
+  enabled: boolean = colorEnabledFor(),
+): string {
+  if (!enabled) {
+    return label;
+  }
+  return `\u001b]8;;${url}\u0007\u001b[4m${label}\u001b[24m\u001b]8;;\u0007`;
+}
+
+/**
+ * Unicode box around `lines`. `color` wraps the whole box (borders + body)
+ * so a warning panel can be yellow without per-line prefixes.
+ */
+export function formatTerminalBox(
+  lines: readonly string[],
+  options?: {
+    color?: (s: string) => string;
+    minWidth?: number;
+    padding?: number;
+  },
+): string {
+  const color = options?.color ?? IDENTITY;
+  const padding = options?.padding ?? 1;
+  const contentWidth = Math.max(
+    options?.minWidth ?? 0,
+    ...lines.map(line => visibleWidth(line)),
+    1,
+  );
+  const inner = contentWidth + padding * 2;
+  const padLine = (line: string): string => {
+    const extra = contentWidth - visibleWidth(line);
+    return `│${" ".repeat(padding)}${line}${" ".repeat(padding + extra)}│`;
+  };
+  const paint = (line: string): string => color(line);
+  const box = [
+    paint(`╭${"─".repeat(inner)}╮`),
+    ...lines.map(line => paint(padLine(line))),
+    paint(`╰${"─".repeat(inner)}╯`),
+  ].join("\n");
+  return box;
+}
+
+/** Wipe the terminal before a `dev` Enter-to-restart cycle. */
+export function clearTerminal(stream: NodeJS.WriteStream = process.stdout): void {
+  if (stream.isTTY !== true) {
+    return;
+  }
+  cursorTo(stream, 0, 0);
+  clearScreenDown(stream);
+}

package/src/internal/testing/factory-resource-fixtures.ts

@@ -0,0 +1,84 @@
+/**
+ * Factory resource continuation fixtures shared by July and the control
+ * plane identity suite. Pure data: no imports, so server-shared can load
+ * this file by relative path without pulling `@cursor/bdk`.
+ */
+
+export const FACTORY_CHECKPOINT_NAME: string = "changeMonitors/cm-1/checkpoints/cp-1";
+export const FACTORY_ISSUE_NAME: string = "issues/iss-1";
+
+export interface FactoryCheckpointResourceFixture {
+  name: string;
+  deployment: string;
+  runKey: string;
+  issues: { title: string };
+  evidenceSummary: string;
+  planRevision: string;
+  createTime: string;
+  description: string;
+}
+
+export interface FactoryIssueResourceFixture {
+  name: string;
+  title: string;
+  body: string;
+  state: "STATE_OPEN";
+  createTime: string;
+  updateTime: string;
+  path: string;
+  etag: string;
+}
+
+export interface CheckpointCreatedPayloadFixture {
+  eventId: string;
+  eventType: "checkpoint.created";
+  teamId: string;
+  occurredAtMs: number;
+  checkpoint: FactoryCheckpointResourceFixture;
+}
+
+export interface IssueCreatedPayloadFixture {
+  eventId: string;
+  eventType: "issue.created";
+  teamId: string;
+  occurredAtMs: number;
+  issue: FactoryIssueResourceFixture;
+}
+
+export const FACTORY_CHECKPOINT_RESOURCE: FactoryCheckpointResourceFixture = {
+  name: FACTORY_CHECKPOINT_NAME,
+  deployment: "deployments/11111111-1111-4111-8111-111111111111",
+  runKey: "t+1h",
+  issues: { title: "POST /checkout 500 rate elevated" },
+  evidenceSummary: "5xx rate rose after the deploy.",
+  planRevision: "changeMonitors/cm-1/planRevisions/3",
+  createTime: "2026-09-08T21:00:00Z",
+  description: "Checkout 500s are elevated.",
+};
+
+export const FACTORY_ISSUE_RESOURCE: FactoryIssueResourceFixture = {
+  name: FACTORY_ISSUE_NAME,
+  title: "Checkout 500s",
+  body: "5xx rate rose after the deploy.",
+  state: "STATE_OPEN",
+  createTime: "2026-09-08T21:00:00Z",
+  updateTime: "2026-09-08T21:00:00Z",
+  path: "checkout/500s",
+  etag: 'W/"1"',
+};
+
+export const CHECKPOINT_CREATED_PAYLOAD: CheckpointCreatedPayloadFixture = {
+  eventId: "evt-cp-1",
+  eventType: "checkpoint.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  checkpoint: FACTORY_CHECKPOINT_RESOURCE,
+};
+
+export const ISSUE_CREATED_PAYLOAD: IssueCreatedPayloadFixture = {
+  eventId: "evt-iss-1",
+  eventType: "issue.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  issue: FACTORY_ISSUE_RESOURCE,
+};

package/src/internal/testing/scm-continuation-fixtures.ts

@@ -0,0 +1,285 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/bdk` into the control plane.
+ */
+
+export interface ScmContinuationFixture {
+  name: string;
+  kind: "gitlab" | "bitbucket";
+  /** Conversation type the channel's `<kind>.<type>/v2` selector names. */
+  type: "gitlab-mr" | "bitbucket-pr";
+  /**
+   * Mailbox event name. Bitbucket Data Center deliveries arrive with their
+   * Cloud-normalized key (`pr:opened` → `pullrequest:created`) next to the
+   * raw DC payload.
+   */
+  eventType: string;
+  payload: Record<string, unknown>;
+  /** `cont:` key, or `undefined` when the delivery stamps `evt:`. */
+  expectedKey: string | undefined;
+}
+
+export interface ScmDefaultSelectorFixture {
+  kind: "gitlab" | "bitbucket";
+  eventTypes: readonly string[];
+  expected: string;
+}
+
+const GITLAB_PROJECT = {
+  id: 1234,
+  name: "api",
+  path_with_namespace: "Acme/platform/api",
+  web_url: "https://gitlab.com/Acme/platform/api",
+  default_branch: "main",
+};
+
+const GITLAB_MERGE_REQUEST = {
+  id: 9001,
+  iid: 42,
+  title: "Add widgets",
+  state: "opened",
+  source_branch: "feature/widgets",
+  target_branch: "main",
+  url: "https://gitlab.com/Acme/platform/api/-/merge_requests/42",
+  last_commit: { id: "0123456789abcdef0123456789abcdef01234567" },
+};
+
+const BITBUCKET_CLOUD_REPOSITORY = {
+  type: "repository",
+  full_name: "acme/widgets",
+  name: "widgets",
+  uuid: "{5f2d1d5e-6d66-4f5b-9d3e-1b6e5b1c2f3a}",
+  workspace: { slug: "acme", uuid: "{a4f1c5d0-1111-4a2b-8c3d-9e0f1a2b3c4d}" },
+  links: { html: { href: "https://bitbucket.org/acme/widgets" } },
+};
+
+const BITBUCKET_DC_REPOSITORY = {
+  slug: "widgets",
+  id: 17,
+  name: "widgets",
+  project: { key: "ACME", id: 3, name: "Acme" },
+};
+
+export const SCM_CONTINUATION_FIXTURES: readonly ScmContinuationFixture[] = [
+  {
+    name: "gitlab merge_request open",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: { ...GITLAB_MERGE_REQUEST, action: "open" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab merge_request update (new commits)",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        ...GITLAB_MERGE_REQUEST,
+        action: "update",
+        oldrev: "fedcba9876543210fedcba9876543210fedcba98",
+      },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 501,
+        note: "Looks good",
+        noteable_type: "MergeRequest",
+        noteable_id: 9001,
+      },
+      merge_request: GITLAB_MERGE_REQUEST,
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on issue",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 502,
+        note: "Tracking",
+        noteable_type: "Issue",
+        noteable_id: 300,
+      },
+      issue: { id: 300, iid: 9, title: "Bug" },
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab pipeline attached to a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 77, status: "success", sha: "0123456789ab" },
+      merge_request: { iid: 42, id: 9001, title: "Add widgets" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab pipeline without a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 78, status: "success", sha: "0123456789ab" },
+      merge_request: null,
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab push",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "push",
+    payload: {
+      object_kind: "push",
+      event_name: "push",
+      ref: "refs/heads/main",
+      project: GITLAB_PROJECT,
+      commits: [],
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "bitbucket cloud pullrequest:created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      pullrequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        source: {
+          branch: { name: "feature/widgets" },
+          commit: { hash: "0123456789ab" },
+        },
+        destination: { branch: { name: "main" }, commit: { hash: "fedcba98" } },
+        links: {
+          html: { href: "https://bitbucket.org/acme/widgets/pull-requests/7" },
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket data center pr:opened (normalized to pullrequest:created)",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      eventKey: "pr:opened",
+      date: "2026-09-01T12:00:00+0000",
+      actor: { name: "alice", displayName: "Alice", id: 1 },
+      pullRequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        open: true,
+        fromRef: {
+          id: "refs/heads/feature/widgets",
+          displayId: "feature/widgets",
+          latestCommit: "0123456789ab",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+        toRef: {
+          id: "refs/heads/main",
+          displayId: "main",
+          latestCommit: "fedcba98",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud pullrequest:comment_created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:comment_created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Bob", uuid: "{u-2}" },
+      pullrequest: { id: 7, title: "Add widgets", state: "OPEN" },
+      comment: { id: 11, content: { raw: "Looks good" } },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud repo:push",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "repo:push",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      push: { changes: [] },
+    },
+    expectedKey: undefined,
+  },
+];
+
+export const SCM_DEFAULT_SELECTOR_FIXTURES: readonly ScmDefaultSelectorFixture[] = [
+  { kind: "gitlab", eventTypes: ["merge_request"], expected: "gitlab.mr/v2" },
+  {
+    kind: "gitlab",
+    eventTypes: ["merge_request", "note"],
+    expected: "gitlab.mr/v2",
+  },
+  {
+    kind: "gitlab",
+    eventTypes: ["merge_request", "push"],
+    expected: "gitlab.none/v2",
+  },
+  {
+    kind: "bitbucket",
+    eventTypes: ["pullrequest:created", "pullrequest:updated"],
+    expected: "bitbucket.pr/v2",
+  },
+  {
+    kind: "bitbucket",
+    eventTypes: ["pullrequest:created", "repo:push"],
+    expected: "bitbucket.none/v2",
+  },
+];

package/src/internal/tool-catalog.ts

@@ -0,0 +1,104 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+
+import type { DiscoveredTool, JsonSchemaObject, ToolEffect, ToolExecution } from "../types.js";
+
+/**
+ * Display names for the well-known tool names that do not come from MCP
+ * (authored tools have no title field; adding one to `defineTool` for a
+ * presentation concern is not worth the authoring surface).
+ */
+const WELL_KNOWN_TOOL_TITLES: Readonly<Record<string, string>> = {
+  Delete: "Delete a file",
+  Diff: "Show change diffs",
+  Glob: "Find files by pattern",
+  Grep: "Search file contents",
+  LS: "List a directory",
+  Read: "Read a file",
+  StrReplace: "Replace text in a file",
+  Write: "Write a file",
+  script: "Run a TypeScript program",
+  search: "Search with a typed query",
+};
+
+function catalogTitle(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised === true) {
+    return tool.annotations?.title;
+  }
+  return WELL_KNOWN_TOOL_TITLES[tool.name];
+}
+
+/**
+ * Sand connector identifiers scope the connector name by owner
+ * (`dashboard-team-<id>-Buildkite`, `dashboard-<Name>`, `user-<Name>`);
+ * the suffix is the human-meaningful name.
+ */
+const CONNECTOR_SCOPE_PREFIX = /^(?:dashboard-team-\d+-|dashboard-|user-)/;
+
+/**
+ * Where a tool comes from, for humans: the upstream connector/plugin name
+ * when the tool declares one (the reserved `__conn__` selector's values
+ * name it), the connection name otherwise. One aggregating connection
+ * (e.g. a tenant `plugins` endpoint) hosts tools from several connectors,
+ * and "plugins" tells an operator nothing — "Buildkite" does.
+ */
+function catalogSource(tool: DiscoveredTool): string | undefined {
+  if (tool.advertised !== true) {
+    return undefined;
+  }
+  const properties = tool.inputSchema.properties as
+    | Record<string, { enum?: unknown[] } | undefined>
+    | undefined;
+  const first = properties?.__conn__?.enum?.[0];
+  if (typeof first === "string" && first !== "") {
+    return first.replace(CONNECTOR_SCOPE_PREFIX, "");
+  }
+  return tool.connection;
+}
+
+/** Light listing entry: identifiers and curated display data only. */
+export interface CatalogListEntry {
+  name: string;
+  title?: string;
+  /** Connection name for advertised MCP tools; absent for authored tools. */
+  source?: string;
+}
+
+/** Full description behind `GET /v1/tools/:name`. */
+export interface CatalogDetailEntry extends CatalogListEntry {
+  description: string;
+  execution: ToolExecution;
+  needsApproval: boolean;
+  effect?: ToolEffect | "dynamic";
+  inputSchema: JsonSchemaObject;
+  outputSchema?: JsonSchemaObject;
+}
+
+export function catalogListEntry(tool: DiscoveredTool): CatalogListEntry {
+  return {
+    name: tool.name,
+    title: catalogTitle(tool),
+    source: catalogSource(tool),
+  };
+}
+
+export function catalogDetailEntry(tool: DiscoveredTool): CatalogDetailEntry {
+  return {
+    ...catalogListEntry(tool),
+    description: tool.description,
+    execution: tool.execution,
+    needsApproval: tool.needsApproval,
+    effect: tool.effect,
+    inputSchema: tool.inputSchema,
+    outputSchema: tool.outputSchema,
+  };
+}