@cursor/july 0.1.94 → 0.1.96

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), and `ORIGIN_API_BASE_URL` for the public
+ * REST 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
@@ -58,7 +73,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 {
@@ -181,6 +199,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
@@ -224,6 +383,18 @@ export interface OriginClientOptions {
   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 +413,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 +429,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;
@@ -264,20 +442,55 @@ export function createOriginClient(
     }
     if (tokenProvider === undefined) {
       const credentials = options.credentials ?? resolveOriginAppCredentials();
-      if (credentials === undefined) {
+      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 +500,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

@@ -38,8 +38,8 @@ 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">

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/origin-channel.ts

@@ -26,6 +26,7 @@ import {
 import { deriveOriginWebhookEvents, ORIGIN_CHANNEL_KIND } from "./events.js";
 import {
   DEFAULT_ORIGIN_API_BASE_URL,
+  OriginJwksUnavailableError,
   type OriginWebhookHeaders,
   verifyOriginWebhook,
 } from "./origin-webhook.js";
@@ -300,10 +301,12 @@ export function parseOriginPullRequestEvent(input: {
     ctx: {
       deliveryId: input.envelope.deliveryId,
       eventType,
+      eventTime: input.envelope.event.eventTime,
       installationId: input.envelope.installationId,
       repository,
       pullRequestNumber: number,
       pullRequestUrl: url,
+      payload,
       sender: originSender(input.envelope, payload),
     },
     pullRequest: {
@@ -687,7 +690,16 @@ export async function handleOriginWebhookRequest(input: {
       await verifyOriginWebhook(bodyText, originHeaders(input.request), {
         apiBaseUrl: resolveApiBaseUrl(input.options),
       });
-    } catch {
+    } catch (error) {
+      // A JWKS outage means the delivery was never checked: answer 503 so
+      // Origin's delivery worker retries. Only a real signature mismatch
+      // is the terminal 401.
+      if (error instanceof OriginJwksUnavailableError) {
+        return Response.json(
+          { ok: false, error: "signature_verification_unavailable" },
+          { status: 503 }
+        );
+      }
       return Response.json(
         { ok: false, error: "invalid_signature" },
         { status: 401 }

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

@@ -247,7 +247,31 @@ export interface VerifyOriginWebhookOptions {
 }
 
 /**
- * Verify a Standard-Webhooks v1ed Origin payload. Throws on failure.
+ * The signing JWKS could not be fetched (and no cached copy applies), so
+ * the delivery was never actually checked. Callers must answer retryably
+ * (5xx) — a 401 would make Origin's delivery worker drop the wake as
+ * terminal on what is only a transient outage.
+ */
+export class OriginJwksUnavailableError extends Error {}
+
+async function fetchJwksOrUnavailable(
+  apiBaseUrl: string,
+  fetchImpl: typeof fetch,
+  options?: FetchOriginJwksOptions
+): Promise<readonly OriginJwk[]> {
+  try {
+    return await fetchOriginJwks(apiBaseUrl, fetchImpl, options);
+  } catch (error) {
+    throw new OriginJwksUnavailableError(
+      `Origin JWKS unavailable: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Verify a Standard-Webhooks v1ed Origin payload. Throws
+ * {@link OriginJwksUnavailableError} when the keys cannot be fetched, and a
+ * plain error when the signature does not verify against them.
  */
 export async function verifyOriginWebhook(
   body: string | Buffer,
@@ -256,7 +280,7 @@ export async function verifyOriginWebhook(
 ): Promise<void> {
   const apiBaseUrl = options?.apiBaseUrl ?? DEFAULT_ORIGIN_API_BASE_URL;
   const fetchImpl = options?.fetchImpl ?? fetch;
-  const keys = await fetchOriginJwks(apiBaseUrl, fetchImpl);
+  const keys = await fetchJwksOrUnavailable(apiBaseUrl, fetchImpl);
   if (
     verifyV1edWebhookPayload({
       publicJwks: keys,
@@ -267,7 +291,7 @@ export async function verifyOriginWebhook(
   ) {
     return;
   }
-  const refreshed = await fetchOriginJwks(apiBaseUrl, fetchImpl, {
+  const refreshed = await fetchJwksOrUnavailable(apiBaseUrl, fetchImpl, {
     force: true,
   });
   if (

package/src/channels/origin/types.ts

@@ -51,11 +51,19 @@ export interface OriginReview {
 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;
+  /**
+   * 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;
   host: HostContext;
   artifacts: ArtifactsApi;

package/src/channels/slack/api.ts

@@ -193,6 +193,12 @@ export function truncateTitle(title: string, max?: number): string {
 // Assistant / stream helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Show or clear the Working chip. Agent UX ignores empty
+ * `assistant.threads.setStatus`; `agents.sessions.setStatus` `active` is
+ * what actually clears it. The assistant call stays for loading_messages
+ * and older workspaces.
+ */
 export async function setThreadStatus(args: {
   botToken: SlackBotToken | undefined;
   channelId: string;
@@ -204,13 +210,21 @@ export async function setThreadStatus(args: {
     return { ok: false, error: "missing_channel_or_thread" };
   }
   const status = truncateTypingStatus(args.status);
+  const sessionResult = await callSlackApiSoft({
+    botToken: args.botToken,
+    operation: "agents.sessions.setStatus",
+    body: {
+      channel_id: args.channelId,
+      thread_ts: args.threadTs,
+      status: status.length > 0 ? "processing" : "active",
+    },
+  });
+
   const body: Record<string, unknown> = {
     channel_id: args.channelId,
     thread_ts: args.threadTs,
     status,
   };
-  // Empty status clears Slack's assistant chip ("App is working…").
-  // Sending loading_messages with it keeps the chip rotating.
   if (status.length > 0) {
     const loadingRaw =
       args.loadingMessages !== undefined && args.loadingMessages.length > 0
@@ -224,11 +238,19 @@ export async function setThreadStatus(args: {
       body.loading_messages = loading_messages;
     }
   }
-  return callSlackApiSoft({
+  const assistantResult = await callSlackApiSoft({
     botToken: args.botToken,
     operation: "assistant.threads.setStatus",
     body,
   });
+
+  if (sessionResult.ok) {
+    return sessionResult;
+  }
+  if (sessionResult.unsupported === true || assistantResult.ok) {
+    return assistantResult;
+  }
+  return sessionResult;
 }
 
 export async function setThreadTitle(args: {
@@ -278,16 +300,30 @@ export async function startChatStream(args: {
   channel: string;
   thread_ts?: string;
   markdown_text?: string;
+  chunks?: StreamTaskChunk[];
+  recipient_user_id?: string;
+  recipient_team_id?: string;
 }): Promise<SoftSlackResult<{ ts: string; channel: string }>> {
   const body: Record<string, unknown> = {
     channel: args.channel,
   };
+  // Empty markdown_text is rejected or opens a stream the assistant pane
+  // never attaches. Recipients are required outside DMs.
   if (args.thread_ts !== undefined && args.thread_ts !== "") {
     body.thread_ts = args.thread_ts;
   }
-  if (args.markdown_text !== undefined) {
+  if (args.markdown_text !== undefined && args.markdown_text !== "") {
     body.markdown_text = args.markdown_text;
   }
+  if (args.chunks !== undefined && args.chunks.length > 0) {
+    body.chunks = args.chunks;
+  }
+  if (args.recipient_user_id !== undefined && args.recipient_user_id !== "") {
+    body.recipient_user_id = args.recipient_user_id;
+  }
+  if (args.recipient_team_id !== undefined && args.recipient_team_id !== "") {
+    body.recipient_team_id = args.recipient_team_id;
+  }
   const result = await callSlackApiSoft({
     botToken: args.botToken,
     operation: "chat.startStream",
@@ -642,7 +678,7 @@ export function buildSlackBinding(args: {
         ...(loadingMessages === undefined ? {} : { loadingMessages }),
       });
       if (!result.ok) {
-        log.warn("assistant.threads.setStatus not-ok", {
+        log.warn("slack setStatus not-ok", {
           error: result.error,
           channel: args.channelId,
           thread_ts: threadTs,