@offbynan/pi-cursor-provider 0.5.1 → 0.5.3

package/README.md

@@ -4,7 +4,7 @@
 
 - **Image support** — base64 `image_url` content parts forwarded to Cursor end-to-end; the upstream silently drops them
 - **Compaction support** — old turns archived as inline text to cut `getBlobArgs` round-trips from O(history) to O(tail); bridge termination errors surface as real failures instead of silent empty responses; checkpoint cleared after compaction to keep both sides in sync
-- **Reliability** — bridge timeouts hardened and configurable; SSE keepalive prevents pi from timing out during blob-fetching; conversation state and checkpoints survive transient failures and client disconnects
+- **Reliability** — transparent retry for transient Cursor protocol errors (internal / unavailable / deadline_exceeded); HTTP/2 PING keepalive detects dead connections; stall timer kills stuck bridges; bridge timeouts hardened and configurable; SSE keepalive prevents pi from timing out during blob-fetching; conversation state and checkpoints survive transient failures and client disconnects
 - **Model support** — per-model context window inference (vs. hardcoded 200 k); runtime cap scaling when Cursor enforces a tighter window; detailed cost table for all current families; effort-suffix variants deduplicated so pi's reasoning-level setting drives the suffix automatically
 - **Thinking-tag filtering** — inline `<think>` / `<reasoning>` tags stripped from the response and routed to `reasoning_content`
 - **Fixes & observability** — `pi -p` exit hang fixed; dead TTL eviction code removed; opt-in JSONL debug logging with a bundled timeline viewer
@@ -59,6 +59,10 @@ pi  →  openai-completions  →  localhost:PORT/v1/chat/completions
 | `PI_CURSOR_PROVIDER_DEBUG_FILE` | auto in tmpdir | Override the debug log file path |
 | `PI_CURSOR_BRIDGE_INITIAL_TIMEOUT_MS` | `120000` | Kill bridge if no HTTP/2 activity within this many ms of spawn |
 | `PI_CURSOR_BRIDGE_ACTIVITY_TIMEOUT_MS` | `300000` | Kill bridge if no HTTP/2 activity for this many ms after the first frame |
+| `PI_CURSOR_BRIDGE_PING_INTERVAL_MS` | `15000` | HTTP/2 PING interval to detect dead connections |
+| `PI_CURSOR_BRIDGE_PING_TIMEOUT_MS` | `10000` | Timeout for each HTTP/2 PING before declaring the connection dead |
+| `PI_CURSOR_BRIDGE_STALL_TIMEOUT_MS` | `120000` | Kill bridge if no data received from Cursor within this many ms |
+| `PI_CURSOR_MAX_BRIDGE_RETRIES` | `2` | Max transparent retries on transient Cursor errors or bridge crashes |
 | `PI_CURSOR_TURN_ARCHIVE_THRESHOLD` | `20` | Keep this many recent turns as raw blobs; older turns are archived as inline text |
 | `PI_CURSOR_RAW_MODELS` | off | Set to disable model deduplication and see all raw Cursor model IDs |
 
