@cursor/bdk 0.2.1

package/dist/channels/origin/api.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+/**
+ * Public Origin REST base (check runs, installation tokens). Distinct from
+ * the webhook JWKS base (`DEFAULT_ORIGIN_API_BASE_URL` in
+ * `origin-webhook.ts`).
+ */
+export declare 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 declare const DEFAULT_ORIGIN_RPC_BASE_URL = "https://api.origin.cursor.com";
+export type OriginApiMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+/** Normalized Origin REST failure — the `GitHubApiError` analogue. */
+export declare 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;
+    });
+}
+/**
+ * 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;
+}
+/** Each Origin app credential field found in the environment, when set. */
+export declare function resolveOriginAppCredentialParts(env?: NodeJS.ProcessEnv): Partial<OriginAppCredentials>;
+/**
+ * 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 declare function resolveOriginAppCredentials(env?: NodeJS.ProcessEnv): OriginAppCredentials | undefined;
+/** Public Origin REST base. Trailing slashes are stripped for path joins. */
+export declare function originPublicApiBaseUrl(env?: NodeJS.ProcessEnv): string;
+/** Origin ConnectRPC base. Trailing slashes are stripped for path joins. */
+export declare function originRpcBaseUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * Exchange endpoint for Cursor-account session tokens. Override with
+ * `AGENT_SERVE_CURSOR_SESSION_EXCHANGE_URL`; defaults to the Cursor backend.
+ */
+export declare function resolveCursorSessionExchangeUrl(): string;
+/**
+ * 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;
+};
+/** Test-only: drop the process-wide exchanged-session cache. */
+export declare function _clearCursorSessionTokenCacheForTesting(): void;
+export declare 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;
+/**
+ * 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 declare function originAppTokenProvider(input: {
+    credentials: OriginAppCredentials;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+}): OriginTokenProvider;
+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 declare function createOriginClient(options?: OriginClientOptions): OriginClient;
+//# sourceMappingURL=api.d.ts.map

package/dist/channels/origin/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/channels/origin/api.ts"],"names":[],"mappings":"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"}

package/dist/channels/origin/api.js

@@ -0,0 +1,379 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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 = 30000;
+/** Normalized Origin REST failure — the `GitHubApiError` analogue. */
+export class OriginApiError extends Error {
+    constructor(input) {
+        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;
+    }
+}
+/** Vault/env round-trip: literal `\n` sequences appear in practice. */
+function normalizePrivateKeyPem(raw) {
+    const pem = raw === null || raw === void 0 ? void 0 : raw.trim().replace(/\\n/g, "\n");
+    return pem === undefined || pem === "" ? undefined : pem;
+}
+function envValue(value) {
+    const trimmed = value === null || value === void 0 ? void 0 : value.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+/** Each Origin app credential field found in the environment, when set. */
+export function resolveOriginAppCredentialParts(env = process.env) {
+    var _a;
+    return {
+        appId: (_a = envValue(env.ORIGIN_APP_ID)) !== null && _a !== void 0 ? _a : 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 = process.env) {
+    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 = process.env) {
+    var _a;
+    const fromEnv = (_a = envValue(env.ORIGIN_API_BASE_URL)) === null || _a === void 0 ? void 0 : _a.replace(/\/+$/, "");
+    return fromEnv !== null && fromEnv !== void 0 ? fromEnv : DEFAULT_ORIGIN_PUBLIC_API_BASE_URL;
+}
+/** Origin ConnectRPC base. Trailing slashes are stripped for path joins. */
+export function originRpcBaseUrl(env = process.env) {
+    var _a;
+    const fromEnv = (_a = envValue(env.ORIGIN_RPC_BASE_URL)) === null || _a === void 0 ? void 0 : _a.replace(/\/+$/, "");
+    return fromEnv !== null && fromEnv !== void 0 ? fromEnv : DEFAULT_ORIGIN_RPC_BASE_URL;
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function mintOriginAppJwt(credentials, nowMs) {
+    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}`;
+}
+function mintOriginInstallationToken(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const jwt = mintOriginAppJwt(input.credentials, input.nowMs);
+        const path = `/v1/origin/app/installations/${encodeURIComponent(input.credentials.installationId)}/access_tokens`;
+        const response = yield input.fetchImpl(`${input.apiBaseUrl}${path}`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${jwt}` },
+            signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
+        });
+        const body = yield response.json().catch(() => undefined);
+        const token = typeof body === "object" && body !== null && !Array.isArray(body)
+            ? body.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() {
+    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}`;
+}
+/**
+ * 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();
+const cursorSessionTokenInFlight = new Map();
+/** Test-only: drop the process-wide exchanged-session cache. */
+export function _clearCursorSessionTokenCacheForTesting() {
+    cursorSessionTokenCache.clear();
+    cursorSessionTokenInFlight.clear();
+}
+export function cursorSessionTokenProvider(input) {
+    var _a, _b, _c;
+    const getApiKey = (_a = input === null || input === void 0 ? void 0 : input.getApiKey) !== null && _a !== void 0 ? _a : (() => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; });
+    const fetchImpl = (_b = input === null || input === void 0 ? void 0 : input.fetch) !== null && _b !== void 0 ? _b : fetch;
+    const now = (_c = input === null || input === void 0 ? void 0 : input.now) !== null && _c !== void 0 ? _c : Date.now;
+    const cacheKey = (url, apiKey) => `${url}\u0000${apiKey}`;
+    const resolveUrl = () => { var _a; return (_a = input === null || input === void 0 ? void 0 : input.exchangeUrl) !== null && _a !== void 0 ? _a : resolveCursorSessionExchangeUrl(); };
+    const mint = (url, apiKey) => __awaiter(this, void 0, void 0, function* () {
+        const nowMs = now();
+        let session;
+        try {
+            session = yield 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 + 1000, session.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS);
+        cursorSessionTokenCache.set(cacheKey(url, apiKey), {
+            token: session.token,
+            renewAtMs,
+        });
+        return session.token;
+    });
+    const provider = () => __awaiter(this, void 0, void 0, function* () {
+        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 yield inFlight;
+        }
+        const pending = mint(url, apiKey).finally(() => {
+            cursorSessionTokenInFlight.delete(key);
+        });
+        cursorSessionTokenInFlight.set(key, pending);
+        return yield 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) => {
+        var _a;
+        const apiKey = getApiKey();
+        if (apiKey === undefined || apiKey === "") {
+            return;
+        }
+        const key = cacheKey(resolveUrl(), apiKey);
+        if (((_a = cursorSessionTokenCache.get(key)) === null || _a === void 0 ? void 0 : _a.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) {
+    var _a, _b, _c;
+    const apiBaseUrl = (_a = input.apiBaseUrl) !== null && _a !== void 0 ? _a : originPublicApiBaseUrl();
+    const fetchImpl = (_b = input.fetch) !== null && _b !== void 0 ? _b : fetch;
+    const now = (_c = input.now) !== null && _c !== void 0 ? _c : Date.now;
+    let cached;
+    return () => __awaiter(this, void 0, void 0, function* () {
+        const nowMs = now();
+        if (cached !== undefined && nowMs - cached.mintedAtMs < TOKEN_REUSE_MS) {
+            return cached.token;
+        }
+        const token = yield mintOriginInstallationToken({
+            credentials: input.credentials,
+            apiBaseUrl,
+            fetchImpl,
+            nowMs,
+        });
+        cached = { token, mintedAtMs: nowMs };
+        return token;
+    });
+}
+/**
+ * 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 = {}) {
+    var _a, _b;
+    const apiBaseUrl = ((_a = options.apiBaseUrl) !== null && _a !== void 0 ? _a : originPublicApiBaseUrl()).replace(/\/+$/, "");
+    const fetchImpl = (_b = options.fetch) !== null && _b !== void 0 ? _b : fetch;
+    let tokenProvider;
+    // 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;
+    const getToken = () => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        if (typeof options.token === "string") {
+            return options.token;
+        }
+        if (typeof options.token === "function") {
+            return yield options.token();
+        }
+        if (tokenProvider === undefined) {
+            const credentials = options.credentials === false
+                ? undefined
+                : ((_a = options.credentials) !== null && _a !== void 0 ? _a : resolveOriginAppCredentials());
+            const exchange = (_b = options.cursorAccountExchange) !== null && _b !== void 0 ? _b : true;
+            const exchangeOptions = exchange === false ? undefined : exchange === true ? {} : exchange;
+            const getExchangeApiKey = (_c = exchangeOptions === null || exchangeOptions === void 0 ? void 0 : exchangeOptions.getApiKey) !== null && _c !== void 0 ? _c : (() => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; });
+            if (credentials !== undefined) {
+                tokenProvider = originAppTokenProvider({
+                    credentials,
+                    apiBaseUrl,
+                    fetch: fetchImpl,
+                });
+            }
+            else if (exchangeOptions !== undefined && ((_d = getExchangeApiKey()) !== null && _d !== void 0 ? _d : "") !== "") {
+                sessionProvider = cursorSessionTokenProvider(Object.assign({ 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 yield tokenProvider();
+    });
+    const send = (input, path, token) => __awaiter(this, void 0, void 0, function* () {
+        return yield fetchImpl(`${apiBaseUrl}${path}`, {
+            method: input.method,
+            headers: Object.assign({ authorization: `Bearer ${token}` }, (input.body === undefined ? {} : { "content-type": "application/json" })),
+            body: input.body === undefined ? undefined : JSON.stringify(input.body),
+        });
+    });
+    return {
+        apiBaseUrl,
+        request(input) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
+                const token = yield getToken();
+                let response = yield 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.
+                    yield response.text().catch(() => undefined);
+                    sessionProvider.invalidate(token);
+                    const retryToken = yield getToken();
+                    response = yield send(input, path, retryToken);
+                }
+                const text = yield response.text();
+                let parsed;
+                try {
+                    parsed = text === "" ? undefined : JSON.parse(text);
+                }
+                catch (_a) {
+                    parsed = text;
+                }
+                if (!response.ok) {
+                    throw new OriginApiError({
+                        body: parsed,
+                        method: input.method,
+                        path,
+                        status: response.status,
+                    });
+                }
+                return parsed;
+            });
+        },
+    };
+}

package/dist/channels/origin/binding.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { type OriginApiMethod } from "./api.js";
+import { type OriginCheck, type OriginCheckCreateInput } from "./checks.js";
+import { type OriginCommentReactionInput } 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 declare 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;
+//# sourceMappingURL=binding.d.ts.map

package/dist/channels/origin/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../../src/channels/origin/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,KAAK,eAAe,EAIrB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EAAE,KAAK,0BAA0B,EAA4B,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAExE,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE;QAC1B,MAAM,EAAE,eAAe,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACf;;;;OAIG;IACH,WAAW,CACT,KAAK,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC,GAC/D,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,UAAU,EAAE,mBAAmB,CAAC;IAChC,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB,GAAG,YAAY,CA+Cf"}

package/dist/channels/origin/binding.js

@@ -0,0 +1,57 @@
+/**
+ * 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, originRpcBaseUrl, resolveOriginAppCredentialParts, } from "./api.js";
+import { createOriginCheck } from "./checks.js";
+import { setOriginCommentReaction } from "./reactions.js";
+export function buildOriginBinding(input) {
+    var _a;
+    var _b;
+    const buildClient = (apiBaseUrl) => {
+        var _a, _b, _c, _d;
+        var _e, _f, _g, _h;
+        const fromEnv = input.cursorAccount ? {} : resolveOriginAppCredentialParts();
+        const appId = (_e = (_a = input.app) === null || _a === void 0 ? void 0 : _a.appId) !== null && _e !== void 0 ? _e : fromEnv.appId;
+        const installationId = (_g = (_f = (_b = input.app) === null || _b === void 0 ? void 0 : _b.installationId) !== null && _f !== void 0 ? _f : input.installationId) !== null && _g !== void 0 ? _g : fromEnv.installationId;
+        const privateKey = (_h = (_c = input.app) === null || _c === void 0 ? void 0 : _c.privateKey) !== null && _h !== void 0 ? _h : fromEnv.privateKey;
+        const credentials = appId !== undefined && installationId !== undefined && privateKey !== undefined
+            ? { appId, installationId, privateKey }
+            : undefined;
+        return createOriginClient({
+            token: input.cursorAccount ? undefined : (_d = input.app) === null || _d === void 0 ? void 0 : _d.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;
+    const getRestClient = () => {
+        var _a;
+        restClient !== null && restClient !== void 0 ? restClient : (restClient = buildClient((_a = input.app) === null || _a === void 0 ? void 0 : _a.apiBaseUrl));
+        return restClient;
+    };
+    let rpcClient;
+    const getRpcClient = () => {
+        var _a;
+        var _b;
+        rpcClient !== null && rpcClient !== void 0 ? rpcClient : (rpcClient = buildClient((_b = (_a = input.app) === null || _a === void 0 ? void 0 : _a.rpcBaseUrl) !== null && _b !== void 0 ? _b : originRpcBaseUrl()));
+        return rpcClient;
+    };
+    return {
+        installationId: (_b = (_a = input.app) === null || _a === void 0 ? void 0 : _a.installationId) !== null && _b !== void 0 ? _b : input.installationId,
+        repository: input.repository,
+        request: request => getRestClient().request(request),
+        createCheck: check => { var _a; return createOriginCheck(Object.assign(Object.assign({}, check), { executionId: (_a = check.executionId) !== null && _a !== void 0 ? _a : input.executionId, origin: getRestClient(), owner: input.repository.owner, repo: input.repository.name })); },
+        reactToComment: reaction => setOriginCommentReaction(Object.assign(Object.assign({}, reaction), { origin: getRpcClient() })),
+    };
+}