@stigmer/runner 3.0.1

package/src/activities/execute-cursor/error-classifier.ts

@@ -0,0 +1,247 @@
+/**
+ * Classifies Cursor SDK errors into actionable categories.
+ *
+ * Used after run.wait() returns status: "error" to:
+ * 1. Determine whether the poisoned-handle retry should fire
+ * 2. Prefix status.error with a human-readable category
+ * 3. Surface isRetryable for future workflow-level retry decisions
+ *
+ * Error detail can come from several sources (in priority order):
+ * - A thrown CursorSdkError's structured fields (highest fidelity)
+ * - run.wait().result (SDK-provided string, often bare/generic)
+ * - SDKStatusMessage with status "ERROR" from the stream
+ * - ConnectError captured from process unhandledRejection
+ * - Text extracted from the failing run.conversation() turn
+ *
+ * Execution context (isResumedHandle) is applied as a post-classification
+ * override: when no source can positively identify the error category and
+ * the agent was obtained via resume, the error is upgraded to "agent-stale"
+ * so that poisoned-handle recovery fires.
+ */
+
+import type { CapturedRejection } from "./rejection-capture.js";
+
+export type ErrorCategory =
+  | "auth"
+  | "rate-limit"
+  | "network"
+  | "agent-stale"
+  | "model"
+  | "unknown";
+
+export interface ClassifiedError {
+  category: ErrorCategory;
+  message: string;
+  retryable: boolean;
+  source: "sdk" | "stream" | "rejection" | "conversation" | "fallback";
+}
+
+/**
+ * Structured fields lifted from a thrown CursorSdkError (errors.d.ts:
+ * { code, status, isRetryable, cause, endpoint, requestId, operation }).
+ * Only the fields used for classification are retained.
+ */
+export interface SdkErrorFields {
+  code?: string;
+  status?: number;
+  message?: string;
+}
+
+const AUTH_PATTERNS = [
+  "unauthenticated", "unauthorized", "401", "forbidden",
+  "permission_denied", "invalid api key", "not logged in",
+];
+const RATE_LIMIT_PATTERNS = [
+  "resource_exhausted", "rate limit", "429", "too many",
+  "usage limit",
+];
+const NETWORK_PATTERNS = [
+  "unavailable", "deadline_exceeded", "503", "504",
+  "timeout", "econnrefused", "econnreset", "enotfound",
+  "network error", "fetch failed", "refused_stream",
+];
+const MODEL_PATTERNS = [
+  "invalid model", "model not found", "model.*not available",
+  "unsupported model",
+];
+
+function matchesAny(text: string, patterns: string[]): boolean {
+  const lower = text.toLowerCase();
+  return patterns.some((p) => lower.includes(p));
+}
+
+function classifyText(text: string): { category: ErrorCategory; retryable: boolean } {
+  if (matchesAny(text, AUTH_PATTERNS)) return { category: "auth", retryable: false };
+  if (matchesAny(text, RATE_LIMIT_PATTERNS)) return { category: "rate-limit", retryable: true };
+  if (matchesAny(text, NETWORK_PATTERNS)) return { category: "network", retryable: true };
+  if (matchesAny(text, MODEL_PATTERNS)) return { category: "model", retryable: false };
+  return { category: "unknown", retryable: false };
+}
+
+interface SynthesizeErrorOpts {
+  /** Structured fields from a thrown CursorSdkError — highest-fidelity source. */
+  sdkError?: SdkErrorFields;
+  sdkResultFields: string | undefined;
+  streamErrorMessage: string | undefined;
+  capturedRejection: CapturedRejection | undefined;
+  /** Text extracted from the failing run.conversation() turn, if any. */
+  conversationErrorText?: string;
+  isResumedHandle: boolean;
+  fallbackContext: { model: string; mode: string; agentId: string };
+  /** Duration of the SDK run in ms — used for transport timeout heuristic. */
+  durationMs?: number;
+  /** Number of messages received from the stream (0 = no response at all). */
+  messageCount?: number;
+}
+
+/**
+ * Synthesize a classified error from up to three sources, then apply
+ * execution context.
+ *
+ * Two-step process:
+ * 1. Classify from the best available source (SDK > stream > rejection > fallback).
+ * 2. Apply execution context: on resumed handles, "unknown" from any source
+ *    is upgraded to "agent-stale" so poisoned-handle recovery can fire.
+ *
+ * The override only applies to "unknown" — specific diagnoses (auth,
+ * rate-limit, network, model) are never overridden, even on resumed handles.
+ */
+export function synthesizeError(opts: SynthesizeErrorOpts): ClassifiedError {
+  console.log(
+    `[error-classifier] synthesizeError diagnostic: ` +
+    `sdkError=${JSON.stringify(opts.sdkError)}, ` +
+    `sdkResultFields=${JSON.stringify(opts.sdkResultFields)}, ` +
+    `streamErrorMessage=${JSON.stringify(opts.streamErrorMessage)}, ` +
+    `hasCapturedRejection=${!!opts.capturedRejection}, ` +
+    `conversationErrorText=${JSON.stringify(opts.conversationErrorText)}, ` +
+    `isResumedHandle=${opts.isResumedHandle}, ` +
+    `model=${opts.fallbackContext.model}, mode=${opts.fallbackContext.mode}`,
+  );
+
+  const classified = classifyFromSources(opts);
+
+  if (classified.category === "unknown" && opts.isResumedHandle) {
+    return { ...classified, category: "agent-stale", retryable: true };
+  }
+
+  return classified;
+}
+
+/**
+ * Classify from the best available error source.
+ *
+ * Priority: thrown CursorSdkError > SDK result fields > stream ERROR message >
+ * captured ConnectError > conversation error turn > transport-timeout heuristic.
+ * Falls back to a diagnostic message with model/mode/agentId context.
+ */
+function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
+  if (opts.sdkError) {
+    const { code, status, message } = opts.sdkError;
+    // Classify across all structured fields so a code/status alone (no message
+    // text) still resolves a category.
+    const text = [code, status != null ? String(status) : undefined, message]
+      .filter((v): v is string => typeof v === "string" && v.length > 0)
+      .join(" ");
+    if (text.trim().length > 0) {
+      const { category, retryable } = classifyText(text);
+      return {
+        category,
+        message: message ?? text,
+        retryable,
+        source: "sdk",
+      };
+    }
+  }
+
+  if (opts.sdkResultFields) {
+    const isBareGeneric = opts.sdkResultFields === "Cursor run failed";
+    if (!isBareGeneric) {
+      const { category, retryable } = classifyText(opts.sdkResultFields);
+      return {
+        category,
+        message: opts.sdkResultFields,
+        retryable,
+        source: "sdk",
+      };
+    }
+  }
+
+  if (opts.streamErrorMessage) {
+    const { category, retryable } = classifyText(opts.streamErrorMessage);
+    return {
+      category,
+      message: opts.streamErrorMessage,
+      retryable,
+      source: "stream",
+    };
+  }
+
+  if (opts.capturedRejection) {
+    const { category } = classifyText(
+      `${opts.capturedRejection.code} ${opts.capturedRejection.message}`,
+    );
+    return {
+      category: category === "unknown" ? "network" : category,
+      message: `[${opts.capturedRejection.code}] ${opts.capturedRejection.message}`,
+      retryable: category !== "auth",
+      source: "rejection",
+    };
+  }
+
+  // The SDK frequently swallows the real reason in run.wait() but retains it on
+  // the failing conversation turn. Surface that text even when it does not match
+  // a known pattern — a specific message beats the generic fallback.
+  if (opts.conversationErrorText) {
+    const { category, retryable } = classifyText(opts.conversationErrorText);
+    return {
+      category,
+      message: opts.conversationErrorText,
+      retryable,
+      source: "conversation",
+    };
+  }
+
+  // Transport timeout heuristic: SDK returned error with 0 messages and
+  // duration ~30s (default SDK timeout). This indicates the proxy connection
+  // was degraded and the agent stream could not be established at all.
+  if (
+    opts.messageCount === 0
+    && opts.durationMs != null
+    && opts.durationMs >= 25000
+    && opts.durationMs <= 35000
+    && !opts.isResumedHandle
+  ) {
+    const { model, mode, agentId } = opts.fallbackContext;
+    return {
+      category: "network",
+      message: `Transport timeout (${opts.durationMs}ms, 0 messages received). Model=${model}, mode=${mode}, agentId=${agentId}`,
+      retryable: true,
+      source: "fallback",
+    };
+  }
+
+  if (opts.isResumedHandle) {
+    return {
+      category: "agent-stale",
+      message: "Cursor run failed (no detail from SDK, resumed agent handle may be stale)",
+      retryable: true,
+      source: "fallback",
+    };
+  }
+
+  const { model, mode, agentId } = opts.fallbackContext;
+  return {
+    category: "unknown",
+    message: `Cursor run failed (no detail from SDK). Model=${model}, mode=${mode}, agentId=${agentId}`,
+    retryable: false,
+    source: "fallback",
+  };
+}
+
+export function formatClassifiedError(err: ClassifiedError): string {
+  return `${err.message} [category=${err.category}, source=${err.source}, retryable=${err.retryable}]`;
+}
+
+export function shouldRetryWithFreshAgent(err: ClassifiedError): boolean {
+  return err.category === "agent-stale" || err.category === "network";
+}

