pi-provider-cursor-ask 0.1.0

package/src/stream/thinking-filter.ts

@@ -0,0 +1,63 @@
+/**
+ * Strips inline thinking tags out of Cursor's text stream.
+ *
+ * Some models wrap reasoning in `<think>`/`<thinking>`/... tags inside the
+ * ordinary text channel. Pi has a separate thinking channel, so the tags have to
+ * come out of the visible text without waiting for the full response — the
+ * filter is incremental and holds back only a partial tag's worth of characters
+ * at a chunk boundary.
+ */
+
+const THINKING_TAG_NAMES = ["think", "thinking", "reasoning", "thought", "think_intent"];
+
+const MAX_THINKING_TAG_LEN = 16;
+
+// Hoisted to module scope so it is compiled once rather than rebuilt on every
+// streamed chunk. `lastIndex` is reset at the start of each process() call.
+const THINKING_TAG_RE = new RegExp(`<(/?)(?:${THINKING_TAG_NAMES.join("|")})\\s*>`, "gi");
+
+export function createThinkingTagFilter() {
+  let buffer = "";
+  let inThinking = false;
+  return {
+    process(text: string) {
+      const input = buffer + text;
+      buffer = "";
+      let content = "";
+      let reasoning = "";
+      let lastIdx = 0;
+      const re = THINKING_TAG_RE;
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(input)) !== null) {
+        const before = input.slice(lastIdx, match.index);
+        if (inThinking) reasoning += before;
+        else content += before;
+        inThinking = match[1] !== "/";
+        lastIdx = re.lastIndex;
+      }
+      const rest = input.slice(lastIdx);
+      const ltPos = rest.lastIndexOf("<");
+      if (
+        ltPos >= 0 &&
+        rest.length - ltPos < MAX_THINKING_TAG_LEN &&
+        /^<\/?[a-z_]*$/i.test(rest.slice(ltPos))
+      ) {
+        buffer = rest.slice(ltPos);
+        const before = rest.slice(0, ltPos);
+        if (inThinking) reasoning += before;
+        else content += before;
+      } else {
+        if (inThinking) reasoning += rest;
+        else content += rest;
+      }
+      return { content, reasoning };
+    },
+    flush() {
+      const b = buffer;
+      buffer = "";
+      if (!b) return { content: "", reasoning: "" };
+      return inThinking ? { content: "", reasoning: b } : { content: b, reasoning: "" };
+    },
+  };
+}

package/src/stream/tool-schema.ts

