@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/origin/checks.ts

@@ -1,250 +0,0 @@
-/**
- * Origin CI checks — the Origin {@link CiCheckWriter} behind the shared check
- * lifecycle in `../checks.js`.
- *
- * Origin check runs are idempotent upserts keyed by `(repo, head SHA, suite
- * key, check key, externalId)`, so every write re-POSTs the full desired
- * state with a fresh `externalUpdatedAt`, and `resumeOriginCheck` needs only
- * those identity fields (no server id) to rebuild a handle after a restart.
- * The default `externalId` is per execution, so a re-run on the same head
- * posts a new attempt under the same key instead of rewriting the last one.
- *
- * Posting needs `repository:checks:write`: an `oit_…` installation token for
- * app channels, or a deployment service-account session (hosted v2 forks —
- * the `agent-serve` allowlist grants checks:write on team-owned namespaces).
- * See `createOriginClient` in `api.js`. Works with any client exposing
- * `request()` (`ctx.origin`, `createOriginClient()`), and is also reachable
- * as `ctx.origin.createCheck(...)`. API failures throw `OriginApiError`.
- */
-
-import { randomUUID } from "node:crypto";
-import {
-  type CiCheck,
-  type CiCheckConcludeInput,
-  type CiCheckConclusion,
-  type CiCheckCreateInput,
-  type CiCheckOutput,
-  type CiCheckRef,
-  type CiCheckStatus,
-  type CiChecksClient,
-  type CiCheckUpdateInput,
-  type CiCheckWriter,
-  openCiCheck,
-  resumeCiCheck,
-} from "../checks.js";
-import type { OriginApiMethod } from "./api.js";
-
-/** Any client that can call the Origin public REST API. */
-export interface OriginCheckClient {
-  request<T = unknown>(input: {
-    method: OriginApiMethod;
-    path: string;
-    body?: unknown;
-  }): Promise<T>;
-}
-
-export type OriginCheckRunStatus = CiCheckStatus;
-
-/** Origin accepts the shared conclusion set plus `stale`. */
-export type OriginCheckRunConclusion = CiCheckConclusion | "stale";
-
-export type OriginCheckOutput = CiCheckOutput;
-export type OriginCheckUpdateInput = CiCheckUpdateInput<OriginCheckRunConclusion>;
-export type OriginCheckConcludeInput = CiCheckConcludeInput<OriginCheckRunConclusion>;
-
-/** A created check run. All methods throw `OriginApiError` on API failure. */
-export type OriginCheck = CiCheck<OriginCheckRunConclusion> & CiCheckRef;
-
-/** The upsert identity + client an Origin check is bound to. */
-export interface OriginCheckIdentityInput {
-  /** Client used for every API call on the returned handle. */
-  origin: OriginCheckClient;
-  /** Repository owner slug, e.g. `"anysphere"`. */
-  owner: string;
-  /** Repository name, e.g. `"everysphere"`. */
-  repo: string;
-  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
-  name: string;
-  /** Commit the check attaches to (usually the PR head SHA). */
-  sha: string;
-  /**
-   * Stable, app-chosen key identifying the logical check across attempts
-   * (part of the upsert identity). Defaults to a slug of `name`.
-   */
-  key?: string;
-  /** Suite the check belongs to. Defaults to a suite mirroring the check. */
-  suite?: { key?: string; name?: string; detailsUrl?: string };
-  /**
-   * Per-execution component of the default `externalId` (`ctx.origin` seeds
-   * the webhook delivery id). Defaults to a fresh UUID per check.
-   */
-  executionId?: string;
-  /**
-   * Provider-assigned immutable identity for this check attempt. Defaults to
-   * `agent-serve:<suite key>:<key>:<sha>:<executionId>`.
-   */
-  externalId?: string;
-}
-
-// The identity input's `suite` also carries Origin's key and details URL, so
-// the forge-agnostic `suite` label is replaced rather than merged.
-export interface OriginCheckCreateInput
-  extends OriginCheckIdentityInput, Omit<CiCheckCreateInput, "suite"> {}
-
-/**
- * Origin rejects the whole upsert when `output.title` exceeds 255 characters
- * or a body exceeds 65,535 UTF-8 bytes, so the writer caps rather than
- * risking a lost check write.
- */
-const OUTPUT_TITLE_MAX_CHARS = 255;
-const OUTPUT_BODY_MAX_BYTES = 65_000;
-
-/** Truncate to at most `maxBytes` UTF-8 bytes without severing a character. */
-function capUtf8Bytes(text: string, maxBytes: number): string {
-  const encoded = new TextEncoder().encode(text);
-  if (encoded.length <= maxBytes) {
-    return text;
-  }
-  // A non-fatal decode turns a trailing partial character into U+FFFD;
-  // stripping it keeps the result valid (and re-encodable) under the cap.
-  return new TextDecoder("utf-8").decode(encoded.subarray(0, maxBytes)).replace(/\uFFFD+$/, "");
-}
-
-function cappedOutput(output: CiCheckOutput | undefined): Record<string, unknown> | undefined {
-  if (output === undefined) {
-    return undefined;
-  }
-  return {
-    title: output.title.slice(0, OUTPUT_TITLE_MAX_CHARS),
-    summary: capUtf8Bytes(output.summary, OUTPUT_BODY_MAX_BYTES),
-    ...(output.text === undefined
-      ? {}
-      : { text: capUtf8Bytes(output.text, OUTPUT_BODY_MAX_BYTES) }),
-  };
-}
-
-/** Derive a stable check key from a display name, e.g. `cursor-security-review`. */
-export function originCheckKeyFromName(name: string): string {
-  const slug = name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 100);
-  return slug === "" ? "check" : slug;
-}
-
-/**
- * Origin writer: every write is a full keyed upsert. Tracks the last written
- * status so an output-only update cannot regress a running check to queued.
- */
-function originCheckWriter(
-  input: OriginCheckIdentityInput & { status?: CiCheckStatus },
-): CiCheckWriter<OriginCheckRunConclusion> {
-  const key = input.key ?? originCheckKeyFromName(input.name);
-  const suiteKey = input.suite?.key ?? key;
-  const externalId =
-    input.externalId ??
-    `agent-serve:${suiteKey}:${key}:${input.sha}:${input.executionId ?? randomUUID()}`;
-  const path = `/v1/origin/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(
-    input.repo,
-  )}/check-runs`;
-  let lastStatus: CiCheckStatus = input.status ?? "in_progress";
-  return async write => {
-    const status = write.status ?? (write.conclusion === undefined ? lastStatus : "completed");
-    lastStatus = status;
-    const response = await input.origin.request<{
-      checkRun?: { id?: unknown };
-    }>({
-      method: "POST",
-      path,
-      body: {
-        headSha: input.sha,
-        checkSuite: {
-          key: suiteKey,
-          name: input.suite?.name ?? input.name,
-          externalId: `agent-serve:${suiteKey}`,
-          ...(input.suite?.detailsUrl === undefined ? {} : { detailsUrl: input.suite.detailsUrl }),
-        },
-        checkRun: {
-          key,
-          name: input.name,
-          status,
-          conclusion: write.conclusion,
-          // Origin only applies an upsert when this timestamp is at least as
-          // new as the stored check; timestamp every write when it is built.
-          externalUpdatedAt: new Date().toISOString(),
-          externalId,
-          startedAt: write.startedAt,
-          completedAt: write.completedAt,
-          detailsUrl: write.detailsUrl,
-          output: cappedOutput(write.output),
-        },
-      },
-    });
-    const id = response?.checkRun?.id;
-    return typeof id === "string" ? { id } : undefined;
-  };
-}
-
-/**
- * Create a CI check run on a commit and return a handle for later updates.
- *
- * ```ts
- * const check = await createOriginCheck({
- *   origin: ctx.origin,
- *   owner: ctx.repository.owner,
- *   repo: ctx.repository.name,
- *   name: "Cursor Security Review",
- *   sha: pr.headSha,
- *   detailsUrl: sessionUrl,
- *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
- * });
- * // …do the work…
- * await check.conclude({ conclusion: "success", output: { … } });
- * ```
- */
-export function createOriginCheck(input: OriginCheckCreateInput): Promise<OriginCheck> {
-  return openCiCheck(originCheckWriter(input), input);
-}
-
-/**
- * Rebuild an {@link OriginCheck} handle for an existing check run (e.g.
- * after a process restart) from its upsert identity, including the
- * `executionId` (or explicit `externalId`) it was created with — no server
- * id needed. No API call is made until the first update.
- */
-export function resumeOriginCheck(
-  input: OriginCheckIdentityInput &
-    ({ executionId: string } | { externalId: string }) & {
-      /** Last known status; defaults to `"in_progress"`. */
-      status?: CiCheckStatus;
-      /** Server-assigned id (`cr_…`) when known. */
-      id?: string;
-    },
-): OriginCheck {
-  return resumeCiCheck(
-    originCheckWriter(input),
-    input.id === undefined ? undefined : { id: input.id },
-  );
-}
-
-/**
- * Repo-bound checks adapter satisfying the shared {@link CiChecksClient}
- * contract — hand it to forge-agnostic check code when there is no channel
- * `ctx.origin` (e.g. CI entrypoints).
- */
-export function bindOriginChecks(input: {
-  origin: OriginCheckClient;
-  owner: string;
-  repo: string;
-}): CiChecksClient<OriginCheckRunConclusion> {
-  return {
-    createCheck: check =>
-      createOriginCheck({
-        ...check,
-        origin: input.origin,
-        owner: input.owner,
-        repo: input.repo,
-      }),
-  };
-}

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

