@cursor/july 0.1.95 → 0.1.97

package/src/channels/origin/api.ts

@@ -1,22 +1,37 @@
 /**
  * Origin public REST helpers (`https://api.cursor.com/v1/origin/...`).
  *
- * Origin writes such as CI check runs are installation-only: they need an
- * `oit_…` installation token minted from Origin app credentials (EdDSA app
- * JWT → `/v1/origin/app/installations/{id}/access_tokens`). This module
- * consolidates that flow so agents configure credentials once and call
- * {@link createOriginClient} — the GitHub-channel analogue of
+ * This module consolidates Origin auth so agents configure credentials once
+ * and call {@link createOriginClient} — the GitHub-channel analogue of
  * `createGitHubOctokit`.
  *
- * Credentials resolve 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), and
- * `ORIGIN_API_BASE_URL` for the public REST base.
+ * 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
@@ -25,6 +40,15 @@ import { createPrivateKey, sign } from "node:crypto";
  */
 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;
@@ -58,7 +82,10 @@ export class OriginApiError extends Error {
   }
 }
 
-/** Yields a bearer for Origin REST calls (usually a short-lived `oit_…`). */
+/**
+ * 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 {
@@ -121,6 +148,12 @@ export function originPublicApiBaseUrl(
   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");
 }
@@ -181,6 +214,147 @@ async function mintOriginInstallationToken(input: {
   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 re-read on every mint so Bind can drop
+ * `CURSOR_API_KEY_FILE` onto a listening process; 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
@@ -217,13 +391,26 @@ export interface OriginClientOptions {
   token?: string | OriginTokenProvider;
   /**
    * App credentials to mint installation tokens from. Defaults to the
-   * environment ({@link resolveOriginAppCredentials}).
+   * environment ({@link resolveOriginAppCredentials}). Pass `false` to
+   * disable app credential lookup and force the Cursor-account exchange.
    */
