cartethyia 2.4.6 → 2.5.1

package/src/providers/integrations/cursor/cursor-catalog.ts

@@ -0,0 +1,368 @@
+// Cursor live model catalog and Run-origin discovery.
+//
+// Two unary Connect-RPC calls on the API host back this module:
+// `/aiserver.v1.AiService/AvailableModels` for the roster and
+// `/aiserver.v1.ServerConfigService/GetServerConfig` for the region-specific Run
+// origin. Both go through the validated outbound fetch the dispatch path hands
+// the adapter, so a catalog refresh obeys the same SSRF policy and the same
+// network pool as a dispatch.
+//
+// Nothing here invents a capability. A model is marked image-capable, tool-
+// capable, or reasoning-capable only because Cursor declared it; limits come
+// from Cursor's own variant parameter or its own context fields.
+import { defineModel } from "../../provider-model-definition";
+import type { ModelDefinition } from "../../provider-model-definition";
+import {
+  AVAILABLE_MODELS_PATH,
+  CURSOR_API_BASE_URL,
+  CURSOR_PROVIDER_ID,
+  FALLBACK_CLIENT_VERSION,
+  SERVER_CONFIG_PATH,
+  normalizeAgentRunOrigin,
+} from "./cursor-shared";
+import { createCursorChecksumHeader, resolveCursorDeviceIds } from "./cursor-identity";
+
+/** One parameter value of a Cursor-declared model variant. */
+export interface CursorParameterValue {
+  readonly id: string;
+  readonly value: string;
+}
+
+/** One variant (parameter tuple) Cursor advertises for a model. */
+export interface CursorModelVariant {
+  readonly displayName: string;
+  readonly parameterValues: readonly CursorParameterValue[];
+  readonly isDefaultNonMax: boolean;
+  readonly isDefaultMax: boolean;
+  readonly isMaxMode: boolean;
+}
+
+/** One model entry as Cursor declares it. */
+export interface CursorModelInfo {
+  readonly id: string;
+  readonly displayName: string;
+  readonly maxContext?: number;
+  readonly maxContextForMaxMode?: number;
+  readonly supportsImages?: boolean;
+  readonly supportsThinking?: boolean;
+  readonly supportsAgent?: boolean;
+  readonly supportsMaxMode?: boolean;
+  readonly variants: readonly CursorModelVariant[];
+}
+
+/** Headers every Cursor unary call carries, matching the CLI's identity. */
+async function unaryHeaders(
+  credential: string,
+  clientVersion: string,
+): Promise<Record<string, string>> {
+  const { machineId, macMachineId } = await resolveCursorDeviceIds();
+  return {
+    authorization: `Bearer ${credential}`,
+    "connect-protocol-version": "1",
+    "content-type": "application/json",
+    accept: "application/json",
+    "x-cursor-client-type": "cli",
+    "x-cursor-client-version": clientVersion,
+    "x-cursor-checksum": createCursorChecksumHeader(machineId, macMachineId),
+    "x-ghost-mode": "true",
+    "x-request-id": crypto.randomUUID(),
+  };
+}
+
+async function postUnary(
+  fetcher: typeof fetch,
+  path: string,
+  credential: string,
+  body: unknown,
+  clientVersion: string,
+  signal: AbortSignal | undefined,
+): Promise<Record<string, unknown>> {
+  const response = await fetcher(`${CURSOR_API_BASE_URL}${path}`, {
+    method: "POST",
+    headers: await unaryHeaders(credential, clientVersion),
+    body: JSON.stringify(body),
+    ...(signal === undefined ? {} : { signal }),
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      `Cursor ${path} failed (${response.status}): ${text.slice(0, 200)}`,
+    );
+  }
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    throw new Error(`Cursor ${path} returned malformed JSON`);
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function optionalBoolean(
+  record: Record<string, unknown>,
+  names: readonly string[],
+): boolean | undefined {
+  for (const name of names) {
+    if (!Object.hasOwn(record, name)) continue;
+    const value = record[name];
+    return typeof value === "boolean" ? value : undefined;
+  }
+  return undefined;
+}
+
+function positiveNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/** Parses Cursor's `200k` / `1m` context spelling into tokens. */
+export function parseCursorContextLimit(value: unknown): number | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  const match = /^(\d+(?:\.\d+)?)\s*([km])$/i.exec(text);
+  if (match !== null) {
+    const multiplier = match[2]!.toLowerCase() === "k" ? 1_000 : 1_000_000;
+    const limit = Number(match[1]) * multiplier;
+    return Number.isSafeInteger(limit) && limit > 0 ? limit : undefined;
+  }
+  const numeric = Number(text);
+  return Number.isSafeInteger(numeric) && numeric > 0 ? numeric : undefined;
+}
+
+function normalizeParameterValues(value: unknown): CursorParameterValue[] | undefined {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return undefined;
+  const parameters: CursorParameterValue[] = [];
+  for (const entry of value) {
+    if (!isPlainRecord(entry)) return undefined;
+    const id = typeof entry["id"] === "string" ? entry["id"].trim() : "";
+    const parameterValue = entry["value"] ?? entry["value"];
+    if (id.length === 0 || typeof parameterValue !== "string") return undefined;
+    parameters.push({ id, value: parameterValue });
+  }
+  return parameters;
+}
+
+/**
+ * Maps a live `AvailableModels` response onto Cursor model entries.
+ *
+ * Every entry's capability is Cursor's own declaration. A malformed variant or
+ * a non-boolean capability throws rather than being coerced: a catalog that
+ * guesses "supports images" where Cursor said nothing routes image traffic to a
+ * model that will refuse it.
+ */
+export function mapAvailableModelsResponse(raw: Record<string, unknown>): CursorModelInfo[] {
+  const entries = Array.isArray(raw["models"]) ? raw["models"] : [];
+  const models: CursorModelInfo[] = [];
+  for (const entry of entries) {
+    if (!isPlainRecord(entry)) continue;
+    const id = typeof entry["name"] === "string" ? entry["name"].trim() : "";
+    if (id.length === 0) continue;
+    const rawVariants = entry["variants"] ?? [];
+    if (!Array.isArray(rawVariants)) {
+      throw new Error(`Cursor AvailableModels returned invalid variants for ${id}`);
+    }
+    const variants: CursorModelVariant[] = [];
+    for (const variant of rawVariants) {
+      if (!isPlainRecord(variant)) {
+        throw new Error(`Cursor AvailableModels returned an invalid variant for ${id}`);
+      }
+      const parameterValues = normalizeParameterValues(
+        variant["parameterValues"] ?? variant["parameter_values"],
+      );
+      if (parameterValues === undefined) {
+        throw new Error(`Cursor AvailableModels returned invalid parameter values for ${id}`);
+      }
+      const isMaxMode = optionalBoolean(variant, ["isMaxMode", "is_max_mode"]) ?? false;
+      variants.push({
+        displayName: (typeof variant["displayName"] === "string"
+          ? variant["displayName"]
+          : typeof variant["display_name"] === "string"
+            ? variant["display_name"]
+            : id) as string,
+        parameterValues,
+        isDefaultNonMax:
+          optionalBoolean(variant, ["isDefaultNonMaxConfig", "is_default_non_max_config"]) ?? false,
+        isDefaultMax:
+          optionalBoolean(variant, ["isDefaultMaxConfig", "is_default_max_config"]) ?? false,
+        isMaxMode,
+      });
+    }
+    const contextOf = (variant: CursorModelVariant | undefined): number | undefined =>
+      parseCursorContextLimit(variant?.parameterValues.find((p) => p.id === "context")?.value);
+    const baseContext =
+      contextOf(variants.find((variant) => variant.isDefaultNonMax)) ??
+      contextOf(variants.find((variant) => variant.isDefaultMax) ?? variants[0]) ??
+      positiveNumber(entry["contextTokenLimit"] ?? entry["context_token_limit"]);
+    const maxContext =
+      contextOf(variants.find((variant) => variant.isDefaultMax)) ??
+      positiveNumber(entry["contextTokenLimitForMaxMode"] ?? entry["context_token_limit_for_max_mode"]);
+    models.push({
+      id,
+      displayName: (typeof entry["clientDisplayName"] === "string"
+        ? entry["clientDisplayName"]
+        : typeof entry["client_display_name"] === "string"
+          ? entry["client_display_name"]
+          : id) as string,
+      ...(baseContext === undefined ? {} : { maxContext: baseContext }),
+      ...(maxContext === undefined ? {} : { maxContextForMaxMode: maxContext }),
+      ...(() => {
+        const images = optionalBoolean(entry, ["supportsImages", "supports_images"]);
+        return images === undefined ? {} : { supportsImages: images };
+      })(),
+      supportsThinking: optionalBoolean(entry, ["supportsThinking", "supports_thinking"]) ?? false,
+      supportsAgent: optionalBoolean(entry, ["supportsAgent", "supports_agent"]) ?? false,
+      supportsMaxMode: optionalBoolean(entry, ["supportsMaxMode", "supports_max_mode"]) ?? false,
+      variants,
+    });
+  }
+  return models;
+}
+
+/**
+ * Cursor's declared default parameter tuple for one model.
+ *
+ * The public catalog lists one row per model and sends Cursor's own default:
+ * no variant picker is part of this integration, so the tuple is the one Cursor
+ * marked default (its max default when the model runs in max mode, otherwise its
+ * non-max default). An empty tuple is correct for a model that declares none.
+ */
+export function defaultParameterValues(
+  model: CursorModelInfo | undefined,
+  maxMode = false,
+): CursorParameterValue[] {
+  if (model === undefined || model.variants.length === 0) return [];
+  const tier = model.variants.filter((variant) => variant.isMaxMode === maxMode);
+  const candidates = tier.length > 0 ? tier : model.variants;
+  const declared = candidates.find((variant) =>
+    maxMode ? variant.isDefaultMax : variant.isDefaultNonMax,
+  );
+  const chosen = declared ?? candidates.find((variant) => variant.isMaxMode === maxMode) ?? candidates[0];
+  return chosen === undefined ? [] : chosen.parameterValues.map((parameter) => ({ ...parameter }));
+}
+
+/** Projects one Cursor model entry onto a Cartethyia catalog row. */
+export function cursorModelDefinition(model: CursorModelInfo): ModelDefinition {
+  return cursorModel(model.id, model.maxContext, {
+    vision: model.supportsImages === true,
+    reasoning: model.supportsThinking === true,
+  });
+}
+
+function cursorModel(
+  modelId: string,
+  ctx?: number,
+  options: { vision?: boolean; reasoning?: boolean; out?: number } = {},
+): ModelDefinition {
+  return defineModel({
+    id: modelId,
+    providerId: CURSOR_PROVIDER_ID,
+    wireFamily: "chat",
+    endpoint: "/agent.v1.AgentService/Run",
+    ...(ctx === undefined ? {} : { ctx }),
+    ...(options.out === undefined ? {} : { out: options.out }),
+    // Tools are served through Cursor's MCP exec channel, which this adapter
+    // answers for every request that declares tools — so the row advertises
+    // them and the adapter refuses anything it did not advertise.
+    toolCall: true,
+    vision: options.vision ?? true,
+    reasoning: options.reasoning ?? false,
+  });
+}
+
+/**
+ * Static fallback catalog for Cursor.
+ *
+ * The authoritative roster is resolved per account from `AvailableModels`,
+ * while these static rows give the provider offline floor visibility and
+ * establish canonical IDs for Auto and Grok 4.6/4.7.
+ *
+ * `auto` is the only id surfaced for Cursor's Auto model: the upstream wire id
+ * is `default` and the two are the same model, not two entries. Dispatch maps
+ * `auto` is an alias: Cursor's own roster names its Auto model `default`, and
+ * dispatch maps `auto` onto it, so seeding the upstream id as well would list
+ * the same model twice. Grok ids are already upstream ids and are not rewritten.
+ *
+ * Output is stated explicitly: `defineModel` would otherwise inherit a
+ * base-catalog output equal to the whole 256k window, which is not a limit
+ * Cursor serves and makes admission reserve the entire context as headroom.
+ */
+export const CURSOR_MODELS: readonly ModelDefinition[] = [
+  cursorModel("auto", 256_000, { vision: true, reasoning: false, out: 64_000 }),
+  cursorModel("grok-4.6", 256_000, { vision: true, reasoning: true, out: 64_000 }),
+  cursorModel("grok-4.7", 256_000, { vision: true, reasoning: true, out: 64_000 }),
+];
+
+/** Fetches Cursor's live model roster through validated egress. */
+export async function fetchCursorModels(input: {
+  readonly credential: string;
+  readonly fetcher?: typeof fetch;
+  readonly signal?: AbortSignal;
+  readonly clientVersion?: string;
+}): Promise<CursorModelInfo[]> {
+  const fetcher = input.fetcher ?? globalThis.fetch;
+  const body = await postUnary(
+    fetcher,
+    AVAILABLE_MODELS_PATH,
+    input.credential,
+    // Parameterized effort/context/fast variants, as Cursor IDE requests them.
+    {
+      includeLongContextModels: true,
+      useModelParameters: true,
+      useCloudAgentEffortModes: true,
+    },
+    input.clientVersion ?? FALLBACK_CLIENT_VERSION,
+    input.signal,
+  );
+  return mapAvailableModelsResponse(body);
+}
+
+/**
+ * Resolves the Run-stream origin Cursor routes this account to.
+ *
+ * Fails closed: a region-routed account is silently rejected by the wrong
+ * regional host, so a missing, malformed, non-HTTPS, or non-`*.cursor.sh` value
+ * is an error rather than a fallback to the API host. The API origin does serve
+ * auth and catalog calls, but it is not the origin `GetServerConfig` names for
+ * Run, and assuming it does is what makes a Run land on a host that refuses it.
+ */
+export async function fetchCursorRunOrigin(input: {
+  readonly credential: string;
+  readonly fetcher?: typeof fetch;
+  readonly signal?: AbortSignal;
+  readonly clientVersion?: string;
+}): Promise<string> {
+  const fetcher = input.fetcher ?? globalThis.fetch;
+  const body = await postUnary(
+    fetcher,
+    SERVER_CONFIG_PATH,
+    input.credential,
+    { telem_enabled: false },
+    input.clientVersion ?? FALLBACK_CLIENT_VERSION,
+    input.signal,
+  );
+  const config = isPlainRecord(body["agentUrlConfig"]) ? body["agentUrlConfig"] : undefined;
+  const raw = config?.["agentnUrl"] ?? config?.["agentUrl"];
+  const origin = normalizeAgentRunOrigin(typeof raw === "string" ? raw : undefined);
+  if (origin === null) {
+    throw new Error(
+      raw === undefined
+        ? "Cursor GetServerConfig response missing agentUrlConfig.agentnUrl"
+        : "Cursor GetServerConfig returned an invalid Cursor agent URL",
+    );
+  }
+  return origin;
+}
+
+/** Discovery entry point: the live roster, as catalog rows. */
+export async function discoverCursorModels(input: {
+  readonly credential: string;
+  readonly fetcher?: typeof fetch;
+  readonly signal?: AbortSignal;
+}): Promise<readonly ModelDefinition[]> {
+  const models = await fetchCursorModels(input);
+  return models.map(cursorModelDefinition);
+}