@@ -150,6 +154,24 @@ The upstream has no observability. This fork adds opt-in JSONL event logging (se
 npm run debug:timeline -- --latest
 ```
 
+### Transparent retry for transient errors
+
+When Cursor returns a retryable Connect-level error (`internal`, `unavailable`, `deadline_exceeded`) or the bridge process crashes mid-request, the proxy now automatically retries on a fresh HTTP/2 bridge — up to `PI_CURSOR_MAX_BRIDGE_RETRIES` times (default 2). The SSE response to pi stays open; the client sees at most a brief pause.
+
+Retry is only attempted when no content has been streamed yet (so partial responses are never replayed). On retry the proxy rebuilds the Cursor request using the pre-turn checkpoint and replays cleanly.
+
+Previously these transient errors were surfaced as `finish_reason: "error"`, requiring the user to manually continue each time.
+
+### HTTP/2 PING keepalive and stall detection
+
+The bridge now configures HTTP/2-level PINGs (`PI_CURSOR_BRIDGE_PING_INTERVAL_MS` / `PI_CURSOR_BRIDGE_PING_TIMEOUT_MS`) so dead TCP connections (NAT timeout, load-balancer cycling) are detected within seconds rather than waiting for the 5-minute activity timeout.
+
+Additionally, a stall timer (`PI_CURSOR_BRIDGE_STALL_TIMEOUT_MS`, default 120 s) kills the bridge if no data arrives from Cursor — catching cases where the HTTP/2 connection is technically alive but the server is stuck processing a stale checkpoint.
+
+### Usage reporting on tool-call continuations
+
+When the proxy pauses mid-turn for a tool call and responds with pending tool calls (the partial-wait path), it now reports meaningful `usage` token counts instead of zeros. The stored `lastTotalTokens` from the previous stream segment is scaled proportionally if Cursor is enforcing a tighter context window than the model's nominal size. This lets pi track cumulative token usage accurately across multi-step tool-call turns.
+
 ### Bridge timeout hardening
 
 The upstream `h2-bridge.mjs` used a 30-second initial connection timeout and a 120-second activity timeout. Large conversations require Cursor to deserialise a big checkpoint and complete many `getBlobArgs` round-trips before it starts streaming tokens, which regularly exceeded these limits and caused compaction to fail with a `terminated` error.
@@ -276,7 +298,7 @@ Session state is cleared on pi lifecycle events — session switch, fork, `/tree
 
 ### Error resilience
 
-A bridge timeout or Connect-level error from Cursor does not wipe the stored checkpoint. The last good checkpoint survives transient failures and is used on the next retry. If Cursor sends a checkpoint before a client disconnect, that checkpoint is also preserved.
+Transient Cursor errors (`internal`, `unavailable`, `deadline_exceeded`) and bridge crashes are retried automatically — up to `PI_CURSOR_MAX_BRIDGE_RETRIES` times — without dropping the SSE connection to pi. The last good checkpoint survives all error types and is used on retry. If Cursor sends a checkpoint before a client disconnect, that checkpoint is also preserved.
 
 ## Requirements
 

package/h2-bridge.mjs

@@ -87,15 +87,19 @@ if (!configBuf) process.exit(1);
 const config = JSON.parse(configBuf.toString("utf8"));
 const { accessToken, url, path: rpcPath, unary } = config;
 
-const client = http2.connect(url || "https://api2.cursor.sh");
-
-// Guard against initial connection failure. Reset on any h2 activity
-// so long-running agent conversations (with tool call round-trips) survive.
-// Initial timeout is generous because large conversations require Cursor to
-// deserialize a big checkpoint + run many getBlobArgs round-trips before it
-// starts streaming tokens — 30 s was too short and caused compaction failures.
 const INITIAL_TIMEOUT_MS = parseInt(process.env.PI_CURSOR_BRIDGE_INITIAL_TIMEOUT_MS ?? "") || 120_000;
 const ACTIVITY_TIMEOUT_MS = parseInt(process.env.PI_CURSOR_BRIDGE_ACTIVITY_TIMEOUT_MS ?? "") || 300_000;
+const H2_PING_INTERVAL_MS = parseInt(process.env.PI_CURSOR_BRIDGE_PING_INTERVAL_MS ?? "") || 15_000;
+const H2_PING_TIMEOUT_MS = parseInt(process.env.PI_CURSOR_BRIDGE_PING_TIMEOUT_MS ?? "") || 10_000;
+
+const client = http2.connect(url || "https://api2.cursor.sh", {
+  // Detect dead TCP connections at the HTTP/2 level — without this, a silently
+  // dropped connection (NAT timeout, LB cycling) can leave the bridge waiting
+  // for up to ACTIVITY_TIMEOUT_MS (5 min) with no indication of failure.
+  pingInterval: H2_PING_INTERVAL_MS,
+  pingTimeout: H2_PING_TIMEOUT_MS,
+});
+
 let timeout = setTimeout(killBridge, INITIAL_TIMEOUT_MS);
 
 function resetTimeout() {
@@ -105,12 +109,14 @@ function resetTimeout() {
 
 function killBridge() {
   clearTimeout(timeout);
+  process.stderr.write(JSON.stringify({ type: "exit_reason", reason: "timeout" }) + "\n");
   client.destroy();
-  process.exit(1);
+  process.exit(2);
 }
 
 client.on("error", () => {
   clearTimeout(timeout);
+  process.stderr.write(JSON.stringify({ type: "exit_reason", reason: "connection_error" }) + "\n");
   process.exit(1);
 });
 
@@ -130,6 +136,20 @@ if (!unary) {
 }
 const h2Stream = client.request(headers);
 
+// Read response headers: switch to activity timeout and forward status to stderr
+h2Stream.on("response", (headers) => {
+  resetTimeout();
+  const status = headers[":status"] ?? null;
+  const grpcStatus = headers["grpc-status"] ?? null;
+  process.stderr.write(
+    JSON.stringify({
+      type: "response_headers",
+      status: status !== null ? Number(status) : null,
+      grpcStatus: grpcStatus !== null ? Number(grpcStatus) : null,
+    }) + "\n",
+  );
+});
+
 // Forward H2 response data → stdout (length-prefixed)
 h2Stream.on("data", (chunk) => {
   resetTimeout();
@@ -145,6 +165,7 @@ h2Stream.on("end", () => {
 
 h2Stream.on("error", () => {
   clearTimeout(timeout);
+  process.stderr.write(JSON.stringify({ type: "exit_reason", reason: "stream_error" }) + "\n");
   client.close();
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offbynan/pi-cursor-provider",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Pi extension providing access to Cursor models via OAuth and a local OpenAI-compatible gRPC proxy",
   "type": "module",
   "license": "MIT",

package/proxy.ts

@@ -154,6 +154,11 @@ interface PendingExec {
   decodedArgs: string;
 }
 
+interface StderrData {
+  responseHeaders?: { status: number; grpcStatus: number | null };
+  exitReason?: "timeout" | "connection_error" | "stream_error";
+}
+
 interface BridgeHandle {
   proc: Pick<ChildProcess, "kill">;
   readonly alive: boolean;
@@ -162,6 +167,7 @@ interface BridgeHandle {
   unref(): void;
   onData(cb: (chunk: Buffer) => void): void;
   onClose(cb: (code: number) => void): void;
+  getStderr(): StderrData;
 }
 
 export type BridgeFactory = (options: SpawnBridgeOptions) => BridgeHandle;
@@ -173,6 +179,7 @@ interface ActiveBridge {
   mcpTools: McpToolDefinition[];
   pendingExecs: PendingExec[];
   currentTurn: ParsedTurn;
+  lastTotalTokens: number;
 }
 
 export interface StoredConversation {
@@ -185,6 +192,15 @@ export interface StoredConversation {
    * our static inferContextWindow() estimate when Cursor enforces a tighter cap.
    */
   effectiveContextWindow?: number;
+  /**
+   * Last known usedTokens from Cursor's ConversationTokenDetails.  Persisted
+   * so that tool-call continuations (which create a fresh StreamState) can
+   * report meaningful usage even if the checkpoint hasn't arrived yet in the
+   * new stream segment.
+   */
+  lastTotalTokens?: number;
+  /** Cached for transparent retry when a bridge dies mid-request. */
+  systemPrompt?: string;
 }
 
 interface StreamState {
@@ -263,6 +279,7 @@ interface ParsedMessages {
 // ── State ──
 
 const activeBridges = new Map<string, ActiveBridge>();
+const sessionBridges = new Map<string, BridgeHandle>();
 const conversationStates = new Map<string, StoredConversation>();
 let bridgeFactory: BridgeFactory = spawnBridge;
 let debugRequestCounter = 0;
@@ -353,6 +370,7 @@ function nextDebugRequestId(): string {
 
 export const __testInternals = {
   activeBridges,
+  sessionBridges,
   conversationStates,
 };
 
@@ -395,7 +413,33 @@ function spawnBridge(options: SpawnBridgeOptions): BridgeHandle {
     unary: options.unary ?? false,
   });
   const proc = spawn("node", [BRIDGE_PATH], {
-    stdio: ["pipe", "pipe", "ignore"],
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  const stderrData: StderrData = {};
+  let stderrBuf = "";
+  proc.stderr!.on("data", (chunk: Buffer) => {
+    stderrBuf += chunk.toString("utf8");
+    let nl: number;
+    while ((nl = stderrBuf.indexOf("\n")) !== -1) {
+      const line = stderrBuf.slice(0, nl).trim();
+      stderrBuf = stderrBuf.slice(nl + 1);
+      if (!line) continue;
+      debugLog("bridge.stderr", { rpcPath: options.rpcPath, line });
+      try {
+        const parsed = JSON.parse(line) as Record<string, unknown>;
+        if (parsed["type"] === "response_headers") {
+          stderrData.responseHeaders = {
+            status: parsed["status"] as number,
+            grpcStatus: parsed["grpcStatus"] as number | null,
+          };
+        } else if (parsed["type"] === "exit_reason") {
+          stderrData.exitReason = parsed["reason"] as StderrData["exitReason"];
+        }
+      } catch {
+        // not structured JSON — ignore
+      }
+    }
   });
 
   const config = JSON.stringify({
@@ -433,6 +477,7 @@ function spawnBridge(options: SpawnBridgeOptions): BridgeHandle {
     // loop alive after the bridge exits (critical for `pi -p` to exit cleanly).
     try { proc.stdout!.destroy(); } catch {}
     try { proc.stdin!.destroy(); } catch {}
+    try { proc.stderr!.destroy(); } catch {}
     debugLog("bridge.exit", { rpcPath: options.rpcPath, exitCode });
     cbs.close?.(exitCode);
   });
@@ -469,9 +514,43 @@ function spawnBridge(options: SpawnBridgeOptions): BridgeHandle {
         cbs.close = cb;
       }
     },
+    getStderr() {
+      return stderrData;
+    },
   };
 }
 
+// ── Bridge failure classification ──
+
+function classifyBridgeFailure(code: number, stderr: StderrData): string {
+  const hadHeaders = !!stderr.responseHeaders;
+  const status = stderr.responseHeaders?.status;
+  const reason = stderr.exitReason;
+
+  // Timeout (exit 2 or explicit reason)
+  if (code === 2 || reason === "timeout") {
+    return hadHeaders
+      ? "Cursor did not respond within 5 minutes — try again"
+      : "Could not reach Cursor's API within 2 minutes — check your network";
+  }
+
+  // Connection or stream error (exit 1)
+  if (status === 401 || status === 403) {
+    return "Cursor authentication expired — run /login cursor to re-authenticate";
+  }
+  if (status === 429) {
+    return "Cursor rate limited — try again shortly";
+  }
+  if (status !== undefined && status >= 500 && status < 600) {
+    return `Cursor server error (${status}) — try again`;
+  }
+  if (!hadHeaders) {
+    return "Could not connect to Cursor's API — check your network";
+  }
+
+  return `Cursor bridge terminated (exit ${code}) before response — try again or shorten the conversation`;
+}
+
 // ── Unary RPC (for model discovery) ──
 
 export async function callCursorUnaryRpc(options: {
@@ -758,6 +837,7 @@ export function cleanupAllSessionState(): void {
   for (const [bridgeKey, active] of activeBridges) {
     cleanupBridge(active.bridge, active.heartbeatTimer, bridgeKey);
   }
+  sessionBridges.clear();
   conversationStates.clear();
 }
 
@@ -878,6 +958,7 @@ async function handleChatCompletion(
         res,
         body.stream !== false,
         requestId,
+        accessToken,
       );
       return;
     }
@@ -886,9 +967,7 @@ async function handleChatCompletion(
   }
 
   if (activeBridge && activeBridges.has(bridgeKey)) {
-    clearInterval(activeBridge.heartbeatTimer);
-    activeBridge.bridge.end();
-    activeBridges.delete(bridgeKey);
+    cleanupBridge(activeBridge.bridge, activeBridge.heartbeatTimer, bridgeKey);
   }
 
   let stored = conversationStates.get(convKey);
@@ -902,6 +981,8 @@ async function handleChatCompletion(
     conversationStates.set(convKey, stored);
   }
 
+  stored.systemPrompt = systemPrompt;
+
   const mcpTools = buildMcpToolDefinitions(tools);
   const effectiveUserText =
     userText ||
@@ -942,11 +1023,12 @@ async function handleChatCompletion(
   };
 
   if (body.stream === false) {
-    debugLog("chat.dispatch_nonstream", { requestId, convKey });
+    debugLog("chat.dispatch_nonstream", { requestId, bridgeKey, convKey });
     await handleNonStreamingResponse(
       payload,
       accessToken,
       modelId,
+      bridgeKey,
       convKey,
       turns,
       currentTurn,
@@ -2165,15 +2247,52 @@ function createConnectFrameParser(
   };
 }
 
-function parseConnectEndStream(data: Uint8Array): Error | null {
+const CONTEXT_OVERFLOW_MSG =
+  "context length exceeded — Cursor rejected the request as too large";
+
+function isContextOverflowMessage(msg: string): boolean {
+  return /context|token|length|overflow|too.?long|too.?large/i.test(msg);
+}
+
+function mapConnectErrorCode(code: string, message: string): string {
+  switch (code) {
+    case "unauthenticated":
+      return "Cursor authentication expired — run /login cursor";
+    case "resource_exhausted":
+      return CONTEXT_OVERFLOW_MSG;
+    case "deadline_exceeded":
+      return "Cursor request timed out server-side — try again";
+    case "unavailable":
+      return "Cursor service unavailable — try again";
+    case "internal":
+      return "Cursor internal error — try again";
+    case "invalid_argument":
+      return isContextOverflowMessage(message) ? CONTEXT_OVERFLOW_MSG : message;
+    default:
+      return message;
+  }
+}
+
+interface ConnectEndStreamError {
+  message: string;
+  retryable: boolean;
+}
+
+const RETRYABLE_CONNECT_CODES = new Set(["internal", "unavailable", "deadline_exceeded"]);
+
+function parseConnectEndStream(data: Uint8Array): ConnectEndStreamError | null {
   if (data.length === 0) return null;
   try {
     const payload = JSON.parse(new TextDecoder().decode(data));
     const error = payload?.error;
-    if (error)
-      return new Error(
-        `Connect error ${error.code ?? "unknown"}: ${error.message ?? "Unknown error"}`,
-      );
+    if (error) {
+      const code = String(error.code ?? "unknown");
+      const rawMessage = String(error.message ?? "Unknown error");
+      return {
+        message: mapConnectErrorCode(code, rawMessage),
+        retryable: RETRYABLE_CONNECT_CODES.has(code),
+      };
+    }
     return null;
   } catch {
     return null;
@@ -2212,11 +2331,29 @@ function computeUsage(state: StreamState) {
   return { prompt_tokens, completion_tokens, total_tokens };
 }
 
+function computeUsageFromStored(
+  lastTotalTokens: number,
+  convKey: string,
+  modelId: string,
+): { prompt_tokens: number; completion_tokens: number; total_tokens: number } | undefined {
+  const totalTokens = lastTotalTokens || conversationStates.get(convKey)?.lastTotalTokens || 0;
+  if (totalTokens === 0) return undefined;
+  const stored = conversationStates.get(convKey);
+  const cursorWindow = stored?.effectiveContextWindow ?? 0;
+  const piWindow = inferContextWindow(modelId);
+  let total_tokens = totalTokens;
+  if (cursorWindow > 0 && piWindow > cursorWindow) {
+    total_tokens = Math.round(totalTokens * piWindow / cursorWindow);
+  }
+  return { prompt_tokens: total_tokens, completion_tokens: 0, total_tokens };
+}
+
 function respondWithPendingToolCalls(
   modelId: string,
   pendingExecs: PendingExec[],
   stream: boolean,
   res: ServerResponse,
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number },
 ): void {
   const completionId = `chatcmpl-${crypto.randomUUID().replace(/-/g, "").slice(0, 28)}`;
   const created = Math.floor(Date.now() / 1000);
@@ -2250,6 +2387,18 @@ function respondWithPendingToolCalls(
         })}\n\n`,
       );
     }
+    if (usage) {
+      res.write(
+        `data: ${JSON.stringify({
+          id: completionId,
+          object: "chat.completion.chunk",
+          created,
+          model: modelId,
+          choices: [],
+          usage,
+        })}\n\n`,
+      );
+    }
     res.write(
       `data: ${JSON.stringify({
         id: completionId,
@@ -2278,19 +2427,32 @@ function respondWithPendingToolCalls(
           finish_reason: "tool_calls",
         },
       ],
-      usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+      usage: usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
     }),
   );
 }
 
 // ── Streaming response ──
 
-function startBridge(accessToken: string, requestBytes: Uint8Array) {
+function startBridge(accessToken: string, requestBytes: Uint8Array, bridgeKey: string) {
+  let staleBridgeKilled = false;
+  const existing = sessionBridges.get(bridgeKey);
+  if (existing) {
+    if (existing.alive) {
+      console.error(
+        `[cursor-provider] Stale bridge detected for session ${bridgeKey} — force-killing and replacing`,
+      );
+      staleBridgeKilled = true;
+      try { existing.proc.kill(); } catch {}
+    }
+    sessionBridges.delete(bridgeKey);
+  }
+
   const bridge = bridgeFactory({
     accessToken,
     rpcPath: "/agent.v1.AgentService/Run",
   });
-  debugLog("bridge.start_run", { requestBytes });
+  debugLog("bridge.start_run", { requestBytes, bridgeKey, staleBridgeKilled });
   bridge.write(frameConnectMessage(requestBytes));
   const heartbeatTimer = setInterval(
     () => bridge.write(makeHeartbeatBytes()),
@@ -2298,7 +2460,8 @@ function startBridge(accessToken: string, requestBytes: Uint8Array) {
   );
   // Don't hold the event loop open between heartbeats.
   heartbeatTimer.unref();
-  return { bridge, heartbeatTimer };
+  sessionBridges.set(bridgeKey, bridge);
+  return { bridge, heartbeatTimer, staleBridgeKilled };
 }
 
 function handleStreamingResponse(
@@ -2314,9 +2477,10 @@ function handleStreamingResponse(
   requestId: string,
 ): void {
   debugLog("stream.start", { requestId, bridgeKey, convKey, modelId });
-  const { bridge, heartbeatTimer } = startBridge(
+  const { bridge, heartbeatTimer, staleBridgeKilled } = startBridge(
     accessToken,
     payload.requestBytes,
+    bridgeKey,
   );
   writeSSEStream(
     bridge,
@@ -2331,6 +2495,8 @@ function handleStreamingResponse(
     req,
     res,
     requestId,
+    staleBridgeKilled,
+    accessToken,
   );
 }
 
@@ -2357,13 +2523,18 @@ function cleanupBridge(
   if (bridge.alive) {
     sendCancelAction(bridge);
     bridge.end();
+    setTimeout(() => { try { bridge.proc.kill(); } catch {} }, 10_000);
   }
+  if (sessionBridges.get(bridgeKey) === bridge) sessionBridges.delete(bridgeKey);
   activeBridges.delete(bridgeKey);
 }
 
+const MAX_BRIDGE_RETRIES =
+  parseInt(process.env.PI_CURSOR_MAX_BRIDGE_RETRIES ?? "") || 2;
+
 function writeSSEStream(
-  bridge: BridgeHandle,
-  heartbeatTimer: ReturnType<typeof setInterval>,
+  initialBridge: BridgeHandle,
+  initialHeartbeatTimer: ReturnType<typeof setInterval>,
   blobStore: Map<string, Uint8Array>,
   mcpTools: McpToolDefinition[],
   modelId: string,
@@ -2374,6 +2545,8 @@ function writeSSEStream(
   req: IncomingMessage,
   res: ServerResponse,
   requestId?: string,
+  staleBridgeKilled = false,
+  accessToken?: string,
 ): void {
   debugLog("stream.writer_start", {
     requestId,
@@ -2386,11 +2559,35 @@ function writeSSEStream(
   const completionId = `chatcmpl-${crypto.randomUUID().replace(/-/g, "").slice(0, 28)}`;
   const created = Math.floor(Date.now() / 1000);
 
+  // Mutable bridge references — updated on retry.
+  let activeBridge = initialBridge;
+  let activeHeartbeatTimer = initialHeartbeatTimer;
+  let retryCount = 0;
+  let retryableConnectError = false;
+
+  // Snapshot the checkpoint before this turn so retries replay cleanly
+  // without risking a mid-turn checkpoint that includes partial progress.
+  const preTurnCheckpoint = (() => {
+    const s = conversationStates.get(convKey);
+    return s?.checkpoint ? new Uint8Array(s.checkpoint) : null;
+  })();
+
   res.writeHead(200, {
     "Content-Type": "text/event-stream",
     "Cache-Control": "no-cache",
     Connection: "close",
   });
+  if (staleBridgeKilled) {
+    res.write(
+      `data: ${JSON.stringify({
+        id: completionId,
+        object: "chat.completion.chunk",
+        created,
+        model: modelId,
+        choices: [{ index: 0, delta: { content: "\u26a0 A previous request for this session was still running and has been cancelled.\n" }, finish_reason: null }],
+      })}\n\n`,
+    );
+  }
 
   let closed = false;
   let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
@@ -2406,6 +2603,7 @@ function writeSSEStream(
     if (closed) return;
     closed = true;
     clearInterval(keepAliveTimer);
+    if (stallTimer) clearTimeout(stallTimer);
     res.end();
   };
 
@@ -2438,11 +2636,10 @@ function writeSSEStream(
     toolCallIndex: 0,
     pendingExecs: [],
     outputTokens: 0,
-    totalTokens: 0,
+    totalTokens: storedForState?.lastTotalTokens ?? 0,
     cursorContextWindow: storedForState?.effectiveContextWindow ?? 0,
     inferredContextWindow: inferContextWindow(modelId),
   };
-  const tagFilter = createThinkingTagFilter();
   let mcpExecReceived = false;
   let cancelled = false;
   let latestCheckpoint: Uint8Array | null = null;
@@ -2454,225 +2651,341 @@ function writeSSEStream(
   }, 15_000);
   keepAliveTimer.unref();
 
+  // Stall detector: kill the bridge if no data arrives from Cursor for too
+  // long.  This catches cases where the H2 connection is technically alive
+  // but Cursor's server is stuck processing a stale conversation checkpoint.
+  // Reset on every incoming Connect frame.
+  const STALL_TIMEOUT_MS = parseInt(process.env.PI_CURSOR_BRIDGE_STALL_TIMEOUT_MS ?? "") || 120_000;
+  let stallTimer: ReturnType<typeof setTimeout> | undefined;
+  const resetStallTimer = () => {
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      if (cancelled || closed) return;
+      debugLog("stream.stall_timeout", { requestId, bridgeKey, convKey, modelId });
+      console.error(
+        `[cursor-provider] Bridge stalled for ${STALL_TIMEOUT_MS / 1000}s \u2014 killing (${modelId})`,
+      );
+      cleanupBridge(activeBridge, activeHeartbeatTimer, bridgeKey);
+    }, STALL_TIMEOUT_MS);
+    stallTimer.unref?.();
+  };
+
   // Detect client disconnect (e.g. user pressed Escape in pi)
   const onClientClose = () => {
     if (cancelled || closed) return;
     debugLog("stream.client_close", { requestId, bridgeKey, convKey });
     cancelled = true;
-    cleanupBridge(bridge, heartbeatTimer, bridgeKey);
+    cleanupBridge(activeBridge, activeHeartbeatTimer, bridgeKey);
     closeResponse();
   };
   req.on("close", onClientClose);
   res.on("close", onClientClose);
 
-  const processChunk = createConnectFrameParser(
-    (messageBytes) => {
-      try {
-        const serverMessage = fromBinary(
-          AgentServerMessageSchema,
-          messageBytes,
-        );
-        processServerMessage(
-          serverMessage,
-          blobStore,
-          mcpTools,
-          (data) => bridge.write(data),
-          state,
-          (text, isThinking) => {
-            if (isThinking) {
-              sendSSE(makeChunk({ reasoning_content: text }));
-            } else {
-              const { content, reasoning } = tagFilter.process(text);
-              if (reasoning)
-                sendSSE(makeChunk({ reasoning_content: reasoning }));
-              if (content) {
-                appendAssistantTextToTurn(currentTurn, content);
-                sendSSE(makeChunk({ content }));
+  // Wire data/close handlers onto the current activeBridge.  Called once on
+  // initial setup and again on each transparent retry.
+  function attachToBridge(): void {
+    // Each attempt gets a fresh thinking-tag filter so retried output doesn't
+    // inherit stale parser state from the dead bridge.
+    const tagFilter = createThinkingTagFilter();
+    let contentSent = false;
+    mcpExecReceived = false;
+    resetStallTimer();
+
+    const processChunk = createConnectFrameParser(
+      (messageBytes) => {
+        resetStallTimer();
+        try {
+          const serverMessage = fromBinary(
+            AgentServerMessageSchema,
+            messageBytes,
+          );
+          processServerMessage(
+            serverMessage,
+            blobStore,
+            mcpTools,
+            (data) => activeBridge.write(data),
+            state,
+            (text, isThinking) => {
+              if (isThinking) {
+                contentSent = true;
+                sendSSE(makeChunk({ reasoning_content: text }));
+              } else {
+                const { content, reasoning } = tagFilter.process(text);
+                if (reasoning) {
+                  contentSent = true;
+                  sendSSE(makeChunk({ reasoning_content: reasoning }));
+                }
+                if (content) {
+                  contentSent = true;
+                  appendAssistantTextToTurn(currentTurn, content);
+                  sendSSE(makeChunk({ content }));
+                }
+              }
+            },
+            (exec) => {
+              state.pendingExecs.push(exec);
+              mcpExecReceived = true;
+
+              const flushed = tagFilter.flush();
+              if (flushed.reasoning)
+                sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
+              if (flushed.content) {
+                appendAssistantTextToTurn(currentTurn, flushed.content);
+                sendSSE(makeChunk({ content: flushed.content }));
               }
-            }
-          },
-          (exec) => {
-            state.pendingExecs.push(exec);
-            mcpExecReceived = true;
-
-            const flushed = tagFilter.flush();
-            if (flushed.reasoning)
-              sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
-            if (flushed.content) {
-              appendAssistantTextToTurn(currentTurn, flushed.content);
-              sendSSE(makeChunk({ content: flushed.content }));
-            }
-
-            currentTurn.steps.push({
-              kind: "toolCall",
-              toolCallId: exec.toolCallId,
-              toolName: exec.toolName,
-              arguments: parseToolCallArguments(exec.decodedArgs),
-            });
 
-            const toolCallIndex = state.toolCallIndex++;
-            sendSSE(
-              makeChunk({
-                tool_calls: [
-                  {
-                    index: toolCallIndex,
-                    id: exec.toolCallId,
-                    type: "function",
-                    function: {
-                      name: exec.toolName,
-                      arguments: exec.decodedArgs,
+              currentTurn.steps.push({
+                kind: "toolCall",
+                toolCallId: exec.toolCallId,
+                toolName: exec.toolName,
+                arguments: parseToolCallArguments(exec.decodedArgs),
+              });
+
+              const toolCallIndex = state.toolCallIndex++;
+              sendSSE(
+                makeChunk({
+                  tool_calls: [
+                    {
+                      index: toolCallIndex,
+                      id: exec.toolCallId,
+                      type: "function",
+                      function: {
+                        name: exec.toolName,
+                        arguments: exec.decodedArgs,
+                      },
                     },
-                  },
-                ],
-              }),
+                  ],
+                }),
+              );
+
+              activeBridges.set(bridgeKey, {
+                bridge: activeBridge,
+                heartbeatTimer: activeHeartbeatTimer,
+                blobStore,
+                mcpTools,
+                pendingExecs: state.pendingExecs,
+                currentTurn,
+                lastTotalTokens: state.totalTokens,
+              });
+              debugLog("stream.tool_call_pause", {
+                requestId,
+                bridgeKey,
+                exec,
+                pendingExecs: state.pendingExecs,
+                currentTurn,
+              });
+
+              sendSSE(makeUsageChunk());
+              sendSSE(makeChunk({}, "tool_calls"));
+              sendDone();
+              closeResponse();
+            },
+            (checkpointBytes) => {
+              latestCheckpoint = checkpointBytes;
+              const stored = conversationStates.get(convKey);
+              if (stored) {
+                stored.checkpoint = checkpointBytes;
+                for (const [k, v] of blobStore) stored.blobStore.set(k, v);
+                if (state.cursorContextWindow > 0) {
+                  stored.effectiveContextWindow = state.cursorContextWindow;
+                }
+                if (state.totalTokens > 0) {
+                  stored.lastTotalTokens = state.totalTokens;
+                }
+              }
+              debugLog("stream.checkpoint_buffered", {
+                requestId,
+                convKey,
+                checkpointBytes,
+              });
+            },
+          );
+        } catch (err) {
+          console.error(
+            "[cursor-provider] Stream message processing error:",
+            err instanceof Error ? err.message : err,
+          );
+        }
+      },
+      (endStreamBytes) => {
+        resetStallTimer();
+        const endError = parseConnectEndStream(endStreamBytes);
+        clearInterval(activeHeartbeatTimer);
+        if (stallTimer) clearTimeout(stallTimer);
+        if (endError) {
+          if (endError.retryable && !contentSent && !closed && accessToken && retryCount < MAX_BRIDGE_RETRIES) {
+            debugLog("stream.retryable_connect_error", {
+              requestId, bridgeKey, convKey, modelId,
+              message: endError.message, attempt: retryCount + 1,
+            });
+            console.error(
+              `[cursor-provider] Retryable Cursor error (${modelId}): ${endError.message} — will retry (${retryCount + 1}/${MAX_BRIDGE_RETRIES})`,
             );
+            retryableConnectError = true;
+            try { activeBridge.proc.kill(); } catch {}
+            return;
+          }
+          console.error(
+            `[cursor-provider] Cursor stream error (${modelId}):`,
+            endError.message,
+          );
+          activeBridge.end();
+          activeBridge.unref();
+          sendSSE(makeChunk({ content: endError.message }, "error"));
+          sendSSE(makeUsageChunk());
+          sendDone();
+          closeResponse();
+        } else {
+          activeBridge.end();
+          activeBridge.unref();
+          const flushed = tagFilter.flush();
+          if (flushed.reasoning)
+            sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
+          if (flushed.content) {
+            appendAssistantTextToTurn(currentTurn, flushed.content);
+            sendSSE(makeChunk({ content: flushed.content }));
+          }
+          sendSSE(makeChunk({}, "stop"));
+          sendSSE(makeUsageChunk());
+          sendDone();
+          closeResponse();
+        }
+      },
+    );
 
-            activeBridges.set(bridgeKey, {
-              bridge,
-              heartbeatTimer,
-              blobStore,
-              mcpTools,
-              pendingExecs: state.pendingExecs,
-              currentTurn,
-            });
-            debugLog("stream.tool_call_pause", {
-              requestId,
-              bridgeKey,
-              exec,
-              pendingExecs: state.pendingExecs,
-              currentTurn,
-            });
+    activeBridge.onData(processChunk);
 
-            sendSSE(makeChunk({}, "tool_calls"));
-            sendDone();
-            closeResponse();
-          },
-          (checkpointBytes) => {
-            latestCheckpoint = checkpointBytes;
-            const stored = conversationStates.get(convKey);
-            if (stored) {
-              stored.checkpoint = checkpointBytes;
-              for (const [k, v] of blobStore) stored.blobStore.set(k, v);
-              if (state.cursorContextWindow > 0) {
-                stored.effectiveContextWindow = state.cursorContextWindow;
-              }
-            }
-            debugLog("stream.checkpoint_buffered", {
-              requestId,
-              convKey,
-              checkpointBytes,
-            });
-          },
-        );
-      } catch (err) {
-        console.error(
-          "[cursor-provider] Stream message processing error:",
-          err instanceof Error ? err.message : err,
-        );
-      }
-    },
-    (endStreamBytes) => {
-      const endError = parseConnectEndStream(endStreamBytes);
-      // Always stop heartbeats and unref the bridge regardless of error/success
-      // so the parent process is not kept alive waiting for HTTP/2 END_STREAM.
-      clearInterval(heartbeatTimer);
-      bridge.end();
-      bridge.unref();
-      if (endError) {
-        console.error(
-          `[cursor-provider] Cursor stream error (${modelId}):`,
-          endError.message,
-        );
-        sendSSE(makeChunk({ content: endError.message }, "error"));
-        sendSSE(makeUsageChunk());
-        sendDone();
-        closeResponse();
-      } else {
-        // Cursor's Connect-level response is complete. Send the SSE response
-        // immediately without waiting for HTTP/2 END_STREAM, which Cursor can
-        // delay by several seconds after the Connect end-stream frame.
-        const flushed = tagFilter.flush();
-        if (flushed.reasoning)
-          sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
-        if (flushed.content) {
-          appendAssistantTextToTurn(currentTurn, flushed.content);
-          sendSSE(makeChunk({ content: flushed.content }));
+    activeBridge.onClose((code) => {
+      debugLog("stream.bridge_close", {
+        requestId,
+        bridgeKey,
+        convKey,
+        code,
+        cancelled,
+        mcpExecReceived,
+        currentTurn,
+        latestCheckpoint,
+        retryCount,
+      });
+      clearInterval(activeHeartbeatTimer);
+      if (stallTimer) clearTimeout(stallTimer);
+      if (sessionBridges.get(bridgeKey) === activeBridge) sessionBridges.delete(bridgeKey);
+      const stored = conversationStates.get(convKey);
+      if (stored) {
+        for (const [k, v] of blobStore) stored.blobStore.set(k, v);
+        if (latestCheckpoint) {
+          stored.checkpoint = latestCheckpoint;
+          debugLog("stream.checkpoint_committed", { requestId, convKey, stored });
+        }
+        if (state.cursorContextWindow > 0) {
+          stored.effectiveContextWindow = state.cursorContextWindow;
+        }
+        if (state.totalTokens > 0) {
+          stored.lastTotalTokens = state.totalTokens;
         }
-        sendSSE(makeChunk({}, "stop"));
-        sendSSE(makeUsageChunk());
-        sendDone();
-        closeResponse();
       }
-    },
-  );
+      if (cancelled) return;
+
+      // ── Transparent retry on bridge failure ──
+      // When the bridge dies mid-request (connection killed by LB, TCP
+      // timeout, etc.) or Cursor returns a retryable protocol error
+      // (internal, unavailable, deadline_exceeded), rebuild the Cursor
+      // request and replay on a fresh bridge.  The SSE response stays
+      // open — the client sees at most a brief pause.
+      const shouldRetry = retryableConnectError || code !== 0;
+      if (shouldRetry && !closed && accessToken && retryCount < MAX_BRIDGE_RETRIES) {
+        const cp = preTurnCheckpoint ?? stored?.checkpoint ?? null;
+        // For retryable Connect errors, allow retry even without a
+        // checkpoint (first request in session) — buildCursorRequest
+        // handles checkpoint=null by rebuilding from turns.
+        if (stored && (cp || retryableConnectError)) {
+          retryCount++;
+          const wasConnectError = retryableConnectError;
+          retryableConnectError = false;
+          debugLog("stream.retry", {
+            requestId,
+            bridgeKey,
+            convKey,
+            attempt: retryCount,
+            maxRetries: MAX_BRIDGE_RETRIES,
+            connectError: wasConnectError,
+          });
+          console.error(
+            `[cursor-provider] ${wasConnectError ? "Retryable Cursor error" : `Bridge died (exit ${code})`}, retry ${retryCount}/${MAX_BRIDGE_RETRIES} (${modelId})`,
+          );
 
-  bridge.onData(processChunk);
+          // Reset per-attempt stream state; keep cumulative token counts.
+          state.pendingExecs = [];
+          latestCheckpoint = null;
+
+          const retryPayload = buildCursorRequest(
+            modelId,
+            stored.systemPrompt || "You are a helpful assistant.",
+            currentTurn.userText,
+            completedTurns,
+            stored.conversationId,
+            cp,
+            blobStore,
+            currentTurn.images,
+          );
+          retryPayload.mcpTools = mcpTools;
 
-  bridge.onClose((code) => {
-    debugLog("stream.bridge_close", {
-      requestId,
-      bridgeKey,
-      convKey,
-      code,
-      cancelled,
-      mcpExecReceived,
-      currentTurn,
-      latestCheckpoint,
-    });
-    clearInterval(heartbeatTimer);
-    req.removeListener("close", onClientClose);
-    res.removeListener("close", onClientClose);
-    const stored = conversationStates.get(convKey);
-    if (stored) {
-      for (const [k, v] of blobStore) stored.blobStore.set(k, v);
-      if (latestCheckpoint) {
-        stored.checkpoint = latestCheckpoint;
-        debugLog("stream.checkpoint_committed", { requestId, convKey, stored });
-      }
-      if (state.cursorContextWindow > 0) {
-        stored.effectiveContextWindow = state.cursorContextWindow;
+          const { bridge: newBridge, heartbeatTimer: newTimer } = startBridge(
+            accessToken,
+            retryPayload.requestBytes,
+            bridgeKey,
+          );
+          activeBridge = newBridge;
+          activeHeartbeatTimer = newTimer;
+
+          // Re-register client-close listener with new bridge refs (the old
+          // listener already uses the mutable activeBridge/activeHeartbeatTimer).
+          attachToBridge();
+          return;
+        }
       }
-    }
-    if (cancelled) return;
-    if (!mcpExecReceived) {
-      if (code !== 0) {
-        // Bridge was killed before receiving any response (e.g. timeout waiting
-        // for Cursor to process a large checkpoint during compaction). Treat as
-        // an error so callers (like pi compaction) see a real failure instead of
-        // an empty successful-looking response.
-        console.error(
-          `[cursor-provider] Bridge exited (code ${code}) before receiving response (${modelId})`,
-        );
-        sendSSE(makeChunk({ content: `Cursor bridge terminated (exit ${code}) before response — try again or shorten the conversation` }, "error"));
+
+      // No retry — remove client-close listeners since this bridge is done.
+      req.removeListener("close", onClientClose);
+      res.removeListener("close", onClientClose);
+
+      if (!mcpExecReceived) {
+        if (code !== 0) {
+          console.error(
+            `[cursor-provider] Bridge exited (code ${code}) before receiving response (${modelId})`,
+          );
+          const failureMsg = classifyBridgeFailure(code, activeBridge.getStderr());
+          sendSSE(makeChunk({ content: failureMsg }, "error"));
+          sendSSE(makeUsageChunk());
+          sendDone();
+          closeResponse();
+        } else {
+          const flushed = tagFilter.flush();
+          if (flushed.reasoning)
+            sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
+          if (flushed.content) {
+            appendAssistantTextToTurn(currentTurn, flushed.content);
+            sendSSE(makeChunk({ content: flushed.content }));
+          }
+          sendSSE(makeChunk({}, "stop"));
+          sendSSE(makeUsageChunk());
+          sendDone();
+          closeResponse();
+        }
+      } else if (code !== 0) {
+        sendSSE(makeChunk({ content: "Bridge connection lost" }, "error"));
         sendSSE(makeUsageChunk());
         sendDone();
         closeResponse();
+        activeBridges.delete(bridgeKey);
       } else {
-        const flushed = tagFilter.flush();
-        if (flushed.reasoning)
-          sendSSE(makeChunk({ reasoning_content: flushed.reasoning }));
-        if (flushed.content) {
-          appendAssistantTextToTurn(currentTurn, flushed.content);
-          sendSSE(makeChunk({ content: flushed.content }));
-        }
-        sendSSE(makeChunk({}, "stop"));
-        sendSSE(makeUsageChunk());
-        sendDone();
+        activeBridges.delete(bridgeKey);
         closeResponse();
       }
-    } else if (code !== 0) {
-      sendSSE(makeChunk({ content: "Bridge connection lost" }, "error"));
-      sendSSE(makeUsageChunk());
-      sendDone();
-      closeResponse();
-      activeBridges.delete(bridgeKey);
-    } else {
-      // Bridge closed cleanly after a tool call pause. The HTTP response was
-      // already ended by the MCP exec handler; just ensure cleanup.
-      activeBridges.delete(bridgeKey);
-      closeResponse();
-    }
-  });
+    });
+  }
+
+  attachToBridge();
 }
 
 export function writeSSEStreamForTests(args: {
@@ -2688,6 +3001,7 @@ export function writeSSEStreamForTests(args: {
   req: IncomingMessage;
   res: ServerResponse;
   requestId?: string;
+  accessToken?: string;
 }): void {
   writeSSEStream(
     args.bridge,
@@ -2702,6 +3016,8 @@ export function writeSSEStreamForTests(args: {
     args.req,
     args.res,
     args.requestId,
+    false,
+    args.accessToken,
   );
 }
 
@@ -2718,6 +3034,7 @@ function handleToolResultResume(
   res: ServerResponse,
   stream: boolean,
   requestId?: string,
+  accessToken?: string,
 ): void {
   const {
     bridge,
@@ -2758,6 +3075,7 @@ function handleToolResultResume(
       mcpTools,
       pendingExecs,
       currentTurn,
+      lastTotalTokens: active.lastTotalTokens,
     });
     debugLog("tool_resume.partial_wait", {
       requestId,
@@ -2765,7 +3083,7 @@ function handleToolResultResume(
       unresolvedExecs,
       currentTurn,
     });
-    respondWithPendingToolCalls(modelId, unresolvedExecs, stream, res);
+    respondWithPendingToolCalls(modelId, unresolvedExecs, stream, res, computeUsageFromStored(active.lastTotalTokens, convKey, modelId));
     return;
   }
 
@@ -2819,6 +3137,8 @@ function handleToolResultResume(
     req,
     res,
     requestId,
+    false,
+    accessToken,
   );
 }
 
@@ -2828,6 +3148,7 @@ async function handleNonStreamingResponse(
   payload: CursorRequestPayload,
   accessToken: string,
   modelId: string,
+  bridgeKey: string,
   convKey: string,
   completedTurns: ParsedTurn[],
   currentTurn: ParsedTurn,
@@ -2837,6 +3158,7 @@ async function handleNonStreamingResponse(
 ): Promise<void> {
   debugLog("nonstream.start", {
     requestId,
+    bridgeKey,
     convKey,
     modelId,
     currentTurn,
@@ -2848,6 +3170,7 @@ async function handleNonStreamingResponse(
   const { bridge, heartbeatTimer } = startBridge(
     accessToken,
     payload.requestBytes,
+    bridgeKey,
   );
   let cancelled = false;
 
@@ -2868,13 +3191,13 @@ async function handleNonStreamingResponse(
     toolCallIndex: 0,
     pendingExecs: [],
     outputTokens: 0,
-    totalTokens: 0,
+    totalTokens: storedForNonStream?.lastTotalTokens ?? 0,
     cursorContextWindow: storedForNonStream?.effectiveContextWindow ?? 0,
     inferredContextWindow: inferContextWindow(modelId),
   };
   const tagFilter = createThinkingTagFilter();
   let fullText = "";
-  let nonStreamError: Error | null = null;
+  let nonStreamError: ConnectEndStreamError | null = null;
   let latestCheckpoint: Uint8Array | null = null;
 
   return new Promise((resolve) => {
@@ -2973,6 +3296,7 @@ async function handleNonStreamingResponse(
     bridge.onClose((code) => {
       debugLog("nonstream.bridge_close", {
         requestId,
+        bridgeKey,
         convKey,
         code,
         cancelled,
@@ -2981,6 +3305,7 @@ async function handleNonStreamingResponse(
         latestCheckpoint,
       });
       clearInterval(heartbeatTimer);
+      if (sessionBridges.get(bridgeKey) === bridge) sessionBridges.delete(bridgeKey);
       req.removeListener("close", onClientClose);
       res.removeListener("close", onClientClose);
       const stored = conversationStates.get(convKey);
@@ -2997,6 +3322,9 @@ async function handleNonStreamingResponse(
         if (state.cursorContextWindow > 0) {
           stored.effectiveContextWindow = state.cursorContextWindow;
         }
+        if (state.totalTokens > 0) {
+          stored.lastTotalTokens = state.totalTokens;
+        }
       }
 
       if (cancelled) {
@@ -3035,11 +3363,12 @@ async function handleNonStreamingResponse(
         console.error(
           `[cursor-provider] Bridge exited (code ${code}) before non-stream response (${modelId})`,
         );
+        const failureMsg = classifyBridgeFailure(code, bridge.getStderr());
         res.writeHead(502, { "Content-Type": "application/json" });
         res.end(
           JSON.stringify({
             error: {
-              message: `Cursor bridge terminated (exit ${code}) before response — try again or shorten the conversation`,
+              message: failureMsg,
               type: "upstream_error",
               code: "bridge_terminated",
             },