npm - @bitkyc08/opencodex - Versions diffs - 2.30.0-preview.20260821 → 2.31.0 - Mend

@bitkyc08/opencodex 2.30.0-preview.20260821 → 2.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/README.md +1 -1
package/gui/dist/assets/index-DkcRs1fL.js +102 -0
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/adapters/cursor/cursor-errors.ts +65 -6
package/src/adapters/cursor/discovery.ts +7 -2
package/src/adapters/cursor/effort-map.ts +6 -0
package/src/adapters/cursor/h2-pool.ts +123 -0
package/src/adapters/cursor/live-models.ts +21 -26
package/src/adapters/cursor/live-transport.ts +213 -3
package/src/adapters/cursor/native-exec-common.ts +17 -0
package/src/adapters/cursor/native-exec.ts +9 -4
package/src/adapters/cursor/protobuf-events.ts +5 -1
package/src/adapters/cursor/protobuf-request.ts +11 -4
package/src/adapters/cursor/tool-definitions.ts +20 -0
package/src/adapters/cursor/transport.ts +10 -0
package/src/adapters/cursor.ts +23 -5
package/src/adapters/google.ts +16 -3
package/src/adapters/openai-responses.ts +66 -20
package/src/adapters/xai-web-search.ts +185 -0
package/src/cli/agent.ts +2 -1
package/src/cli/dispatch.ts +2 -2
package/src/cli/doctor.ts +89 -0
package/src/cli/help.ts +2 -0
package/src/cli/registry.ts +7 -2
package/src/codex/auth-context.ts +41 -2
package/src/codex/catalog/effort.ts +1 -1
package/src/codex/catalog/parsing.ts +2 -0
package/src/codex/catalog/provider-fetch.ts +20 -5
package/src/codex/coordinator-doctor.ts +332 -0
package/src/codex/inject-coordination.ts +39 -6
package/src/codex/transition-state.ts +12 -12
package/src/generated/compatibility-version.json +74 -50
package/src/lib/errors.ts +8 -2
package/src/oauth/cursor.ts +21 -0
package/src/providers/cursor-pool.ts +72 -0
package/src/providers/derive.ts +3 -0
package/src/providers/fastwire.ts +12 -1
package/src/providers/openai-sidecar.ts +1 -0
package/src/providers/registry.ts +25 -0
package/src/providers/service-tier.ts +22 -7
package/src/responses/custom-tool-compat.ts +24 -8
package/src/responses/namespace-tool-compat.ts +2 -3
package/src/router.ts +3 -0
package/src/server/chat-completions.ts +4 -0
package/src/server/chat-native.ts +20 -0
package/src/server/management/agent-settings-routes.ts +16 -5
package/src/server/management/config-routes.ts +25 -5
package/src/server/management/vision-sidecar-options.ts +54 -19
package/src/server/responses/compact.ts +1 -2
package/src/server/responses/core.ts +54 -13
package/src/service.ts +122 -14
package/src/types/config.ts +9 -3
package/src/types/provider.ts +6 -0
package/src/usage/cost.ts +52 -38
package/src/usage/expected-prices.ts +79 -9
package/src/vision/backends.ts +97 -0
package/src/vision/eligibility.ts +43 -22
package/src/vision/index.ts +73 -5
package/src/vision/routed-describe.ts +175 -0
package/gui/dist/assets/index-eBA05kYB.js +0 -102

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-eBA05kYB.js"></script>
+    <script type="module" crossorigin src="/assets/index-DkcRs1fL.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CH7ncHCC.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.30.0-preview.20260821",
+  "version": "2.31.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/adapters/cursor/cursor-errors.ts CHANGED Viewed

@@ -112,6 +112,58 @@ export function isCursorInvalidArgumentError(value: unknown): boolean {
 }
 const QUOTA_RATE_CUES = ["too many requests", "quota", "rate limit", "rate-limit", "throttl"];
