@cursor/bdk 0.2.2 → 0.2.4

package/src/channels/origin/types.ts

@@ -1,295 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type {
-  AgentCloudOptions,
-  ArtifactsApi,
-  AuthContext,
-  AuthPolicy,
-  ChannelEventHandlers,
-  ChannelStartArgs,
-  HostContext,
-  JsonObject,
-  SendMessageFn,
-} from "../../types.js";
-import type { OriginTokenProvider } from "./api.js";
-import type { OriginHandle } from "./binding.js";
-import type { OriginChannelState } from "./state.js";
-
-export interface OriginActor {
-  id: string;
-  kind?: string;
-}
-
-export interface OriginRepositoryRef {
-  owner: string;
-  name: string;
-  fullName: string;
-}
-
-export interface OriginPullRequestEvent {
-  type: string;
-  number: number;
-  url: string;
-  title?: string;
-  body?: string | null;
-  draft?: boolean;
-  merged?: boolean;
-  authorId?: string;
-  headRef?: string;
-  headSha?: string;
-  baseRef?: string;
-  baseSha?: string;
-}
-
-export interface OriginComment {
-  id: string;
-  body: string;
-  author?: OriginActor;
-}
-
-export interface OriginReview {
-  id?: string;
-  verdict?: string;
-  author?: OriginActor;
-}
-
-export interface OriginEventContext {
-  deliveryId?: string;
-  eventType: string;
-  /** Delivery envelope `event.eventTime`, when present. */
-  eventTime?: string;
-  /** Origin app installation id from the delivery envelope, when present. */
-  installationId?: string;
-  repository: OriginRepositoryRef;
-  pullRequestNumber: number;
-  pullRequestUrl: string;
-  /**
-   * Who opened the pull request, when the payload carries it. Distinct from
-   * {@link sender} — on a comment event the sender is the commenter.
-   */
-  pullRequestAuthor?: OriginActor;
-  /**
-   * Raw parsed `event.payload` record (`{}` when absent), for consumers
-   * whose normalization needs more than the typed event — the GitHub
-   * channel's hook ctx exposes the same.
-   */
-  payload: Record<string, unknown>;
-  sender?: OriginActor;
-  /**
-   * 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;
-  host: HostContext;
-  artifacts: ArtifactsApi;
-  /**
-   * Repo-bound Origin public API handle (REST calls + `createCheck`).
-   * Outbound credentials come from {@link OriginChannelOptions.app} or the
-   * `ORIGIN_APP_*` environment; resolution is lazy, so hooks that never call
-   * it need no credentials.
-   */
-  origin: OriginHandle;
-}
-
-export type OriginTurnDispatch = {
-  auth: AuthContext;
-  message?: string;
-  title?: string;
-  context?: readonly string[];
-  /** Per-turn cloud options. Overrides the channel-level `cloud` resolver. */
-  cloud?: AgentCloudOptions;
-  /** Extra durable channel state. Provider-owned fields take precedence. */
-  state?: JsonObject;
-};
-
-/** Bound per-delivery helpers passed to an {@link OriginTaskDispatch.task}. */
-export interface OriginTaskArgs {
-  /**
-   * Start (or resume) a session for this delivery. In hosted admission it
-   * captures the send for the control plane; a send captured at `onStart`
-   * bypasses that capture and is rejected.
-   */
-  send: SendMessageFn;
-  /**
-   * Extend the local delivery's background window past the task promise.
-   * Hosted admission awaits the task promise only.
-   */
-  waitUntil: (promise: Promise<unknown>) => void;
-}
-
-/**
- * Run a host-side handler after the webhook is acknowledged with a 202.
- * Zero-argument tasks remain valid.
- */
-export type OriginTaskDispatch = {
-  task: (args: OriginTaskArgs) => void | Promise<void>;
-};
-
-export type OriginDispatch = OriginTurnDispatch | OriginTaskDispatch;
-
-export type OriginDispatchResult = OriginDispatch | null | Promise<OriginDispatch | null>;
-
-export type OriginPullRequestHook = (
-  ctx: OriginEventContext,
-  pullRequest: OriginPullRequestEvent,
-) => OriginDispatchResult;
-
-export type OriginCommentHook = (
-  ctx: OriginEventContext,
-  comment: OriginComment,
-) => OriginDispatchResult;
-
-export type OriginReviewHook = (
-  ctx: OriginEventContext,
-  review: OriginReview,
-) => OriginDispatchResult;
-
-export type OriginEventHook = (
-  ctx: OriginEventContext,
-  event: { eventType: string; payload: unknown },
-) => OriginDispatchResult;
-
-export type OriginCloudOptionsResolver = (
-  ctx: OriginEventContext,
-  pullRequest: OriginPullRequestEvent,
-) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
-
-/**
- * Origin delivery envelope. Public payloads are proto3 camelCase
- * (`pullRequest`, `repository.owner.slug`).
- */
-export interface OriginWebhookEnvelope {
-  deliveryId?: string;
-  appId?: string;
-  installationId?: string;
-  sender?: OriginActor;
-  event: {
-    id?: string;
-    type: string;
-    eventTime?: string;
-    payload?: unknown;
-  };
-}
-
-/**
- * Outbound Origin app credentials for `ctx.origin` (public REST calls, CI
- * check runs). Fields left unset fall back to the environment
- * (`ORIGIN_APP_ID` / `ORIGIN_APP_INSTALLATION_ID` / `ORIGIN_APP_PRIVATE_KEY`
- * / `ORIGIN_API_BASE_URL`); the delivery's installation id fills in when
- * neither pins one.
- */
-export interface OriginAppOptions {
-  /** Origin app id (`app_<typeid>`). */
-  appId?: string;
-  /** Installation id outbound tokens are minted for. */
-  installationId?: string;
-  /** PKCS8 PEM for the app's EdDSA (Ed25519) private key. */
-  privateKey?: string;
-  /** Static bearer (`oit_…`) or provider, bypassing the app-JWT mint. */
-  token?: string | OriginTokenProvider;
-  /** Public Origin REST base, e.g. `https://api.cursor.com`. */
-  apiBaseUrl?: string;
-  /**
-   * Origin ConnectRPC base for operations without a REST binding (comment
-   * reactions), e.g. `https://api.origin.cursor.com`. Falls back to
-   * `ORIGIN_RPC_BASE_URL`.
-   */
-  rpcBaseUrl?: string;
-}
-
-export interface OriginChannelOptions {
-  /**
-   * Use the signed-in Cursor account for inbound Origin events via
-   * `/v0/scm-events` (`provider: "origin"`). `true` takes repository scope
-   * from `serve --cursor-events --repo`; `{ repos }` makes the channel
-   * self-contained. Origin identity is the Cursor user — there is no
-   * separate OAuth principal, and this does not mint a GitHub token.
-   */
-  cursorAccount?: boolean | { repos: readonly string[] };
-  /**
-   * Origin app id this channel accepts (`envelope.appId`). v1ed only proves
-   * Origin signed the body with the platform JWKS; it does not bind the
-   * delivery to one app (any Origin app can aim signed POSTs at a public
-   * URL). Required for non-loopback HTTP, same role as GitHub's per-channel
-   * webhook secret. Falls back to `AGENT_SERVE_ORIGIN_APP_ID`.
-   */
-  appId?: string | readonly string[];
-  /**
-   * Optional Origin installation id bind (`envelope.installationId`). When
-   * set, HTTP deliveries for any other installation are rejected.
-   */
-  installationId?: string | readonly string[];
-  /**
-   * Optional HTTP/dispatch repo allowlist (`owner/name`). `{ cursorAccount:
-   * { repos } }` is also an allowlist. Events outside the set are acked
-   * without starting a turn. Omit to accept every repo the bound app sends.
-   */
-  repos?: readonly string[];
-  /**
-   * Route auth chain. Defaults to allow-all when {@link appId} (or
-   * `AGENT_SERVE_ORIGIN_APP_ID`) is set, because v1ed plus that app-id bind
-   * is the request auth. Without an app id, production stays loopback-strict
-   * (GitHub's no-secret posture); `--dev` / skip-verify admits loopback only.
-   */
-  auth?: AuthPolicy[];
-  /**
-   * Outbound Origin app credentials for `ctx.origin` (REST calls, CI check
-   * runs). Optional: every field falls back to the `ORIGIN_APP_*`
-   * environment, and inbound-only channels need none.
-   */
-  app?: OriginAppOptions;
-  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
-  path?: string;
-  /** Origin API base used to fetch `/v1/origin/keys` for v1ed verify. */
-  apiBaseUrl?: string | (() => string | undefined);
-  /**
-   * Pin the Origin event types this channel dispatches on (published as
-   * `meta.originWebhookEvents`). Defaults to the set derived from hooks.
-   */
-  webhookEvents?: readonly string[];
-  /**
-   * Continuation selector. Omit this to inherit the agent architecture's
-   * default. Set it explicitly only when migrating persisted identities.
-   */
-  continuation?: ContinuationIdentity;
-  /**
-   * Decide whether an inbound pull-request event starts a turn. Return
-   * `{ auth: defaultOriginAuth(ctx) }` to dispatch, `null` to ignore.
-   * Without this hook the channel dispatches on created / published /
-   * head_ref.pushed / base_ref.updated.
-   */
-  onPullRequest?: OriginPullRequestHook;
-  /** Opt-in `pull_request.comment.*` handler. No default dispatch. */
-  onComment?: OriginCommentHook;
-  /** Opt-in `pull_request.review.*` handler. No default dispatch. */
-  onReview?: OriginReviewHook;
-  /**
-   * Catch-all for Origin event types without a typed hook. NOT a fallback:
-   * events with a typed hook never reach this one.
-   */
-  onEvent?: OriginEventHook;
-  /**
-   * 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 | OriginCloudOptionsResolver;
-  /**
-   * When false, skip posting completed assistant messages (and failure
-   * notices) back to the Origin pull request. Defaults to true — the GitHub
-   * channel's reply-delivery posture. Outbound credentials resolve like
-   * `ctx.origin`: {@link app} / `ORIGIN_APP_*` env when configured,
-   * otherwise the Cursor-account session exchange (hosted v2 deployments
-   * post as the deployment service-account principal).
-   */
-  deliverReplies?: boolean;
-  /**
-   * Channel stream-event handlers, merged over the built-in reply-delivery
-   * defaults (`buildDefaultOriginEvents`) — same override contract as the
-   * GitHub channel's `events`.
-   */
-  events?: ChannelEventHandlers<OriginChannelState>;
-  /** Called once when the server mounts this channel. */
-  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
-  /** Called when the server shuts down. */
-  onStop?: () => void | Promise<void>;
-}