import { CursorForegroundShellOwner } from "./native-foreground-shell";
import http2 from "node:http2";
import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
import { namespacedToolName, type OcxProviderConfig, type OcxUsage } from "../../types";
import { CONNECT_FLAG_END_STREAM, ConnectFrameError, consumeConnectFrames, encodeConnectFrame } from "./framing";
import {
  CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES,
  CURSOR_MAX_CONNECT_FRAME_BYTES,
  CURSOR_MAX_PENDING_FRAMES,
  CURSOR_PENDING_FRAMES_RESUME,
  CURSOR_TRANSPORT_MAX_BUFFERED_BYTES,
  CURSOR_TRANSPORT_RESUME_BYTES,
  TranslatorBudgetExceededError,
  type TranslatorBudget,
} from "../../lib/translator-budget";
import { activePromptText, prepareCursorRunRequest } from "./protobuf-request";
import { prepareCursorRawMessages, resolveActiveCursorImages } from "./images";
import { isCursorExternalWireModel } from "./discovery";
import { cursorUsesPlainToolWording } from "./tool-wording";
import { cursorRequestMessagesFromRaw } from "./request-builder";
import {
  createCursorContextUsageTracker,
  createCursorProtobufEventState,
  finalizeTurnEvents,
  hasBufferedTextToolCalls,
  mapCursorProtobufServerMessage,
  mapSyntheticMcpExecToToolEvents,
  reportableContextTokens,
  resolvedTurnUsage,
  usageFromContextTokens,
} from "./protobuf-events";
import {
  AgentClientMessageSchema,
  AgentServerMessageSchema,
  AskQuestionInteractionResponseSchema,
  AskQuestionRejectedSchema,
  AskQuestionResultSchema,
  ClientHeartbeatSchema,
  CreatePlanRequestResponseSchema,
  CreatePlanResultSchema,
  CreatePlanSuccessSchema,
  ConversationStateStructureSchema,
  ExaFetchRequestResponseSchema,
  ExaFetchRequestResponse_ApprovedSchema,
  ExaSearchRequestResponseSchema,
  ExaSearchRequestResponse_ApprovedSchema,
  InteractionResponseSchema,
  SwitchModeRequestResponseSchema,
  SwitchModeRequestResponse_RejectedSchema,
  WebSearchRequestResponseSchema,
  WebSearchRequestResponse_ApprovedSchema,
  type AgentServerMessage,
  type ExecServerMessage,
  type InteractionQuery,
  type InteractionResponse,
} from "./gen/agent_pb";
import { debugProviderDiagnostic } from "../../lib/debug";
import { classifyCursorError, CursorUnexpectedCancelError, isCursorAbortError, isCursorBenignCancelError, safeCursorErrorMessage } from "./cursor-errors";
import { cursorPolicyErrorExplanation } from "./policy-error";
import { mcpArgsFromToolCall } from "./protobuf-events";
import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
import {
  cursorNativeExecRedirectHint,
  handleCursorNativeExec,
  handleCursorNativeKv,
  releaseCursorBlobRequestScope,
  type CursorBlobRequestScopeToken,
  type CursorNativeExecContext,
} from "./native-exec";
import { effectiveCursorNativeExecAllow } from "./exec-policy";
import { resolveMcpServers } from "./mcp-config";
import { CursorMcpManager } from "./mcp-manager";
import { buildMcpToolDefinitions, mcpDepsFromManager } from "./native-exec-mcp";
import { desktopDepsFromConfig } from "./native-exec-desktop";
import {
  buildCursorToolDefinitions,
  cursorRequestAdvertisesApplyPatch,
  cursorRequestHasShellAlias,
  cursorToolArgNormalizeSchema,
  cursorToolWireName,
  cursorToolsForActivePrompt,
  isCursorSyntheticStructuredEditTool,
  isGenericToolUseCountDemoPrompt,
  requestedCursorToolUseCount,
} from "./tool-definitions";
import type { CursorNativeToolDeps } from "./native-exec-tools";
import {
  terminateBackgroundShellsForSession,
  type BackgroundShellTerminationReport,
} from "./native-exec-shell";
import type { CursorClientMessage, CursorRunRequest, CursorServerMessage } from "./types";
import type { CursorStreamHealthClock, CursorTransport, CursorTransportFactoryInput } from "./transport";
import { CursorHttp1BidiConnection } from "./http1-bidi";
import { isPinnedHttp1 } from "../../lib/upstream-http-version";

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;
/**
 * The production T04 clock. The watchdog reads time and schedules its one timer through this
 * object so a test can supply a clock it advances by hand; nothing else about the transport's
 * timers moves with it.
 */
const REAL_STREAM_HEALTH_CLOCK: CursorStreamHealthClock = {
  now: () => Date.now(),
  setTimeout: (callback, ms) => setTimeout(callback, ms),
  clearTimeout: timer => clearTimeout(timer),
};
/**
 * 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;
const GENERIC_TOOL_COUNT_MAX_FINALIZE_GRACE_MS = 1_800;
const GENERIC_TOOL_COUNT_PER_TOOL_GRACE_MS = 125;
/**
 * A client-tool turn suspends before `turnEnded`, and upstream sends that turn's conversation
 * checkpoint right after `toolCallStarted` — after the 50 ms drain grace, so it used to be
 * cancelled away and every such turn full-replayed with `cached_tokens: 0`. Measured on a live
 * account with the tool catalog held constant: 50 ms captures nothing, 1500 ms captures 3036
 * bytes (#4245, devlog 260911_cursor_checkpoint_capture). This window is paid only by a turn
 * that never sends one; `handleServerMessage` finalizes early as soon as the frame lands.
 */
const CHECKPOINT_CAPTURE_GRACE_MS = 1_500;
const cursorContextUsageTracker = createCursorContextUsageTracker();

/**
 * Single-shot terminal settlement for one Cursor turn: whichever of fail/finish wins first owns
 * the terminal; later calls are no-ops. Prevents double-terminal mutation when multiple sources
 * race (stream error + session error, end + late session error, timeout + destroy error).
 * Exported for direct unit testing — the callbacks are otherwise private to run()/open().
 */
export function createTerminalSettler(hooks: {
  fail: (error: Error) => void;
  finish: () => void;
  clearTimer: () => void;
}): { settleFail: (error: Error) => void; settleFinish: () => void; settled: () => boolean } {
  let settled = false;
  return {
    settleFail(error) {
      if (settled) return;
      settled = true;
      hooks.clearTimer();
      hooks.fail(error);
    },
    settleFinish() {
      if (settled) return;
      settled = true;
      hooks.clearTimer();
      hooks.finish();
    },
    settled: () => settled,
  };
}

/**
 * Arm the post-close destroy fallback for a timed-out turn: close() waits for in-flight frames,
 * but a dead socket can ignore it, leaving a stalled TLS session past the timeout. Exported for
 * unit testing with fakes. The timer is unref'd so it never holds the process open.
 */
export function armTimeoutDestroyFallback(
  stream: { destroyed: boolean; destroy: () => void },
  session: { destroyed: boolean; destroy: () => void },
  graceMs: number,
): ReturnType<typeof setTimeout> {
  const timer = setTimeout(() => {
    try { if (!stream.destroyed) stream.destroy(); } catch { /* gone */ }
    try { if (!session.destroyed) session.destroy(); } catch { /* gone */ }
  }, graceMs);
  timer.unref?.();
  return timer;
}

/** Carry context-usage totals across conversation-id rotation for external-model replay. */
export function rekeyCursorContextUsage(fromConversationId: string, toConversationId: string): void {
  cursorContextUsageTracker.rekey(fromConversationId, toConversationId);
}

export class CursorMissingCredentialError extends Error {
  readonly code = "cursor_missing_credential";

  constructor() {
    super("Cursor live transport requires a Cursor access token in provider.apiKey, Authorization, or OPENCODEX_CURSOR_TEST_TOKEN.");
    this.name = "CursorMissingCredentialError";
  }
}

export function resolveCursorToken(provider: OcxProviderConfig, headers?: Headers): string {
  const providerKey = provider.apiKey?.trim();
  if (providerKey) return providerKey;

  const forwarded = headers?.get("authorization") ?? headers?.get("Authorization");
  if (forwarded?.toLowerCase().startsWith("bearer ")) return forwarded.slice("bearer ".length).trim();

  const envToken = process.env.OPENCODEX_CURSOR_TEST_TOKEN?.trim();
  if (envToken) return envToken;
  throw new CursorMissingCredentialError();
}

/**
 * Classify a Connect end-stream (trailer) frame. Cursor terminates EVERY stream with this
 * frame; success is signalled by the ABSENCE of an `error` field (typically `{}`), not by the
 * absence of the frame. Returns null on success, an Error only on a real Connect error.
 * Mirrors jawcode `parseConnectEndStream` (see devlog 350.98). Exported for unit testing.
 */