+/**
+ * A bare `resource_exhausted` end-stream with no detail beyond a generic error wrapper
+ * ("Error" or empty tail) and zero tokens billed is the shape Cursor's backend emits when
+ * the request payload exceeded its context window — not when quota ran out (senpi #1009,
+ * #1036: same wording, two causes). Quota rejections always carry an explicit rate cue
+ * ("too many requests", "quota exhausted"), so the ABSENCE of those cues plus the
+ * absence of a size phrase means payload overflow. Classifying it as 429 makes Codex
+ * back off instead of compacting, which burns retries on an unfixable-by-retry failure.
+ */
+const BARE_RE_TAILS = new Set(["error", "", "resource_exhausted", "resource exhausted"]);
+/**
+ * Size prior for bare resource_exhausted classification (devlog 260, live probe 210):
+ * a plan-gated model returns the SAME bare RE shape on a ~20-token prompt that a real
+ * payload overflow produces, so the message alone cannot separate "compact and retry"
+ * from "this account cannot use this model". When the caller can supply how large the
+ * request actually was relative to the model's window, a small request keeps the
+ * 429-class mapping; only a plausibly-large one classifies as overflow. Unknown
+ * sizes keep today's overflow mapping so the prior only ever REMOVES false overflows
+ * it can prove.
+ */
+export interface CursorSizeContext {
+  estimatedInputTokens?: number;
+  contextWindow?: number;
+}
+const OVERFLOW_MIN_FRACTION = 0.5;
+function bareReLooksLikeOverflow(context?: CursorSizeContext): boolean {
+  if (!context) return true;
+  const { estimatedInputTokens, contextWindow } = context;
+  if (estimatedInputTokens === undefined || contextWindow === undefined || contextWindow <= 0) return true;
+  return estimatedInputTokens >= OVERFLOW_MIN_FRACTION * contextWindow;
+}
+export function isCursorZeroTokenResourceExhausted(lowerMessage: string): boolean {
+  if (!lowerMessage.includes("resource_exhausted") && !lowerMessage.includes("resource exhausted")) return false;
+  // Any explicit quota/rate cue wins: this is a real 429.
+  if (QUOTA_RATE_CUES.some(cue => lowerMessage.includes(cue))) return false;
+  // An explicit size phrase also wins (already handled by the existing classifier).
+  if (isCursorRequestTooLargeDetail(lowerMessage)) return false;
+  // Extract the tail after the resource_exhausted marker. If it names a specific
+  // non-quota, non-size cause, this is NOT bare overflow.
+  const idx = Math.max(
+    lowerMessage.indexOf("resource_exhausted"),
+    lowerMessage.indexOf("resource exhausted"),
+  );
+  const tail = lowerMessage.slice(idx + "resource_exhausted".length).trim().replace(/^[:\s]+/, "").trim();
+  if (!BARE_RE_TAILS.has(tail)) return false;
+  return true;
+}
 const REQUEST_TOO_LARGE_PATTERNS: (string | RegExp)[] = [
   "tool catalog too large",
   "tool registration too large",
@@ -144,7 +196,7 @@ export function isCursorRequestTooLargeDetail(lowerMessage: string): boolean {
  * The returned prefix string is recognized by `src/lib/errors.ts` `classifyError` keywords,
  * so bridge-level error mapping produces the right Codex error type (rate_limit, auth, etc.).
  */
-export function classifyCursorError(message: string): string {
+export function classifyCursorError(message: string, sizeContext?: CursorSizeContext): string {
   const lower = message.toLowerCase();
   if (isCursorBenignCancelError(message)) return "Cursor stream suspended";
@@ -158,9 +210,16 @@ export function classifyCursorError(message: string): string {
     // client-fixable 400; everything else surfaces as a 429 so Codex backs off
     // instead of hammering retries (live evidence: 6x 400 retry storm, devlog
     // 260723_cursor_context_continuity/000_plan.md).
-    return isCursorRequestTooLargeDetail(lower)
-      ? "Cursor resource limit exceeded"
-      : "Cursor rate limit exceeded";
+    if (isCursorRequestTooLargeDetail(lower)) return "Cursor resource limit exceeded";
+    // A bare resource_exhausted with no quota cue and no size phrase is payload
+    // overflow, not rate limiting. Classifying it as 429 makes Codex back off on a
+    // failure that only compaction can fix (senpi #1009 / #1036; research unit T01).
+    // Refinement (devlog 260): plan-gated models emit the same bare shape on tiny
+    // requests — when the caller proves the request was small, keep the 429 class.
+    if (isCursorZeroTokenResourceExhausted(lower)) {
+      return bareReLooksLikeOverflow(sizeContext) ? "Cursor context limit exceeded" : "Cursor rate limit exceeded";
+    }
+    return "Cursor rate limit exceeded";
   }
   if (
@@ -220,8 +279,8 @@ export function classifyCursorError(message: string): string {
  * Produce a user-facing, secret-safe Cursor error message with an actionable category prefix.
  * Mirrors `safeKiroErrorMessage` / `safeKiroHttpErrorMessage` in kiro-errors.ts.
  */
-export function safeCursorErrorMessage(rawMessage: string): string {
-  const prefix = classifyCursorError(rawMessage);
+export function safeCursorErrorMessage(rawMessage: string, sizeContext?: CursorSizeContext): string {
+  const prefix = classifyCursorError(rawMessage, sizeContext);
   const detail = sanitize(rawMessage)
     .replace(/resource[_ ]exhausted/gi, "resource limit exceeded")
     .slice(0, 500);

package/src/adapters/cursor/discovery.ts CHANGED Viewed

@@ -236,10 +236,15 @@ export const CURSOR_STATIC_MODELS: readonly CursorModelInfo[] = normalizeCursorM
   { id: "claude-4.6-opus", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "claude-4.6-sonnet", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "claude-opus-4-7", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
-  // opus-4-7-fast: effort-suffix tiers unverified -> no tier picker; sent bare like live-only ids.
-  { id: "claude-opus-4-7-fast", contextWindow: CONTEXT_200K },
+  // Opus Fast families: live GetUsableModels (260822) lists ONLY effort-suffixed wire ids
+  // ({base-without-fast}-{effort}-fast; the bare id returns not_found), so every entry
+  // carries a tier picker. Live-verified: claude-opus-4-8-high-fast completed a turn.
+  // Tiers per the 260822 dump (devlog 260822_senpi_cursor_transfer/300).
+  { id: "claude-opus-4-7-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
+  { id: "claude-opus-4-8-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "claude-opus-4-8", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "claude-opus-5", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
+  { id: "claude-opus-5-fast", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "claude-fable-5", contextWindow: CONTEXT_200K, supportsReasoningEffort: true },
   { id: "composer-1", contextWindow: CONTEXT_200K },

package/src/adapters/cursor/effort-map.ts CHANGED Viewed

@@ -24,8 +24,14 @@ const CURSOR_MODEL_EFFORT_TIERS: Record<string, readonly string[]> = {
   // against Anthropic's effort ladder docs and Cursor's live model lineup.
   "claude-fable-5": ["low", "medium", "high", "xhigh", "max"],
   "claude-opus-4-7": ["low", "medium", "high", "xhigh", "max"],
+  // Opus Fast tiers from the 260822 GetUsableModels dump (devlog .../300): the wire
+  // exposes {base-without-fast}-{effort}-fast only; suffix derivation at the bottom of
+  // this file produces those ids. opus-5-fast has no xhigh/max (non-thinking) yet.
+  "claude-opus-4-7-fast": ["low", "medium", "high", "xhigh", "max"],
   "claude-opus-4-8": ["low", "medium", "high", "xhigh", "max"],
+  "claude-opus-4-8-fast": ["low", "medium", "high", "xhigh", "max"],
   "claude-opus-5": ["low", "medium", "high", "xhigh", "max"],
+  "claude-opus-5-fast": ["low", "medium", "high"],
   "claude-sonnet-5": ["low", "medium", "high", "xhigh", "max"],
   "glm-5.2": ["high", "max"],
   // 260814 preemptive: glm-5.3 seeded ahead of Cursor's lineup update. Unlike 5.2, Z.AI folds

package/src/adapters/cursor/h2-pool.ts ADDED Viewed

@@ -0,0 +1,123 @@
+import http2 from "node:http2";
+import { registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
+const DEFAULT_MAX_SESSIONS = 8;
+const SESSION_CLOSE_TIMEOUT_MS = 2_000;
+interface PoolEntry {
+  readonly session: http2.ClientHttp2Session;
+  readonly streams: Set<http2.ClientHttp2Stream>;
+  usable: boolean;
+}
+/**
+ * HTTP/2 connection pool for Cursor Connect DISCOVERY calls (GetUsableModels).
+ * Sessions are keyed by origin (scheme+host+port) and reused to avoid fresh
+ * TCP+TLS per call. The Run path deliberately dials its own session: Run
+ * streams are long-lived bidi whose lifecycle/EOF semantics are owned by
+ * live-transport (see devlog 260822_senpi_cursor_transfer/190 — Run-path
+ * pooling is a separate, deliberate unit if ever taken).
+ */
+export class CursorH2SessionPool {
+  private readonly entries = new Map<string, PoolEntry>();
+  private closed = false;
+  constructor(private readonly maxSessions = DEFAULT_MAX_SESSIONS) {}
+  /**
+   * Lazily registered on first use so a process that never talks to Cursor registers
+   * nothing (optional-subsystem doctrine). The seam is synchronous and best-effort;
+   * shutdown() is fire-and-forget there because lifecycle's drainAndShutdown runs
+   * under its own absolute deadline.
+   */
+  private armShutdownHook: (() => void) | undefined = () => {
+    this.armShutdownHook = undefined;
+    registerOptionalShutdownHook("cursor-h2-pool", () => { void this.shutdown(); });
+  };
+  request(
+    url: string,
+    headers: http2.OutgoingHttpHeaders,
+  ): http2.ClientHttp2Stream {
+    if (this.closed) throw new Error("Cursor H2 session pool is closed");
+    this.armShutdownHook?.();
+    const origin = new URL(url).origin;
+    const entry = this.usableEntry(origin) ?? this.createEntry(origin);
+    try {
+      const stream = entry.session.request(headers);
+      entry.streams.add(stream);
+      stream.once("close", () => { entry.streams.delete(stream); });
+      return stream;
+    } catch (error) {
+      this.drain(entry, true);
+      throw error;
+    }
+  }
+  async shutdown(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    const pending: Promise<void>[] = [];
+    for (const entry of [...this.entries.values()]) {
+      for (const stream of [...entry.streams]) stream.destroy();
+      entry.session.close();
+      if (entry.session.destroyed) continue;
+      pending.push(new Promise<void>(resolve => {
+        const timer = setTimeout(resolve, SESSION_CLOSE_TIMEOUT_MS);
+        timer.unref?.();
+        entry.session.once("close", () => { clearTimeout(timer); resolve(); });
+      }));
+    }
+    this.entries.clear();
+    await Promise.all(pending);
+  }
+  get size(): number { return this.entries.size; }
+  private usableEntry(origin: string): PoolEntry | undefined {
+    const entry = this.entries.get(origin);
+    if (!entry) return undefined;
+    if (entry.usable && !entry.session.closed && !entry.session.destroyed) return entry;
+    this.drain(entry, false);
+    return undefined;
+  }
+  private createEntry(origin: string): PoolEntry {
+    const session = http2.connect(origin);
+    const entry: PoolEntry = {
+      session,
+      streams: new Set(),
+      usable: true,
+    };
+    this.entries.set(origin, entry);
+    session.once("goaway", () => { this.drain(entry, true); });
+    session.on("error", () => { this.drain(entry, false); });
+    session.once("close", () => {
+      // Identity check: a stale close event from an old session must not evict
+      // a healthy replacement entry that was created after drain() removed the old one.
+      if (this.entries.get(origin) === entry) this.entries.delete(origin);
+    });
+    // Enforce bound: evict oldest when over capacity.
+    while (this.entries.size > this.maxSessions) {
+      const oldest = this.entries.keys().next().value;
+      if (!oldest || oldest === origin) break;
+      const old = this.entries.get(oldest);
+      if (old) this.drain(old, true);
+    }
+    return entry;
+  }
+  private drain(entry: PoolEntry, closeSession: boolean): void {
+    entry.usable = false;
+    for (const stream of [...entry.streams]) stream.destroy();
+    entry.streams.clear();
+    if (closeSession) entry.session.close();
+    // Remove from map by finding the matching key.
+    for (const [key, value] of this.entries) {
+      if (value === entry) { this.entries.delete(key); break; }
+    }
+  }
+}
+/** Shared singleton pool for all Cursor adapter H2 traffic. */
+export const cursorH2Pool = new CursorH2SessionPool();

package/src/adapters/cursor/live-models.ts CHANGED Viewed

@@ -14,6 +14,7 @@
  *   5-byte gRPC/Connect frame makes the server mis-parse it ("illegal tag: field no 0").
  */
 import http2 from "node:http2";
+import { cursorH2Pool } from "./h2-pool";
 import { fromBinary } from "@bufbuild/protobuf";
 import type { UpstreamHttpVersion } from "../../types";
 import { readBoundedResponseBytes } from "../../lib/bounded-body";
@@ -205,35 +206,29 @@ async function fetchCursorUsableModelsHttp2Once(opts: CursorUsableModelsOptions)
       resolve(value);
     };
-    let client: http2.ClientHttp2Session;
-    try {
-      client = http2.connect(baseUrl);
-    } catch {
-      return finish({ ok: false, error: "transport", detail: "HTTP/2 connection setup failed" });
-    }
-    const timer = setTimeout(() => {
-      finish({ ok: false, error: "timeout", detail: `No response within ${timeoutMs}ms` });
-      client.destroy();
-    }, timeoutMs);
-    const close = (value: CursorUsableModelsResult): void => {
-      clearTimeout(timer);
-      client.close();
-      finish(value);
-    };
+   const timer = setTimeout(() => {
+     // Cancel the borrowed pooled stream so it does not continue receiving
+     // body bytes after the caller has timed out (regression vs pre-pool behavior).
+     req?.destroy();
+     finish({ ok: false, error: "timeout", detail: `No response within ${timeoutMs}ms` });
+   }, timeoutMs);
+   const close = (value: CursorUsableModelsResult): void => {
+     clearTimeout(timer);
+     finish(value);
+   };
-    client.on("error", () => close({ ok: false, error: "transport", detail: "HTTP/2 session failed" }));
-    let req: http2.ClientHttp2Stream;
-    try {
-      req = client.request({
-        ":method": "POST",
-        ":path": CURSOR_GET_USABLE_MODELS_PATH,
-        ...cursorDiscoveryHeaders(opts),
-      });
-    } catch {
-      return close({ ok: false, error: "transport", detail: "HTTP/2 request setup failed" });
-    }
+   let req: http2.ClientHttp2Stream;
+   try {
+      req = cursorH2Pool.request(baseUrl, {
+       ":method": "POST",
+       ":path": CURSOR_GET_USABLE_MODELS_PATH,
+       ...cursorDiscoveryHeaders(opts),
+     });
+   } catch {
+     return close({ ok: false, error: "transport", detail: "HTTP/2 request setup failed" });
+   }
     let status = 0;
     const chunks: Buffer[] = [];

package/src/adapters/cursor/live-transport.ts CHANGED Viewed

@@ -91,6 +91,24 @@ const CURSOR_RUN_PATH = "/agent.v1.AgentService/Run";
 const CURSOR_CLIENT_VERSION = "cli-2026.07.08-0c04a8a";
 const HEARTBEAT_MS = 5_000;
 const CURSOR_FIRST_FRAME_TIMEOUT_MS = 30_000;
+/**
+ * T04 (senpi #1062 second half): after the first frame, a turn with NO inbound decoded
+ * frames for this long is failed instead of waiting for the 300s bridge stall watchdog
+ * (issue #2210). Reset on every decoded AgentServerMessage.
+ */
+const CURSOR_STREAM_SILENCE_FAIL_MS = 30_000;
+/**
+ * A stream that produces ONLY liveness frames (server heartbeat / conversationCheckpointUpdate)
+ * for this long is equally stuck — the server is alive but the turn is not progressing.
+ * Reset on every decoded frame that is not liveness-only.
+ */
+const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 90_000;
+/**
+ * After `turnEnded` is decoded, the application turn is complete. A server that keeps
+ * HTTP/2 open past this point cannot hold the turn hostage (senpi #1062): we close our side
+ * after a short grace so any trailing frames (late usage, checkpoint) still land.
+ */
+const TURN_ENDED_CLOSE_GRACE_MS = 500;
 const CURSOR_TIMEOUT_DESTROY_GRACE_MS = 1_000;
 const CLIENT_TOOL_FINALIZE_GRACE_MS = 50;
 const GENERIC_TOOL_COUNT_MIN_FINALIZE_GRACE_MS = 750;
@@ -414,6 +432,18 @@ class LiveCursorTransport implements CursorTransport {
   private http1Connection?: CursorHttp1BidiConnection;
   private heartbeat?: ReturnType<typeof setInterval>;
   private firstFrameTimer?: ReturnType<typeof setTimeout>;
+  private turnEndedCloseTimer?: ReturnType<typeof setTimeout>;
+  /**
+   * T04 inbound stream-health watchdog. Armed after the request is on the wire, reset by
+   * every DECODED frame (raw chunks deliberately do not count — TLS keepalive noise must not
+   * defeat it), disarmed by any settle/expected-close path. One timer covers both thresholds:
+   * it always fires at min(lastInbound + silence, lastMeaningful + heartbeatOnly) and re-arms
+   * when neither deadline has actually elapsed.
+   */
+  private streamHealthTimer?: ReturnType<typeof setTimeout>;
+  private lastInboundFrameAt = 0;
+  private lastMeaningfulFrameAt = 0;
+  private streamHealthFail?: (error: Error) => void;
   private committed = false;
   private expectedClose = false;
   /**
@@ -753,14 +783,100 @@ class LiveCursorTransport implements CursorTransport {
     }
   }
+  private clearStreamHealthTimer(): void {
+    if (this.streamHealthTimer) {
+      clearTimeout(this.streamHealthTimer);
+      this.streamHealthTimer = undefined;
+    }
+    this.streamHealthFail = undefined;
+  }
+  /**
+   * T04: arm (or re-arm) the inbound stream-health watchdog. `fail` is the turn's
+   * failAndClear; the timer owns nothing else. Never armed before the first decoded
+   * frame (the first-frame timer covers dial + first response), and disarmed by
+   * every settle / expected-close path alongside the other timers.
+   */
+  private armStreamHealthTimer(fail: (error: Error) => void): void {
+    if (this.streamHealthTimer) clearTimeout(this.streamHealthTimer);
+    if (this.expectedClose) return;
+    this.streamHealthFail = fail;
+    const silenceMs = this.input.streamSilenceFailMs ?? CURSOR_STREAM_SILENCE_FAIL_MS;
+    const heartbeatOnlyMs = this.input.streamHeartbeatOnlyFailMs ?? CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS;
+    const now = Date.now();
+    const deadline = Math.min(
+      this.lastInboundFrameAt + silenceMs,
+      this.lastMeaningfulFrameAt + heartbeatOnlyMs,
+    );
+    this.streamHealthTimer = setTimeout(() => {
+      this.streamHealthTimer = undefined;
+      const failFn = this.streamHealthFail;
+      if (!failFn || this.expectedClose) return;
+      const stalledFor = Date.now() - this.lastInboundFrameAt;
+      const meaningfulStalledFor = Date.now() - this.lastMeaningfulFrameAt;
+      if (stalledFor < silenceMs && meaningfulStalledFor < heartbeatOnlyMs) {
+        // A frame landed between arming and firing — re-arm for the fresh deadline.
+        this.armStreamHealthTimer(failFn);
+        return;
+      }
+      const heartbeatOnly = stalledFor < silenceMs;
+      debugProviderDiagnostic("cursor", "stream-health-timeout", {
+        stalledMs: stalledFor,
+        meaningfulStalledMs: meaningfulStalledFor,
+        heartbeatOnly,
+        framesReceived: this.framesReceived,
+        elapsedMs: Date.now() - this.turnStartedAt,
+      });
+      const reason = heartbeatOnly
+        ? `Cursor stream stalled: heartbeat-only traffic for ${Math.round(meaningfulStalledFor / 1000)}s without turn progress`
+        : `Cursor stream stalled: no inbound frames for ${Math.round(stalledFor / 1000)}s before turnEnded`;
+      failFn(new Error(reason));
+      try { this.stream?.close(); } catch { this.stream?.destroy(); }
+      this.session?.close();
+      this.http1Connection?.close();
+    }, Math.max(0, deadline - now));
+  }
+  /**
+   * T04: record a decoded inbound frame. Liveness-only frames (server heartbeat,
+   * conversationCheckpointUpdate) keep the silence clock fresh but not the progress
+   * clock — matching senpi's split so a server that only pings still fails at the
+   * heartbeat-only threshold.
+   */
+  private noteInboundFrame(livenessOnly: boolean): void {
+    const now = Date.now();
+    this.lastInboundFrameAt = now;
+    if (!livenessOnly) this.lastMeaningfulFrameAt = now;
+    if (this.streamHealthFail) this.armStreamHealthTimer(this.streamHealthFail);
+  }
+  /**
+   * A clean Connect END_STREAM owns the turn terminal even when Cursor keeps the
+   * HTTP body open or tears it down with an abort/reset immediately afterward.
+   * Stop client-side liveness work and classify that later transport close as
+   * expected without actively sending an RST_STREAM back to Cursor.
+   */
+  private markProtocolComplete(): void {
+    this.expectedClose = true;
+    this.clearPendingFinalize();
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = undefined;
+    }
+    this.clearFirstFrameTimer();
+    this.clearStreamHealthTimer();
+  }
   private startShellCleanup(): Promise<BackgroundShellTerminationReport> {
     return this.shellCleanup ??= terminateBackgroundShellsForSession(this.shellOwnerId);
   }
   async close(): Promise<void> {
     if (this.heartbeat) clearInterval(this.heartbeat);
+    if (this.turnEndedCloseTimer) clearTimeout(this.turnEndedCloseTimer);
     this.clearPendingFinalize();
     this.clearFirstFrameTimer();
+    this.clearStreamHealthTimer();
     this.stream?.close();
     this.session?.close();
     this.http1Connection?.close();
@@ -776,6 +892,7 @@ class LiveCursorTransport implements CursorTransport {
     this.clearPendingFinalize();
     if (this.heartbeat) clearInterval(this.heartbeat);
     this.clearFirstFrameTimer();
+    this.clearStreamHealthTimer();
     if (this.http1Connection) {
       this.http1Connection.close();
     } else {
@@ -793,6 +910,46 @@ class LiveCursorTransport implements CursorTransport {
     void this.startShellCleanup().catch(() => { /* close() observes the same cleanup promise */ });
   }
+  /**
+   * T03 (#1062): after the server sends `turnEnded`, the application turn is complete.
+   * A server that keeps the HTTP/2 stream open past this point cannot hold the turn
+   * hostage until a 300s bridge idle timeout. Close our side after a short grace so any
+   * trailing frames (late usage, checkpoint) still land before we release the socket.
+   */
+  private closeAfterTurnEnded(): void {
+    if (this.turnEndedCloseTimer) return;
+    // The application turn is over: the T03 grace timer owns the socket from here.
+    // The T04 watchdog must disarm NOW, not at the grace close — a watchdog shorter
+    // than the grace would otherwise fail a completed turn.
+    this.clearStreamHealthTimer();
+    this.turnEndedCloseTimer = setTimeout(() => {
+      this.turnEndedCloseTimer = undefined;
+      // Only expectedClose (client-tool suspend cancel) blocks the close.
+      // emittedTerminal is intentionally NOT checked here: finalizeTurnEvents sets it
+      // synchronously during turnEnded mapping, ~500ms before this timer fires, so
+      // checking it would make the close unreachable on every real path (the exact
+      // scenario this PR exists to fix — senpi #1062).
+      if (this.expectedClose) return;
+      debugProviderDiagnostic("cursor", "turn-ended-close", {
+        committed: this.committed,
+        framesReceived: this.framesReceived,
+      });
+      this.expectedClose = true;
+      this.clearFirstFrameTimer();
+      this.clearStreamHealthTimer();
+      if (this.heartbeat) clearInterval(this.heartbeat);
+      if (this.http1Connection) {
+        this.http1Connection.close();
+      } else {
+        try {
+          this.stream?.close();
+        } catch {
+          this.stream?.destroy();
+        }
+      }
+    }, TURN_ENDED_CLOSE_GRACE_MS);
+  }
   private releaseBlobRequestScope(): void {
     const scope = this.blobRequestScope;
     if (!scope) return;
@@ -903,7 +1060,10 @@ class LiveCursorTransport implements CursorTransport {
     const settler = createTerminalSettler({
       fail,
       finish,
-      clearTimer: () => this.clearFirstFrameTimer(),
+      clearTimer: () => {
+        this.clearFirstFrameTimer();
+        this.clearStreamHealthTimer();
+      },
     });
     const failAndClear = (error: Error) => {
       releaseBacklogLease();
@@ -1000,10 +1160,54 @@ class LiveCursorTransport implements CursorTransport {
           framesReceived: this.framesReceived,
           elapsedMs: Date.now() - this.turnStartedAt,
         } : { framesReceived: this.framesReceived, elapsedMs: Date.now() - this.turnStartedAt });
-        if (endError) failAndClear(endError);
+        if (endError) {
+          failAndClear(endError);
+          return;
+        }
+        // Connect's clean END_STREAM envelope is the protocol terminal. Cursor's RunSSE body can
+        // remain open after this frame (or close through an AbortError), so waiting for HTTP EOF
+        // strands an otherwise completed turn until the outer bridge stall watchdog fires.
+        //
+        // Earlier frames in this serialized frameWork chain have already run. Preserve their real
+        // turnEnded terminal when present; otherwise finalize the clean protocol end once so open
+        // tool calls still fail closed, a text-only turn receives its normal done event, and a
+        // drained client-tool turn does not lose the pending terminal when protocol cleanup clears
+        // its grace timer.
+        const hasPendingClientToolFinalization = this.pendingFinalize !== undefined;
+        if (
+          !this.expectedClose
+          && !state.terminated
+          && !this.emittedTerminal
+          && (
+            state.openToolCalls.size > 0
+            || this.sawAssistantText
+            || hasPendingClientToolFinalization
+          )
+        ) {
+          const terminal = hasPendingClientToolFinalization && state.openToolCalls.size === 0
+            ? finalizeAfterDrain(state)
+            : finalizeTurnEvents(state);
+          for (const event of terminal) push(event);
+        }
+        this.markProtocolComplete();
+        releaseBacklogLease();
+        settler.settleFinish();
         return;
       }
-      await this.handleServerMessage(fromBinary(AgentServerMessageSchema, frame.payload), state, push);
+      const decoded = fromBinary(AgentServerMessageSchema, frame.payload);
+      // T04: every decoded frame refreshes the silence clock; only non-liveness frames
+      // refresh the progress clock. First decoded frame arms the watchdog (the first-frame
+      // timer owned everything before this point).
+      const decodedUpdate = decoded.message.case === "interactionUpdate" ? decoded.message.value.message?.case : undefined;
+      const livenessOnly = decodedUpdate === "heartbeat" || decoded.message.case === "conversationCheckpointUpdate";
+      if (!this.streamHealthFail) {
+        const now = Date.now();
+        this.lastInboundFrameAt = now;
+        this.lastMeaningfulFrameAt = now;
+        this.streamHealthFail = failAndClear;
+      }
+      this.noteInboundFrame(livenessOnly);
+      await this.handleServerMessage(decoded, state, push);
     };
     const drainPendingFrames = () => {
       const availableSlots = CURSOR_MAX_PENDING_FRAMES - this.pendingTransportFrames;
@@ -1273,6 +1477,12 @@ class LiveCursorTransport implements CursorTransport {
     // A completion may carry only callId. Capture its ownership before mapping removes the open
     // call, because the embedded-tool classifier cannot identify that valid compact frame.
     const update = message.message.case === "interactionUpdate" ? message.message.value.message : undefined;
+    if (update?.case === "turnEnded") {
+      // T03: the application turn is complete. Close our side of HTTP/2 after a short
+      // grace so a held-open server response cannot pin the turn to the bridge's idle
+      // timeout (senpi #1062). finalizeTurnEvents already emitted done via the mapper.
+      this.closeAfterTurnEnded();
+    }
     const completesOpenClientTool = update?.case === "toolCallCompleted"
       && state.openToolCalls.has(update.value.callId);
     const awaitedNativeArgsBeforeMapping = update?.case === "toolCallCompleted"

package/src/adapters/cursor/native-exec-common.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import { create, toBinary } from "@bufbuild/protobuf";
 import {
   AgentClientMessageSchema,
+  ExecClientThrowSchema,
   ExecClientControlMessageSchema,
   ExecClientMessageSchema,
   ExecClientStreamCloseSchema,
@@ -49,6 +50,22 @@ export function execStreamCloseBytes(execMsg: ExecServerMessage): Uint8Array {
   });
 }
+/**
+ * Exec-channel typed throw (`execClientControlMessage.throw`). senpi's contract (T05):
+ * a frame that cannot be answered at all must get an explicit error reply + stream-close
+ * so the server unblocks with a known failure, instead of waiting forever on silence.
+ */
+export function execThrowBytes(execMsg: ExecServerMessage, error: string): Uint8Array {
+  return clientBytes({
+    message: {
+      case: "execClientControlMessage",
+      value: create(ExecClientControlMessageSchema, {
+        message: { case: "throw", value: create(ExecClientThrowSchema, { id: execMsg.id, error }) },
+      }),
+    },
+  });
+}
 export function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }