@cursor/bdk 0.2.2 → 0.2.4

package/src/channels/issues/types.ts

@@ -1,38 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
-
-export const ISSUE_CREATED_EVENT_TYPE = "issue.created" as const;
-
-export type IssueCreatedEventType = typeof ISSUE_CREATED_EVENT_TYPE;
-
-export type IssueState = "STATE_UNSPECIFIED" | "STATE_OPEN" | "STATE_CLOSED";
-
-/** Factory Issue JSON (camelCase proto JSON). */
-export type IssueResource = {
-  name: string;
-  title: string;
-  body: string;
-  state?: IssueState;
-  createTime?: string;
-  updateTime?: string;
-  path?: string;
-  etag?: string;
-};
-
-/** Factory `issue.created` for every Issue create. */
-export type IssueCreatedEvent = {
-  eventId: string;
-  eventType: IssueCreatedEventType;
-  teamId: string;
-  occurredAtMs: number;
-  issue: IssueResource;
-};
-
-export type IssuesChannelOptions = {
-  onEvent: (event: IssueCreatedEvent, args: ChannelHandlerArgs) => Promise<unknown> | unknown;
-  continuation?: ContinuationIdentity;
-  path?: string;
-  auth?: ChannelDefinition["auth"];
-  onStart?: ChannelDefinition["onStart"];
-  onStop?: ChannelDefinition["onStop"];
-};

package/src/channels/origin/api.ts