export function parseConnectEndStreamError(payload: Uint8Array): Error | null {
  try {
    const parsed = JSON.parse(new TextDecoder().decode(payload)) as { error?: { code?: string; message?: string } };
    if (parsed?.error) {
      const explanation = cursorPolicyErrorExplanation(parsed.error);
      return new Error(`Cursor Connect error ${parsed.error.code ?? "unknown"}: ${explanation ?? parsed.error.message ?? "Unknown error"}`);
    }
    return null;
  } catch {
    return new Error("Cursor Connect end-stream error");
  }
}

function encodeClientMessage(message: Parameters<typeof create<typeof AgentClientMessageSchema>>[1]): Uint8Array {
  return encodeConnectFrame(toBinary(AgentClientMessageSchema, create(AgentClientMessageSchema, message)));
}

/**
 * Decide how to handle an `execServerMessage.mcpArgs` frame for a client (Responses-provider) tool.
 *
 * A stateless Responses proxy cannot send Cursor a real `mcpResult` later (Cursor's MCP exec is
 * synchronous on the live h2 stream; there is no deferred-result signal). So when Cursor asks us to
 * run a client Responses tool we must:
 *   1. surface the tool call to Codex (tool_call_start/delta/end),
 *   2. deliberately END turn 1 as `done`/completed — Cursor will never send `turnEnded` because it
 *      is waiting for an `mcpResult` that never comes, so relying on the stall watchdog would make
 *      turn 1 `response.incomplete` and drop the conversation id (continuation dies at step 1), and
 *   3. cancel the Cursor run WITHOUT writing any fake `mcpResult`.
 * The real tool result arrives on the NEXT /v1/responses request as structured history.
 *
 * Pure (no I/O) so the decision is unit-testable. `handleServerMessage` performs the side effects.
 */
export interface McpArgsPlan {
  handledByResponsesBridge: boolean;
  events: CursorServerMessage[];
  cancelCursorRun: boolean;
  /**
   * The Responses bridge owns this exec and every known client tool call is committed, but turn 1 is
   * NOT ended synchronously: a sibling call may still be announced in a later receive chunk. The
   * transport arms a revocable grace timer and only ends the turn (see finalizeAfterDrain) if the set
   * is still drained when it fires.
   */
  finalizeWhenDrained: boolean;
  writeMcpResult?: never;
}

export function planMcpArgsHandling(
  execMsg: ExecServerMessage,
  state: ReturnType<typeof createCursorProtobufEventState>,
): McpArgsPlan {
  if (execMsg.message.case !== "mcpArgs") {
    return { handledByResponsesBridge: false, events: [], cancelCursorRun: false, finalizeWhenDrained: false };
  }
  const args = execMsg.message.value;
  if (args.providerIdentifier !== OCX_RESPONSES_TOOL_PROVIDER) {
    // A real MCP server tool: native exec handles it (executed locally, real mcpResult written).
    return { handledByResponsesBridge: false, events: [], cancelCursorRun: false, finalizeWhenDrained: false };
  }

  // From here on the Responses bridge owns the exec: never fall through to native exec, which would
  // send Cursor a bogus "bridge suspension not implemented" mcpResult error.
  const toolEvents = mapSyntheticMcpExecToToolEvents(args, `exec_${execMsg.id}`, {
    allowEmptyArgs: true,
    state,
  });

  if (toolEvents.some(event => event.type === "error")) {
    // The error is itself the terminal signal; do not also emit `done`.
    return { handledByResponsesBridge: true, events: toolEvents, cancelCursorRun: true, finalizeWhenDrained: false };
  }

  // Parallel safety ("tool use N"): Cursor sends one exec mcpArgs per client tool call. An empty
  // openToolCalls set proves only that every KNOWN call is committed, not that Cursor has finished
  // announcing siblings — a sibling's toolCallStarted can still arrive in a later receive chunk. So
  // never end turn 1 synchronously here: surface this call's events, and when the set is drained flag
  // finalizeWhenDrained so the transport arms a revocable grace timer (finalizeAfterDrain re-checks
  // the guard when it fires). While siblings are still open, just keep the stream open.
  return {
    handledByResponsesBridge: true,
    events: toolEvents,
    cancelCursorRun: false,
    finalizeWhenDrained: state.openToolCalls.size === 0,
  };
}

/**
 * Build the `interactionResponse` reply for a server `interactionQuery`. Cursor's server-side agent
 * BLOCKS on these queries until the client answers (matching `id`); an unanswered query is the
 * proven cause of the heartbeat-only stall → watchdog `upstream_stall_timeout` → upstream 502 loop
 * (devlog 260702_cursor-live-stability-rca). ocx is a headless non-interactive client, so:
 *   - createPlan: acknowledge success (the agent proceeds to execute); the plan text is surfaced to
 *     Codex as visible output so the user still sees it.
 *   - askQuestion: reject with a reason — the agent must proceed autonomously; there is no human to
 *     answer mid-turn. (Future: bridge to a Codex user-input request.)
 *   - webSearch / exaSearch / exaFetch: APPROVE (empty approval). These are approve/reject
 *     permission gates, not client-run requests — the response schema has no result field, so
 *     approval delegates the search to Cursor's SERVER, which runs it and injects results into the
 *     model server-side (the answer then streams back as textDelta; the display-plane
 *     web_search_tool_call/exa_*_tool_call result frames are native, non-mcp, and safely dropped by
 *     the event mapper). Rejecting them (the old default) killed the model's web capability on the
 *     Cursor path. Tradeoff: approval consumes the user's Cursor web-search/Exa quota. The synthetic
 *     web_search sidecar (src/web-search) is an orthogonal proxy-side path used only when the client
 *     sends a hosted web_search tool; it does not cover Cursor-native web search.
 *   - switchMode: reject (deterministic default; no non-interactive mode switch).
 *   - setupVmEnvironment: the result schema has no error case — reply success so the agent is not
 *     left waiting; the command itself was never run locally.
 * Pure (no I/O) for unit testing; `handleServerMessage` writes the frame and emits liveness.
 */
export function planInteractionQueryReply(query: InteractionQuery): { response: InteractionResponse; replyCase: string; planText?: string } {
  const NON_INTERACTIVE_REASON = "opencodex bridge is non-interactive; proceed without this interaction.";
  const q = query.query;
  const respond = (result: InteractionResponse["result"]): InteractionResponse =>
    create(InteractionResponseSchema, { id: query.id, result });

  if (q.case === "createPlanRequestQuery") {
    const args = q.value.args;
    const parts = [
      args?.name ? `Plan: ${args.name}` : undefined,
      args?.overview?.trim() ? args.overview.trim() : undefined,
      args?.plan?.trim() ? args.plan.trim() : undefined,
    ].filter((part): part is string => typeof part === "string" && part.length > 0);
    return {
      response: respond({
        case: "createPlanRequestResponse",
        value: create(CreatePlanRequestResponseSchema, {
          result: create(CreatePlanResultSchema, { result: { case: "success", value: create(CreatePlanSuccessSchema, {}) } }),
        }),
      }),
      replyCase: "createPlanRequestResponse:success",
      planText: parts.length > 0 ? `${parts.join("\n\n")}\n` : undefined,
    };
  }
  if (q.case === "askQuestionInteractionQuery") {
    return {
      response: respond({
        case: "askQuestionInteractionResponse",
        value: create(AskQuestionInteractionResponseSchema, {
          result: create(AskQuestionResultSchema, {
            result: { case: "rejected", value: create(AskQuestionRejectedSchema, { reason: NON_INTERACTIVE_REASON }) },
          }),
        }),
      }),
      replyCase: "askQuestionInteractionResponse:rejected",
    };
  }
  if (q.case === "switchModeRequestQuery") {
    return {
      response: respond({
        case: "switchModeRequestResponse",
        value: create(SwitchModeRequestResponseSchema, {
          result: { case: "rejected", value: create(SwitchModeRequestResponse_RejectedSchema, { reason: NON_INTERACTIVE_REASON }) },
        }),
      }),
      replyCase: "switchModeRequestResponse:rejected",
    };
  }
  if (q.case === "webSearchRequestQuery") {
    return {
      response: respond({
        case: "webSearchRequestResponse",
        value: create(WebSearchRequestResponseSchema, {
          result: { case: "approved", value: create(WebSearchRequestResponse_ApprovedSchema, {}) },
        }),
      }),
      replyCase: "webSearchRequestResponse:approved",
    };
  }
  if (q.case === "exaSearchRequestQuery") {
    return {
      response: respond({
        case: "exaSearchRequestResponse",
        value: create(ExaSearchRequestResponseSchema, {
          result: { case: "approved", value: create(ExaSearchRequestResponse_ApprovedSchema, {}) },
        }),
      }),
      replyCase: "exaSearchRequestResponse:approved",
    };
  }
  if (q.case === "exaFetchRequestQuery") {
    return {
      response: respond({
        case: "exaFetchRequestResponse",
        value: create(ExaFetchRequestResponseSchema, {
          result: { case: "approved", value: create(ExaFetchRequestResponse_ApprovedSchema, {}) },
        }),
      }),
      replyCase: "exaFetchRequestResponse:approved",
    };
  }
  if (q.case === "setupVmEnvironmentArgs") {
    // setupVmEnvironment is not supported — reply with an empty InteractionResponse so the stream
    // stays alive instead of throwing (which kills the entire gRPC connection via failAndClear).
    return {
      response: respond({ case: undefined, value: undefined }),
      replyCase: "unsupported:setupVmEnvironment",
    };
  }
  // Unknown interaction query case — Cursor added a new query type that our protobuf definition
  // does not include yet. Gracefully reply with an empty InteractionResponse (matching id, no
  // result) so the server unblocks and the stream stays alive. Previously this threw, which
  // propagated through .catch → failAndClear and killed the entire connection (#116).
  return {
    response: respond({ case: undefined, value: undefined }),
    replyCase: `unsupported:${q.case ?? "unknown"}`,
  };
}