package/src/activities/execute-cursor/fetch-interceptor.ts

@@ -0,0 +1,382 @@
+/**
+ * Global fetch interceptor for Cursor SDK proxy support.
+ *
+ * In cloud mode, the cursor-runner must be credential-free -- it holds only
+ * STIGMER_TOKEN, never CURSOR_API_KEY. To achieve this, we intercept all
+ * outbound fetch() calls to Cursor's backend and rewrite them to go through
+ * Stigmer's CursorProxyController, which injects the real Cursor API key.
+ *
+ * This is the JavaScript-level equivalent of LangChain's base_url parameter
+ * that the Python agent-runner uses for the LLM proxy pattern.
+ *
+ * IMPORTANT: This module must be imported BEFORE @cursor/sdk to ensure the
+ * interceptor is in place when the SDK initializes its HTTP client.
+ *
+ * When STIGMER_PROXY_ENDPOINT is not set, this module is a no-op.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const CURSOR_DOMAINS = [
+  "api2.cursor.sh",
+  "api.cursor.com",
+  "api.cursor.sh",
+];
+
+interface ProxyConfig {
+  proxyEndpoint: string;
+  stigmerToken: string;
+  executionId?: string;
+}
+
+let interceptorConfig: ProxyConfig | null = null;
+const originalFetch = globalThis.fetch;
+
+interface ExecutionContextStore {
+  executionId: string;
+}
+
+const executionContext = new AsyncLocalStorage<ExecutionContextStore>();
+
+export function getExecutionContext(): AsyncLocalStorage<ExecutionContextStore> {
+  return executionContext;
+}
+
+/**
+ * Connect RPC path prefixes used by the Cursor SDK. Most requests with
+ * these prefixes go through connect-node (native HTTP/2) and are handled
+ * by the HTTP/2 interceptor. However, some SDK calls to these paths use
+ * fetch (HTTP/1.1) instead — e.g. BootstrapStatsig, LogStatsigExposure.
+ * Those still need proxy auth injection even though they don't need URL
+ * rewriting.
+ */
+const CONNECT_RPC_PREFIXES = ["/agent.v1.", "/aiserver.v1."];
+
+function isConnectRpcPath(pathname: string): boolean {
+  return CONNECT_RPC_PREFIXES.some((p) => pathname.startsWith(p));
+}
+
+/**
+ * Checks whether the URL targets the proxy endpoint itself. When
+ * CURSOR_BACKEND_URL is set to proxyEndpoint, SDK REST calls (token
+ * exchange, CloudApiClient) target this host instead of Cursor domains.
+ */
+function isProxyEndpointHost(parsed: URL, proxyEndpoint: string): boolean {
+  try {
+    const proxy = new URL(proxyEndpoint);
+    return parsed.hostname === proxy.hostname && parsed.port === proxy.port;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determines whether a fetch request needs URL rewriting through the
+ * CursorProxyController (/v1/proxy/cursor/...). This applies to REST
+ * calls (token exchange, /v1/models, agent CRUD) but NOT to Connect
+ * RPC paths which are dispatched directly by path routing.
+ */
+function needsUrlRewrite(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (CURSOR_DOMAINS.some((d) => parsed.hostname === d || parsed.hostname.endsWith(`.${d}`))) {
+      return true;
+    }
+    if (interceptorConfig && isProxyEndpointHost(parsed, interceptorConfig.proxyEndpoint)) {
+      return !isConnectRpcPath(parsed.pathname) && !parsed.pathname.startsWith("/v1/proxy/");
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determines whether a fetch request targets the proxy endpoint with a
+ * Connect-RPC-like path. The Cursor SDK sends some /aiserver.v1.* calls
+ * (BootstrapStatsig, analytics, telemetry) via fetch (HTTP/1.1) rather
+ * than connect-node (HTTP/2). These bypass the HTTP/2 interceptor, so
+ * this fetch interceptor must inject x-stigmer-auth to authenticate
+ * with the BiDi proxy. The URL is NOT rewritten — path routing delivers
+ * them to the BiDi proxy directly.
+ */
+function needsProxyAuthOnly(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (!interceptorConfig) return false;
+    if (!isProxyEndpointHost(parsed, interceptorConfig.proxyEndpoint)) return false;
+    return isConnectRpcPath(parsed.pathname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determines the upstream Cursor host for a given REST path.
+ *
+ * - /auth/* → api2.cursor.sh (token exchange, served by this host)
+ * - everything else → api.cursor.com (CloudApiClient REST: /v1/models, agent CRUD)
+ */
+function resolveUpstreamHost(pathname: string): string {
+  if (pathname.startsWith("/auth/") || pathname === "/auth") {
+    return "api2.cursor.sh";
+  }
+  return "api.cursor.com";
+}
+
+/**
+ * Rewrites a Cursor-bound URL to route through the Stigmer proxy.
+ *
+ * Two cases:
+ * 1. Direct Cursor-domain request (e.g. from CloudApiClient when CURSOR_BACKEND_URL unset):
+ *    https://api2.cursor.sh/auth/exchange_user_api_key
+ *    → https://api.stigmer.ai/v1/proxy/cursor/api2.cursor.sh/auth/exchange_user_api_key
+ *
+ * 2. Proxy-endpoint-targeted REST (when CURSOR_BACKEND_URL = proxyEndpoint):
+ *    http://localhost:9090/auth/exchange_user_api_key
+ *    → http://localhost:9090/v1/proxy/cursor/api2.cursor.sh/auth/exchange_user_api_key
+ *    The upstream host is inferred from the path since it's not in the URL.
+ *
+ * The proxy uses the embedded original hostname to route to the correct
+ * upstream Cursor service.
+ */
+function rewriteUrl(originalUrl: string, proxyEndpoint: string): string {
+  const parsed = new URL(originalUrl);
+  const proxyBase = proxyEndpoint.replace(/\/+$/, "");
+
+  // Proxy-endpoint-targeted request: CURSOR_BACKEND_URL sent this here.
+  // The hostname IS the proxy, so infer the upstream from the path.
+  if (interceptorConfig && isProxyEndpointHost(parsed, proxyEndpoint)) {
+    const upstream = resolveUpstreamHost(parsed.pathname);
+    return `${proxyBase}/v1/proxy/cursor/${upstream}${parsed.pathname}${parsed.search}`;
+  }
+
+  // Direct Cursor-domain request: hostname IS the upstream.
+  return `${proxyBase}/v1/proxy/cursor/${parsed.hostname}${parsed.pathname}${parsed.search}`;
+}
+
+/**
+ * Replaces the authorization header with the Stigmer token. Used for
+ * REST calls routed through CursorProxyController, where the proxy
+ * itself authenticates with Cursor using the configured API key.
+ */
+function replaceAuth(init: RequestInit | undefined, config: ProxyConfig): RequestInit {
+  const headers = new Headers(init?.headers);
+  headers.set("authorization", `Bearer ${config.stigmerToken}`);
+  const ctx = executionContext.getStore();
+  const effectiveExecutionId = ctx?.executionId ?? config.executionId;
+  if (effectiveExecutionId) {
+    headers.set("x-stigmer-execution-id", effectiveExecutionId);
+  }
+  return { ...init, headers };
+}
+
+/**
+ * Injects x-stigmer-auth alongside the existing authorization header.
+ * Used for Connect-RPC-like paths that arrive via fetch — the BiDi
+ * proxy authenticates the runner via x-stigmer-auth and forwards the
+ * original authorization (Cursor access token) to upstream Cursor.
+ */
+function injectProxyAuth(init: RequestInit | undefined, config: ProxyConfig): RequestInit {
+  const headers = new Headers(init?.headers);
+  headers.set("x-stigmer-auth", `Bearer ${config.stigmerToken}`);
+  const ctx = executionContext.getStore();
+  const effectiveExecutionId = ctx?.executionId ?? config.executionId;
+  if (effectiveExecutionId) {
+    headers.set("x-stigmer-execution-id", effectiveExecutionId);
+  }
+  return { ...init, headers };
+}
+
+function extractPath(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Paths that Cursor SDK calls for analytics, telemetry, or feature flags.
+ * Failures on these endpoints are non-critical and should not pollute logs.
+ */
+const NON_CRITICAL_PATHS = [
+  "/aiserver.v1.AnalyticsService/BootstrapStatsig",
+  "/aiserver.v1.AnalyticsService/LogStatsigExposure",
+  "/aiserver.v1.AnalyticsService/LogStatsigEvent",
+  "/analytics/",
+  "/telemetry/",
+];
+
+function isNonCriticalPath(path: string): boolean {
+  return NON_CRITICAL_PATHS.some(p => path.includes(p));
+}
+
+const interceptedFetch: typeof fetch = async (input, init) => {
+  if (!interceptorConfig) {
+    return originalFetch(input, init);
+  }
+
+  const url = typeof input === "string"
+    ? input
+    : input instanceof URL
+      ? input.toString()
+      : input instanceof Request
+        ? input.url
+        : String(input);
+
+  if (needsUrlRewrite(url)) {
+    return fetchWithUrlRewrite(url, init, interceptorConfig);
+  }
+
+  if (needsProxyAuthOnly(url)) {
+    return fetchWithProxyAuth(url, init, interceptorConfig);
+  }
+
+  return originalFetch(input, init);
+};
+
+/**
+ * REST path: rewrite URL to /v1/proxy/cursor/{upstream}{path} and
+ * replace auth with Stigmer token for CursorProxyController.
+ */
+async function fetchWithUrlRewrite(
+  url: string, init: RequestInit | undefined, config: ProxyConfig,
+): Promise<Response> {
+  const rewrittenUrl = rewriteUrl(url, config.proxyEndpoint);
+  const rewrittenInit = replaceAuth(init, config);
+  const path = extractPath(url);
+
+  try {
+    const response = await originalFetch(rewrittenUrl, rewrittenInit);
+
+    if (!response.ok) {
+      if (isNonCriticalPath(path)) {
+        console.debug(
+          `[proxy-interceptor] Non-critical Cursor request failed (expected): ${init?.method ?? "GET"} ${path} → proxy status=${response.status}`,
+        );
+      } else {
+        console.warn(
+          `[proxy-interceptor] Cursor request failed: ${init?.method ?? "GET"} ${path} → proxy status=${response.status}`,
+        );
+      }
+    }
+
+    return response;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(
+      `[proxy-interceptor] Cursor request error: ${init?.method ?? "GET"} ${path} → ${msg}`,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Connect-RPC-via-fetch path: inject x-stigmer-auth for BiDi proxy
+ * authentication without rewriting the URL or replacing authorization.
+ */
+async function fetchWithProxyAuth(
+  url: string, init: RequestInit | undefined, config: ProxyConfig,
+): Promise<Response> {
+  const augmentedInit = injectProxyAuth(init, config);
+  const path = extractPath(url);
+
+  try {
+    const response = await originalFetch(url, augmentedInit);
+
+    if (!response.ok && !isNonCriticalPath(path)) {
+      console.warn(
+        `[proxy-interceptor] BiDi fetch request failed: ${init?.method ?? "GET"} ${path} → proxy status=${response.status}`,
+      );
+    }
+
+    return response;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(
+      `[proxy-interceptor] BiDi fetch request error: ${init?.method ?? "GET"} ${path} → ${msg}`,
+    );
+    throw err;
+  }
+}
+
+/**
+ * Install the global fetch interceptor. Call once at startup, BEFORE
+ * importing @cursor/sdk.
+ *
+ * When proxyEndpoint is empty or not provided, the interceptor is not
+ * installed and all fetch calls pass through to the original implementation.
+ */
+export function installFetchInterceptor(config: {
+  proxyEndpoint: string | undefined;
+  stigmerToken: string | undefined;
+}): void {
+  if (!config.proxyEndpoint) {
+    return;
+  }
+
+  if (!config.stigmerToken) {
+    throw new Error(
+      "STIGMER_TOKEN is required when STIGMER_PROXY_ENDPOINT is set. " +
+      "In proxy mode, the runner authenticates with Stigmer's proxy using STIGMER_TOKEN.",
+    );
+  }
+
+  interceptorConfig = {
+    proxyEndpoint: config.proxyEndpoint,
+    stigmerToken: config.stigmerToken,
+  };
+
+  globalThis.fetch = interceptedFetch;
+
+  console.log(
+    `Cursor proxy interceptor installed: Cursor traffic → ${config.proxyEndpoint}/v1/proxy/cursor/`,
+  );
+}
+
+/**
+ * Update the auth token on the live interceptor config. Must be called
+ * whenever the Stigmer JWT is refreshed (e.g. via IPC updateToken) so
+ * that fetch-intercepted REST calls (token exchange, /v1/models) use the
+ * current token instead of the one frozen at install time.
+ */
+export function updateInterceptorToken(token: string): void {
+  if (interceptorConfig) {
+    interceptorConfig = { ...interceptorConfig, stigmerToken: token };
+  }
+}
+
+/**
+ * Update the execution ID on the active interceptor (legacy global path).
+ * Prefer {@link runWithExecutionContext} for concurrent-safe isolation.
+ *
+ * @deprecated Use runWithExecutionContext() instead for concurrent activities.
+ */
+export function setInterceptorExecutionId(executionId: string | undefined): void {
+  if (interceptorConfig) {
+    interceptorConfig = { ...interceptorConfig, executionId };
+  }
+}
+
+/**
+ * Run an async function with execution-scoped context. The executionId is
+ * propagated through the async call chain via AsyncLocalStorage, ensuring
+ * concurrent activities on the same runner process don't overwrite each
+ * other's proxy headers.
+ */
+export function runWithExecutionContext<T>(
+  executionId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return executionContext.run({ executionId }, fn);
+}
+
+/**
+ * Remove the interceptor and restore the original fetch. Primarily for
+ * testing.
+ */
+export function uninstallFetchInterceptor(): void {
+  interceptorConfig = null;
+  globalThis.fetch = originalFetch;
+}