@@ -1,507 +0,0 @@
-/**
- * Origin public REST helpers (`https://api.cursor.com/v1/origin/...`).
- *
- * This module consolidates Origin auth so agents configure credentials once
- * and call {@link createOriginClient} — the GitHub-channel analogue of
- * `createGitHubOctokit`.
- *
- * Self-configured channels with their own Origin app resolve credentials
- * from options first, then the environment: `ORIGIN_APP_ID` (or
- * `AGENT_SERVE_ORIGIN_APP_ID`), `ORIGIN_APP_INSTALLATION_ID`,
- * `ORIGIN_APP_PRIVATE_KEY` (PKCS8 PEM for the app's Ed25519 key; literal
- * `\n` sequences are normalized), `ORIGIN_API_BASE_URL` for the public REST
- * base, and `ORIGIN_RPC_BASE_URL` for the first-party ConnectRPC base.
- *
- * Hosted v2 forks configure none of that: their only credential is the
- * deployment service account's `CURSOR_API_KEY`, exchanged for a Cursor
- * session ({@link cursorSessionTokenProvider}, `POST
- * /auth/exchange_user_api_key`) and sent as the Origin bearer. Reads and
- * writes both run as the deployment **service-account principal**; Origin's
- * `agent-serve` allowlist grants team-namespace read/write, so there is no
- * app-installation token exchange for managed deployments.
- */
-
-import { Buffer } from "node:buffer";
-import { createPrivateKey, sign } from "node:crypto";
-import { cursorBackendUrl, resolveApiKeySync } from "../../internal/cursor/credentials.js";
-import {
-  CURSOR_SESSION_EXCHANGE_PATH,
-  exchangeCursorApiKeyForSession,
-  SESSION_TOKEN_EXPIRY_LEEWAY_MS,
-} from "../../internal/cursor/session-token.js";
-
-/**
- * Public Origin REST base (check runs, installation tokens). Distinct from
- * the webhook JWKS base (`DEFAULT_ORIGIN_API_BASE_URL` in
- * `origin-webhook.ts`).
- */
-export const DEFAULT_ORIGIN_PUBLIC_API_BASE_URL = "https://api.cursor.com";
-
-/**
- * Origin's first-party ConnectRPC host (`origin.v1.OriginService`). Separate
- * deployment from {@link DEFAULT_ORIGIN_PUBLIC_API_BASE_URL}: a handful of
- * workflow operations — comment reactions among them — have no
- * `/v1/origin/...` REST binding yet and are only reachable as Connect unary
- * JSON here.
- */
-export const DEFAULT_ORIGIN_RPC_BASE_URL = "https://api.origin.cursor.com";
-
-/** Fixed audience for Origin app JWTs (`APP_TOKEN_AUDIENCE` backend-side). */
-const ORIGIN_APP_TOKEN_AUDIENCE = "origin-apps";
-const APP_JWT_TTL_SECONDS = 5 * 60;
-/** Re-mint the `oit_` token after this long; tokens outlive it comfortably. */
-const TOKEN_REUSE_MS = 4 * 60 * 1000;
-const TOKEN_EXCHANGE_TIMEOUT_MS = 30_000;
-
-export type OriginApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
-
-/** Normalized Origin REST failure — the `GitHubApiError` analogue. */
-export class OriginApiError extends Error {
-  readonly body: unknown;
-  readonly method: string;
-  readonly path: string;
-  readonly status: number;
-
-  constructor(input: { body: unknown; method: string; path: string; status: number }) {
-    super(`Origin ${input.method} ${input.path} failed with HTTP ${input.status}.`);
-    this.name = "OriginApiError";
-    this.body = input.body;
-    this.method = input.method;
-    this.path = input.path;
-    this.status = input.status;
-  }
-}
-
-/**
- * Yields a bearer for Origin REST calls (a short-lived `oit_…` for app
- * channels, or a Cursor session token for service-account access).
- */
-export type OriginTokenProvider = () => Promise<string>;
-
-export interface OriginAppCredentials {
-  /** Origin app id (`app_<typeid>`). */
-  appId: string;
-  /** Installation the token is minted for. */
-  installationId: string;
-  /** PKCS8 PEM for the app's EdDSA (Ed25519) private key. */
-  privateKey: string;
-}
-
-/** Vault/env round-trip: literal `\n` sequences appear in practice. */
-function normalizePrivateKeyPem(raw: string | undefined): string | undefined {
-  const pem = raw?.trim().replace(/\\n/g, "\n");
-  return pem === undefined || pem === "" ? undefined : pem;
-}
-
-function envValue(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
-}
-
-/** Each Origin app credential field found in the environment, when set. */
-export function resolveOriginAppCredentialParts(
-  env: NodeJS.ProcessEnv = process.env,
-): Partial<OriginAppCredentials> {
-  return {
-    appId: envValue(env.ORIGIN_APP_ID) ?? envValue(env.AGENT_SERVE_ORIGIN_APP_ID),
-    installationId: envValue(env.ORIGIN_APP_INSTALLATION_ID),
-    privateKey: normalizePrivateKeyPem(env.ORIGIN_APP_PRIVATE_KEY),
-  };
-}
-
-/**
- * Read Origin app credentials from the environment. Returns `undefined` when
- * incomplete so callers can fail with a clear message at use time instead of
- * at startup.
- */
-export function resolveOriginAppCredentials(
-  env: NodeJS.ProcessEnv = process.env,
-): OriginAppCredentials | undefined {
-  const { appId, installationId, privateKey } = resolveOriginAppCredentialParts(env);
-  if (appId === undefined || installationId === undefined || privateKey === undefined) {
-    return undefined;
-  }
-  return { appId, installationId, privateKey };
-}
-
-/** Public Origin REST base. Trailing slashes are stripped for path joins. */
-export function originPublicApiBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
-  const fromEnv = envValue(env.ORIGIN_API_BASE_URL)?.replace(/\/+$/, "");
-  return fromEnv ?? DEFAULT_ORIGIN_PUBLIC_API_BASE_URL;
-}
-
-/** Origin ConnectRPC base. Trailing slashes are stripped for path joins. */
-export function originRpcBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
-  const fromEnv = envValue(env.ORIGIN_RPC_BASE_URL)?.replace(/\/+$/, "");
-  return fromEnv ?? DEFAULT_ORIGIN_RPC_BASE_URL;
-}
-
-function base64UrlJson(value: unknown): string {
-  return Buffer.from(JSON.stringify(value)).toString("base64url");
-}
-
-function mintOriginAppJwt(credentials: OriginAppCredentials, nowMs: number): string {
-  const now = Math.floor(nowMs / 1000);
-  const header = base64UrlJson({
-    alg: "EdDSA",
-    kid: credentials.appId,
-    typ: "JWT",
-  });
-  const payload = base64UrlJson({
-    iss: credentials.appId,
-    aud: ORIGIN_APP_TOKEN_AUDIENCE,
-    iat: now,
-    exp: now + APP_JWT_TTL_SECONDS,
-  });
-  const signingInput = `${header}.${payload}`;
-  const key = createPrivateKey(credentials.privateKey);
-  const signature = sign(null, Buffer.from(signingInput), key).toString("base64url");
-  return `${signingInput}.${signature}`;
-}
-
-async function mintOriginInstallationToken(input: {
-  credentials: OriginAppCredentials;
-  apiBaseUrl: string;
-  fetchImpl: typeof fetch;
-  nowMs: number;
-}): Promise<string> {
-  const jwt = mintOriginAppJwt(input.credentials, input.nowMs);
-  const path = `/v1/origin/app/installations/${encodeURIComponent(
-    input.credentials.installationId,
-  )}/access_tokens`;
-  const response = await input.fetchImpl(`${input.apiBaseUrl}${path}`, {
-    method: "POST",
-    headers: { authorization: `Bearer ${jwt}` },
-    signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
-  });
-  const body: unknown = await response.json().catch(() => undefined);
-  const token =
-    typeof body === "object" && body !== null && !Array.isArray(body)
-      ? (body as Record<string, unknown>).token
-      : undefined;
-  if (!response.ok || typeof token !== "string" || token === "") {
-    // Never echo the body: on success it contains the installation token.
-    throw new OriginApiError({
-      body: undefined,
-      method: "POST",
-      path,
-      status: response.status,
-    });
-  }
-  return token;
-}
-
-/**
- * Exchange endpoint for Cursor-account session tokens. Override with
- * `AGENT_SERVE_CURSOR_SESSION_EXCHANGE_URL`; defaults to the Cursor backend.
- */
-export function resolveCursorSessionExchangeUrl(): string {
-  const override = process.env.AGENT_SERVE_CURSOR_SESSION_EXCHANGE_URL;
-  if (override !== undefined && override.trim() !== "") {
-    return override.trim().replace(/\/+$/, "");
-  }
-  return `${cursorBackendUrl()}${CURSOR_SESSION_EXCHANGE_PATH}`;
-}
-
-/**
- * A session-backed Origin token provider: {@link OriginTokenProvider} plus
- * an `invalidate` hook `createOriginClient` calls when Origin rejects the
- * bearer (401), so the next mint re-exchanges instead of serving the
- * rejected session until its local renewal deadline.
- */
-export type CursorSessionTokenProvider = OriginTokenProvider & {
-  invalidate: (token: string) => void;
-};
-
-/**
- * Token provider backed by the shared Cursor session exchange
- * (`exchangeCursorApiKeyForSession`, `POST /auth/exchange_user_api_key` —
- * the same primitive `CursorBackendClient` mints through).
- *
- * Hosted v2 forks hold exactly one credential — the deployment service
- * account's `CURSOR_API_KEY` — and Origin authenticates the exchanged
- * session directly: reads and writes run as the deployment
- * **service-account principal**, confined server-side to namespaces owned
- * by the deployment's team (`agent-serve` allowlist). Local runs work the
- * same way with a personal key: Origin authorizes the user principal.
- *
- * The API key is resolved on every mint so a task-time bind reaches a
- * listening process without a restart — hosted deliveries consume the bind
- * file into `CURSOR_API_KEY` before authored work, so this resolve reads env.
- * Sessions are cached until
- * shortly before their JWT expiry. The cache is **process-wide**, keyed by
- * (endpoint, API key): hosted channels build a fresh `createOriginClient()`
- * per event, so a per-provider cache would re-exchange on every read/write
- * and concurrent first calls would race. In-flight exchanges are deduped
- * for the same reason.
- */
-const cursorSessionTokenCache = new Map<string, { token: string; renewAtMs: number }>();
-const cursorSessionTokenInFlight = new Map<string, Promise<string>>();
-
-/** Test-only: drop the process-wide exchanged-session cache. */
-export function _clearCursorSessionTokenCacheForTesting(): void {
-  cursorSessionTokenCache.clear();
-  cursorSessionTokenInFlight.clear();
-}
-
-export function cursorSessionTokenProvider(input?: {
-  /** Cursor API key source. Defaults to the standard host resolution. */
-  getApiKey?: () => string | undefined;
-  /** Exchange endpoint. Defaults to {@link resolveCursorSessionExchangeUrl}. */
-  exchangeUrl?: string;
-  fetch?: typeof fetch;
-  now?: () => number;
-}): CursorSessionTokenProvider {
-  const getApiKey = input?.getApiKey ?? ((): string | undefined => resolveApiKeySync()?.apiKey);
-  const fetchImpl = input?.fetch ?? fetch;
-  const now = input?.now ?? Date.now;
-
-  const cacheKey = (url: string, apiKey: string): string => `${url}\u0000${apiKey}`;
-  const resolveUrl = (): string => input?.exchangeUrl ?? resolveCursorSessionExchangeUrl();
-
-  const mint = async (url: string, apiKey: string): Promise<string> => {
-    const nowMs = now();
-    let session: { token: string; expiresAtMs: number };
-    try {
-      session = await exchangeCursorApiKeyForSession({
-        exchangeUrl: url,
-        apiKey,
-        fetchImpl,
-        nowMs,
-      });
-    } catch (error) {
-      throw new Error(
-        `originClient: ${
-          error instanceof Error ? error.message : String(error)
-        } Check CURSOR_API_KEY / CURSOR_API_KEY_FILE, or pass an explicit token.`,
-      );
-    }
-    const renewAtMs = Math.max(nowMs + 1_000, session.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS);
-    cursorSessionTokenCache.set(cacheKey(url, apiKey), {
-      token: session.token,
-      renewAtMs,
-    });
-    return session.token;
-  };
-
-  const provider = async (): Promise<string> => {
-    const apiKey = getApiKey();
-    if (apiKey === undefined || apiKey === "") {
-      throw new Error(
-        "originClient: no Cursor credential available for the session exchange (set CURSOR_API_KEY or CURSOR_API_KEY_FILE).",
-      );
-    }
-    const url = resolveUrl();
-    const key = cacheKey(url, apiKey);
-    const cached = cursorSessionTokenCache.get(key);
-    if (cached !== undefined && now() < cached.renewAtMs) {
-      return cached.token;
-    }
-    // Dedupe concurrent first calls: one exchange per (endpoint, key).
-    const inFlight = cursorSessionTokenInFlight.get(key);
-    if (inFlight !== undefined) {
-      return await inFlight;
-    }
-    const pending = mint(url, apiKey).finally(() => {
-      cursorSessionTokenInFlight.delete(key);
-    });
-    cursorSessionTokenInFlight.set(key, pending);
-    return await pending;
-  };
-
-  // Origin answered 401 for this bearer: drop it (unless a newer session
-  // already replaced it) so the next call re-exchanges immediately.
-  const invalidate = (token: string): void => {
-    const apiKey = getApiKey();
-    if (apiKey === undefined || apiKey === "") {
-      return;
-    }
-    const key = cacheKey(resolveUrl(), apiKey);
-    if (cursorSessionTokenCache.get(key)?.token === token) {
-      cursorSessionTokenCache.delete(key);
-    }
-  };
-
-  return Object.assign(provider, { invalidate });
-}
-
-/**
- * A cached per-use token provider for one set of app credentials. Every call
- * inside the reuse window returns the same `oit_…`; the first call after it
- * re-mints.
- */
-export function originAppTokenProvider(input: {
-  credentials: OriginAppCredentials;
-  apiBaseUrl?: string;
-  fetch?: typeof fetch;
-  now?: () => number;
-}): OriginTokenProvider {
-  const apiBaseUrl = input.apiBaseUrl ?? originPublicApiBaseUrl();
-  const fetchImpl = input.fetch ?? fetch;
-  const now = input.now ?? Date.now;
-  let cached: { token: string; mintedAtMs: number } | undefined;
-  return async () => {
-    const nowMs = now();
-    if (cached !== undefined && nowMs - cached.mintedAtMs < TOKEN_REUSE_MS) {
-      return cached.token;
-    }
-    const token = await mintOriginInstallationToken({
-      credentials: input.credentials,
-      apiBaseUrl,
-      fetchImpl,
-      nowMs,
-    });
-    cached = { token, mintedAtMs: nowMs };
-    return token;
-  };
-}
-
-export interface OriginClientOptions {
-  /** Static bearer (`oit_…`) or refreshing provider used for every call. */
-  token?: string | OriginTokenProvider;
-  /**
-   * App credentials to mint installation tokens from. Defaults to the
-   * environment ({@link resolveOriginAppCredentials}). Pass `false` to
-   * disable app credential lookup and force the Cursor-account exchange.
-   */
-  credentials?: OriginAppCredentials | false;
-  /** Public Origin REST base. Defaults to `ORIGIN_API_BASE_URL` / prod. */
-  apiBaseUrl?: string;
-  /** Injectable fetch for tests. */
-  fetch?: typeof fetch;
-  /**
-   * Cursor-account session exchange fallback (hosted v2 deployment SAs and
-   * local personal keys). `true` (default) engages when no explicit token
-   * or app credentials resolve and a Cursor credential is present; `false`
-   * disables it; an object injects the key source / endpoint.
-   */
-  cursorAccountExchange?:
-    | boolean
-    | {
-        getApiKey?: () => string | undefined;
-        exchangeUrl?: string;
-      };
-}
-
-/** Minimal authenticated Origin REST client (the `Octokit` analogue). */
-export interface OriginClient {
-  readonly apiBaseUrl: string;
-  /**
-   * Call an Origin public REST path (e.g. `/v1/origin/repos/o/r/check-runs`).
-   * Throws {@link OriginApiError} on non-2xx responses.
-   */
-  request<T = unknown>(input: {
-    method: OriginApiMethod;
-    path: string;
-    body?: unknown;
-  }): Promise<T>;
-}
-
-/**
- * Build an authenticated Origin REST client. Auth resolution: explicit
- * token/provider, then app credentials (options or environment, for
- * channels with their own Origin app), then the Cursor-account session
- * exchange (hosted v2 deployment SAs — reads and writes both run as the
- * deployment service-account principal). Missing auth fails at the first
- * request with a clear message.
- */
-export function createOriginClient(options: OriginClientOptions = {}): OriginClient {
-  const apiBaseUrl = (options.apiBaseUrl ?? originPublicApiBaseUrl()).replace(/\/+$/, "");
-  const fetchImpl = options.fetch ?? fetch;
-
-  let tokenProvider: OriginTokenProvider | undefined;
-  // Set when the session-exchange fallback is engaged: a 401 from Origin
-  // invalidates the cached session and retries once with a fresh one, the
-  // `CursorBackendClient` re-exchange behavior.
-  let sessionProvider: CursorSessionTokenProvider | undefined;
-  const getToken = async (): Promise<string> => {
-    if (typeof options.token === "string") {
-      return options.token;
-    }
-    if (typeof options.token === "function") {
-      return await options.token();
-    }
-    if (tokenProvider === undefined) {
-      const credentials =
-        options.credentials === false
-          ? undefined
-          : (options.credentials ?? resolveOriginAppCredentials());
-      const exchange = options.cursorAccountExchange ?? true;
-      const exchangeOptions = exchange === false ? undefined : exchange === true ? {} : exchange;
-      const getExchangeApiKey =
-        exchangeOptions?.getApiKey ?? ((): string | undefined => resolveApiKeySync()?.apiKey);
-      if (credentials !== undefined) {
-        tokenProvider = originAppTokenProvider({
-          credentials,
-          apiBaseUrl,
-          fetch: fetchImpl,
-        });
-      } else if (exchangeOptions !== undefined && (getExchangeApiKey() ?? "") !== "") {
-        sessionProvider = cursorSessionTokenProvider({
-          fetch: fetchImpl,
-          getApiKey: getExchangeApiKey,
-          ...(exchangeOptions.exchangeUrl === undefined
-            ? {}
-            : { exchangeUrl: exchangeOptions.exchangeUrl }),
-        });
-        tokenProvider = sessionProvider;
-      } else {
-        throw new Error(
-          "originClient: no Origin credential available (pass token / credentials, set ORIGIN_APP_ID + ORIGIN_APP_INSTALLATION_ID + ORIGIN_APP_PRIVATE_KEY, or sign in with a Cursor credential for the session exchange).",
-        );
-      }
-    }
-    return await tokenProvider();
-  };
-
-  const send = async (
-    input: { method: OriginApiMethod; path: string; body?: unknown },
-    path: string,
-    token: string,
-  ): Promise<Response> =>
-    await fetchImpl(`${apiBaseUrl}${path}`, {
-      method: input.method,
-      headers: {
-        authorization: `Bearer ${token}`,
-        ...(input.body === undefined ? {} : { "content-type": "application/json" }),
-      },
-      body: input.body === undefined ? undefined : JSON.stringify(input.body),
-    });
-
-  return {
-    apiBaseUrl,
-    async request<T = unknown>(input: {
-      method: OriginApiMethod;
-      path: string;
-      body?: unknown;
-    }): Promise<T> {
-      const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
-      const token = await getToken();
-      let response = await send(input, path, token);
-      if (response.status === 401 && sessionProvider !== undefined) {
-        // The session aged out server-side. Drop it — unless a concurrent
-        // retry already minted a newer one — and retry once.
-        await response.text().catch(() => undefined);
-        sessionProvider.invalidate(token);
-        const retryToken = await getToken();
-        response = await send(input, path, retryToken);
-      }
-      const text = await response.text();
-      let parsed: unknown;
-      try {
-        parsed = text === "" ? undefined : JSON.parse(text);
-      } catch {
-        parsed = text;
-      }
-      if (!response.ok) {
-        throw new OriginApiError({
-          body: parsed,
-          method: input.method,
-          path,
-          status: response.status,
-        });
-      }
-      return parsed as T;
-    },
-  };
-}