/**
 * Re-check the drain guard at grace-timer fire time and finalize turn 1 only if still drained. A
 * sibling client tool call announced after the timer was armed reopens `openToolCalls`, so this
 * returns `[]` (the pending finalize is revoked); a later drain re-arms it. Pure for unit testing.
 */
export function finalizeAfterDrain(state: ReturnType<typeof createCursorProtobufEventState>): CursorServerMessage[] {
  if (state.terminated) return [];
  if (state.openToolCalls.size > 0) return [];
  return finalizeTurnEvents(state);
}

/**
 * Whether a drained client-tool turn should wait one more bounded window for the conversation
 * checkpoint instead of cancelling now.
 *
 * This mirrors `finalizeAfterDrain`'s two guards rather than calling it, and that is load-bearing:
 * `finalizeAfterDrain` reaches `finalizeTurnEvents`, which sets `state.terminated`, and then returns
 * `[]` for a terminated state. Draining first and re-arming would make the retry return early at the
 * length check and leave the stream uncancelled. Pure for unit testing.
 */
export function shouldExtendForCheckpointCapture(input: {
  /** Optional on the event state, so accept its real shape rather than forcing a cast at the call site. */
  terminated: boolean | undefined;
  openToolCallCount: number;
  wantsCheckpointCapture: boolean;
  hasCapturedCheckpoint: boolean;
  alreadyExtended: boolean;
}): boolean {
  if (input.terminated || input.openToolCallCount > 0) return false;
  if (!input.wantsCheckpointCapture || input.hasCapturedCheckpoint) return false;
  return !input.alreadyExtended;
}

export function clientToolFinalizeGraceMsForRequest(request: CursorRunRequest, baseGraceMs = CLIENT_TOOL_FINALIZE_GRACE_MS): number {
  if (request.rawMessages?.at(-1)?.role === "toolResult") return baseGraceMs;
  const text = activePromptText(request);
  // Parallel-tool requests with several advertised tools get the expanded window regardless of
  // prompt shape: external models (grok) assemble sibling calls serially over multiple frames,
  // and the 50ms drain grace ended the turn after 1-2 of them (devlog 260826_cursor_responses_gap,
  // live 10-parallel probe: calls=2 then calls=1).
  if (request.parallelToolCalls === true && (request.tools?.length ?? 0) > 1) {
    const advertised = request.tools?.length ?? 0;
    return Math.max(
      baseGraceMs,
      Math.min(
        GENERIC_TOOL_COUNT_MAX_FINALIZE_GRACE_MS,
        Math.max(GENERIC_TOOL_COUNT_MIN_FINALIZE_GRACE_MS, advertised * GENERIC_TOOL_COUNT_PER_TOOL_GRACE_MS),
      ),
    );
  }
  if (!cursorRequestHasShellAlias(request.tools) || !isGenericToolUseCountDemoPrompt(text)) return baseGraceMs;
  const requestedCount = requestedCursorToolUseCount(text);
  const expandedGraceMs = requestedCount
    ? Math.min(
        GENERIC_TOOL_COUNT_MAX_FINALIZE_GRACE_MS,
        Math.max(GENERIC_TOOL_COUNT_MIN_FINALIZE_GRACE_MS, requestedCount * GENERIC_TOOL_COUNT_PER_TOOL_GRACE_MS),
      )
    : GENERIC_TOOL_COUNT_MIN_FINALIZE_GRACE_MS;
  return Math.max(baseGraceMs, expandedGraceMs);
}

class LiveCursorTransport implements CursorTransport {
  private session?: http2.ClientHttp2Session;
  private stream?: http2.ClientHttp2Stream;
  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;
  /** Time source for the T04 watchdog only; the globals unless a test injects one. */
  private readonly streamHealthClock: CursorStreamHealthClock;
  private committed = false;
  private expectedClose = false;
  /**
   * True once a terminal (`done` or `error`) has been admitted to the outbound queue. Read only
   * by the EOF branch below: after a mapper error the bridge has already failed the turn, so
   * failing again on EOF would add a duplicate adapter error for no benefit.
   */
  private emittedTerminal = false;
  private pendingFinalize?: ReturnType<typeof setTimeout>;
  /** The armed finalize body, so the checkpoint frame can run it early instead of waiting out the window. */
  private pendingFinalizeRun?: () => void;
  private checkpointGraceExtended = false;
  private wantsCheckpointCapture = false;
  private readonly clientToolFinalizeGraceMs: number;
  private activeClientToolFinalizeGraceMs: number;
  private readonly token: string;
  private readonly mcpManager?: CursorMcpManager;
  private readonly translatorBudget: TranslatorBudget;
  private pendingTransportFrames = 0;
  private transportBufferedBytes = 0;
  private readonly desktopDeps: CursorNativeToolDeps;
  private execContext: CursorNativeExecContext = {};
  private mcpPrepared?: Promise<void>;
  private releaseMcpObservation?: () => void;
  private blobRequestScope?: CursorBlobRequestScopeToken;
  private readonly foregroundShellOwner = new CursorForegroundShellOwner();
  private requestSignal?: AbortSignal;
  private shellCleanup?: Promise<BackgroundShellTerminationReport>;
  // Per-turn diagnostic counters/timestamps when provider debug is on (`ocx debug provider on`). Stamped in open(), cleared on
  // close; safe to read after a stream failure because open() owns the only writer before run().
  private turnStartedAt = 0;
  private framesReceived = 0;
  private sawAssistantText = false;
 private firstFrameAt?: number;
  private firstFrameLogged = false;
  /** Stable session identifier sent as x-session-id; mirrors IDE session semantics. */
  private readonly sessionId: string;
  /** Per-transport owner for native-exec / background shells. Must not share conversationId. */
  private readonly shellOwnerId = crypto.randomUUID();
  private capturedCheckpointBytes?: Uint8Array;

  constructor(private readonly input: CursorTransportFactoryInput) {
    this.sessionId = input.sessionId?.trim() || crypto.randomUUID();
    this.translatorBudget = input.translatorBudget;
    this.token = resolveCursorToken(input.provider, input.headers);
    // Grace window before a drained client-tool turn is finalized. Small enough not to look like a
    // stall, large enough to catch a sibling tool call announced in the next receive chunk. Injectable
    // so the transport-level race test can drive it deterministically.
    this.clientToolFinalizeGraceMs = input.clientToolFinalizeGraceMs ?? CLIENT_TOOL_FINALIZE_GRACE_MS;
    this.activeClientToolFinalizeGraceMs = this.clientToolFinalizeGraceMs;
    this.streamHealthClock = input.streamHealthClock ?? REAL_STREAM_HEALTH_CLOCK;
    // Desktop (computer-use / record-screen) executors are available even with no MCP servers.
    this.desktopDeps = desktopDepsFromConfig(input.provider.desktopExecutor);
    this.execContext = {
      ...this.desktopDeps,
      sessionId: this.shellOwnerId,
      unsafeAllowNativeLocalExec: effectiveCursorNativeExecAllow(input.provider, input.requestDeclaresFullAccess === true),
    };
    const servers = resolveMcpServers(input.provider);
    if (servers.length > 0) {
      this.mcpManager = new CursorMcpManager(servers, {
        log: message => console.warn(message),
        maxTools: input.provider.mcpMaxTools,
        maxSchemaBytes: input.provider.mcpMaxSchemaBytes,
        maxResultBytes: input.provider.mcpMaxResultBytes,
      });
    }
  }