-  credentials?: OriginAppCredentials;
+  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). */
@@ -242,8 +429,11 @@ export interface OriginClient {
 
 /**
  * Build an authenticated Origin REST client. Auth resolution: explicit
- * token/provider, then app credentials (options or environment). Missing
- * auth fails at the first request with a clear message.
+ * 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 = {}
@@ -255,6 +445,10 @@ export function createOriginClient(
   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;
@@ -263,21 +457,59 @@ export function createOriginClient(
       return await options.token();
     }
     if (tokenProvider === undefined) {
-      const credentials = options.credentials ?? resolveOriginAppCredentials();
-      if (credentials === 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, or set ORIGIN_APP_ID + ORIGIN_APP_INSTALLATION_ID + ORIGIN_APP_PRIVATE_KEY)."
+          "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)."
         );
       }
-      tokenProvider = originAppTokenProvider({
-        credentials,
-        apiBaseUrl,
-        fetch: fetchImpl,
-      });
     }
     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: {
@@ -287,16 +519,15 @@ export function createOriginClient(
     }): Promise<T> {
       const path = input.path.startsWith("/") ? input.path : `/${input.path}`;
       const token = await getToken();
-      const 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),
-      });
+      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 {

package/src/channels/origin/binding.ts

@@ -13,6 +13,7 @@ import {
   createOriginClient,
   type OriginApiMethod,
   type OriginClient,
+  originRpcBaseUrl,
   resolveOriginAppCredentialParts,
 } from "./api.js";
 import {
@@ -20,6 +21,10 @@ import {
   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`). */
@@ -38,59 +43,83 @@ export interface OriginHandle {
   }): Promise<T>;
   /**
    * Open a CI check run on `sha` and get a handle for updating and
-   * concluding it. Needs an app installation with
-   * `repository:checks:write` — Origin check writes are installation-only.
+   * 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;
+  /** 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 {
-  let client: OriginClient | undefined;
-  const getClient = (): OriginClient => {
-    if (client === undefined) {
-      const fromEnv = 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;
-      client = createOriginClient({
-        token: input.app?.token,
-        credentials,
-        apiBaseUrl: input.app?.apiBaseUrl,
-        fetch: input.fetch,
-      });
-    }
-    return client;
+  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) => getClient().request(request),
+    request: (request) => getRestClient().request(request),
     createCheck: (check) =>
       createOriginCheck({
         ...check,
-        origin: getClient(),
+        origin: getRestClient(),
         owner: input.repository.owner,
         repo: input.repository.name,
       }),
+    reactToComment: (reaction) =>
+      setOriginCommentReaction({ ...reaction, origin: getRpcClient() }),
   };
 }

package/src/channels/origin/checks.ts

@@ -7,12 +7,12 @@
  * fresh `externalUpdatedAt`, and `resumeOriginCheck` needs only those
  * identity fields (no server id) to rebuild a handle after a restart.
  *
- * Posting needs `repository:checks:write` and is installation-only: the
- * client must authenticate with an `oit_…` installation token (see
- * `createOriginClient` / `originAppTokenProvider` in `api.js`). Works with
- * any client exposing `request()` (`ctx.origin`, `createOriginClient()`),
- * and is also reachable as `ctx.origin.createCheck(...)`. API failures throw
- * `OriginApiError`.
+ * 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 {

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

@@ -3,9 +3,11 @@
  *
  * 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. Unlike GitHub,
- * there is no installation token to mint — outbound Origin API calls already
- * authenticate as the Cursor principal.
+ * `/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";

package/src/channels/origin/index.ts

@@ -29,4 +29,5 @@ export * from "./cursor-account.js";
 export * from "./events.js";
 export * from "./origin-channel.js";
 export * from "./origin-webhook.js";
+export * from "./reactions.js";
 export * from "./types.js";

package/src/channels/origin/origin-channel.ts

@@ -306,6 +306,7 @@ export function parseOriginPullRequestEvent(input: {
       repository,
       pullRequestNumber: number,
       pullRequestUrl: url,
+      pullRequestAuthor: author,
       payload,
       sender: originSender(input.envelope, payload),
     },
@@ -432,6 +433,9 @@ function enrichEventContext(input: {
     origin: buildOriginBinding({
       repository: input.ctx.repository,
       installationId: input.ctx.installationId,
+      cursorAccount:
+        input.options.cursorAccount !== undefined &&
+        input.options.cursorAccount !== false,
       app: input.options.app,
     }),
   };

package/src/channels/origin/reactions.ts

@@ -0,0 +1,82 @@
+/**
+ * Origin PR comment reactions — the Origin analogue of the GitHub channel's
+ * `thread.react("eyes")`.
+ *
+ * Unlike checks and comments, reactions have no `/v1/origin/...` REST
+ * binding. The only write is Connect unary JSON against Origin's first-party
+ * service (`origin.v1.OriginService/SetCommentReaction`), which lives on a
+ * different host than the public REST API — {@link originRpcBaseUrl}, not
+ * {@link originPublicApiBaseUrl}. `ctx.origin.reactToComment` already points
+ * at the right one; a hand-built client must too.
+ *
+ * Writing needs `repository:pull_requests:reviews:write`: an `oit_…`
+ * installation token for app channels, or a deployment service-account
+ * session (hosted v2 forks). Origin rejects reactions on comments that
+ * belong to an unsubmitted review. API failures throw `OriginApiError`.
+ */
+
+import type { OriginApiMethod } from "./api.js";
+
+/** Any client that can call Origin's ConnectRPC host. */
+export interface OriginReactionClient {
+  request<T = unknown>(input: {
+    method: OriginApiMethod;
+    path: string;
+    body?: unknown;
+  }): Promise<T>;
+}
+
+/** Connect unary route backing {@link setOriginCommentReaction}. */
+export const SET_ORIGIN_COMMENT_REACTION_PATH =
+  "/origin.v1.OriginService/SetCommentReaction";
+
+/**
+ * The eight reactions Origin accepts. Anything else is rejected with
+ * `invalid_argument`, so channels get a compile error instead of a 400.
+ */
+export const ORIGIN_COMMENT_REACTIONS = [
+  "👍",
+  "👎",
+  "😄",
+  "🎉",
+  "😕",
+  "❤️",
+  "🚀",
+  "👀",
+] as const;
+
+export type OriginCommentReaction = (typeof ORIGIN_COMMENT_REACTIONS)[number];
+
+export interface OriginCommentReactionInput {
+  /** Origin comment TypeID (`cmt_…`), i.e. `comment.id` on a comment hook. */
+  commentId: string;
+  emoji: OriginCommentReaction;
+  /** `false` removes the reaction. Removing one that is absent is a no-op. */
+  active?: boolean;
+}
+
+/**
+ * Add (or, with `active: false`, remove) one reaction on an Origin PR
+ * comment as the client's own principal.
+ *
+ * ```ts
+ * await setOriginCommentReaction({
+ *   origin: createOriginClient({ apiBaseUrl: originRpcBaseUrl() }),
+ *   commentId: comment.id,
+ *   emoji: "👀",
+ * });
+ * ```
+ */
+export async function setOriginCommentReaction(
+  input: OriginCommentReactionInput & { origin: OriginReactionClient }
+): Promise<void> {
+  await input.origin.request({
+    method: "POST",
+    path: SET_ORIGIN_COMMENT_REACTION_PATH,
+    body: {
+      commentId: input.commentId,
+      emoji: input.emoji,
+      active: input.active ?? true,
+    },
+  });
+}