package/src/channels/origin/binding.ts

@@ -1,114 +0,0 @@
-/**
- * Rebuild the Origin API handle (`ctx.origin`) for inbound hooks.
- *
- * The handle is repo-bound and lazy: no credential is resolved until the
- * first call, so channels without outbound Origin credentials still dispatch
- * normally. Credential resolution combines the channel's `app` option with
- * the environment (`ORIGIN_APP_ID` / `ORIGIN_APP_INSTALLATION_ID` /
- * `ORIGIN_APP_PRIVATE_KEY`); the delivery's installation id fills in when
- * neither pins one — the GitHub webhook `installation.id` analogue.
- */
-
-import {
-  createOriginClient,
-  type OriginApiMethod,
-  type OriginClient,
-  originRpcBaseUrl,
-  resolveOriginAppCredentialParts,
-} from "./api.js";
-import { createOriginCheck, type OriginCheck, type OriginCheckCreateInput } from "./checks.js";
-import { type OriginCommentReactionInput, setOriginCommentReaction } from "./reactions.js";
-import type { OriginAppOptions, OriginRepositoryRef } from "./types.js";
-
-/** Origin operations exposed to hooks (`ctx.origin`). */
-export interface OriginHandle {
-  /** Installation id the outbound credential is minted for, when known. */
-  installationId: string | undefined;
-  repository: OriginRepositoryRef;
-  /**
-   * Call an Origin public REST path with the channel's app credential.
-   * Throws `OriginApiError` on API failure.
-   */
-  request<T = unknown>(input: {
-    method: OriginApiMethod;
-    path: string;
-    body?: unknown;
-  }): Promise<T>;
-  /**
-   * Open a CI check run on `sha` and get a handle for updating and
-   * concluding it. Needs `repository:checks:write` — via an app
-   * installation, or the deployment service account on hosted v2 forks.
-   */
-  createCheck(
-    input: Omit<OriginCheckCreateInput, "origin" | "owner" | "repo">,
-  ): Promise<OriginCheck>;
-  /**
-   * Add or remove one reaction on a PR comment — the Origin analogue of
-   * GitHub's `thread.react("eyes")`. Needs
-   * `repository:pull_requests:reviews:write`. Reactions have no REST
-   * binding, so this call goes to Origin's ConnectRPC host rather than the
-   * public API base {@link request} uses.
-   */
-  reactToComment(input: OriginCommentReactionInput): Promise<void>;
-}
-
-export function buildOriginBinding(input: {
-  repository: OriginRepositoryRef;
-  /** Installation id from the delivery envelope, when present. */
-  installationId?: string;
-  /** Delivery id seeding the default per-execution check-run `externalId`. */
-  executionId?: string;
-  /** Force the signed-in Cursor account / deployment SA credential path. */
-  cursorAccount?: boolean;
-  /** Channel-authored outbound app credentials / API base. */
-  app?: OriginAppOptions;
-  /** Injectable fetch for tests. */
-  fetch?: typeof fetch;
-}): OriginHandle {
-  const buildClient = (apiBaseUrl: string | undefined): OriginClient => {
-    const fromEnv = input.cursorAccount ? {} : resolveOriginAppCredentialParts();
-    const appId = input.app?.appId ?? fromEnv.appId;
-    const installationId =
-      input.app?.installationId ?? input.installationId ?? fromEnv.installationId;
-    const privateKey = input.app?.privateKey ?? fromEnv.privateKey;
-    const credentials =
-      appId !== undefined && installationId !== undefined && privateKey !== undefined
-        ? { appId, installationId, privateKey }
-        : undefined;
-    return createOriginClient({
-      token: input.cursorAccount ? undefined : input.app?.token,
-      credentials: input.cursorAccount ? false : credentials,
-      apiBaseUrl,
-      fetch: input.fetch,
-    });
-  };
-
-  // Public REST and ConnectRPC are separate Origin deployments, so the
-  // handle keeps a client per host. Both stay lazy: a hook that touches
-  // neither needs no credential.
-  let restClient: OriginClient | undefined;
-  const getRestClient = (): OriginClient => {
-    restClient ??= buildClient(input.app?.apiBaseUrl);
-    return restClient;
-  };
-  let rpcClient: OriginClient | undefined;
-  const getRpcClient = (): OriginClient => {
-    rpcClient ??= buildClient(input.app?.rpcBaseUrl ?? originRpcBaseUrl());
-    return rpcClient;
-  };
-
-  return {
-    installationId: input.app?.installationId ?? input.installationId,
-    repository: input.repository,
-    request: request => getRestClient().request(request),
-    createCheck: check =>
-      createOriginCheck({
-        ...check,
-        executionId: check.executionId ?? input.executionId,
-        origin: getRestClient(),
-        owner: input.repository.owner,
-        repo: input.repository.name,
-      }),
-    reactToComment: reaction => setOriginCommentReaction({ ...reaction, origin: getRpcClient() }),
-  };
-}