@@ -1,58 +0,0 @@
-/**
- * Cursor-account mode for Origin channels.
- *
- * Origin identity is the signed-in Cursor user (no third-party OAuth). The
- * channel declares repos at definition time; the serve host subscribes
- * `/v0/scm-events` with `provider: "origin"` as that user. Outbound Origin
- * API calls authenticate with the channel's app credentials when configured;
- * hosted v2 deployments instead exchange the Cursor credential for a
- * session (`cursorSessionTokenProvider` in ./api.ts), so reads and writes
- * both run as the deployment service-account principal.
- */
-
-import type { OriginChannelOptions } from "./types.js";
-
-export const CURSOR_ORIGIN_MAX_REPOS = 20;
-const CURSOR_ORIGIN_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-
-export interface CursorOriginRepoScope {
-  repos: readonly string[];
-}
-
-export interface OriginCursorAccountRuntime {
-  options: OriginChannelOptions;
-  scope: CursorOriginRepoScope | undefined;
-}
-
-const runtimeByDefinition = new WeakMap<object, OriginCursorAccountRuntime>();
-
-export function parseCursorOriginRepoScope(values: readonly string[]): CursorOriginRepoScope {
-  const repos = [...new Set(values.map(repo => repo.trim().toLowerCase()).filter(Boolean))];
-  if (repos.length === 0) {
-    throw new Error("originChannel({ cursorAccount }) requires at least one repository.");
-  }
-  if (repos.length > CURSOR_ORIGIN_MAX_REPOS) {
-    throw new Error(
-      `originChannel({ cursorAccount }) supports at most ${CURSOR_ORIGIN_MAX_REPOS} repositories.`,
-    );
-  }
-  for (const repo of repos) {
-    if (!CURSOR_ORIGIN_REPO_PATTERN.test(repo) || repo.includes("..")) {
-      throw new Error(`Invalid Origin repository "${repo}"; expected owner/repo.`);
-    }
-  }
-  return { repos };
-}
-
-export function registerOriginCursorAccountRuntime(
-  definition: object,
-  runtime: OriginCursorAccountRuntime,
-): void {
-  runtimeByDefinition.set(definition, runtime);
-}
-
-export function getOriginCursorAccountRuntime(
-  definition: object,
-): OriginCursorAccountRuntime | undefined {
-  return runtimeByDefinition.get(definition);
-}

package/src/channels/origin/defaults.ts

@@ -1,140 +0,0 @@
-/**
- * Default stream-event handlers for the Origin channel: reply delivery.
- *
- * The GitHub channel posts completed assistant messages back to the PR via
- * `buildDefaultGitHubEvents`; this is the Origin analogue. Outbound
- * credentials resolve exactly like `ctx.origin` in hooks (see
- * ./binding.ts): channel app credentials / `ORIGIN_APP_*` env when
- * configured, otherwise — for `cursorAccount` channels — the Cursor-account
- * session exchange, which on hosted v2 acts as the deployment
- * service-account principal. The `agent-serve` SA scope allowlist includes
- * `repository:pull_requests:reviews:write`, the scope
- * `CreatePullRequestComment` checks, so no extra grant is needed.
- */
-
-import type { ChannelEventHandlers } from "../../types.js";
-import { buildOriginBinding, type OriginHandle } from "./binding.js";
-import type { OriginChannelState } from "./state.js";
-import type { OriginAppOptions } from "./types.js";
-
-/** Hidden marker on outbound Origin comments so consumers can spot them. */
-export const ORIGIN_OUTBOUND_MARKER = "<!-- agent-serve-origin -->";
-
-export function formatOriginOutboundComment(body: string): string {
-  if (body.includes(ORIGIN_OUTBOUND_MARKER)) {
-    return body;
-  }
-  return `${body.trimEnd()}\n\n${ORIGIN_OUTBOUND_MARKER}`;
-}
-
-export interface BuildDefaultOriginEventsOptions {
-  /** Force the signed-in Cursor account / deployment SA credential path. */
-  cursorAccount?: boolean | { repos: readonly string[] };
-  /** Channel-authored outbound app credentials / API base. */
-  app?: OriginAppOptions;
-  /**
-   * When false, skip posting completed assistant messages (and failure
-   * notices) back to the Origin pull request. Defaults to true.
-   */
-  deliverReplies?: boolean;
-  /** Injectable binding builder for tests. */
-  buildBinding?: typeof buildOriginBinding;
-}
-
-function bindingForState(
-  options: BuildDefaultOriginEventsOptions,
-  state: OriginChannelState,
-): OriginHandle {
-  const build = options.buildBinding ?? buildOriginBinding;
-  return build({
-    repository: {
-      owner: state.owner,
-      name: state.repo,
-      fullName: `${state.owner}/${state.repo}`,
-    },
-    ...(state.installationId === null ? {} : { installationId: state.installationId }),
-    cursorAccount: options.cursorAccount !== undefined && options.cursorAccount !== false,
-    app: options.app,
-  });
-}
-
-async function postPullRequestComment(
-  options: BuildDefaultOriginEventsOptions,
-  state: OriginChannelState,
-  body: string,
-): Promise<void> {
-  if (state.owner === "" || state.repo === "" || state.pullRequestNumber === null) {
-    return;
-  }
-  const origin = bindingForState(options, state);
-  await origin.request({
-    method: "POST",
-    path: `/v1/origin/repos/${encodeURIComponent(state.owner)}/${encodeURIComponent(
-      state.repo,
-    )}/pulls/${state.pullRequestNumber}/comments`,
-    body: { body: formatOriginOutboundComment(body) },
-  });
-}
-
-/**
- * Built-in delivery: post assistant text on `message.completed`, and a
- * short error comment on turn/session failure. Every post soft-fails so a
- * missing outbound credential (or an Origin refusal) never crashes the
- * session — the GitHub defaults' posture.
- */
-export function buildDefaultOriginEvents(
-  options: BuildDefaultOriginEventsOptions = {},
-): ChannelEventHandlers<OriginChannelState> {
-  const deliverReplies = options.deliverReplies !== false;
-
-  return {
-    async "message.completed"(event, channel) {
-      if (!deliverReplies) {
-        return;
-      }
-      if (
-        event.data.parentCallId !== undefined ||
-        event.data.finishReason === "tool_call" ||
-        event.data.text === ""
-      ) {
-        return;
-      }
-      try {
-        await postPullRequestComment(options, channel.state, event.data.text);
-      } catch {
-        // Soft-fail delivery so a missing credential does not crash the session.
-      }
-    },
-
-    async "turn.failed"(_event, channel) {
-      await postFailure(options, channel, deliverReplies);
-    },
-
-    async "session.failed"(_event, channel) {
-      await postFailure(options, channel, deliverReplies);
-    },
-  };
-}
-
-async function postFailure(
-  options: BuildDefaultOriginEventsOptions,
-  channel: { state: OriginChannelState },
-  deliverReplies: boolean,
-): Promise<void> {
-  if (!deliverReplies) {
-    return;
-  }
-  try {
-    await postPullRequestComment(
-      options,
-      channel.state,
-      [
-        "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/origin/events.ts

@@ -1,35 +0,0 @@
-/** {@link ChannelMeta.kind} value used by {@link originChannel}. */
-export const ORIGIN_CHANNEL_KIND = "origin";
-
-const BASE_WEBHOOK_EVENTS: readonly string[] = [
-  "pull_request.created",
-  "pull_request.published",
-  "pull_request.head_ref.pushed",
-  "pull_request.base_ref.updated",
-  "pull_request.closed",
-  "pull_request.merged",
-];
-
-const COMMENT_EVENTS: readonly string[] = ["pull_request.comment.created"];
-const REVIEW_EVENTS: readonly string[] = ["pull_request.review.submitted"];
-
-export interface OriginWebhookEventOptions {
-  webhookEvents?: readonly string[];
-  onComment?: unknown;
-  onReview?: unknown;
-  onEvent?: unknown;
-}
-
-export function deriveOriginWebhookEvents(options: OriginWebhookEventOptions): string[] {
-  if (options.webhookEvents !== undefined) {
-    return [...new Set(options.webhookEvents.map(event => event.trim()).filter(Boolean))];
-  }
-  const events: string[] = [...BASE_WEBHOOK_EVENTS];
-  if (options.onComment !== undefined) {
-    events.push(...COMMENT_EVENTS);
-  }
-  if (options.onReview !== undefined) {
-    events.push(...REVIEW_EVENTS);
-  }
-  return [...new Set(events)];
-}

package/src/channels/origin/index.ts

@@ -1,35 +0,0 @@
-/**
- * Origin webhook channel pack for agent-serve.
- *
- * ```ts
- * import { defaultOriginAuth, originChannel } from "@cursor/bdk/channels/origin";
- *
- * export default originChannel({
- *   cursorAccount: { repos: ["owner/repo"] },
- *   onPullRequest: (ctx) => ({ auth: defaultOriginAuth(ctx) }),
- *   onComment: (ctx) => ({ auth: defaultOriginAuth(ctx) }),
- * });
- * ```
- *
- * Direct webhook mode verifies Standard-Webhooks v1ed signatures **and**
- * binds `envelope.appId` to {@link OriginChannelOptions.appId} (or
- * `AGENT_SERVE_ORIGIN_APP_ID`). v1ed alone is not channel auth — Origin
- * signs every app's deliveries with the same JWKS. Pass
- * `{ cursorAccount: true }` to receive events from
- * `serve({ cursor: { events: true } })` after `/v0/scm-events`
- * (`provider: "origin"`) already verified them. The turn principal is
- * `origin-webhook` plus the Origin actor — not the Cursor subscriber —
- * matching GitHub's `github-webhook` pattern.
- */
-
-export * from "./api.js";
-export * from "./binding.js";
-export * from "./checks.js";
-export * from "./cursor-account.js";
-export * from "./defaults.js";
-export * from "./events.js";
-export * from "./origin-channel.js";
-export * from "./origin-webhook.js";
-export * from "./reactions.js";
-export * from "./state.js";
-export * from "./types.js";