@@ -0,0 +1,185 @@
+/**
+ * Cursor MCP tool-schema encoding.
+ *
+ * Pi tools use JSON Schema, while Cursor carries each schema as a protobuf
+ * Value. The optional slimming pass removes model-facing prose without changing
+ * property names or the executable schema contract.
+ */
+import { create, fromJson, toBinary, type JsonValue } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+
+import { McpToolDefinitionSchema, type McpToolDefinition } from "../proto/agent_pb.js";
+import type { OpenAIToolDef } from "./types.js";
+
+/**
+ * Whether to truncate verbose tool descriptions/parameter docs before sending
+ * them to Cursor. Default ON — full Pi/MCP prose often costs tens of thousands
+ * of tokens per turn without improving tool selection. Set
+ * PI_CURSOR_SLIM_TOOLS=0 to keep the original tool definitions.
+ */
+export function isSlimToolsEnabled(envValue = process.env.PI_CURSOR_SLIM_TOOLS): boolean {
+  const raw = envValue?.trim().toLowerCase();
+  if (!raw) return true;
+  return raw !== "0" && raw !== "false" && raw !== "off" && raw !== "no";
+}
+
+const SCHEMA_ANNOTATION_KEYS = new Set([
+  "description",
+  "title",
+  "examples",
+  "default",
+  "$comment",
+  "$schema",
+  "$id",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+]);
+
+/** Keywords whose values are maps from user-defined names to child schemas. */
+const NAMED_SCHEMA_MAP_KEYS = new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  // Draft-07 dependencies values may be either child schemas or string arrays.
+  "dependencies",
+]);
+
+/** Keywords whose value is one child schema or an array of child schemas. */
+const CHILD_SCHEMA_KEYS = new Set([
+  "additionalProperties",
+  "unevaluatedProperties",
+  "propertyNames",
+  "contains",
+  "items",
+  "additionalItems",
+  "unevaluatedItems",
+  "if",
+  "then",
+  "else",
+  "not",
+  "contentSchema",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "prefixItems",
+]);
+
+function slimChildSchema(value: unknown, depth: number): unknown {
+  if (Array.isArray(value)) return value.map((item) => slimJsonSchema(item, depth));
+  return slimJsonSchema(value, depth);
+}
+
+/**
+ * Slim a map such as `properties` without interpreting its user-defined keys as
+ * JSON Schema keywords. A parameter may legally be named `description`,
+ * `default`, or any other annotation keyword.
+ */
+function slimNamedSchemaMap(value: unknown, depth: number): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).map(([name, childSchema]) => [
+      name,
+      slimChildSchema(childSchema, depth),
+    ]),
+  );
+}
+
+/**
+ * Remove prose-only annotations from actual JSON Schema nodes while preserving
+ * the executable contract. Traversal is keyword-aware: blindly recursing into
+ * `properties` treats a parameter named `description` as an annotation and
+ * leaves an invalid dangling entry in `required`.
+ */
+function slimJsonSchema(value: unknown, depth = 0): unknown {
+  if (value == null || depth > 12 || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item) => slimJsonSchema(item, depth + 1));
+
+  const input = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(input)) {
+    if (SCHEMA_ANNOTATION_KEYS.has(key) || child === undefined) continue;
+    if (key === "additionalProperties" && child === true) continue;
+    if (key === "required" && Array.isArray(child) && child.length === 0) continue;
+    if (NAMED_SCHEMA_MAP_KEYS.has(key)) {
+      out[key] = slimNamedSchemaMap(child, depth + 1);
+      continue;
+    }
+    if (CHILD_SCHEMA_KEYS.has(key)) {
+      out[key] = slimChildSchema(child, depth + 1);
+      continue;
+    }
+    // Constraints and literal values (for example enum/const) are executable
+    // data, not schema containers. Keep them byte-for-byte equivalent.
+    out[key] = child;
+  }
+  return out;
+}
+
+function conciseToolDescription(description: string): string {
+  const normalized = description.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 120) return normalized;
+  const firstSentence = normalized.match(/^.{24,117}?[.!?](?:\s|$)/)?.[0]?.trim();
+  return firstSentence || `${normalized.slice(0, 117)}...`;
+}
+
+/** Compact tool prose/schemas for the Cursor MCP tool surface. */
+export function slimOpenAIToolsForCursor(tools: OpenAIToolDef[]): OpenAIToolDef[] {
+  if (!isSlimToolsEnabled()) return tools;
+  return tools.map((tool) => {
+    const fn = tool.function;
+    const parameters =
+      fn.parameters && typeof fn.parameters === "object"
+        ? (slimJsonSchema(fn.parameters) as Record<string, unknown>)
+        : fn.parameters;
+    return {
+      ...tool,
+      function: {
+        ...fn,
+        description: conciseToolDescription(fn.description || ""),
+        ...(parameters ? { parameters } : {}),
+      },
+    };
+  });
+}
+
+// Pi typically hands the provider the same `tools` array reference turn after
+// turn. Cache the pure schema preparation + protobuf encoding by that identity
+// and the env-controlled slimming mode.
+const mcpToolDefinitionsCache = new WeakMap<OpenAIToolDef[], Map<boolean, McpToolDefinition[]>>();
+
+export function buildMcpToolDefinitions(tools: OpenAIToolDef[]): McpToolDefinition[] {
+  const slimEnabled = isSlimToolsEnabled();
+  const byMode = mcpToolDefinitionsCache.get(tools);
+  const cached = byMode?.get(slimEnabled);
+  if (cached) return cached;
+
+  const prepared = slimOpenAIToolsForCursor(tools);
+  const result = prepared.map((tool) => {
+    const fn = tool.function;
+    const jsonSchema: JsonValue =
+      fn.parameters && typeof fn.parameters === "object"
+        ? (fn.parameters as JsonValue)
+        : { type: "object", properties: {}, required: [] };
+    // Cursor CLI's current schema uses google.protobuf.Value for
+    // McpToolDefinition.input_schema. The committed generated schema still
+    // exposes that field as bytes, but the outer wire encoding is identical
+    // for bytes and message fields (length-delimited field #3), so place the
+    // serialized Value bytes here.
+    const inputSchema = toBinary(ValueSchema, fromJson(ValueSchema, jsonSchema));
+    return create(McpToolDefinitionSchema, {
+      name: fn.name,
+      description: fn.description || "",
+      providerIdentifier: "pi",
+      toolName: fn.name,
+      inputSchema,
+    });
+  });
+
+  const modes = byMode ?? new Map<boolean, McpToolDefinition[]>();
+  modes.set(slimEnabled, result);
+  mcpToolDefinitionsCache.set(tools, modes);
+  return result;
+}

