@cursor/bdk 0.2.3 → 0.2.4

package/src/channels/github/types.ts

@@ -1,590 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type {
-  AgentCloudOptions,
-  ArtifactsApi,
-  AuthContext,
-  AuthPolicy,
-  ChannelEventHandlers,
-  ChannelStartArgs,
-  HostContext,
-  JsonObject,
-  SendMessageFn,
-  SendMessageOptions,
-} from "../../types.js";
-import type { GitHubApiOptions } from "./api.js";
-import type { GitHubHandle, GitHubThread } from "./binding.js";
-import type { GitHubProgressConfig } from "./progress.js";
-import type { GitHubChannelState } from "./state.js";
-
-/** A credential value: a literal or a lazy resolver fetched on demand. */
-export type GitHubCredentialValue =
-  | string
-  | (() => string | undefined | Promise<string | undefined>);
-
-/**
- * GitHub webhook + API credentials. Every field falls back to an env var
- * (or `gh auth token` for API calls), so you can drop the `credentials`
- * block entirely once these are set:
- *
- * ```bash
- * GITHUB_WEBHOOK_SECRET=...        # verifies the webhook signature
- * GITHUB_APP_ID=...                # App JWT path (preferred in production)
- * GITHUB_APP_PRIVATE_KEY=...
- * GITHUB_APP_INSTALLATION_ID=...   # host / non-webhook App auth
- * GITHUB_APP_SLUG=...              # supplies botName when it is not set in config
- * GITHUB_TOKEN=...                 # local PAT fallback (or GH_TOKEN / `gh auth`)
- * ```
- *
- * API auth prefers App installation tokens when App credentials are set,
- * then falls back to `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token` for local
- * testing.
- */
-export interface GitHubChannelCredentials {
-  /**
-   * Webhook secret used to verify `X-Hub-Signature-256` before parsing the
-   * payload. Falls back to `GITHUB_WEBHOOK_SECRET`.
-   */
-  webhookSecret?: GitHubCredentialValue;
-  /**
-   * Explicit bearer token for GitHub REST calls. Prefer this only when you
-   * intentionally override ambient auth (e.g. tests). Falls back to App
-   * installation tokens, then `GITHUB_TOKEN` / `GH_TOKEN` / `gh auth token`.
-   */
-  token?: GitHubCredentialValue;
-  /**
-   * Pre-resolved installation access token (Connect-style). Same effect as
-   * {@link token} for API calls; skips App JWT exchange.
-   */
-  installationToken?: GitHubCredentialValue;
-  /** GitHub App id for installation-token minting. Falls back to `GITHUB_APP_ID`. */
-  appId?: GitHubCredentialValue | number;
-  /** GitHub App private key (PEM). Falls back to `GITHUB_APP_PRIVATE_KEY`. */
-  privateKey?: GitHubCredentialValue;
-}
-
-export type GitHubPullRequestAction =
-  | "opened"
-  | "reopened"
-  | "synchronize"
-  | "ready_for_review"
-  | "edited"
-  | "closed"
-  | "labeled"
-  | "unlabeled"
-  | "assigned"
-  | "unassigned"
-  | "review_requested"
-  | "review_request_removed"
-  | "converted_to_draft";
-
-export type GitHubIssueAction =
-  | "opened"
-  | "edited"
-  | "closed"
-  | "reopened"
-  | "labeled"
-  | "unlabeled"
-  | "assigned"
-  | "unassigned";
-
-export type GitHubConversationKind = "issue" | "pull_request" | "review_thread";
-
-export type GitHubCiAction = "created" | "completed" | "rerequested" | "requested_action";
-
-export type GitHubCiConclusion =
-  | "success"
-  | "failure"
-  | "neutral"
-  | "cancelled"
-  | "timed_out"
-  | "action_required"
-  | "stale"
-  | "skipped"
-  | null;
-
-export type GitHubCiStatus =
-  | "queued"
-  | "in_progress"
-  | "completed"
-  | "waiting"
-  | "requested"
-  | "pending"
-  | string;
-
-/** Normalized actor on a delivery. */
-export interface GitHubUser {
-  login: string;
-  id?: number;
-  type?: "User" | "Bot" | "Organization" | string;
-}
-
-/** Normalized repository on a delivery. */
-export interface GitHubRepositoryRef {
-  fullName: string;
-  url: string;
-  owner: string;
-  name: string;
-  id?: number;
-}
-
-/**
- * Wire shape of the `pull_request` webhook payload, narrowed to the fields
- * the channel consumes.
- */
-export type GitHubPullRequestPayload = {
-  action: string;
-  repository: {
-    id?: number;
-    full_name: string;
-    html_url: string;
-    name?: string;
-    owner?: { login?: string };
-  };
-  pull_request: {
-    number: number;
-    html_url: string;
-    title: string;
-    body?: string | null;
-    draft?: boolean;
-    /** Present on real webhook payloads; false/undefined when not merged. */
-    merged?: boolean;
-    user?: {
-      login?: string;
-      id?: number;
-      type?: string;
-    } | null;
-    head: {
-      ref: string;
-      sha: string;
-    };
-    base: {
-      ref: string;
-      sha?: string;
-    };
-  };
-  /**
-   * Present on `edited` deliveries; `changes.base.ref.from` carries the
-   * previous base branch when the PR was retargeted.
-   */
-  changes?: {
-    base?: { ref?: { from?: string } };
-  } | null;
-  sender?: {
-    login?: string;
-    id?: number;
-    type?: string;
-  } | null;
-  installation?: { id?: number } | null;
-  /** Present on `labeled` / `unlabeled` pull_request deliveries. */
-  label?: { name: string } | null;
-};
-
-/** Normalized `pull_request` event handed to {@link GitHubPullRequestHook}. */
-export interface GitHubPullRequestEvent {
-  action: GitHubPullRequestAction | string;
-  number: number;
-  url: string;
-  title: string;
-  body?: string;
-  headRef: string;
-  headSha: string;
-  baseRef: string;
-  baseSha?: string;
-  /**
-   * On `edited` deliveries where the PR base was retargeted, the previous
-   * base branch (`changes.base.ref.from`). Undefined for every other edit
-   * (title / body), so `action === "edited" && baseRefChangedFrom` gates
-   * base-retarget handling without waking on prose edits.
-   */
-  baseRefChangedFrom?: string;
-  draft: boolean;
-  /** True when the PR was merged (from the webhook payload). */
-  merged: boolean;
-  authorLogin?: string;
-  /** Label added/removed on `labeled` / `unlabeled` actions. */
-  label?: { name: string };
-}
-
-/** Normalized `issues` event. */
-export interface GitHubIssueEvent {
-  action: GitHubIssueAction | string;
-  number: number;
-  url: string;
-  title: string;
-  body?: string;
-  authorLogin?: string;
-}
-
-/** Normalized comment on an issue, PR timeline, or review thread. */
-export interface GitHubComment {
-  id: number;
-  body: string;
-  url: string;
-  htmlUrl: string;
-  author?: GitHubUser;
-  /** Present for inline review comments. */
-  path?: string;
-  line?: number | null;
-  pullRequestReviewId?: number | null;
-  /** Root or parent review comment when this comment is a thread reply. */
-  inReplyToId?: number;
-}
-
-/** Shared CI fields across check_suite / check_run / workflow_run. */
-export interface GitHubCiPullRequestRef {
-  number: number;
-  url?: string;
-}
-
-export interface GitHubCiAppRef {
-  slug?: string;
-  name?: string;
-}
-
-export interface GitHubCiBase {
-  action: GitHubCiAction | string;
-  status?: GitHubCiStatus;
-  conclusion?: GitHubCiConclusion;
-  headSha: string;
-  app: GitHubCiAppRef;
-  pullRequests: GitHubCiPullRequestRef[];
-}
-
-export interface GitHubCheckSuiteEvent extends GitHubCiBase {
-  checkSuiteId: number;
-}
-
-export interface GitHubCheckRunEvent extends GitHubCiBase {
-  checkRunId: number;
-  name?: string;
-  checkSuiteId?: number;
-}
-
-export interface GitHubWorkflowRunEvent extends GitHubCiBase {
-  workflowRunId: number;
-  name?: string;
-  workflowId?: number;
-  htmlUrl?: string;
-}
-
-/**
- * Legacy commit `status` webhook (Statuses API). Distinct from Checks /
- * Actions events — use {@link GitHubChannelOptions.onStatus}.
- */
-export interface GitHubStatusEvent {
-  state: "pending" | "success" | "failure" | "error" | string;
-  context: string;
-  description?: string | null;
-  targetUrl?: string | null;
-  sha: string;
-  name?: string;
-  branches: Array<{ name: string; commit?: { sha?: string } }>;
-  commit?: { sha?: string; htmlUrl?: string };
-  raw: unknown;
-}
-
-/**
- * Raw webhook envelope for {@link GitHubChannelOptions.onEvent}. Prefer
- * typed hooks (`onComment`, `onPullRequest`, …) when possible.
- */
-export interface GitHubRawEvent {
-  eventName: string;
-  deliveryId?: string;
-  action?: string;
-  payload: unknown;
-}
-
-/**
- * Per-delivery context shared by every inbound hook: where the event landed,
- * who triggered it, delivery-scoped GitHub helpers (`github` / `thread`), and
- * shared host services (`host`) for MCP / host GitHub / Slack.
- */
-export interface GitHubEventContext {
-  /** `X-GitHub-Delivery` header, when present. */
-  deliveryId?: string;
-  /** `X-GitHub-Event` header. */
-  eventName: string;
-  repository: GitHubRepositoryRef;
-  /** The thread the session is anchored to. */
-  conversation: {
-    kind: GitHubConversationKind;
-    number: number;
-    url: string;
-  };
-  /** Login of the actor that triggered the delivery. */
-  senderLogin?: string;
-  sender?: GitHubUser;
-  /** Installation id from the webhook payload, when present. */
-  installationId?: number;
-  /** Verified webhook body for this delivery. */
-  payload: unknown;
-  /** Authenticated GitHub helpers (`getOctokit`, `request`, `createStatus`). */
-  github: GitHubHandle;
-  /** Post / react on the conversation thread. */
-  thread: GitHubThread;
-  /** Shared host services (MCP / host GitHub / Slack). Same as tool `ctx.host`. */
-  host: HostContext;
-  /**
-   * Durable artifacts (unbound — the hook runs before any session is
-   * admitted; pass `sessionId` in `tag` input to attribute one).
-   */
-  artifacts: ArtifactsApi;
-  /**
-   * Channel `send`. Set on every delivery path (HTTP webhook, hosted
-   * admission, SCM events) so a hook can start a turn itself instead of
-   * returning `{ auth, message }` or a deferred `{ task }`.
-   */
-  send?: SendMessageFn;
-}
-
-/**
- * A hook's decision to handle an inbound event. Return `null` from the hook
- * to ignore the delivery instead.
- */
-export type GitHubDispatch = GitHubTurnDispatch | GitHubTaskDispatch;
-
-/** Files seeded into the session workspace before the turn. */
-export type GitHubWorkspaceFiles = NonNullable<SendMessageOptions["workspaceFiles"]>;
-
-/** Start (or resume) a model turn for the event. */
-export interface GitHubTurnDispatch {
-  /** Who the turn runs as. Use `defaultGitHubAuth(ctx)` to derive it from the actor. */
-  auth: AuthContext | null;
-  /** Extra prompt lines appended to the default event message. */
-  context?: readonly string[];
-  /** Optional message override (comment hooks use the comment body by default). */
-  message?: string;
-  /** Optional session title override. */
-  title?: string;
-  /** Per-turn cloud options. Overrides the channel-level `cloud` resolver. */
-  cloud?: AgentCloudOptions;
-  /** Extra durable channel state. Provider-owned fields take precedence. */
-  state?: JsonObject;
-  /**
-   * Seeded into the session workspace before the turn (`send`'s
-   * `workspaceFiles`). A function runs after the webhook is
-   * acknowledged (202) so fetch I/O can outlive GitHub's ~10s window.
-   */
-  workspaceFiles?:
-    | GitHubWorkspaceFiles
-    | (() => GitHubWorkspaceFiles | undefined | Promise<GitHubWorkspaceFiles | undefined>);
-}
-
-/** Bound per-delivery helpers passed to a {@link GitHubTaskDispatch.task}. */
-export interface GitHubTaskArgs {
-  /**
-   * Start (or resume) a session for this delivery. Locally this runs a real
-   * turn and returns the live session. In hosted admission it captures the
-   * send for the control plane to execute after `ses_…` is allocated and
-   * returns an inert deferred handle, so the task body keeps running.
-   * Always use this over a send captured at `onStart` — a startup-captured
-   * send bypasses hosted capture and is rejected during hosted admission.
-   */
-  send: SendMessageFn;
-  /** Extend the delivery's background window past the task promise. */
-  waitUntil: (promise: Promise<unknown>) => void;
-}
-
-/**
- * Run a host-side handler for the event instead of a model turn. The task
- * runs in the background (`waitUntil`) after the webhook is acknowledged
- * with a 202, so it can outlive GitHub's ~10s delivery timeout. The callback
- * receives {@link GitHubTaskArgs}; zero-argument tasks remain valid.
- */
-export interface GitHubTaskDispatch {
-  task: (args: GitHubTaskArgs) => void | Promise<void>;
-}
-
-export type GitHubDispatchResult = GitHubDispatch | null | Promise<GitHubDispatch | null>;
-
-/**
- * Inbound `pull_request` hook. Return `{ auth }` to dispatch a turn,
- * `{ task }` to run a host-side handler, or `null` to ignore the delivery.
- * Without this hook the channel keeps the agent-serve default action gate
- * (opened / reopened / synchronize / ready_for_review). Eve has no default —
- * declare the hook for Eve-style opt-in dispatch.
- */
-export type GitHubPullRequestHook = (
-  ctx: GitHubEventContext,
-  pullRequest: GitHubPullRequestEvent,
-) => GitHubDispatchResult;
-
-/**
- * Invoked for every `@mention` of the bot in an issue/PR timeline comment or
- * an inline review comment; `ctx.conversation.kind` distinguishes the surface.
- * Return `{ auth }` to dispatch or `null` to ignore. Replaces the default
- * mention gate when declared.
- */
-export type GitHubCommentHook = (
-  ctx: GitHubEventContext,
-  comment: GitHubComment,
-) => GitHubDispatchResult;
-
-/** Opt-in `issues` webhook hook. No default dispatch. */
-export type GitHubIssueHook = (
-  ctx: GitHubEventContext,
-  issue: GitHubIssueEvent,
-) => GitHubDispatchResult;
-
-/** Opt-in `check_suite` webhook hook. No default dispatch. */
-export type GitHubCheckSuiteHook = (
-  ctx: GitHubEventContext,
-  checkSuite: GitHubCheckSuiteEvent,
-) => GitHubDispatchResult;
-
-/** Opt-in `check_run` webhook hook. No default dispatch. */
-export type GitHubCheckRunHook = (
-  ctx: GitHubEventContext,
-  checkRun: GitHubCheckRunEvent,
-) => GitHubDispatchResult;
-
-/** Opt-in `workflow_run` webhook hook. No default dispatch. */
-export type GitHubWorkflowRunHook = (
-  ctx: GitHubEventContext,
-  workflowRun: GitHubWorkflowRunEvent,
-) => GitHubDispatchResult;
-
-/**
- * Opt-in legacy commit `status` webhook hook. No default dispatch. Turns are
- * only started when the hook returns a dispatch *and* a PR can be resolved
- * from the payload (otherwise use `{ task }` for host-side work).
- */
-export type GitHubStatusHook = (
-  ctx: GitHubEventContext,
-  status: GitHubStatusEvent,
-) => GitHubDispatchResult;
-
-/**
- * Catch-all for webhook events with no typed hook (`push`,
- * `pull_request_review`, `pull_request_review_thread`, …). Events that have
- * a typed hook (`pull_request`, `issues`, `check_suite`, `check_run`,
- * `workflow_run`, `status`, comments) NEVER reach this hook — when their
- * typed hook is not declared, the delivery is skipped as `no_handler`
- * instead of falling back here. Return `null` to ignore.
- */
-export type GitHubEventHook = (
-  ctx: GitHubEventContext,
-  event: GitHubRawEvent,
-) => GitHubDispatchResult;
-
-export type GitHubCloudOptionsResolver = (
-  ctx: GitHubEventContext,
-  pullRequest: GitHubPullRequestEvent,
-) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
-
-export interface GitHubChannelOptions {
-  /**
-   * Bot / App slug used by the default `@mention` gate on comments.
-   * Falls back to `GITHUB_APP_SLUG`.
-   */
-  botName?: string;
-  /**
-   * Continuation selector. Omit this to inherit the agent architecture's
-   * default. Set it explicitly only when migrating persisted identities.
-   */
-  continuation?: ContinuationIdentity;
-  /**
-   * Webhook + API credentials. When the resolved webhook secret is set, the
-   * channel verifies `X-Hub-Signature-256` before parsing the payload.
-   * API calls prefer App installation tokens, then local PAT / `gh auth`.
-   */
-  credentials?: GitHubChannelCredentials;
-  /**
-   * Use the signed-in Cursor account's GitHub connection for inbound events
-   * and outbound API calls. `true` takes repository scope from
-   * `serve --cursor-events --repo`; `{ repos }` makes the channel self-contained.
-   * `permissions` chooses the minted token tier (`"pr-write"` default).
-   * Cannot be combined with explicit token or GitHub App credentials.
-   */
-  cursorAccount?:
-    | boolean
-    | {
-        repos: readonly string[];
-        /**
-         * Token capability tier:
-         * - `"read"` — PR/issue/status read
-         * - `"pr-write"` (default) — comments / PR+issue write, no `contents:write`
-         * - `"contents-write"` — push code and post merge-box check runs (host-held)
-         */
-        permissions?: "read" | "pr-write" | "contents-write";
-      };
-  /** Optional GitHub API transport overrides (`apiBaseUrl`, `fetch`). */
-  api?: GitHubApiOptions;
-  /**
-   * Route auth chain. Defaults to strict loopback auth without a webhook
-   * secret, and allow-all with one because the GitHub HMAC is the request
-   * auth.
-   */
-  auth?: AuthPolicy[];
-  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
-  path?: string;
-  /**
-   * Webhook events advertised to `agent-sdk github forward` (published as
-   * `meta.githubWebhookEvents`). Defaults to the set derived from the declared
-   * hooks. Set this to pin an exact list — e.g. to include events only handled
-   * through {@link onEvent} such as `pull_request_review`.
-   */
-  webhookEvents?: readonly string[];
-  /**
-   * Decide whether an inbound `pull_request` event starts a turn. Return
-   * `{ auth: defaultGitHubAuth(ctx) }` to dispatch, `null` to ignore.
-   * Without this hook the channel dispatches on opened, reopened,
-   * synchronize, and ready_for_review (agent-serve default; Eve is opt-in).
-   */
-  onPullRequest?: GitHubPullRequestHook;
-  /**
-   * `@mention` gate for `issue_comment` and `pull_request_review_comment`.
-   * Without this hook, comments that `@mention` {@link botName} dispatch.
-   */
-  onComment?: GitHubCommentHook;
-  /** Opt-in `issues` webhook handler. No default dispatch. */
-  onIssue?: GitHubIssueHook;
-  /** Opt-in `check_suite` webhook handler. No default dispatch. */
-  onCheckSuite?: GitHubCheckSuiteHook;
-  /** Opt-in `check_run` webhook handler. No default dispatch. */
-  onCheckRun?: GitHubCheckRunHook;
-  /** Opt-in `workflow_run` webhook handler. No default dispatch. */
-  onWorkflowRun?: GitHubWorkflowRunHook;
-  /** Opt-in legacy commit `status` webhook handler. No default dispatch. */
-  onStatus?: GitHubStatusHook;
-  /**
-   * Catch-all webhook handler for events without a typed hook (`push`,
-   * `pull_request_review`, …). NOT a fallback: events with a typed hook are
-   * skipped as `no_handler` when that hook is undeclared, and never reach
-   * this one. Prefer typed hooks when the event has one.
-   */
-  onEvent?: GitHubEventHook;
-  /**
-   * Override / extend default stream-event handlers (eyes reaction, reply
-   * posting, opt-in check run / banner). Handlers you provide replace
-   * the matching defaults.
-   */
-  events?: ChannelEventHandlers<GitHubChannelState>;
-  /**
-   * Acknowledgement progress surfaces. Reactions default on; merge-box check
-   * and sticky banner are opt-in via `commitStatus` / `banner`.
-   */
-  progress?: GitHubProgressConfig;
-  /**
-   * Declare that this channel posts its own CI checks
-   * (`ctx.github.createCheck` / `createGitHubCheck`). With `cursorAccount`,
-   * opts the minted token up to `permissions: "contents-write"` so the
-   * hosted lease includes `checks:write` — same opt-up as
-   * `progress.commitStatus`. Has no effect on App / PAT credentials.
-   */
-  checks?: boolean;
-  /**
-   * When false, skip posting assistant / error comments back to GitHub.
-   * Defaults to true.
-   */
-  deliverReplies?: boolean;
-  /**
-   * Per-session cloud options. Pass `true` to attach the PR repo using the
-   * pull request URL, or a resolver for custom cloud options.
-   */
-  cloud?: boolean | AgentCloudOptions | GitHubCloudOptionsResolver;
-  /** Called once when the server mounts this channel. */
-  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
-  /** Called when the server shuts down. */
-  onStop?: () => void | Promise<void>;
-}