package/src/providers/integrations/cursor/cursor-http2.ts

@@ -0,0 +1,300 @@
+// Cursor Run transport: one validated HTTP/2 bidi stream, framed.
+//
+// This module owns the wire and nothing else. It opens the stream through the
+// validated HTTP/2 binding, writes Connect frames, decodes response frames back
+// into protobuf messages, and maps stream/HTTP/gRPC outcomes onto typed errors.
+// It never calls `node:http2.connect` itself — the binding owns the socket, the
+// DNS pinning, the SSRF policy, and the pool tunnel.
+import { GatewayError } from "../../../protocol/gateway-error";
+import type { ValidatedHttp2BidiStream, Http2BidiEndReason } from "../../../network/http2-bidi";
+import type { ValidatedOutboundHttp2Bidi } from "../../provider-contracts";
+import { decodeFramePayload, encodeFrame, streamFrames, FLAG_END_STREAM } from "./protocol/framing";
+import { decodeMessage } from "./protocol/messages";
+import {
+  CONTENT_TYPE_CONNECT_PROTO,
+  CONNECT_PROTOCOL_VERSION,
+  FALLBACK_CLIENT_VERSION,
+  RUN_PATH,
+  isAllowedAgentHost,
+} from "./cursor-shared";
+import { createCursorChecksumHeader, resolveCursorDeviceIds } from "./cursor-identity";
+
+import { isRecord } from "../../../protocol/codecs";
+
+/**
+ * The refusal Cursor sends inside an otherwise-successful 200 Run stream.
+ *
+ * It is a Connect JSON error envelope, not protobuf, and it is where a real
+ * account-level refusal lands — a rate-limited or exhausted account streams a
+ * heartbeat and then this. Without it the Run looks like a deadlock: the
+ * stream opened, no text ever arrived, and nothing named the reason.
+ */
+function connectErrorEnvelope(payload: Uint8Array): GatewayError | undefined {
+  const text = new TextDecoder().decode(payload);
+  if (!text.trimStart().startsWith("{\"error\"")) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed["error"])) return undefined;
+  const error = parsed["error"];
+  const code = typeof error["code"] === "string" ? error["code"] : "";
+  const detail = cursorErrorDetail(error);
+  if (code === "resource_exhausted") {
+    return new GatewayError(
+      "quota_exceeded",
+      429,
+      `Cursor refused the Run: ${detail}`,
+      { providerId: "cursor", upstreamCode: code },
+      "upstream",
+    );
+  }
+  return new GatewayError(
+    "platform_unavailable",
+    502,
+    `Cursor refused the Run: ${detail}`,
+    { providerId: "cursor", upstreamCode: code },
+    "upstream",
+  );
+}
+
+/** The human-readable refusal, preferring Cursor's own `chatMessage`/`detail`. */
+function cursorErrorDetail(error: Record<string, unknown>): string {
+  const raw = typeof error["message"] === "string" ? error["message"] : "";
+  for (const detail of Array.isArray(error["details"]) ? error["details"] : []) {
+    if (!isRecord(detail)) continue;
+    const debug = detail["debug"];
+    if (!isRecord(debug)) continue;
+    const info = debug["details"];
+    if (isRecord(info)) {
+      const chat = info["chatMessage"];
+      if (typeof chat === "string" && chat.length > 0) return chat;
+      const title = info["title"];
+      if (typeof title === "string" && title.length > 0) return title;
+    }
+  }
+  return raw.length > 0 ? raw : "Cursor refused the Run";
+}
+
+/** One decoded Cursor server message. */
+export interface CursorServerMessage {
+  readonly raw: Record<string, unknown>;
+}
+
+/** Read-idle bound for one Run stream. */
+const DEFAULT_READ_IDLE_MS = 120_000;
+
+/** Cursor identity headers for the Run stream. */
+async function runHeaders(credential: string, clientVersion: string): Promise<Record<string, string>> {
+  const { machineId, macMachineId } = await resolveCursorDeviceIds();
+  return {
+    authorization: `Bearer ${credential}`,
+    "content-type": CONTENT_TYPE_CONNECT_PROTO,
+    "connect-protocol-version": CONNECT_PROTOCOL_VERSION,
+    "connect-accept-encoding": "gzip,br",
+    "x-cursor-client-type": "cli",
+    "x-cursor-client-version": clientVersion,
+    "x-cursor-checksum": createCursorChecksumHeader(machineId, macMachineId),
+    // The CLI's streaming interceptor sets this on the bidi Run stream.
+    // Without it Cursor may treat the stream as non-streaming.
+    "x-cursor-streaming": "true",
+    "x-ghost-mode": "true",
+    "x-request-id": crypto.randomUUID(),
+    "user-agent": "connect-es/1.6.1",
+  };
+}
+
+/**
+ * Opens one Cursor Run stream.
+ *
+ * The host is re-validated here as well as in the binding: the Run origin comes
+ * from `GetServerConfig`, which is upstream data, so it is checked against the
+ * Cursor allowlist before a credentialed connection is opened to it.
+ */
+export async function openCursorRun(input: {
+  readonly origin: string;
+  readonly credential: string;
+  readonly outboundHttp2: ValidatedOutboundHttp2Bidi;
+  readonly signal: AbortSignal;
+  readonly clientVersion?: string;
+  readonly readIdleMs?: number;
+}): Promise<{ stream: ValidatedHttp2BidiStream; write: (message: Uint8Array) => Promise<void> }> {
+  const url = new URL(`${input.origin}${RUN_PATH}`);
+  if (url.protocol !== "https:" || !isAllowedAgentHost(url.hostname)) {
+    throw new GatewayError(
+      "invalid_request",
+      400,
+      "Cursor Run requires an allowlisted Cursor agent origin",
+      { origin: input.origin },
+    );
+  }
+  const headers = await runHeaders(input.credential, input.clientVersion ?? FALLBACK_CLIENT_VERSION);
+  const stream = await input.outboundHttp2(url, headers, {
+    signal: input.signal,
+    readIdleMs: input.readIdleMs ?? DEFAULT_READ_IDLE_MS,
+    allowHostname: isAllowedAgentHost,
+  });
+  return {
+    stream,
+    write: async (message: Uint8Array): Promise<void> => {
+      await stream.write(encodeFrame(0, message));
+    },
+  };
+}
+
+/** Map of gRPC status codes onto gateway errors. */
+function grpcError(status: string, message: string | undefined): GatewayError {
+  const code = Number(status);
+  const detail = message === undefined || message.length === 0 ? "" : `: ${message}`;
+  if (code === 16 || code === 7) {
+    // UNAUTHENTICATED / PERMISSION_DENIED: the credential, not the request.
+    return new GatewayError(
+      "authentication_failed",
+      401,
+      `Cursor refused the credential${detail}`,
+      { grpcStatus: status },
+      "upstream",
+    );
+  }
+  if (code === 8 || code === 14) {
+    return new GatewayError(
+      "quota_exceeded",
+      429,
+      `Cursor refused the Run${detail}`,
+      { grpcStatus: status },
+      "upstream",
+    );
+  }
+  if (code === 4 || code === 10) {
+    return new GatewayError(
+      "deadline_exceeded",
+      504,
+      `Cursor Run ended before it finished${detail}`,
+      { grpcStatus: status },
+      "upstream",
+    );
+  }
+  return new GatewayError(
+    "platform_unavailable",
+    502,
+    `Cursor Run failed (gRPC ${status})${detail}`,
+    { grpcStatus: status },
+    "upstream",
+  );
+}
+
+/**
+ * The terminal error for one ended Run stream.
+ *
+ * Status, trailers, and transport error are read in that order because that is
+ * the order of authority: an HTTP status is what the edge answered, a gRPC
+ * trailer is what the server decided, and a transport error is what the socket
+ * did. A clean close with none of them is still a failure — a Run that ends
+ * without `turn_ended` produced no answer.
+ */
+export function cursorRunTerminationError(input: {
+  readonly stream: ValidatedHttp2BidiStream;
+  readonly reason: Http2BidiEndReason;
+}): GatewayError | undefined {
+  if (input.reason.kind === "local-close") return undefined;
+  if (input.reason.kind === "remote-error") {
+    return input.reason.error instanceof GatewayError
+      ? input.reason.error
+      : new GatewayError(
+          "transport_unavailable",
+          502,
+          `Cursor Run transport interrupted: ${input.reason.error.message}`,
+          {},
+          "network",
+        );
+  }
+  const { status, headers } = input.stream.response;
+  if (status !== 0 && status !== 200) {
+    const message = headers["grpc-message"];
+    return new GatewayError(
+      status === 401 || status === 403 ? "authentication_failed" : "platform_unavailable",
+      status === 401 || status === 403 ? 401 : 502,
+      `Cursor Run failed by remote: ${status}`,
+      { httpStatus: status, ...(message === undefined ? {} : { upstreamMessage: message }) },
+      "upstream",
+    );
+  }
+  const trailers = input.stream.trailers;
+  const grpcStatus = trailers["grpc-status"] ?? headers["grpc-status"];
+  if (grpcStatus !== undefined && grpcStatus !== "0") {
+    return grpcError(grpcStatus, trailers["grpc-message"] ?? headers["grpc-message"]);
+  }
+  return new GatewayError(
+    "platform_unavailable",
+    502,
+    "Cursor Run ended before turn_ended",
+    {},
+    "upstream",
+  );
+}
+
+/**
+ * Decodes a response byte stream into Cursor server messages.
+ *
+ * Buffering is bounded and the leftover is carried forward rather than
+ * re-merged from scratch: a Run frame can be many megabytes, and copying the
+ * whole pending buffer on every chunk is what turns a long Run into a stall.
+ */
+export async function* decodeServerMessages(
+  body: AsyncIterable<Uint8Array>,
+  maxBufferedBytes = 64 * 1024 * 1024,
+): AsyncGenerator<Record<string, unknown>, void, void> {
+  let pending: Uint8Array = new Uint8Array(0);
+  for await (const chunk of body) {
+    pending = pending.byteLength === 0 ? chunk : concat(pending, chunk);
+    if (pending.byteLength > maxBufferedBytes) {
+      throw new GatewayError(
+        "platform_unavailable",
+        502,
+        "Cursor Run exceeded the frame buffer bound",
+        {},
+        "upstream",
+      );
+    }
+    const frames = [...streamFrames(pending)];
+    if (frames.length === 0) continue;
+    let consumed = 0;
+    for (const frame of frames) consumed += 5 + frame.payload.byteLength;
+    const leftover = pending.subarray(consumed);
+    pending = leftover.byteLength === 0 ? new Uint8Array(0) : new Uint8Array(leftover);
+    for (const frame of frames) {
+      const payload = decodeFramePayload(frame);
+      // A refusal is a Connect JSON error envelope, not protobuf: an exhausted
+      // account answers with one inside a normal 200 stream. Surfacing it is
+      // the difference between "the model said nothing" and "you hit your
+      // usage limit".
+      const envelope = connectErrorEnvelope(payload);
+      if (envelope !== undefined) throw envelope;
+      try {
+        yield decodeMessage("AgentServerMessage", payload);
+      } catch {
+        // One undecodable frame is not a protocol failure to abort on: Cursor
+        // extends this schema with fields this vendored copy does not model, and
+        // a Run that produced usable output must not die on one unknown field.
+        continue;
+      }
+      // `END_STREAM` ends the *response*, not the payload: Cursor sets it on the
+      // last frame of a Run, which is exactly the frame carrying `turn_ended`
+      // and the model's final text. Returning before decoding it dropped every
+      // answer and left the Run looking like a heartbeat-only deadlock.
+      if ((frame.flags & FLAG_END_STREAM) !== 0) return;
+    }
+  }
+}
+
+function concat(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const out = new Uint8Array(left.byteLength + right.byteLength);
+  out.set(left, 0);
+  out.set(right, left.byteLength);
+  return out;
+}
+
+/** Heartbeat cadence while a Run is held open waiting for a tool result. */
+export const RUN_HEARTBEAT_INTERVAL_MS = 20_000;