package/src/stream/transport-errors.ts

@@ -0,0 +1,150 @@
+/**
+ * Structured classification for Cursor transport failures.
+ *
+ * Callers use this to decide whether a transport close / Connect error is safe to
+ * recover from (new generation + checkpoint/history) versus permanent.
+ */
+
+import { TransportFailureKind } from "../types/enums.js";
+
+export { TransportFailureKind };
+
+export interface TransportFailure {
+  kind: TransportFailureKind;
+  /** Whether a new stream generation may be attempted. */
+  retryable: boolean;
+  /** Prefer force-refreshing credentials before the next attempt. */
+  refreshAuth: boolean;
+  /** Human-readable summary (secrets must already be redacted by caller). */
+  message: string;
+  /** Optional normalized transport close code. */
+  exitCode?: number;
+  /** Optional in-process transport diagnostics tail. */
+  stderr?: string;
+}
+
+const AUTH_RE =
+  /\b(401|403|unauthenticated|unauthorized|forbidden|invalid[_ ]token|token (?:expired|revoked)|auth(?:entication|orization) (?:failed|error))\b/i;
+const RATE_RE = /\b(429|resource_exhausted|rate[_ ]?limit|too many requests)\b/i;
+const GOAWAY_RE = /\bGOAWAY\b/i;
+const RESET_RE = /\b(ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE|socket hang up|connection reset)\b/i;
+const TIMEOUT_RE = /\b(ETIMEDOUT|timed? ?out|timeout)\b/i;
+const PROTOCOL_RE = /\b(protocol|protobuf|wire drift|invalid argument|failed_precondition)\b/i;
+
+export function classifyBridgeExit(input: {
+  exitCode: number;
+  stderr?: string;
+  endErrorMessage?: string;
+}): TransportFailure {
+  const stderr = (input.stderr || "").trim();
+  const endError = (input.endErrorMessage || "").trim();
+  const combined = [endError, stderr].filter(Boolean).join(" | ");
+
+  if (input.exitCode === 2 || GOAWAY_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.Goaway,
+      retryable: true,
+      refreshAuth: false,
+      message: combined
+        ? `Cursor upstream closed the connection (GOAWAY): ${combined}`
+        : "Cursor upstream closed the connection (GOAWAY).",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (AUTH_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.Authentication,
+      retryable: true,
+      refreshAuth: true,
+      message: combined || "Cursor authentication failed.",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (RATE_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.RateLimit,
+      retryable: true,
+      refreshAuth: false,
+      message: combined || "Cursor rate limited the request.",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (TIMEOUT_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.SocketTimeout,
+      retryable: true,
+      refreshAuth: false,
+      message: combined || "Cursor transport timed out.",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (RESET_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.ConnectionReset,
+      retryable: true,
+      refreshAuth: false,
+      message: combined || "Cursor connection was reset.",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (PROTOCOL_RE.test(combined)) {
+    return {
+      kind: TransportFailureKind.ProtocolDrift,
+      retryable: false,
+      refreshAuth: false,
+      message: combined || "Cursor protocol mismatch.",
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  if (input.exitCode !== 0) {
+    return {
+      kind: TransportFailureKind.BridgeCrash,
+      retryable: true,
+      refreshAuth: false,
+      message: combined
+        ? `Cursor transport connection lost (code ${input.exitCode}): ${combined}`
+        : `Cursor transport connection lost (code ${input.exitCode}).`,
+      exitCode: input.exitCode,
+      stderr: stderr || undefined,
+    };
+  }
+
+  return {
+    kind: TransportFailureKind.Unknown,
+    retryable: false,
+    refreshAuth: false,
+    message: combined || "Cursor transport closed cleanly.",
+    exitCode: input.exitCode,
+    stderr: stderr || undefined,
+  };
+}
+
+export function formatTransportFailure(failure: TransportFailure): string {
+  const hints: string[] = [];
+  if (failure.retryable) {
+    hints.push("A checkpoint/history recovery may continue the turn.");
+  }
+  if (failure.refreshAuth) {
+    hints.push("Token may need refresh — run /login cursor or check /cursor.doctor tokenSource.");
+  }
+  if (failure.kind === TransportFailureKind.ProtocolDrift) {
+    hints.push("Pin PI_CURSOR_CLIENT_VERSION or regenerate proto if wire drift persists.");
+  }
+  return hints.length ? `${failure.message} ${hints.join(" ")}` : failure.message;
+}
+
+/** Synthetic user text used when resuming a run after transport loss with a checkpoint. */
+export const CHECKPOINT_CONTINUATION_PROMPT =
+  "[pi-cursor] The previous upstream stream was interrupted. Continue exactly where you left off. Do not repeat content already produced.";

package/src/stream/tuning.ts

@@ -0,0 +1,250 @@
+/**
+ * Tuning knobs for the stream runtime: timeouts, retry budgets, and the
+ * silence watchdog that backs them.
+ *
+ * Every `resolve*` function takes the raw env string so the parsing rules
+ * (blank = default, 0 = disabled, floors on the rest) are unit-testable without
+ * mutating `process.env`.
+ */
+
+export const CONVERSATION_TTL_MS = 30 * 60 * 1000;
+
+export const DEFAULT_ACTIVE_BRIDGE_TTL_MS = 60 * 60 * 1000;
+
+// Safety net against permanent hangs: if the upstream stream produces no progress
+// for this long, the watchdog recovers/retries or ends the turn with a clear error
+// instead of parking forever. Real work (textDelta, thinkingDelta, tokenDelta,
+// tool-call events, answered interaction/exec) always resets it, and it is paused
+// during tool execution — so long reasoning turns and slow tools are unaffected.
+// Set the env vars to 0 to disable. 3 minutes: long pure-thinking stretches without
+// tokenDelta still need headroom, while a true silent park should not hang forever.
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 180_000;
+
+// A stream parked on an exec we could not answer is not slow, it is finished: Cursor
+// waits for a reply that will never arrive while its heartbeats keep the connection
+// alive. Liveness stops counting as progress once that happens (see StreamProgress),
+// and this shorter deadline gives the generic ExecClientThrow answer time to unpark
+// the run before the turn is failed.
+export const DEFAULT_STREAM_PARK_TIMEOUT_MS = 45_000;
+
+export const DEFAULT_RESUME_IDLE_TIMEOUT_MS = 180_000;
+
+// More generations for multi-hour agent sessions; each attempt can force-refresh auth.
+export const DEFAULT_STREAM_IDLE_MAX_RETRIES = 5;
+
+export const DEFAULT_MIDPAUSE_REBUILD_MAX_AGE_MS = 15 * 60 * 1000;
+
+/** Soft cap on retained blob bytes per conversation (images + turn blobs). */
+export const MAX_CONVERSATION_BLOB_BYTES = 128 * 1024 * 1024;
+export const MAX_ACTIVE_BLOB_BYTES = MAX_CONVERSATION_BLOB_BYTES;
+// Entry bound, evicted oldest-first alongside the byte bound. Turn blobs run a
+// couple of KB, so this is reached long before the byte cap on any conversation
+// that lives for a few hundred tool calls; it bounds Map overhead, and matches
+// the number of blobs the run journal is willing to persist.
+export const MAX_ACTIVE_BLOB_ENTRIES = 512;
+export const MAX_INDIVIDUAL_BLOB_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Hard cap on a stored upstream checkpoint's byte size. Unlike blobs and tool
+ * results, the checkpoint Cursor hands back is opaque and unbounded — over a
+ * long-running conversation it can grow past the transport's 64 MiB Connect
+ * frame limit, at which point the checkpoint would fail every future turn
+ * (frameConnectMessage throws before anything is sent). Discarding it above
+ * this cap forces a rebuild from the (bounded) blob store instead, leaving
+ * plenty of headroom under the transport limit for mcpTools/model metadata.
+ */
+export const MAX_CHECKPOINT_BYTES = 48 * 1024 * 1024;
+
+export const DEFAULT_H2_CONNECT_TIMEOUT_MS = 30_000;
+
+/**
+ * Activity idle kill after first I/O. Default 0 (disabled): parent heartbeats
+ * already keep the bridge alive, and a hard idle kill during long tool pauses
+ * was a common source of "Bridge connection lost" mid-session. Set
+ * PI_CURSOR_H2_IDLE_TIMEOUT_MS to re-enable a safety net.
+ */
+export const DEFAULT_H2_IDLE_TIMEOUT_MS = 0;
+
+export function resolveActiveBridgeTtlMs(envValue?: string): number {
+  if (envValue === undefined || envValue === "") return DEFAULT_ACTIVE_BRIDGE_TTL_MS;
+  const parsed = Number(envValue);
+  if (!Number.isFinite(parsed)) return DEFAULT_ACTIVE_BRIDGE_TTL_MS;
+  return Math.max(1_000, parsed);
+}
+
+export function resolveStreamIdleTimeoutMs(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  if (parsed === 0) return 0;
+  return Math.max(1_000, Math.floor(parsed));
+}
+
+export function resolveStreamIdleMaxRetries(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_STREAM_IDLE_MAX_RETRIES;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_STREAM_IDLE_MAX_RETRIES;
+  if (parsed === 0) return 0;
+  return Math.min(10, Math.max(1, Math.floor(parsed)));
+}
+
+export function resolveResumeIdleTimeoutMs(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_RESUME_IDLE_TIMEOUT_MS;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RESUME_IDLE_TIMEOUT_MS;
+  if (parsed === 0) return 0;
+  return Math.max(1_000, Math.floor(parsed));
+}
+
+export function resolveH2ConnectTimeoutMs(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_H2_CONNECT_TIMEOUT_MS;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_H2_CONNECT_TIMEOUT_MS;
+  if (parsed === 0) return 0;
+  return Math.max(1_000, Math.floor(parsed));
+}
+
+export function resolveH2IdleTimeoutMs(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_H2_IDLE_TIMEOUT_MS;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_H2_IDLE_TIMEOUT_MS;
+  if (parsed === 0) return 0;
+  return Math.max(5_000, Math.floor(parsed));
+}
+
+/**
+ * What a server message says about the stream.
+ *
+ * `work` is the run moving: tokens, tool calls, answered execs, checkpoints.
+ * `liveness` is the connection breathing while the run itself may be stuck —
+ * a heartbeat proves the socket, not the turn. `none` is noise.
+ *
+ * The distinction exists because a park is not silent: Cursor keeps heartbeating
+ * a run that is waiting for an exec reply we never sent, which made a
+ * silence-only watchdog unable to ever fire (a Grok session sat parked for 90
+ * minutes on an unknown exec case in 2026-08).
+ */
+export type StreamProgress = "none" | "liveness" | "work";
+
+/**
+ * How an interaction-update case should be treated by the stream idle watchdog.
+ * tokenDelta is work: long reasoning turns emit it without text for minutes at a
+ * time, and it only flows while the model is actually generating.
+ */
+export function interactionUpdateProgress(
+  updateCase: string | undefined,
+  hasNonEmptyText = false,
+): StreamProgress {
+  if (updateCase === "textDelta" || updateCase === "thinkingDelta")
+    return hasNonEmptyText ? "work" : "none";
+  if (updateCase === "heartbeat") return "liveness";
+  if (updateCase === "tokenDelta") return "work";
+  if (updateCase === "toolCallCompleted") return "work";
+  if (updateCase === "toolCallStarted") return "work";
+  if (updateCase === "partialToolCall") return "work";
+  if (updateCase === "toolCallDelta") return "work";
+  if (updateCase === "thinkingCompleted") return "work";
+  if (
+    updateCase === "summary" ||
+    updateCase === "summaryStarted" ||
+    updateCase === "summaryCompleted"
+  )
+    return "work";
+  return "none";
+}
+
+/** Whether a blind full-request restart is safe given already-streamed content. */
+export function canBlindIdleRestart(emittedUserVisibleContent: boolean): boolean {
+  return !emittedUserVisibleContent;
+}
+
+/**
+ * Whether recovery is allowed after transport loss.
+ * Blind restart only when nothing was streamed; checkpoint continuation is safe
+ * even after partial text because Cursor resumes server-side state and emits
+ * only new tokens (Pi appends them to the existing writer).
+ */
+export function canRecoverAfterTransportLoss(input: {
+  emittedUserVisibleContent: boolean;
+  hasCheckpoint: boolean;
+}): boolean {
+  if (!input.emittedUserVisibleContent) return true;
+  return input.hasCheckpoint;
+}
+
+export function resolveMidPauseRebuildMaxAgeMs(envValue?: string): number {
+  const normalized = envValue?.trim();
+  if (normalized === undefined || normalized === "") return DEFAULT_MIDPAUSE_REBUILD_MAX_AGE_MS;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_MIDPAUSE_REBUILD_MAX_AGE_MS;
+  // Zero should keep the replay trust window bounded; negative values are treated as invalid.
+  return Math.max(1_000, Math.floor(parsed));
+}
+
+export function createStreamIdleWatchdog(options: { timeoutMs: number; onTimeout: () => void }): {
+  start(): void;
+  reset(): void;
+  pause(): void;
+  resume(): void;
+  clear(): void;
+  setTimeoutMs(timeoutMs: number): void;
+} {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let started = false;
+  let paused = false;
+  let fired = false;
+  let timeoutMs = options.timeoutMs;
+
+  const clear = () => {
+    if (timer) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const arm = () => {
+    clear();
+    if (timeoutMs <= 0 || paused || fired) return;
+    timer = setTimeout(() => {
+      timer = undefined;
+      fired = true;
+      options.onTimeout();
+    }, timeoutMs);
+    (timer as { unref?: () => void }).unref?.();
+  };
+
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      paused = false;
+      arm();
+    },
+    reset() {
+      if (paused || fired) return;
+      arm();
+    },
+    pause() {
+      paused = true;
+      clear();
+    },
+    resume() {
+      if (fired) return;
+      paused = false;
+      arm();
+    },
+    setTimeoutMs(next: number) {
+      if (next === timeoutMs) return;
+      timeoutMs = next;
+      if (started) arm();
+    },
+    clear,
+  };
+}
+
+export const ACTIVE_BRIDGE_TTL_MS = resolveActiveBridgeTtlMs(
+  process.env.PI_CURSOR_ACTIVE_BRIDGE_TTL_MS,
+);