@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/github/cursor-account.ts

@@ -1,303 +0,0 @@
-/**
- * Cursor-account mode for GitHub channels.
- *
- * The channel declares the intent at definition time. The serve host binds
- * this placeholder to its signed-in Cursor account after it resolves the
- * repository scope into private runtime metadata (never by rewriting the
- * authored `cursorAccount` options object).
- */
-
-import type { GitHubChannelOptions } from "./types.js";
-
-export const CURSOR_GITHUB_MAX_REPOS = 20;
-const CURSOR_GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const cursorAccountTokenResolvers = new WeakSet<object>();
-
-/** Least → most privilege. Host mints one lease at the max requested tier. */
-export const CURSOR_GITHUB_PERMISSIONS = ["read", "pr-write", "contents-write"] as const;
-
-export type CursorGithubPermissions = (typeof CURSOR_GITHUB_PERMISSIONS)[number];
-
-export interface CursorGithubRepoScope {
-  owner: string;
-  repos: readonly string[];
-  permissions: CursorGithubPermissions;
-}
-
-export type CursorAccountGithubTokenResolver = () => Promise<string>;
-
-/**
- * Backend GitHub-proxy transport bound by the serve host. When set, the
- * channel Octokit targets the proxy `apiBaseUrl` and attaches the scope
- * `headers`; the bound token is the host's Cursor API key, and the raw
- * installation token never reaches this process.
- */
-export interface CursorGithubProxyTransport {
-  apiBaseUrl: string;
-  headers: Readonly<Record<string, string>>;
-}
-
-export interface PendingCursorGithubCredentials {
-  bind(getToken: () => Promise<string>): void;
-  getToken(): Promise<string>;
-  bindProxyTransport(transport: CursorGithubProxyTransport): void;
-  getProxyTransport(): CursorGithubProxyTransport | undefined;
-}
-
-export interface GithubCursorAccountRuntime {
-  /** Authored channel options (not rewritten). */
-  options: GitHubChannelOptions;
-  credentials: PendingCursorGithubCredentials;
-  /**
-   * Normalized repo + permissions scope when `cursorAccount` is an object.
-   * Absent for `cursorAccount: true` (scope comes from serve `--repo`).
-   */
-  scope: CursorGithubRepoScope | undefined;
-}
-
-const runtimeByDefinition = new WeakMap<object, GithubCursorAccountRuntime>();
-
-export function parseCursorGithubPermissions(
-  value: unknown,
-  fallback: CursorGithubPermissions = "pr-write",
-): CursorGithubPermissions {
-  if (value === undefined) {
-    return fallback;
-  }
-  if (value === "read" || value === "pr-write" || value === "contents-write") {
-    return value;
-  }
-  throw new Error(
-    'Cursor account GitHub permissions must be "read", "pr-write", or "contents-write".',
-  );
-}
-
-/**
- * `owner/repo` from an Octokit request, for github-proxy calls that have no
- * static `x-cursor-github-repos` header (`cursorAccount: true` with no
- * `--repo` / channel `{ repos }`).
- */
-export function githubRepoFromOctokitRequest(request: {
-  owner?: unknown;
-  repo?: unknown;
-  url?: unknown;
-}): string | undefined {
-  if (typeof request.owner === "string" && typeof request.repo === "string") {
-    const slug = `${request.owner.trim()}/${request.repo.trim()}`.toLowerCase();
-    if (CURSOR_GITHUB_REPO_PATTERN.test(slug) && !slug.includes("..")) {
-      return slug;
-    }
-  }
-  if (typeof request.url !== "string") {
-    return undefined;
-  }
-  const match = request.url.match(/\/repos\/([^/?#]+)\/([^/?#]+)/);
-  const owner = match?.[1]?.trim() ?? "";
-  const repo = match?.[2]?.trim() ?? "";
-  if (owner === "" || repo === "" || owner.includes("{") || repo.includes("{")) {
-    return undefined;
-  }
-  const slug = `${owner}/${repo}`.toLowerCase();
-  if (!CURSOR_GITHUB_REPO_PATTERN.test(slug) || slug.includes("..")) {
-    return undefined;
-  }
-  return slug;
-}
-
-/**
- * Merge `--repo` / channel-declared repos into a lease scope. Empty is
- * valid for `cursorAccount: true`: hosted engines that pull events from
- * the deployment stream (no `--cursor-events --repo`) still start, and
- * github-proxy fills `x-cursor-github-repos` per Octokit call.
- */
-export function resolveCursorGithubCredentialScope(
-  values: readonly string[],
-  permissions: CursorGithubPermissions = "pr-write",
-): CursorGithubRepoScope | undefined {
-  const repos = [...new Set(values.map(repo => repo.trim().toLowerCase()).filter(Boolean))];
-  if (repos.length === 0) {
-    return undefined;
-  }
-  return parseCursorGithubRepoScope(repos, permissions);
-}
-
-export function parseCursorGithubRepoScope(
-  values: readonly string[],
-  permissions: CursorGithubPermissions = "pr-write",
-): CursorGithubRepoScope {
-  const repos = [...new Set(values.map(repo => repo.trim().toLowerCase()).filter(Boolean))];
-  if (repos.length === 0) {
-    throw new Error("Cursor account GitHub credentials require at least one repository.");
-  }
-  if (repos.length > CURSOR_GITHUB_MAX_REPOS) {
-    throw new Error(
-      `Cursor account GitHub credentials support at most ${CURSOR_GITHUB_MAX_REPOS} repositories.`,
-    );
-  }
-  for (const repo of repos) {
-    if (!CURSOR_GITHUB_REPO_PATTERN.test(repo) || repo.includes("..")) {
-      throw new Error(`Invalid Cursor account GitHub repository "${repo}"; expected owner/repo.`);
-    }
-  }
-  const owner = repos[0]?.split("/", 1)[0];
-  if (owner === undefined) {
-    throw new Error("Cursor account GitHub repository owner is missing.");
-  }
-  if (repos.some(repo => repo.split("/", 1)[0] !== owner)) {
-    throw new Error(
-      "Cursor account GitHub repositories must share one owner for a single installation token.",
-    );
-  }
-  return {
-    owner,
-    repos,
-    permissions: parseCursorGithubPermissions(permissions),
-  };
-}
-
-/**
- * Hosted `cursorAccount` mints `checks:write` on the `contents-write` tier.
- * Enabling `progress.commitStatus` or `checks: true` opts a `pr-write` (or
- * omitted) channel up to that tier so github-proxy / `/github-token` can
- * post Checks API runs. `"read"` cannot post merge-box checks.
- */
-export function cursorGithubPermissionsForChannel(
-  options: Pick<GitHubChannelOptions, "progress" | "checks">,
-  authored: CursorGithubPermissions | undefined = "pr-write",
-): CursorGithubPermissions {
-  const base = authored ?? "pr-write";
-  const commitStatus = options.progress?.commitStatus;
-  const wantsChecks =
-    options.checks === true || (commitStatus !== undefined && commitStatus !== false);
-  if (!wantsChecks) {
-    return base;
-  }
-  if (base === "read") {
-    throw new Error(
-      'progress.commitStatus / checks need checks:write; cursorAccount permissions: "read" cannot post merge-box checks. Use "pr-write" or "contents-write".',
-    );
-  }
-  return "contents-write";
-}
-
-/** One host credential: the most privileged requested tier wins. */
-export function resolveCursorGithubPermissions(
-  values: readonly CursorGithubPermissions[],
-): CursorGithubPermissions {
-  let max: CursorGithubPermissions = "read";
-  for (const value of values) {
-    if (CURSOR_GITHUB_PERMISSIONS.indexOf(value) > CURSOR_GITHUB_PERMISSIONS.indexOf(max)) {
-      max = value;
-    }
-  }
-  return values.length === 0 ? "pr-write" : max;
-}
-
-export function createCursorAccountGithubTokenResolver(
-  getToken: () => Promise<string>,
-  pending?: PendingCursorGithubCredentials,
-): CursorAccountGithubTokenResolver {
-  const resolver = () => getToken();
-  cursorAccountTokenResolvers.add(resolver);
-  if (pending !== undefined) {
-    pendingByResolver.set(resolver, pending);
-  }
-  return resolver;
-}
-
-/**
- * Token resolver for `ctx.host.github` in proxy mode with no startup token
- * mint (empty repo scope): resolves the Cursor API key and carries the
- * proxy transport so `createGitHubOctokit` targets github-proxy and fills
- * `x-cursor-github-repos` per request — the same route channel Octokit
- * calls take.
- */
-export function createCursorGithubProxyHostResolver(input: {
-  getApiKey: () => Promise<string>;
-  transport: CursorGithubProxyTransport;
-}): CursorAccountGithubTokenResolver {
-  const credentials = createPendingCursorGithubCredentials();
-  credentials.bind(input.getApiKey);
-  credentials.bindProxyTransport(input.transport);
-  return createCursorAccountGithubTokenResolver(() => credentials.getToken(), credentials);
-}
-
-/** Proxy transport for a resolver's credentials, when the host bound one. */
-export function getCursorAccountGithubProxyTransport(
-  resolver: CursorAccountGithubTokenResolver,
-): CursorGithubProxyTransport | undefined {
-  return pendingByResolver.get(resolver)?.getProxyTransport();
-}
-
-const pendingByResolver = new WeakMap<
-  CursorAccountGithubTokenResolver,
-  PendingCursorGithubCredentials
->();
-
-/** Forges whose cursorAccount packs route through the backend SCM forwarder. */
-export type CursorScmProxyForge = "github" | "gitlab" | "bitbucket";
-
-/**
- * Backend SCM-proxy base URL for proxy mode (`--cursor-scm-proxy`). Each
- * pack derives its own route, `/v0/<forge>-proxy`, from the Cursor API
- * base URL; `AGENT_SERVE_<FORGE>_PROXY_URL` overrides it.
- */
-export function resolveCursorScmProxyUrl(
-  forge: CursorScmProxyForge,
-  backendBaseUrl: string,
-): string {
-  const override = process.env[`AGENT_SERVE_${forge.toUpperCase()}_PROXY_URL`];
-  const url =
-    override !== undefined && override.trim() !== ""
-      ? new URL(override)
-      : new URL(`/v0/${forge}-proxy`, backendBaseUrl);
-  return url.toString().replace(/\/+$/, "");
-}
-
-/** GitHub-proxy base URL; see {@link resolveCursorScmProxyUrl}. */
-export function resolveCursorGithubProxyUrl(backendBaseUrl: string): string {
-  return resolveCursorScmProxyUrl("github", backendBaseUrl);
-}
-
-export function isCursorAccountGithubTokenResolver(
-  value: unknown,
-): value is CursorAccountGithubTokenResolver {
-  return typeof value === "function" && cursorAccountTokenResolvers.has(value);
-}
-
-export function createPendingCursorGithubCredentials(): PendingCursorGithubCredentials {
-  let getBoundToken: (() => Promise<string>) | undefined;
-  let proxyTransport: CursorGithubProxyTransport | undefined;
-  return {
-    bind(getToken) {
-      getBoundToken = getToken;
-    },
-    getToken() {
-      if (getBoundToken === undefined) {
-        throw new Error(
-          "githubChannel({ cursorAccount: true }) has not been bound to a signed-in Cursor host.",
-        );
-      }
-      return getBoundToken();
-    },
-    bindProxyTransport(transport) {
-      proxyTransport = transport;
-    },
-    getProxyTransport() {
-      return proxyTransport;
-    },
-  };
-}
-
-export function registerGithubCursorAccountRuntime(
-  definition: object,
-  runtime: GithubCursorAccountRuntime,
-): void {
-  runtimeByDefinition.set(definition, runtime);
-}
-
-export function getGithubCursorAccountRuntime(
-  definition: object,
-): GithubCursorAccountRuntime | undefined {
-  return runtimeByDefinition.get(definition);
-}

package/src/channels/github/defaults.ts

@@ -1,168 +0,0 @@
-/**
- * Default stream-event handlers for the GitHub channel.
- */
-
-import type { ChannelEventHandlers } from "../../types.js";
-import type { GitHubBindingConfig } from "./binding.js";
-import { buildGitHubBinding, formatGitHubOutboundComment } from "./binding.js";
-import { applyGitHubProgress, type GitHubProgressConfig } from "./progress.js";
-import type { GitHubChannelState } from "./state.js";
-
-export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
-  botName?: string;
-  progress?: GitHubProgressConfig;
-  /**
-   * When false, skip posting completed assistant messages back to GitHub.
-   * Defaults to true.
-   */
-  deliverReplies?: boolean;
-}
-
-/**
- * Built-in delivery: eyes reaction on turn start, optional Checks API run /
- * sticky banner via {@link GitHubProgressConfig}, post assistant text on
- * `message.completed`, and a short error comment on turn/session failure.
- */
-export function buildDefaultGitHubEvents(
-  options: BuildDefaultGitHubEventsOptions = {},
-): ChannelEventHandlers<GitHubChannelState> {
-  const deliverReplies = options.deliverReplies !== false;
-  const requiredSuccessfulTools = new Set(
-    options.progress?.requireSuccessfulTools
-      ?.map(toolName => toolName.trim())
-      .filter(toolName => toolName !== "") ?? [],
-  );
-  const toolOutcomesBySession = new Map<string, Map<string, boolean>>();
-
-  return {
-    async "turn.started"(event, channel) {
-      if (requiredSuccessfulTools.size > 0) {
-        toolOutcomesBySession.set(event.sessionId, new Map());
-      }
-      await applyGitHubProgress({
-        phase: "pending",
-        sessionId: event.sessionId,
-        channel,
-        options,
-      });
-      if (options.progress?.reactions === false) {
-        return;
-      }
-      if (channel.state.owner === "" || channel.state.repo === "") {
-        return;
-      }
-      try {
-        const { thread } = buildGitHubBinding({
-          config: options,
-          state: channel.state,
-        });
-        await thread.react("eyes");
-      } catch {
-        // Soft-fail: missing token / no triggering comment is fine.
-      }
-    },
-
-    async "action.result"(event) {
-      if (
-        event.data.parentCallId !== undefined ||
-        !requiredSuccessfulTools.has(event.data.toolName)
-      ) {
-        return;
-      }
-      const outcomes = toolOutcomesBySession.get(event.sessionId) ?? new Map();
-      outcomes.set(event.data.toolName, !event.data.isError && event.data.stubbed !== true);
-      toolOutcomesBySession.set(event.sessionId, outcomes);
-    },
-
-    async "turn.completed"(event, channel) {
-      const outcomes = toolOutcomesBySession.get(event.sessionId);
-      const pipelineSucceeded =
-        requiredSuccessfulTools.size === 0 ||
-        [...requiredSuccessfulTools].every(toolName => outcomes?.get(toolName) === true);
-      toolOutcomesBySession.delete(event.sessionId);
-      await applyGitHubProgress({
-        phase: pipelineSucceeded ? "success" : "failure",
-        sessionId: event.sessionId,
-        channel,
-        options,
-      });
-    },
-
-    async "message.completed"(event, channel) {
-      if (!deliverReplies) {
-        return;
-      }
-      if (
-        event.data.parentCallId !== undefined ||
-        event.data.finishReason === "tool_call" ||
-        event.data.text === ""
-      ) {
-        return;
-      }
-      if (channel.state.owner === "" || channel.state.repo === "") {
-        return;
-      }
-      try {
-        const { thread } = buildGitHubBinding({
-          config: options,
-          state: channel.state,
-        });
-        await thread.post(formatGitHubOutboundComment(event.data.text));
-      } catch {
-        // Soft-fail delivery so a missing token does not crash the session.
-      }
-    },
-
-    async "turn.failed"(event, channel) {
-      toolOutcomesBySession.delete(event.sessionId);
-      await applyGitHubProgress({
-        phase: "failure",
-        sessionId: event.sessionId,
-        channel,
-        options,
-      });
-      await postFailure(channel, options, event.data.message);
-    },
-
-    async "session.failed"(event, channel) {
-      toolOutcomesBySession.delete(event.sessionId);
-      await applyGitHubProgress({
-        phase: "failure",
-        sessionId: event.sessionId,
-        channel,
-        options,
-      });
-      await postFailure(channel, options, event.data.message);
-    },
-  };
-}
-
-async function postFailure(
-  channel: { state: GitHubChannelState },
-  options: BuildDefaultGitHubEventsOptions,
-  _error: string,
-): Promise<void> {
-  if (options.deliverReplies === false) {
-    return;
-  }
-  if (channel.state.owner === "" || channel.state.repo === "") {
-    return;
-  }
-  try {
-    const { thread } = buildGitHubBinding({
-      config: options,
-      state: channel.state,
-    });
-    await thread.post(
-      formatGitHubOutboundComment(
-        [
-          "I hit an error while handling your request.",
-          "",
-          "Please try again, or reach out if it keeps failing.",
-        ].join("\n"),
-      ),
-    );
-  } catch {
-    // Soft-fail.
-  }
-}

package/src/channels/github/events.ts

@@ -1,67 +0,0 @@
-/**
- * Webhook event derivation for the GitHub channel.
- *
- * `agent-sdk github forward` reads the set of webhook events a channel is
- * wired to dispatch (published as `meta.githubWebhookEvents`) so it can build
- * `gh webhook forward --events=…` without the operator hand-listing them.
- */
-
-import type { GitHubChannelOptions } from "./types.js";
-
-/** {@link ChannelMeta.kind} value used by {@link githubChannel}. */
-export const GITHUB_CHANNEL_KIND = "github";
-
-/**
- * Events the channel always parses through its built-in defaults: the
- * `pull_request` gate and the `@mention` comment gates exist even when no
- * hook is declared.
- */
-const BASE_WEBHOOK_EVENTS: readonly string[] = [
-  "pull_request",
-  "issue_comment",
-  "pull_request_review_comment",
-];
-
-/** Typed opt-in hooks and the webhook event each subscribes to. */
-const OPT_IN_HOOK_EVENTS: ReadonlyArray<{
-  option: keyof GitHubChannelOptions;
-  event: string;
-}> = [
-  { option: "onIssue", event: "issues" },
-  { option: "onCheckSuite", event: "check_suite" },
-  { option: "onCheckRun", event: "check_run" },
-  { option: "onWorkflowRun", event: "workflow_run" },
-  { option: "onStatus", event: "status" },
-];
-
-/**
- * Common events that only reach the `onEvent` catch-all (no typed hook). When
- * `onEvent` is declared we forward these too so review activity is delivered.
- */
-const CATCH_ALL_EVENTS: readonly string[] = ["pull_request_review", "pull_request_review_thread"];
-
-/**
- * Derive the webhook events a {@link githubChannel} dispatches on from its
- * declared hooks. When {@link GitHubChannelOptions.webhookEvents} is set it is
- * authoritative and returned verbatim (deduped, order preserved) — use it to
- * pin an exact list (e.g. to add events only handled via `onEvent`).
- */
-export function deriveGitHubWebhookEvents(options: GitHubChannelOptions): string[] {
-  if (options.webhookEvents !== undefined) {
-    return dedupe(options.webhookEvents);
-  }
-  const events: string[] = [...BASE_WEBHOOK_EVENTS];
-  for (const { option, event } of OPT_IN_HOOK_EVENTS) {
-    if (options[option] !== undefined) {
-      events.push(event);
-    }
-  }
-  if (options.onEvent !== undefined) {
-    events.push(...CATCH_ALL_EVENTS);
-  }
-  return dedupe(events);
-}
-
-function dedupe(events: readonly string[]): string[] {
-  return [...new Set(events.map(event => event.trim()).filter(Boolean))];
-}