  /**
   * Connect MCP servers and compute the tool definitions advertised to the Cursor server.
   * MUST complete before the first `requestContextArgs` (the server only calls MCP tools it was
   * told about), so `run()` awaits this before opening the stream. Preparation failures reject the
   * turn instead of silently running with MCP disabled.
   */
  private prepareMcp(): Promise<void> {
    if (!this.mcpManager) return Promise.resolve();
    if (!this.mcpPrepared) {
      this.mcpPrepared = (async () => {
        try {
          const mcpToolDefs = await buildMcpToolDefinitions(this.mcpManager!);
          this.releaseMcpObservation?.();
          this.releaseMcpObservation = this.translatorBudget.observeExternallyCapped(
            "mcp_payload",
            new TextEncoder().encode(JSON.stringify(mcpToolDefs)).byteLength,
          );
          this.execContext = {
            ...this.desktopDeps,
            ...mcpDepsFromManager(this.mcpManager!),
            mcpToolDefs,
            sessionId: this.shellOwnerId,
            unsafeAllowNativeLocalExec: effectiveCursorNativeExecAllow(this.input.provider, this.input.requestDeclaresFullAccess === true),
          };
        } catch (err) {
          throw new Error(`Cursor MCP preparation failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
        }
      })();
    }
    return this.mcpPrepared;
  }

  toJSON(): Record<string, string> {
    return { type: "LiveCursorTransport", credential: "redacted" };
  }

  async *run(request: CursorRunRequest, signal?: AbortSignal): AsyncIterable<CursorServerMessage> {
    this.requestSignal = signal;
    const queue: Array<{ message: CursorServerMessage; bytes: number }> = [];
    let notify: (() => void) | undefined;
    let done = false;
    let failure: Error | undefined;
    let state = createCursorProtobufEventState({ translatorBudget: this.translatorBudget });
    let failureLogged = false;
    // One per-turn summary of the failure path (end-stream error, socket reset, abort) so the
    // operator can see how far the turn got and how it was classified without re-scanning every
    // frame. Gated behind provider debug (`ocx debug provider on`).
    const summarizeFailure = (err: Error): Error => {
      if (!failureLogged && !(this.expectedClose && isCursorBenignCancelError(err))) {
        failureLogged = true;
        debugProviderDiagnostic("cursor", "turn-failed", {
          committed: this.committed,
          framesReceived: this.framesReceived,
          outputTokens: state.usage.outputTokens,
          contextTokens: state.contextTokens,
          firstFrameMs: this.firstFrameAt ? this.firstFrameAt - this.turnStartedAt : undefined,
          elapsedMs: this.turnStartedAt ? Date.now() - this.turnStartedAt : undefined,
          classified: classifyCursorError(err.message),
          errorCode: (err as { code?: unknown }).code ?? undefined,
          message: redactCursorForLog(err.message),
        });
      }
      return err;
    };
    /**
     * A cancel we did not request is a real transport failure, but as a raw `NGHTTP2_CANCEL` it
     * gets swallowed twice over: the adapter re-decides "benign" from the error code alone
     * (`cursor.ts:181`) and drops the turn, and any message that survives is re-matched
     * downstream and labelled an intentional "Cursor stream suspended". Raising a typed error
     * carries the provenance this class already holds.
     *
     * Suppressed once a terminal was emitted: the turn already ended, and a second terminal flips
     * a completed buffered response to failed.
     */
    const classifyTurnFailure = (err: Error): Error => {
      if (!this.expectedClose && !this.emittedTerminal && isCursorBenignCancelError(err)) {
        return summarizeFailure(new CursorUnexpectedCancelError(err));
      }
      return summarizeFailure(err);
    };
    const wake = () => {
      const fn = notify;
      notify = undefined;
      fn?.();
    };

    const push = (message: CursorServerMessage) => {
      const bytes = new TextEncoder().encode(JSON.stringify(message)).byteLength;
      this.reserveTransportBytes(bytes);
      if (message.type === "done" || message.type === "error") this.emittedTerminal = true;
      queue.push({ message, bytes });
      wake();
    };

    // Advertise MCP tools before the stream opens — the server only calls tools it was told about.
    await this.prepareMcp();
    // JPEG soft-cap rewrite for active-turn data: images before encode. Rebuild text
    // messages from the prepared raw channel so omission markers replace stale
    // pre-rewrite content that activePromptText and the tool filter would otherwise see.
    const externalToolImages = isCursorExternalWireModel(request.modelId)
      && request.rawMessages?.at(-1)?.role === "toolResult";
    const preparedRaw = await prepareCursorRawMessages(request.rawMessages, signal, {
      trailingToolImages: externalToolImages,
    });
    const preparedRawMessages = preparedRaw.messages;
    const selectedImages = externalToolImages ? preparedRaw.images : await resolveActiveCursorImages(
      preparedRawMessages,
      signal,
      preparedRaw.images,
    );
    const preparedMessages = preparedRawMessages === request.rawMessages
      ? request.messages
      : cursorRequestMessagesFromRaw(preparedRawMessages);
    const activeRequest: CursorRunRequest = {
      ...request,
      messages: preparedMessages,
      rawMessages: preparedRawMessages,
      selectedImages,
    };
    const activeText = activePromptText(activeRequest);
    this.activeClientToolFinalizeGraceMs = clientToolFinalizeGraceMsForRequest(activeRequest, this.clientToolFinalizeGraceMs);
    this.wantsCheckpointCapture = activeRequest.contextUsageStoreCheckpoints !== false;
    const cursorVisibleTools = cursorToolsForActivePrompt(activeRequest.tools, activeText, activeRequest.toolChoice);
    const clientToolDefs = buildCursorToolDefinitions(cursorVisibleTools, activeRequest.toolChoice);
    // `request.tools` is the catalog already filtered and budgeted by request-builder. Derive
    // conversion provenance only from tagged synthetic tools that also survive this final prompt
    // filter; a client tool with the same wire name can never opt into conversion by collision.
    const syntheticStructuredEditToolNames = new Set(
      (cursorVisibleTools ?? [])
        .filter(isCursorSyntheticStructuredEditTool)
        .map(tool => cursorToolWireName(tool, cursorVisibleTools)),
    );
    const freeformToolNames = new Set(
      (cursorVisibleTools ?? [])
        .filter(tool => tool.freeform)
        .map(tool => namespacedToolName(tool.namespace, tool.name)),
    );
    this.execContext = {
      ...this.execContext,
      clientToolDefs,
      rejectNativeFileMutations: cursorRequestAdvertisesApplyPatch(request.tools, request.toolChoice),
      structuredEditAvailable: syntheticStructuredEditToolNames.size > 0,
      nativeExecRedirectHint: cursorNativeExecRedirectHint(cursorVisibleTools, this.execContext.mcpToolDefs ?? [], activeRequest.modelId),
      plainToolWording: cursorUsesPlainToolWording(activeRequest.modelId),
    };
    const toolSchemas = new Map<string, unknown>();
    const cursorToolNameMap = new Map<string, string>();
    for (const tool of cursorVisibleTools ?? []) {
      const cursorWireName = cursorToolWireName(tool, cursorVisibleTools);
      // Normalize against Responses/Codex field names, not the Cursor advertisement schema.
      // Advertising `cmd` while also storing that schema here left `cmd` unmapped and Codex
      // rejected shell_command with "missing field `command`" (#399).
      toolSchemas.set(cursorWireName, cursorToolArgNormalizeSchema(tool));
      cursorToolNameMap.set(cursorWireName, namespacedToolName(tool.namespace, tool.name));
    }
    const contextUsage = cursorContextUsageTracker.controlsForConversation(request.conversationId, {
      clearPrior: request.contextUsageReset === true,
      storeCheckpoints: request.contextUsageStoreCheckpoints !== false,
    });
    // Build the payload once. The estimate is only worth deriving when there is no
    // carry-forward to fall back on — with a carry present it would never be used (#373).
    const prepared = prepareCursorRunRequest(activeRequest, {
      estimateInputTokens: contextUsage.carryForwardTokens === undefined,
    });
    this.blobRequestScope = prepared.blobRequestScope;
    try {
      state = createCursorProtobufEventState({
        clientToolNames: clientToolDefs.map(tool => tool.toolName || tool.name),
        freeformToolNames,
        parallelToolCalls: request.parallelToolCalls,
        toolSchemas,
        cursorToolNameMap,
        syntheticStructuredEditToolNames,
        translatorBudget: this.translatorBudget,
        contextUsage,
        wireModelId: request.modelId,
        identityScope: request._cursorIdentityScope,
        ...(prepared.estimatedInputTokens !== undefined
          ? { estimatedInputTokens: prepared.estimatedInputTokens }
          : {}),
      });
      this.open(prepared.bytes, signal, state, push, err => {
        this.releaseBlobRequestScope();
        failure = err;
        wake();
      }, () => {
        this.releaseBlobRequestScope();
        done = true;
        wake();
      });
    } catch (error) {
      this.releaseBlobRequestScope();
      throw error;
    }

    while (!done || queue.length > 0) {
      while (queue.length > 0) {
        const queued = queue.shift();
        if (queued) {
          this.releaseTransportBytes(queued.bytes);
          yield queued.message;
        }
      }
      if (failure) {
        // A CANCEL is benign only on the client-tool suspend path (expectedClose); an
        // unexpected server-side NGHTTP2_CANCEL must surface as a real transport error.
        if (this.expectedClose && isCursorBenignCancelError(failure)) return;
        // A teardown error arriving AFTER the turn's terminal frame describes the connection,
        // not the turn: the answer is committed and every queued message has been yielded.
        //
        // Narrow on purpose. A benign cancel after a terminal is already swallowed one layer
        // up (`cursor.ts:183`), so widening this to every post-terminal error would change
        // what the adapter sees for genuine faults. What it does cover is the abort case
        // from #1527: `signal.abort` fires `failAndClear(new Error("Cursor request was
        // aborted"))`, which is NOT benign (`cursor-errors.ts:74`), so an ordinary completed
        // turn that is then torn down still surfaced as `turn-failed` with
        // `expectedClose:false`. Only `cancelCursorRun()` sets `expectedClose`, so a normal
        // completion never qualified for the branch above.
        if (this.emittedTerminal && isCursorAbortError(failure)) return;
        throw attachPartialUsage(classifyTurnFailure(failure), state);
      }
      if (done) break;
      await new Promise<void>(resolve => {
        notify = resolve;
      });
    }
    if (failure) {
      if (this.expectedClose && isCursorBenignCancelError(failure)) return;
      if (this.emittedTerminal && isCursorAbortError(failure)) return;
      throw attachPartialUsage(classifyTurnFailure(failure), state);
    }
  }

  writeClient(_message: CursorClientMessage): void {}

  private reserveTransportBytes(bytes: number): void {
    if (this.transportBufferedBytes + bytes > CURSOR_TRANSPORT_MAX_BUFFERED_BYTES) {
      throw new TranslatorBudgetExceededError("cursor_transport", CURSOR_TRANSPORT_MAX_BUFFERED_BYTES);
    }
    this.translatorBudget.chargeRetained(bytes, { kind: "cursor_transport" });
    this.transportBufferedBytes += bytes;
    this.updateTransportFlowControl();
  }

  private releaseTransportBytes(bytes: number): void {
    this.transportBufferedBytes = Math.max(0, this.transportBufferedBytes - bytes);
    this.translatorBudget.releaseRetained(bytes, { kind: "cursor_transport" });
    this.updateTransportFlowControl();
  }

  private updateTransportFlowControl(): void {
    if (
      this.transportBufferedBytes >= CURSOR_TRANSPORT_MAX_BUFFERED_BYTES
      || this.pendingTransportFrames >= CURSOR_MAX_PENDING_FRAMES
    ) {
      this.stream?.pause();
      this.http1Connection?.pause();
      return;
    }
    if (
      this.transportBufferedBytes <= CURSOR_TRANSPORT_RESUME_BYTES
      && this.pendingTransportFrames <= CURSOR_PENDING_FRAMES_RESUME
    ) {
      this.stream?.resume();
      this.http1Connection?.resume();
    }
  }

  private writeConnectFrame(frame: Uint8Array): void {
    if (this.http1Connection) {
      this.http1Connection.write(frame);
      return;
    }
    this.stream?.write(frame);
  }

  requestCommitted(): boolean {
    return this.committed;
  }

  private clearFirstFrameTimer(): void {
    if (this.firstFrameTimer) {
      clearTimeout(this.firstFrameTimer);
      this.firstFrameTimer = undefined;
    }
  }

  private clearStreamHealthTimer(): void {
    if (this.streamHealthTimer) {
      this.streamHealthClock.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.
   *
   * Both clocks and the timer go through `streamHealthClock`, which is the globals in
   * production. The `elapsedMs` diagnostic below deliberately stays on the wall clock,
   * because `turnStartedAt` is stamped there and the pair has to subtract coherently.
   */
  private armStreamHealthTimer(fail: (error: Error) => void): void {
    if (this.streamHealthTimer) this.streamHealthClock.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 = this.streamHealthClock.now();
    const deadline = Math.min(
      this.lastInboundFrameAt + silenceMs,
      this.lastMeaningfulFrameAt + heartbeatOnlyMs,
    );
    this.streamHealthTimer = this.streamHealthClock.setTimeout(() => {
      this.streamHealthTimer = undefined;
      const failFn = this.streamHealthFail;
      if (!failFn || this.expectedClose) return;
      const stalledFor = this.streamHealthClock.now() - this.lastInboundFrameAt;
      const meaningfulStalledFor = this.streamHealthClock.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 = this.streamHealthClock.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 ??= Promise.all([
      terminateBackgroundShellsForSession(this.shellOwnerId),
      this.foregroundShellOwner.close(),
    ]).then(([backgroundReport]) => backgroundReport);
  }

  async close(): Promise<void> {
    const shellCleanup = this.startShellCleanup();
    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();
    this.releaseBlobRequestScope();
    this.releaseMcpObservation?.();
    this.releaseMcpObservation = undefined;
    void this.mcpManager?.dispose();
    await shellCleanup;
  }

  private cancelCursorRun(): void {
    void this.startShellCleanup();
    this.expectedClose = true;
    this.clearPendingFinalize();
    if (this.heartbeat) clearInterval(this.heartbeat);
    this.clearFirstFrameTimer();
    this.clearStreamHealthTimer();
    if (this.http1Connection) {
      this.http1Connection.close();
    } else {
      try {
        this.stream?.close(http2.constants.NGHTTP2_CANCEL);
      } catch {
        this.stream?.destroy();
      }
      this.session?.close();
    }
    this.releaseBlobRequestScope();
    this.releaseMcpObservation?.();
    this.releaseMcpObservation = undefined;
    void this.mcpManager?.dispose();
    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;
    this.blobRequestScope = undefined;
    releaseCursorBlobRequestScope(scope);
  }

  private clearPendingFinalize(): void {
    if (this.pendingFinalize) {
      clearTimeout(this.pendingFinalize);
      this.pendingFinalize = undefined;
    }
    this.pendingFinalizeRun = undefined;
  }

  /**
   * Any frame that records or commits a client tool call revokes a pending finalize: the call set is
   * about to change, so the drain that armed the timer is no longer authoritative. The timer re-arms
   * when the set drains again (see scheduleClientToolFinalize).
   */
  private noteClientToolActivity(): void {
    this.clearPendingFinalize();
  }

  /**
   * Arm the revocable grace timer that ends a drained client-tool turn. On fire it re-checks the
   * drain guard (finalizeAfterDrain): a sibling announced during the window reopened the set, so it
   * emits nothing and waits for the next drain; otherwise it pushes the terminal `done` and cancels
   * the Cursor run with RST_STREAM. No fake mcpResult is ever written.
   */
  private scheduleClientToolFinalize(
    state: ReturnType<typeof createCursorProtobufEventState>,
    push: (message: CursorServerMessage) => void,
    graceMsOverride?: number,
  ): void {
    this.clearPendingFinalize();
    const run = (): void => {
      this.pendingFinalize = undefined;
      this.pendingFinalizeRun = undefined;
      if (this.expectedClose) return;
      // The checkpoint for THIS turn is the one we most want and the one we used to throw
      // away. Extend once, bounded, before draining (#4245).
      if (shouldExtendForCheckpointCapture({
        terminated: state.terminated,
        openToolCallCount: state.openToolCalls.size,
        wantsCheckpointCapture: this.wantsCheckpointCapture,
        hasCapturedCheckpoint: this.capturedCheckpointBytes !== undefined,
        alreadyExtended: this.checkpointGraceExtended,
      })) {
        this.checkpointGraceExtended = true;
        this.scheduleClientToolFinalize(state, push, CHECKPOINT_CAPTURE_GRACE_MS);
        return;
      }
      const terminal = finalizeAfterDrain(state);
      if (terminal.length === 0) return;
      for (const event of terminal) push(event);
      debugProviderDiagnostic("cursor", "client-tool-suspend", {
        reason: "Responses bridge owns client tools; ending turn without fake mcpResult",
        framesReceived: this.framesReceived,
        elapsedMs: Date.now() - this.turnStartedAt,
        graceMs: graceMsOverride ?? this.activeClientToolFinalizeGraceMs,
        checkpointGraceExtended: this.checkpointGraceExtended,
      });
      this.cancelCursorRun();
    };
    this.pendingFinalizeRun = run;
    this.pendingFinalize = setTimeout(run, graceMsOverride ?? this.activeClientToolFinalizeGraceMs);
  }

  private open(
    encodedRequest: Uint8Array,
    signal: AbortSignal | undefined,
    state: ReturnType<typeof createCursorProtobufEventState>,
    push: (message: CursorServerMessage) => void,
    fail: (error: Error) => void,
    finish: () => void,
  ): void {
    if (signal?.aborted) {
      fail(signal.reason instanceof Error ? signal.reason : new Error("Cursor request was aborted"));
      return;
    }
    this.turnStartedAt = Date.now();
    this.framesReceived = 0;
    this.checkpointGraceExtended = false;
    // A turn must not inherit the previous one's snapshot: a stale capture would make
    // shouldExtendForCheckpointCapture skip the wait this turn actually needs.
    this.capturedCheckpointBytes = undefined;
    this.sawAssistantText = false;
    this.emittedTerminal = false;
    this.firstFrameAt = undefined;
    this.firstFrameLogged = false;
    const baseUrl = this.input.provider.baseUrl || "https://api2.cursor.sh";
    const useHttp1 = isPinnedHttp1(this.input.provider.upstreamHttpVersion);
    const requestId = crypto.randomUUID();
    const dialHost = cursorHostLabel(baseUrl);
    debugProviderDiagnostic("cursor", "dial", { host: dialHost, transport: useHttp1 ? "http1.1" : "http2" });

    let session: http2.ClientHttp2Session | undefined;
    let stream: http2.ClientHttp2Stream | undefined;
    if (!useHttp1) {
      this.input.onRunDispatch?.();
      session = http2.connect(baseUrl);
      this.session = session;
      // The run request is buffered until the HTTP/2 session connects. Failures before `connect`
      // (DNS, ECONNREFUSED, TLS, connect timeout) mean the server never received the request, so they
      // are safe to retry. Once connected, bytes flush to the server and the turn must not be replayed.
      session.on("connect", () => {
        this.committed = true;
        debugProviderDiagnostic("cursor", "connected", {
          transport: "http2",
          connectMs: Date.now() - this.turnStartedAt,
        });
      });
      stream = session.request({
        ":method": "POST",
        ":path": CURSOR_RUN_PATH,
        "content-type": "application/connect+proto",
        "connect-protocol-version": "1",
        te: "trailers",
        authorization: `Bearer ${this.token}`,
        "x-ghost-mode": "true",
        "x-cursor-client-version": CURSOR_CLIENT_VERSION,
        "x-cursor-client-type": "cli",
        "x-request-id": requestId,
        "x-session-id": this.sessionId,
      });
      this.stream = stream;
    }

    // Single-shot terminal owner for this turn (createTerminalSettler): stream error, session
    // error, trailers, end, abort, and the first-frame timeout all race into it, and only the
    // first wins. The first-frame timer is cleared by any settlement so it can never leak.
    const settler = createTerminalSettler({
      fail,
      finish,
      clearTimer: () => {
        void this.startShellCleanup();
        this.clearFirstFrameTimer();
        this.clearStreamHealthTimer();
      },
    });
    const failAndClear = (error: Error) => {
      releaseBacklogLease();
      if (this.expectedClose) {
        // We already emitted a terminal `done` and cancelled the run (client-tool suspension). The
        // RST_STREAM CANCEL surfaces here as a stream error/abort; it is expected, not a failure.
        debugProviderDiagnostic("cursor", "stream-cancel-expected", {
          code: (error as { code?: unknown }).code,
          message: redactCursorForLog(error.message),
          framesReceived: this.framesReceived,
          elapsedMs: Date.now() - this.turnStartedAt,
        });
        settler.settleFinish();
        return;
      }
      settler.settleFail(error);
    };
    // Session-level errors (TLS/socket/GOAWAY) do not always propagate to the stream listener;
    // without this handler they could bypass orderly failure reporting entirely.
    const onSessionError = (err: unknown) => {
      const realErr = err instanceof Error ? err : new Error(String(err));
      debugProviderDiagnostic("cursor", "session-error", {
        code: String((realErr as { code?: unknown }).code ?? ""),
        message: redactCursorForLog(realErr.message),
        elapsedMs: Date.now() - this.turnStartedAt,
      });
      failAndClear(realErr);
    };
    this.firstFrameTimer = setTimeout(() => {
      this.firstFrameTimer = undefined;
      debugProviderDiagnostic("cursor", "first-frame-timeout", { timeoutMs: this.input.firstFrameTimeoutMs ?? CURSOR_FIRST_FRAME_TIMEOUT_MS });
      try { stream?.close(); } catch { /* already closing */ }
      try { session?.close(); } catch { /* already closing */ }
      this.http1Connection?.close();
      if (stream && session) {
        // close() waits for in-flight frames; a dead socket can ignore it — force-destroy shortly
        // after so a stalled TLS session cannot linger past the timeout.
        armTimeoutDestroyFallback(stream, session, this.input.timeoutDestroyGraceMs ?? CURSOR_TIMEOUT_DESTROY_GRACE_MS);
      }
      releaseBacklogLease();
      settler.settleFail(new Error("Cursor transport timed out before first response"));
    }, this.input.firstFrameTimeoutMs ?? CURSOR_FIRST_FRAME_TIMEOUT_MS);

    // Raw Connect backlog with a parse cursor: appends copy only the incoming
    // chunk (amortized capacity growth), the consumed prefix is reclaimed
    // lazily, and the RAW used length (headers included) is what the 32 MiB
    // transport cap bounds — payload-only accounting let tiny-frame/header
    // floods slip through.
    let backlog = new Uint8Array();
    let backlogStart = 0;
    let backlogEnd = 0;
    const BACKLOG_COMPACT_MIN_SAVINGS = 64 * 1024;
    const appendBacklog = (chunk: Uint8Array): void => {
      const used = backlogEnd - backlogStart;
      let start = backlogStart;
      let end = backlogEnd;
      // Reclaim the consumed prefix when it is large or needed for capacity.
      if (start > 0 && (start >= BACKLOG_COMPACT_MIN_SAVINGS || end + chunk.byteLength > backlog.byteLength)) {
        backlog = backlog.slice(start, end);
        start = 0;
        end = used;
      }
      if (end + chunk.byteLength > backlog.byteLength) {
        const capacity = Math.max(8192, backlog.byteLength * 2, end + chunk.byteLength);
        const next = new Uint8Array(Math.min(CURSOR_TRANSPORT_MAX_BUFFERED_BYTES, capacity));
        next.set(backlog.subarray(start, end), 0);
        backlog = next;
      }
      backlog.set(chunk, end);
      backlogStart = start;
      backlogEnd = end + chunk.byteLength;
    };
    let frameWork: Promise<void> = Promise.resolve();
    // Idempotent terminal owner for the backlog lease: every settle/close path
    // must leave the raw charge at zero instead of relying on budget disposal.
    let backlogLeaseReleased = false;
    const releaseBacklogLease = () => {
      if (backlogLeaseReleased) return;
      backlogLeaseReleased = true;
      const leftover = backlogEnd - backlogStart;
      if (leftover > 0) this.releaseTransportBytes(leftover);
      backlog = new Uint8Array();
      backlogStart = 0;
      backlogEnd = 0;
    };
    const handleFrame = async (frame: ReturnType<typeof consumeConnectFrames>["frames"][number]) => {
      this.framesReceived++;
      if ((frame.flags & CONNECT_FLAG_END_STREAM) === CONNECT_FLAG_END_STREAM) {
        const endError = parseConnectEndStreamError(frame.payload);
        debugProviderDiagnostic("cursor", "connect-end-stream", endError ? {
          code: cursorConnectErrorCode(frame.payload),
          message: redactCursorForLog(endError.message),
          classified: classifyCursorError(endError.message),
          framesReceived: this.framesReceived,
          elapsedMs: Date.now() - this.turnStartedAt,
        } : { framesReceived: this.framesReceived, elapsedMs: Date.now() - this.turnStartedAt });
        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
            || hasBufferedTextToolCalls(state)
          )
        ) {
          const terminal = hasPendingClientToolFinalization && state.openToolCalls.size === 0
            ? finalizeAfterDrain(state)
            : finalizeTurnEvents(state);
          for (const event of terminal) push(event);
        }
        this.markProtocolComplete();
        releaseBacklogLease();
        settler.settleFinish();
        return;
      }
      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 = this.streamHealthClock.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;
      const used = backlogEnd - backlogStart;
      if (availableSlots <= 0 || used === 0) {
        this.updateTransportFlowControl();
        return;
      }
      // Cursor decode, zero-copy: frame payloads are views into the backlog, so
      // the charge TRANSFERS — only consumed header bytes leave the counter
      // (payload bytes stay charged and are released when each frame's work
      // finishes). An exact 16 MiB payload therefore peaks at 16 MiB + 5, not
      // at double its size.
      const decoded = consumeConnectFrames(
        backlog.subarray(backlogStart, backlogEnd),
        CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES,
        availableSlots,
      );
      if (decoded.frames.length > 0) {
        backlogStart += decoded.consumedBytes;
        this.releaseTransportBytes(decoded.consumedBytes - decoded.frames.reduce((n, frame) => n + frame.payload.byteLength, 0));
      }
      for (const frame of decoded.frames) {
        this.pendingTransportFrames += 1;
        this.updateTransportFlowControl();
        frameWork = frameWork
          .then(() => handleFrame(frame))
          .catch(err => failAndClear(err instanceof Error ? err : new Error(String(err))))
          .finally(() => {
            this.releaseTransportBytes(frame.payload.byteLength);
            this.pendingTransportFrames = Math.max(0, this.pendingTransportFrames - 1);
            this.updateTransportFlowControl();
            drainPendingFrames();
          });
      }
    };
    const onData = (chunk: string | Uint8Array) => {
      this.clearFirstFrameTimer();
      // Once the turn has settled, late network bytes must never be charged —
      // the backlog lease is already released and nobody would own these.
      if (settler.settled()) return;
      if (!this.firstFrameLogged) {
        this.firstFrameLogged = true;
        this.firstFrameAt = Date.now();
        debugProviderDiagnostic("cursor", "first-frame", { latencyMs: this.firstFrameAt - this.turnStartedAt });
      }
      const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
      let charged = false;
      let appended = false;
      try {
        // RAW chunk bytes (headers included) join the backlog charge; consumed
        // bytes leave it at drain. No whole-backlog replacement copy anymore.
        this.reserveTransportBytes(bytes.byteLength);
        charged = true;
        appendBacklog(bytes);
        appended = true;
        drainPendingFrames();
      } catch (err) {
        // Release ONLY when the reservation succeeded but the append never
        // happened. A failed reservation charged nothing — releasing here
        // would debit unrelated existing ownership; an appended chunk is owned
        // by the terminal backlog cleanup.
        if (charged && !appended) this.releaseTransportBytes(bytes.byteLength);
        failAndClear(err instanceof Error ? err : new Error(String(err)));
      }
    };
    const onTrailers = (trailers: http2.IncomingHttpHeaders) => {
      const status = trailers["grpc-status"];
      if (status !== undefined) debugProviderDiagnostic("cursor", "trailers", { grpcStatus: String(status) });
      if (status && status !== "0") failAndClear(new Error(`Cursor gRPC error ${status}`));
    };
    const onStreamError = (err: unknown) => {
      const realErr = err instanceof Error ? err : new Error(String(err));
      if (this.expectedClose) {
        failAndClear(realErr);
        return;
      }
      const code = (realErr as { code?: unknown }).code;
      const errno = (realErr as { errno?: unknown }).errno;
      debugProviderDiagnostic("cursor", "stream-error", {
        code: typeof code === "string" || typeof code === "number" ? String(code) : undefined,
        errno: typeof errno === "string" || typeof errno === "number" ? String(errno) : undefined,
        name: realErr.name,
        message: redactCursorForLog(realErr.message),
        committed: this.committed,
        framesReceived: this.framesReceived,
        elapsedMs: Date.now() - this.turnStartedAt,
      });
      failAndClear(realErr);
    };
    const onStreamEnd = () => {
      // Native frameWork can be awaiting a shell; cancel before waiting for it to drain.
      void this.startShellCleanup();
      this.clearFirstFrameTimer();
      debugProviderDiagnostic("cursor", "stream-end", {
        committed: this.committed,
        framesReceived: this.framesReceived,
        expectedClose: this.expectedClose,
        elapsedMs: Date.now() - this.turnStartedAt,
      });
      // Settle only after queued frame work drains to quiescence (the chain can
      // extend itself while draining), then classify the terminal state:
      // a trailing incomplete frame is a typed failure, and a zero-frame,
      // zero-byte end without an expected close stays the existing unexpected
      // EOF — both beat the old silent success.
      void (async () => {
        let previous: Promise<void>;
        do {
          previous = frameWork;
          await previous;
        } while (previous !== frameWork);
      })().then(() => {
        if (settler.settled()) return;
        const leftover = backlogEnd - backlogStart;
        if (leftover > 0 && !this.expectedClose) {
          releaseBacklogLease();
          settler.settleFail(new ConnectFrameError(
            "frame_incomplete",
            `Cursor Connect stream ended with ${leftover} unconsumed bytes (incomplete frame)`,
          ));
          return;
        }
        if (this.framesReceived === 0 && !this.expectedClose) {
          releaseBacklogLease();
          settler.settleFail(new Error("Cursor stream ended before any response frame (unexpected EOF)"));
          return;
        }
        // `emittedTerminal` joins dev's two conditions so EOF finalization cannot append a
        // second terminal after a mapper error already failed the turn (integration 010).
        if (state.terminated || this.expectedClose || this.emittedTerminal) {
          releaseBacklogLease();
          settler.settleFinish();
          return;
        }
        // Open tools fail-closed as a truncation *event* (finalizeTurnEvents), not a thrown
        // transport error. settleFail here would hide that typed message as adapter_eof.
        if (state.openToolCalls.size > 0) {
          for (const event of finalizeTurnEvents(state)) push(event);
          releaseBacklogLease();
          settler.settleFinish();
          return;
        }
        if (this.framesReceived > 0 && (this.sawAssistantText || hasBufferedTextToolCalls(state))) {
          for (const event of finalizeTurnEvents(state)) push(event);
          releaseBacklogLease();
          settler.settleFinish();
          return;
        }
        releaseBacklogLease();
        settler.settleFinish();
      }).catch((err) => {
        failAndClear(err instanceof Error ? err : new Error(String(err)));
      });
    };

    if (useHttp1) {
      const providerFetch = this.input.fetch
        ?? (this.input.provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch;
      this.http1Connection = new CursorHttp1BidiConnection({
        baseUrl,
        token: this.token,
        clientVersion: CURSOR_CLIENT_VERSION,
        sessionId: this.sessionId,
        requestId,
        translatorBudget: this.translatorBudget,
        onRunDispatch: this.input.onRunDispatch,
        callbacks: {
          onCommitted: () => {
            this.committed = true;
            debugProviderDiagnostic("cursor", "connected", {
              transport: "http1.1",
              connectMs: Date.now() - this.turnStartedAt,
            });
          },
          onData,
          onEnd: onStreamEnd,
          onError: onStreamError,
        },
        ...(providerFetch ? { fetch: providerFetch } : {}),
      });
      this.http1Connection.start();
    } else {
      session!.on("error", onSessionError);
      stream!.on("data", onData);
      stream!.on("trailers", onTrailers);
      stream!.on("error", onStreamError);
      stream!.on("end", onStreamEnd);
      stream!.on("close", () => { void this.startShellCleanup(); });
    }

    signal?.addEventListener("abort", () => {
      this.close();
      failAndClear(new Error("Cursor request was aborted"));
    }, { once: true });
    // Close the race between the preflight above and listener installation. No request payload is
    // written until after this check.
    if (signal?.aborted) {
      this.close();
      failAndClear(signal.reason instanceof Error ? signal.reason : new Error("Cursor request was aborted"));
      return;
    }

    this.writeConnectFrame(encodeConnectFrame(encodedRequest));
    this.heartbeat = setInterval(() => {
      this.writeConnectFrame(encodeClientMessage({
        message: { case: "clientHeartbeat", value: create(ClientHeartbeatSchema, {}) },
      }));
    }, HEARTBEAT_MS);
  }

  capturedConversationCheckpoint(): Uint8Array | undefined {
    return this.capturedCheckpointBytes;
  }

  private async handleServerMessage(
    message: AgentServerMessage,
    state: ReturnType<typeof createCursorProtobufEventState>,
    push: (message: CursorServerMessage) => void,
  ): Promise<void> {
    if (!this.stream && !this.http1Connection) return;
    debugProviderDiagnostic("cursor", "frame", describeCursorServerFrame(message));
    if (message.message.case === "conversationCheckpointUpdate") {
      try {
        this.capturedCheckpointBytes = toBinary(ConversationStateStructureSchema, message.message.value);
      } catch {
        this.capturedCheckpointBytes = undefined;
      }
      // We are only still open because the grace was extended waiting for exactly this frame.
      // Stop waiting, so a turn that does send a checkpoint pays arrival latency rather than the
      // whole window. Deferred one tick so this frame finishes being mapped and pushed first;
      // finalizing inline would emit the terminal events ahead of it.
      if (this.checkpointGraceExtended && this.pendingFinalizeRun && this.capturedCheckpointBytes) {
        const run = this.pendingFinalizeRun;
        this.clearPendingFinalize();
        this.pendingFinalize = setTimeout(run, 0);
        // Keep the pair in step: clearPendingFinalize() drops the callback, and every other
        // owner of pendingFinalize expects pendingFinalizeRun to describe it.
        this.pendingFinalizeRun = run;
      }
    }
    if (message.message.case === "kvServerMessage") {
      this.writeConnectFrame(encodeConnectFrame(handleCursorNativeKv(message.message.value, this.blobRequestScope)));
      return;
    }
    if (message.message.case === "execServerMessage") {
      const execMsg = message.message.value;
      if (execMsg.message.case === "mcpArgs") {
        const plan = planMcpArgsHandling(execMsg, state);
        if (plan.handledByResponsesBridge) {
          this.noteClientToolActivity();
          for (const event of plan.events) push(event);
          if (plan.cancelCursorRun) this.cancelCursorRun();
          else if (plan.finalizeWhenDrained) this.scheduleClientToolFinalize(state, push);
          return;
        }
      }
      // Native exec/MCP is handled inside this transport and can mutate files/process state
      // without emitting a Responses tool event. Mark the turn replay-unsafe before executing so
      // an eventual invalid_argument cannot cause the adapter's fresh-conversation fallback to
      // run the same local action twice.
      push({ type: "local_side_effect" });
      const replies = await handleCursorNativeExec(message.message.value, {
        ...this.execContext, foregroundShellOwner: this.foregroundShellOwner, signal: this.requestSignal,
      });
      for (const reply of replies) this.writeConnectFrame(encodeConnectFrame(reply));
      return;
    }
    if (message.message.case === "interactionQuery") {
      // The server-side agent BLOCKS until this query is answered with the matching id; leaving it
      // unanswered is the proven stall → watchdog → upstream-502 mechanism. Reply immediately with
      // the non-interactive default and emit liveness so the bridge watchdog sees progress.
      const query = message.message.value;
      const plan = planInteractionQueryReply(query);
      debugProviderDiagnostic("cursor", "interaction-query", { id: query.id, queryCase: query.query.case ?? "unknown", reply: plan.replyCase });
      this.writeConnectFrame(encodeClientMessage({ message: { case: "interactionResponse", value: plan.response } }));
      if (!state.terminated) {
        if (plan.planText) {
          this.sawAssistantText = true;
          push({ type: "text", text: plan.planText });
        }
        push({ type: "heartbeat" });
      }
      return;
    }
    // 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"
      && state.openToolCalls.get(update.value.callId)?.awaitingNativeArgs === true;
    const mapped = mapCursorProtobufServerMessage(message, state);
    if (mapped.some(event => event.type === "text")) this.sawAssistantText = true;
    const beganAwaitingNativeClientToolArgs = update?.case === "toolCallCompleted"
      && !awaitedNativeArgsBeforeMapping
      && state.openToolCalls.get(update.value.callId)?.awaitingNativeArgs === true;
    if (mapped.length > 0) {
      // A client tool call announced/committed via interactionUpdate (toolCallStarted/partialToolCall/
      // toolCallCompleted) changes the call set, so revoke any finalize armed by an earlier drain.
      // A completion can also commit and drain a late call without a following mcpArgs frame; in
      // that case re-arm finalization here so the Responses bridge does not wait forever.
      const clientToolFrame = completesOpenClientTool || isClientToolFrame(message);
      if (clientToolFrame) this.noteClientToolActivity();
      for (const event of mapped) push(event);
      if (
        clientToolFrame
        && state.openToolCalls.size === 0
        && mapped.some(event => event.type === "tool_call_end")
      ) this.scheduleClientToolFinalize(state, push);
      return;
    }
    // The frame produced no outward Responses event (e.g. toolCallStarted / partialToolCall args
    // buffering, a completion waiting for native args, toolCallDelta, tokenDelta, or a checkpoint
    // update). Tool-call protocol events are deferred to completion for atomic, parallel-safe
    // emission, so a turn that silently assembles several tool calls can otherwise exceed the
    // bridge's stall watchdog (upstream_stall_timeout).
    // Emit a liveness heartbeat for these progress frames so the watchdog sees the upstream is alive.
    // Never after a terminal (done/truncation): a stray post-terminal frame must stay fully inert.
    if (!state.terminated && (isCursorProgressFrame(message) || beganAwaitingNativeClientToolArgs)) {
      if (isClientToolFrame(message) || beganAwaitingNativeClientToolArgs) this.noteClientToolActivity();
      push({ type: "heartbeat" });
    }
  }
}

/**
 * Build the best-effort partial usage for a turn that failed before a clean `done` (upstream 502,
 * stream error, abort). Mirrors the clean-finalize math in `finalizeTurnEvents`: the last absolute
 * checkpoint (`contextTokens`) is the cumulative context, the streamed delta stays in outputTokens.
 * Returns undefined when the stream died before ANY token signal (nothing meaningful to report).
 * Exported for unit testing.
 */
export function partialUsageFromEventState(state: ReturnType<typeof createCursorProtobufEventState>): OcxUsage | undefined {
  const out = state.usage.outputTokens;
  const hasCurrentCheckpoint = Number.isFinite(state.contextTokens) && (state.contextTokens ?? 0) > 0;
  const hasCurrentOutput = Number.isFinite(out) && out > 0;
  // A carry-forward value belongs to an earlier successful turn. It can complete current-turn
  // usage math after this turn emits output, but cannot by itself prove that a first-frame failure
  // consumed anything.
  if (!hasCurrentCheckpoint && !hasCurrentOutput) return undefined;
  // Same resolution order as a clean turn, so a failed turn does not silently drop
  // back to inputTokens=0 when only the request-local estimate is available (#373).
  return { ...resolvedTurnUsage(state), estimated: true };
}

/**
 * Attach partial usage to a transport failure so the adapter's error path can surface real token
 * consumption for 502/stall rows instead of `usageStatus: unreported` with 0 tokens.
 */
function attachPartialUsage(failure: Error, state: ReturnType<typeof createCursorProtobufEventState>): Error {
  const usage = partialUsageFromEventState(state);
  if (usage) (failure as Error & { partialUsage?: OcxUsage }).partialUsage = usage;
  return failure;
}

/**
 * Compact frame descriptor for provider debug (`ocx debug provider on`): outer case plus the inner
 * interactionUpdate/exec case and tool-call union case when present. No payload content is logged.
 */
function describeCursorServerFrame(message: AgentServerMessage): Record<string, unknown> {
  const out: Record<string, unknown> = { case: message.message.case ?? "unknown" };
  if (message.message.case === "interactionUpdate") {
    const update = message.message.value.message;
    out.update = update.case ?? "unknown";
    if (update.case === "toolCallStarted" || update.case === "partialToolCall" || update.case === "toolCallCompleted") {
      out.toolCase = update.value.toolCall?.tool.case ?? "none";
      out.callId = update.value.callId;
    }
  } else if (message.message.case === "execServerMessage") {
    out.exec = message.message.value.message.case ?? "unknown";
  } else if (message.message.case === "interactionQuery") {
    out.query = message.message.value.query.case ?? "unknown";
    out.id = message.message.value.id;
  } else if (message.message.case === "kvServerMessage") {
    out.kv = message.message.value.message.case ?? "unknown";
  } else if (message.message.case === "conversationCheckpointUpdate") {
    out.usedTokens = message.message.value.tokenDetails?.usedTokens ?? 0;
  }
  return out;
}

/**
 * True when a server frame represents real upstream progress that produced no outward Responses
 * event (so the bridge's stall watchdog would otherwise see silence). Covers tool-call assembly,
 * token/checkpoint accounting — the frames `mapCursorProtobufServerMessage` intentionally swallows.
 */
function isCursorProgressFrame(message: AgentServerMessage): boolean {
  if (message.message.case === "conversationCheckpointUpdate") return true;
  if (message.message.case !== "interactionUpdate") return false;
  switch (message.message.value.message.case) {
    case "toolCallStarted":
    case "partialToolCall":
    case "toolCallDelta":
    case "tokenDelta":
      return true;
    default:
      return false;
  }
}

/**
 * A tool-call lifecycle frame that can change the CLIENT tool call set (announce a new sibling or
 * commit one). Used to revoke a pending finalize so a late-announced parallel call is never dropped.
 * Only frames whose inner ToolCall is an ocx-bridged Responses tool (`mcpToolCall` with our provider)
 * count: Cursor-native tool frames (readToolCall/editToolCall/...) are display-plane and must not
 * revoke a pending client-tool finalize. Exported for unit testing.
 */
export function isClientToolFrame(message: AgentServerMessage): boolean {
  if (message.message.case !== "interactionUpdate") return false;
  const update = message.message.value.message;
  switch (update.case) {
    case "toolCallStarted":
    case "partialToolCall":
    case "toolCallCompleted":
      return mcpArgsFromToolCall(update.value.toolCall) !== undefined;
    default:
      return false;
  }
}

/** Host-only label for Cursor transport diagnostics — never leaks path/query/credentials. */
function cursorHostLabel(baseUrl: string): string {
  try {
    return new URL(baseUrl).host;
  } catch {
    return "cursor";
  }
}

/** Redact a Cursor error message for diagnostic output. Cursor error strings can carry raw
 * credential key=value pairs beyond what redactSecretString covers; safeCursorErrorMessage
 * already applies the full sanitizer plus the classified prefix, so reuse it verbatim. */
function redactCursorForLog(message: string): string {
  return safeCursorErrorMessage(message).slice(0, 300);
}

/** Extract the Connect end-stream `error.code` from the raw trailer frame payload without
 * surfacing the (potentially secret-bearing) message — used for `[ocx:cursor:connect-end-stream]`
 * diagnostics. Returns undefined when the payload is not the expected Connect error shape. */
function cursorConnectErrorCode(payload: Uint8Array): string | undefined {
  try {
    const parsed = JSON.parse(new TextDecoder().decode(payload)) as { error?: { code?: string } };
    return parsed?.error?.code;
  } catch {
    return undefined;
  }
}

export function createLiveCursorTransport(input: CursorTransportFactoryInput): CursorTransport {
  return new LiveCursorTransport(input);
}

export function capturedCursorCheckpointBytes(transport: CursorTransport): Uint8Array | undefined {
  return transport.capturedConversationCheckpoint?.();
}
