import type { OcxUsage } from "../../types";
import type { AgentServerMessage, McpArgs, ToolCall } from "./gen/agent_pb";
import { decodeCursorArgsMap } from "./arg-codec";
import { normalizeArgKeys } from "./arg-normalize";
import { canonicalCursorFreeformArgs } from "./freeform-args";
import {
  CODEX_APPLY_PATCH_TOOL,
  CURSOR_MULTI_EDIT_TOOL,
  cursorShellBridgeArgsValid,
  cursorShellBridgeDropError,
  defaultShellBridgeArgNormalizeSchema,
  isCodexShellBridgeToolName,
  isCursorStructuredEditToolName,
  normalizeCursorWireName,
  OCX_RESPONSES_TOOL_PROVIDER,
  resolveShellBridgeAliasKey,
  responsesToolNameFromCursorWire,
} from "./tool-definitions";
import {
  drainCursorTextToolCalls,
  type DrainedTextToolCall,
  type SuppressedTextToolCallScan,
} from "./text-toolcall";
import { recordObservedCursorContextWindow } from "./discovery";
import type { CursorServerMessage } from "./types";
import type { TranslatorBudget } from "../../lib/translator-budget";
import { CURSOR_INCOMPLETE_TOOL_CALL_MESSAGE_PREFIX } from "./cursor-errors";

const DEFAULT_CONTEXT_USAGE_MAX_ENTRIES = 200;
const DEFAULT_CONTEXT_USAGE_TTL_MS = 60 * 60 * 1_000;
const DEFAULT_MAX_CLIENT_TOOL_CALLS = 330;

export interface CursorContextUsageControls {
  /**
   * Last observed absolute context size for the same Cursor conversation and uncompacted context
   * epoch. Used only when the current turn produces output but no checkpoint.
   */
  carryForwardTokens?: number;
  /** Persist a fresh checkpoint for later turns in this conversation. */
  recordContextTokens?: (tokens: number) => void;
}

export interface CursorContextUsageTracker {
  controlsForConversation(conversationId: string, options?: { clearPrior?: boolean; storeCheckpoints?: boolean }): CursorContextUsageControls;
  get(conversationId: string): number | undefined;
  record(conversationId: string, tokens: number): void;
  /** Copy numeric carry-forward totals when a conversation id is rotated for replay. */
  rekey(fromConversationId: string, toConversationId: string): void;
  clear(conversationId: string): void;
  clearAll(): void;
}

interface CursorContextUsageEntry {
  tokens: number;
  updatedAt: number;
}

/**
 * Bounded numeric-only carry-forward for Cursor context usage. Cursor checkpoints are absolute
 * active-context sizes, but client-tool suspension can end a turn before a checkpoint arrives. Keep
 * only the last known total per provider conversation so a no-checkpoint finalize does not overwrite
 * a real active-context value with the current turn's tiny output delta. Context text, tool args,
 * and model output are never stored here.
 */
export function createCursorContextUsageTracker(options: { maxEntries?: number; ttlMs?: number; now?: () => number } = {}): CursorContextUsageTracker {
  const maxEntries = options.maxEntries ?? DEFAULT_CONTEXT_USAGE_MAX_ENTRIES;
  const ttlMs = options.ttlMs ?? DEFAULT_CONTEXT_USAGE_TTL_MS;
  const now = options.now ?? (() => Date.now());
  const entries = new Map<string, CursorContextUsageEntry>();

  const prune = () => {
    const at = now();
    for (const [conversationId, entry] of entries) {
      if (at - entry.updatedAt > ttlMs) entries.delete(conversationId);
    }
    while (entries.size > maxEntries) {
      const oldest = entries.keys().next().value;
      if (!oldest) break;
      entries.delete(oldest);
    }
  };

  const record = (conversationId: string, tokens: number) => {
    if (!Number.isFinite(tokens) || tokens <= 0) return;
    prune();
    const existing = entries.get(conversationId);
    if (existing && existing.tokens >= tokens) {
      entries.delete(conversationId);
      entries.set(conversationId, { tokens: existing.tokens, updatedAt: now() });
      return;
    }
    entries.delete(conversationId);
    entries.set(conversationId, { tokens, updatedAt: now() });
    prune();
  };

  const get = (conversationId: string): number | undefined => {
    prune();
    const entry = entries.get(conversationId);
    if (!entry) return undefined;
    entries.delete(conversationId);
    entries.set(conversationId, { tokens: entry.tokens, updatedAt: now() });
    return entry.tokens;
  };

  return {
    controlsForConversation(conversationId, requestOptions = {}) {
      if (requestOptions.clearPrior === true) entries.delete(conversationId);
      const storeCheckpoints = requestOptions.storeCheckpoints !== false;
      const carryForwardTokens = storeCheckpoints ? get(conversationId) : undefined;
      return {
        ...(carryForwardTokens !== undefined ? { carryForwardTokens } : {}),
        ...(storeCheckpoints ? { recordContextTokens: tokens => record(conversationId, tokens) } : {}),
      };
    },
    get,
    record,
    rekey(fromConversationId, toConversationId) {
      if (!fromConversationId || !toConversationId || fromConversationId === toConversationId) return;
      prune();
      const from = entries.get(fromConversationId);
      if (!from) return;
      const to = entries.get(toConversationId);
      const tokens = Math.max(from.tokens, to?.tokens ?? 0);
      entries.delete(fromConversationId);
      entries.delete(toConversationId);
      entries.set(toConversationId, { tokens, updatedAt: now() });
      prune();
    },
    clear(conversationId) {
      entries.delete(conversationId);
    },
    clearAll() {
      entries.clear();
    },
  };
}

export interface CursorProtobufEventState {
  usage: OcxUsage;
  /**
   * Absolute conversation context size from Cursor's `conversationCheckpointUpdate.usedTokens`
   * (authoritative cumulative context, NOT a per-turn delta). Kept separate from `usage.outputTokens`
   * so it is never folded into the additive per-turn output count. Surfaced as `done.usage.totalTokens`
   * so Codex's `last_token_usage.total_tokens` reflects the real active context. Mirrors the Kiro
   * contextUsagePercentage SOT fix (devlog 142.10): absolute context and additive output must not
   * share one field, or Codex double-counts (e.g. 10000 then 10300 surfacing as 20300).
   */
  contextTokens?: number;
  /**
   * Request-local input estimate derived from the payload actually sent to Cursor.
   * Used only when neither a checkpoint nor a carry-forward is available — a restart
   * clears the tracker, and reporting inputTokens=0 makes Codex see an almost-empty
   * context (#373). Never written back into the tracker: only real checkpoints are.
   */
  estimatedInputTokens?: number;
  /**
   * Session-level last-known absolute context size for this Cursor conversation. This is a fallback
   * for no-checkpoint client-tool finalize turns only; any checkpoint observed during the current
   * turn remains authoritative, with monotonic max semantics unless a compaction boundary reset the
   * conversation cache before the turn.
   */
  contextCarryForwardTokens?: number;
  recordContextTokens?: (tokens: number) => void;
  openToolCalls: Map<string, { name: string; args: string; awaitingNativeArgs?: boolean }>;
  completedToolCalls: Set<string>;
  /** Set once a terminal `done`/truncation has been emitted, so post-terminal frames stay inert. */
  terminated?: boolean;
  clientToolNames?: Set<string>;
  /** Responses/Codex names of request-declared freeform tools advertised to Cursor. */
  freeformToolNames?: ReadonlySet<string>;
  parallelToolCalls?: boolean;
  startedClientToolCalls: number;
  /** Hard cap on client tool-call records retained during one upstream turn. */
  maxClientToolCalls: number;
  /** Tool wire-name → original JSON Schema parameters object, for arg-key normalization. */
  toolSchemas?: Map<string, unknown>;
  /** Cursor wire-name → original Responses/Codex tool name for this request. */
  cursorToolNameMap?: Map<string, string>;
  /**
   * Bare names WE advertised as synthetic structured-edit tools on this request.
   * See structuredEditCallIsOurs: conversion is gated on provenance, not on the name.
   */
  syntheticStructuredEditToolNames?: ReadonlySet<string>;
  translatorBudget?: TranslatorBudget;
  /**
   * Incomplete `[TOOL_CALL]…[ARGS]{` prefix held across `textDelta` frames so a
   * marker split by the stream cannot leak into assistant text.
   */
  pendingTextToolCall?: string;
  /** Constant-space scanner used after an incomplete textual marker exceeds its retained byte cap. */
  suppressedTextToolCall?: SuppressedTextToolCallScan;
  /** Budgeted textual fallback calls held until turn finalization establishes that no real frame won. */
  bufferedTextToolCalls?: Array<DrainedTextToolCall & { callId: string }>;
  /** True once this turn carries any real client-tool frame, including an incomplete one. */
  sawRealClientToolCall?: boolean;
  /** Monotonic id suffix for tool calls promoted from text markers. */
  textToolCallSeq?: number;
  /** Wire model id used to record checkpoint `maxTokens` for the next turn. */
  wireModelId?: string;
  /** Normalized Cursor identity scope that owns the observed checkpoint ceiling. */
  identityScope: string;
}


/**
 * Did WE advertise this bare tool name as a synthetic structured-edit tool on this request?
 *
 * Provenance, not a name test. `edit_file` / `multi_edit` are ordinary names a client or MCP
 * server may legitimately expose, and `cursorStructuredEditTools` already refuses to shadow one
 * that exists. Converting on the name alone would undo that refusal at the other end of the
 * request: the client's own call would be silently re-emitted as `apply_patch`, or dropped with
 * an error naming a conversion the user never asked for.
 *
 * Absent set = we advertised nothing, so nothing converts. Fail-closed in the safe direction:
 * an unconverted structured call is a visible, recoverable failure; a wrongly converted one
 * edits a file.
 */
function structuredEditCallIsOurs(
  advertised: ReadonlySet<string> | undefined,
  toolName: string,
): boolean {
  return advertised?.has(toolName) === true;
}

export function createCursorProtobufEventState(options: {
  clientToolNames?: Iterable<string>;
  freeformToolNames?: Iterable<string>;
  parallelToolCalls?: boolean;
  maxClientToolCalls?: number;
  toolSchemas?: Map<string, unknown>;
  cursorToolNameMap?: Map<string, string>;
  syntheticStructuredEditToolNames?: Iterable<string>;
  contextUsage?: CursorContextUsageControls;
  /**
   * Request-local input estimate derived from the payload actually sent. Used only
   * when neither a checkpoint nor a carry-forward is available; never recorded into
   * the checkpoint tracker (#373).
   */
  estimatedInputTokens?: number;
  translatorBudget?: TranslatorBudget;
  /** Wire model id for recording checkpoint `maxTokens` into the process-local window map. */
  wireModelId?: string;
  /** Cursor request identity scope; normalized identically to request-builder continuity. */
  identityScope?: string;
} = {}): CursorProtobufEventState {
  return {
    // Cursor provides no authoritative usage frame; token counts are heuristic estimates from
    // checkpoint/delta events, so mark estimated from the start.
    usage: { inputTokens: 0, outputTokens: 0, estimated: true },
    openToolCalls: new Map(),
    completedToolCalls: new Set(),
    ...(options.clientToolNames ? { clientToolNames: new Set(options.clientToolNames) } : {}),
    ...(options.freeformToolNames ? { freeformToolNames: new Set(options.freeformToolNames) } : {}),
    ...(options.syntheticStructuredEditToolNames
      ? { syntheticStructuredEditToolNames: new Set(options.syntheticStructuredEditToolNames) }
      : {}),
    ...(options.parallelToolCalls !== undefined ? { parallelToolCalls: options.parallelToolCalls } : {}),
    startedClientToolCalls: 0,
    maxClientToolCalls: typeof options.maxClientToolCalls === "number"
      && Number.isFinite(options.maxClientToolCalls)
      && options.maxClientToolCalls > 0
      ? Math.floor(options.maxClientToolCalls)
      : DEFAULT_MAX_CLIENT_TOOL_CALLS,
    ...(options.toolSchemas ? { toolSchemas: options.toolSchemas } : {}),
    ...(options.cursorToolNameMap ? { cursorToolNameMap: options.cursorToolNameMap } : {}),
    ...(options.translatorBudget ? { translatorBudget: options.translatorBudget } : {}),
    ...(options.contextUsage?.carryForwardTokens !== undefined ? { contextCarryForwardTokens: options.contextUsage.carryForwardTokens } : {}),
    ...(options.contextUsage?.recordContextTokens ? { recordContextTokens: options.contextUsage.recordContextTokens } : {}),
    ...(typeof options.estimatedInputTokens === "number"
      && Number.isFinite(options.estimatedInputTokens)
      && options.estimatedInputTokens > 0
      ? { estimatedInputTokens: options.estimatedInputTokens }
      : {}),
    ...(options.wireModelId?.trim() ? { wireModelId: options.wireModelId.trim() } : {}),
    identityScope: options.identityScope?.trim() || "local",
  };
}

function observeContextTokens(state: CursorProtobufEventState, usedTokens: number): void {
  if (!Number.isFinite(usedTokens) || usedTokens <= 0) return;
  if (usedTokens > (state.contextTokens ?? 0)) state.contextTokens = usedTokens;
  state.recordContextTokens?.(usedTokens);
}

export function reportableContextTokens(state: CursorProtobufEventState): number | undefined {
  const current = state.contextTokens;
  const carry = state.contextCarryForwardTokens;
  if (current === undefined) return carry;
  if (carry === undefined) return current;
  return Math.max(current, carry);
}

export function usageFromContextTokens(state: CursorProtobufEventState, contextTokens: number): OcxUsage {
  return {
    ...state.usage,
    inputTokens: Math.max(0, contextTokens - state.usage.outputTokens),
    totalTokens: contextTokens,
  };
}

/** Exported for live-transport's client-tool frame classification (finalize revocation). */
export function mcpArgsFromToolCall(toolCall: ToolCall | undefined): McpArgs | undefined {
  if (toolCall?.tool.case !== "mcpToolCall") return undefined;
  const args = toolCall.tool.value.args;
  return args?.providerIdentifier === OCX_RESPONSES_TOOL_PROVIDER ? args : undefined;
}

function mcpWireNameFromArgs(args: McpArgs | undefined): string | undefined {
  const raw = args?.toolName || args?.name;
  // Models may call the Cursor-displayed `mcp_<provider>_<tool>` name; fold it to the advertised name.
  return raw && raw.length > 0 ? normalizeCursorWireName(raw) : undefined;
}

function mcpCursorWireName(toolCall: ToolCall | undefined): string | undefined {
  return mcpWireNameFromArgs(mcpArgsFromToolCall(toolCall));
}

function decodeMcpArgs(args: McpArgs | undefined): string {
  return JSON.stringify(decodeCursorArgsMap(args?.args));
}

/** Resolve an advertised client-tool wire name, including shell_command/exec_command aliases (#399). */
function resolveAdvertisedClientToolName(
  state: CursorProtobufEventState,
  cursorWireName: string,
): string | undefined {
  const normalized = normalizeCursorWireName(cursorWireName);
  if (!state.clientToolNames) return normalized;
  return resolveShellBridgeAliasKey(normalized, alias => (state.clientToolNames!.has(alias) ? alias : undefined));
}

function toolSchemaForWireName(state: CursorProtobufEventState, toolName: string | undefined): unknown | undefined {
  if (!toolName || !state.toolSchemas) return undefined;
  return resolveShellBridgeAliasKey(toolName, alias => state.toolSchemas!.get(alias));
}

function isFreeformCall(state: CursorProtobufEventState, responsesName: string | undefined): boolean {
  return responsesName !== undefined && state.freeformToolNames?.has(responsesName) === true;
}

function decodeMcpArgsNormalized(
  args: McpArgs | undefined,
  state: CursorProtobufEventState,
  openResponsesName?: string,
): string {
  const toolName = mcpWireNameFromArgs(args);
  const responsesName = toolName
    ? responsesToolNameFromCursorWire(toolName, state.cursorToolNameMap)
    : openResponsesName;
  const decoded = decodeCursorArgsMap(args?.args, { preserveStrings: isFreeformCall(state, responsesName) });
  const schema = toolSchemaForWireName(state, toolName);
  if (schema) return JSON.stringify(normalizeArgKeys(decoded, schema));
  return JSON.stringify(decoded);
}

function hasMcpArgBytes(args: McpArgs | undefined): boolean {
  return Object.keys(args?.args ?? {}).length > 0;
}

function isCompleteJson(text: string): boolean {
  if (text.length === 0) return false;
  try {
    JSON.parse(text);
    return true;
  } catch {
    return false;
  }
}

/** Schema-normalize a JSON-text argument blob for a named tool, if a schema is known. */
function normalizeJsonText(text: string, toolName: string | undefined, state: CursorProtobufEventState): string {
  const schema = toolSchemaForWireName(state, toolName);
  if (!schema) return text;
  try {
    const parsed = JSON.parse(text);
    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
      return JSON.stringify(normalizeArgKeys(parsed as Record<string, unknown>, schema));
    }
  } catch {
    // Not parseable as an object: leave as-is.
  }
  return text;
}

/**
 * Resolve the authoritative argument string for a completed client tool call.
 *
 * Cursor sends args two ways: incrementally as `argsTextDelta` (buffered into `open.args`, never
 * streamed onward), and/or as a structured protobuf map on `toolCallCompleted`. We emit the args
 * exactly once, at completion, so they can always be schema-normalized regardless of which form
 * arrived. The completed map wins when present (canonical); otherwise the buffered streamed text is
 * preserved verbatim so the bridge can reject malformed or truncated JSON instead of silently
 * converting it to `{}`. A genuinely empty buffer remains the no-argument case.
 */
function resolveCompletedArgs(
  buffered: string,
  args: McpArgs | undefined,
  state: CursorProtobufEventState,
  openResponsesName?: string,
): string {
  if (hasMcpArgBytes(args)) return decodeMcpArgsNormalized(args, state, openResponsesName);
  const name = mcpWireNameFromArgs(args);
  if (isCompleteJson(buffered)) return normalizeJsonText(buffered, name, state);
  return buffered;
}

const PATCH_BEGIN = "*** Begin Patch";
const PATCH_END = "*** End Patch";
const GIT_HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)?(?: @@.*)?$/;
const MARKDOWN_FENCE = /^```[\w+-]*\s*$/;
const PATH_ARG_KEYS = ["file_path", "filePath", "path", "filepath", "filename", "file", "target_file", "targetFile", "target_path", "targetPath"] as const;
const OLD_STRING_KEYS = ["old_string", "oldString", "oldtext", "old_text", "old_content", "oldContent", "before", "search"] as const;
const NEW_STRING_KEYS = ["new_string", "newString", "newtext", "new_text", "contents", "content", "new_contents", "newContents", "after", "replace"] as const;

export type StructuredEditPair = { old_string: string; new_string: string };

/** First index where `needle` appears as consecutive whole lines in `haystack`, or -1. */
function lineBlockIndex(haystack: string, needle: string): number {
  if (needle.length === 0) return -1;
  const hay = patchLines(haystack);
  const ned = patchLines(needle);
  if (ned.length === 0 || ned.length > hay.length) return -1;
  for (let i = 0; i <= hay.length - ned.length; i++) {
    if (ned.every((line, j) => hay[i + j] === line)) return i;
  }
  return -1;
}

function replaceLineBlock(haystack: string, needle: string, replacement: string): string {
  const at = lineBlockIndex(haystack, needle);
  if (at < 0) return haystack;
  const hay = patchLines(haystack);
  const ned = patchLines(needle);
  const next = [...hay.slice(0, at), ...patchLines(replacement), ...hay.slice(at + ned.length)];
  return next.join("\n");
}

/**
 * Codex apply_patch matches every hunk against the original file (atomic). Cursor models
 * emit sequential multi_edit (later old_string is the text after an earlier replacement).
 * Fold only when one side contains the other as whole lines — raw substring includes()
 * merged independent edits (B8: `hello world` inside `x = hello world`).
 */
export function foldSequentialStructuredEdits(edits: StructuredEditPair[]): StructuredEditPair[] {
  const folded: StructuredEditPair[] = [];
  for (const edit of edits) {
    let absorbed = false;
    for (let i = folded.length - 1; i >= 0; i--) {
      const prior = folded[i];
      if (lineBlockIndex(prior.new_string, edit.old_string) >= 0) {
        folded[i] = {
          old_string: prior.old_string,
          new_string: replaceLineBlock(prior.new_string, edit.old_string, edit.new_string),
        };
        absorbed = true;
        break;
      }
      if (lineBlockIndex(edit.old_string, prior.new_string) >= 0) {
        folded[i] = {
          old_string: replaceLineBlock(edit.old_string, prior.new_string, prior.old_string),
          new_string: edit.new_string,
        };
        absorbed = true;
        break;
      }
    }
    if (!absorbed) folded.push({ old_string: edit.old_string, new_string: edit.new_string });
  }
  return folded;
}

const GIT_NO_NEWLINE = /^\\ No newline at end of file\s*$/;
const GIT_META_PREFIX = /^(diff --git |index |new file mode |deleted file mode |old mode |new mode |similarity index |dissimilarity index |rename from |rename to |copy from |copy to )/;
const GIT_FILE_HEADER = /^(---|\+\+\+) (?:\/dev\/null|"[ab]\/|[ab]\/)/;

function isCodexFileOpLine(line: string): boolean {
  return line.startsWith("*** Update File:")
    || line.startsWith("*** Add File:")
    || line.startsWith("*** Delete File:");
}

function canonicalizeCodexLine(line: string): string {
  const trimmed = line.replace(/^\uFEFF/, "");
  const lower = trimmed.toLowerCase();
  if (lower === "*** begin patch" || lower.startsWith("*** begin patch ")) return PATCH_BEGIN;
  if (lower === "*** end patch" || lower.startsWith("*** end patch ")) return PATCH_END;
  const colonOps = [
    ["*** update file:", "*** Update File:"],
    ["*** add file:", "*** Add File:"],
    ["*** delete file:", "*** Delete File:"],
    ["*** move to:", "*** Move to:"],
  ] as const;
  for (const [needle, canon] of colonOps) {
    if (lower.startsWith(needle)) return `${canon}${trimmed.slice(needle.length)}`;
  }
  const spaceOps = [
    ["*** update file ", "*** Update File: "],
    ["*** add file ", "*** Add File: "],
    ["*** delete file ", "*** Delete File: "],
  ] as const;
  for (const [needle, canon] of spaceOps) {
    if (lower.startsWith(needle)) return `${canon}${trimmed.slice(needle.length)}`;
  }
  return trimmed;
}

function isGitPreambleLine(line: string): boolean {
  return line === "---"
    || GIT_NO_NEWLINE.test(line)
    || GIT_META_PREFIX.test(line)
    || GIT_FILE_HEADER.test(line);
}

function unquoteGitPath(path: string): string {
  const trimmed = path.trim();
  if (
    (trimmed.startsWith("\"") && trimmed.endsWith("\""))
    || (trimmed.startsWith("'") && trimmed.endsWith("'"))
  ) {
    return normalizePatchPath(trimmed.slice(1, -1));
  }
  return normalizePatchPath(trimmed);
}

/** Grammar-only path cleanup: trim, POSIX slashes, drop a leading `./`. */
function normalizePatchPath(path: string): string {
  let next = path.trim().replace(/\\/g, "/");
  while (next.startsWith("./")) next = next.slice(2);
  return next;
}

function parseDiffGitPaths(line: string): { a: string; b: string } | undefined {
  const quoted = /^diff --git "a\/(.+)" "b\/(.+)"$/.exec(line);
  if (quoted) return { a: unquoteGitPath(quoted[1]), b: unquoteGitPath(quoted[2]) };
  const plain = /^diff --git a\/(.+) b\/(.+)$/.exec(line);
  if (plain) return { a: unquoteGitPath(plain[1]), b: unquoteGitPath(plain[2]) };
  return undefined;
}

function parseGitSidePath(line: string, side: "a" | "b"): string | undefined {
  const quoted = new RegExp(`^(?:---|[+][+][+]) "${side}\\/(.+)"$`).exec(line);
  if (quoted) return unquoteGitPath(quoted[1]);
  const plain = new RegExp(`^(?:---|[+][+][+]) ${side}\\/(.+)$`).exec(line);
  if (plain) return unquoteGitPath(plain[1]);
  return undefined;
}

function isDevNull(line: string): boolean {
  return /^(---|\+\+\+) \/dev\/null$/.test(line);
}

function rewriteHunkHeader(line: string): string {
  return GIT_HUNK_HEADER.test(line) ? "@@" : line;
}

function isFenceLine(line: string): boolean {
  return MARKDOWN_FENCE.test(line);
}

function isHunkBodyLine(line: string): boolean {
  return line === "@@"
    || line.startsWith("@@ ")
    || GIT_HUNK_HEADER.test(line)
    || line.startsWith("+")
    || line.startsWith("-")
    || line.startsWith(" ")
    || line === "";
}

function rewriteCodexFileOpLine(line: string): string {
  for (const prefix of ["*** Update File:", "*** Add File:", "*** Delete File:", "*** Move to:"] as const) {
    if (!line.startsWith(prefix)) continue;
    const path = normalizePatchPath(line.slice(prefix.length).replace(/^\s+/, ""));
    return path ? `${prefix} ${path}` : line;
  }
  return line;
}

function normalizeAddFileBody(lines: readonly string[]): string[] {
  const out: string[] = [];
  let inAdd = false;
  for (const line of lines) {
    if (line.startsWith("*** Add File:")) {
      inAdd = true;
      out.push(line);
      continue;
    }
    if (isCodexFileOpLine(line)) {
      inAdd = false;
      out.push(line);
      continue;
    }
    if (inAdd && (line === "@@" || line.startsWith("@@ ") || GIT_HUNK_HEADER.test(line))) continue;
    if (inAdd && line.length > 0 && !line.startsWith("+")) {
      out.push(`+${line}`);
      continue;
    }
    out.push(line);
  }
  return out;
}

function hasNonEmptyCodexOp(lines: readonly string[]): boolean {
  let kind: "add" | "update" | "delete" | undefined;
  let hunk = false;
  let any = false;
  const flush = () => {
    if (kind === "delete" || ((kind === "add" || kind === "update") && hunk)) any = true;
  };
  for (const line of lines) {
    if (line.startsWith("*** Update File:")) {
      flush();
      kind = "update";
      hunk = false;
      continue;
    }
    if (line.startsWith("*** Add File:")) {
      flush();
      kind = "add";
      hunk = false;
      continue;
    }
    if (line.startsWith("*** Delete File:")) {
      flush();
      kind = "delete";
      hunk = false;
      continue;
    }
    if (line.startsWith("+") || line.startsWith("-") || line === "@@" || line.startsWith("@@ ")) hunk = true;
  }
  flush();
  return any;
}

function trimEmptyEdges(lines: readonly string[]): string[] {
  let start = 0;
  let end = lines.length;
  while (start < end && lines[start] === "") start++;
  while (end > start && lines[end - 1] === "") end--;
  return lines.slice(start, end);
}

function cleanHunkLines(lines: readonly string[]): string[] {
  return trimEmptyEdges(
    lines
      .filter(line =>
        !isGitPreambleLine(line)
        && !isFenceLine(line)
        && line !== PATCH_BEGIN
        && line !== PATCH_END
        && !isCodexFileOpLine(line)
        && !line.startsWith("*** Move to:")
      )
      .map(rewriteHunkHeader)
      .filter(line => isHunkBodyLine(line)),
  );
}

function isGitSectionStart(line: string, splitOnDiffGit: boolean): boolean {
  if (splitOnDiffGit) return line.startsWith("diff --git ");
  return /^(--- )(?:\/dev\/null|"a\/|a\/)/.test(line);
}

function splitGitSections(lines: readonly string[]): string[][] {
  const splitOnDiffGit = lines.some(line => line.startsWith("diff --git "));
  const sections: string[][] = [];
  let current: string[] = [];
  for (const line of lines) {
    if (isGitSectionStart(line, splitOnDiffGit) && current.length > 0) {
      sections.push(current);
      current = [line];
      continue;
    }
    current.push(line);
  }
  if (current.length > 0) sections.push(current);
  return sections;
}

function isGitBinarySection(lines: readonly string[]): boolean {
  return lines.some(line => /^Binary files /.test(line) || line.startsWith("GIT binary patch"));
}

function isGitCopySection(lines: readonly string[]): boolean {
  return lines.some(line => line.startsWith("copy from ") || line.startsWith("copy to "));
}

function isGitEmptyRenameSection(lines: readonly string[]): boolean {
  const hasRenameMeta = lines.some(line => line.startsWith("rename from ") || line.startsWith("rename to "));
  const diff = lines.map(parseDiffGitPaths).find(path => path !== undefined);
  if (!hasRenameMeta && !(diff && diff.a !== diff.b)) return false;
  const body = cleanHunkLines(lines);
  return !body.some(line => line === "@@" || line.startsWith("@@ ") || line.startsWith("+") || line.startsWith("-"));
}

function isGitUntranslatableSection(lines: readonly string[]): boolean {
  return isGitBinarySection(lines) || isGitCopySection(lines) || isGitEmptyRenameSection(lines);
}

function convertGitSection(lines: readonly string[]): string[] | undefined {
  if (isGitBinarySection(lines)) return undefined;
  const existingOp = lines.find(isCodexFileOpLine);
  if (existingOp) {
    const move = lines.filter(line => line.startsWith("*** Move to:"));
    return [existingOp, ...move, ...cleanHunkLines(lines)];
  }
  const diffPaths = lines.map(parseDiffGitPaths).find(path => path !== undefined);
  const plusPath = lines.map(line => parseGitSidePath(line, "b")).find(path => path !== undefined);
  const minusPath = lines.map(line => parseGitSidePath(line, "a")).find(path => path !== undefined);
  const renameFrom = lines.find(line => line.startsWith("rename from "))?.slice("rename from ".length);
  const renameTo = lines.find(line => line.startsWith("rename to "))?.slice("rename to ".length);
  const plusIsNull = lines.some(line => line.startsWith("+++ ") && isDevNull(line));
  const minusIsNull = lines.some(line => line.startsWith("--- ") && isDevNull(line));
  const isNewFile = lines.some(line => line.startsWith("new file mode ")) || minusIsNull;
  const isDeleted = lines.some(line => line.startsWith("deleted file mode ")) || plusIsNull;
  const pathA = minusPath ?? (renameFrom ? unquoteGitPath(renameFrom) : undefined) ?? diffPaths?.a;
  const pathB = plusPath ?? (renameTo ? unquoteGitPath(renameTo) : undefined) ?? diffPaths?.b;
  const body = cleanHunkLines(lines);
  if (isDeleted) {
    const path = pathA ?? pathB;
    return path ? [`*** Delete File: ${path}`] : undefined;
  }
  if (isNewFile) {
    const path = pathB ?? pathA;
    if (!path) return undefined;
    return [`*** Add File: ${path}`, ...body.filter(line => line.startsWith("+"))];
  }
  const hasMinus = body.some(line => line.startsWith("-"));
  if (plusPath && !minusPath && !diffPaths && !hasMinus) {
    return [`*** Add File: ${plusPath}`, ...body.filter(line => line.startsWith("+"))];
  }
  const from = (renameFrom ? unquoteGitPath(renameFrom) : undefined) ?? pathA ?? pathB;
  const to = (renameTo ? unquoteGitPath(renameTo) : undefined) ?? pathB;
  if (!from) return undefined;
  const hasHunk = body.some(line => line === "@@" || line.startsWith("@@ ") || line.startsWith("+") || line.startsWith("-"));
  // Codex 0.147 rejects "Update file hunk ... is empty" (mode-only diffs, 100% renames).
  if (!hasHunk) return undefined;
  const header = [`*** Update File: ${from}`];
  if (to && to !== from) header.push(`*** Move to: ${to}`);
  return [...header, ...body];
}

function hasCodexFileOp(lines: readonly string[]): boolean {
  return lines.some(isCodexFileOpLine);
}

/** Grammar-only repair for Cursor-emitted freeform apply_patch. Not a fuzzy filesystem apply. */
export function sanitizeCodexApplyPatch(patch: string): string {
  const trimmed = patch.replace(/^\uFEFF/, "").replace(/\n+$/, "");
  const rawLines = trimmed.split("\n").map(line => canonicalizeCodexLine(line.endsWith("\r") ? line.slice(0, -1) : line));
  const hasCodex = rawLines.some(isCodexFileOpLine);
  const hasGitHeaders = rawLines.some(line => line.startsWith("diff --git ") || GIT_FILE_HEADER.test(line));
  if (hasGitHeaders && !hasCodex) {
    const sections = splitGitSections(rawLines);
    // A binary hunk cannot be expressed in Codex apply_patch. Leave the original
    // text alone rather than wrapping the text files and dropping the binary one.
    if (sections.some(isGitUntranslatableSection)) return patch.replace(/^\uFEFF/, "");
    const ops = sections
      .map(convertGitSection)
      .filter((section): section is string[] => section !== undefined && hasCodexFileOp(section))
      .map(normalizeAddFileBody);
    if (ops.length > 0) return [PATCH_BEGIN, ...ops.flat(), PATCH_END].join("\n");
  }
  const selected: string[] = [];
  let inAdd = false;
  for (const raw of rawLines) {
    if (isGitPreambleLine(raw) || isFenceLine(raw) || raw === PATCH_BEGIN || raw === PATCH_END) continue;
    const line = rewriteCodexFileOpLine(rewriteHunkHeader(raw));
    if (line.startsWith("*** Add File:")) {
      inAdd = true;
      selected.push(line);
      continue;
    }
    if (isCodexFileOpLine(line)) {
      inAdd = false;
      selected.push(line);
      continue;
    }
    if (line.startsWith("*** Move to:") || isHunkBodyLine(line) || (inAdd && line.length > 0)) {
      selected.push(line);
    }
  }
  const lines = normalizeAddFileBody(trimEmptyEdges(selected));
  const looksLikePatch = lines.some(line =>
    line === "@@"
    || line.startsWith("@@ ")
    || isCodexFileOpLine(line)
  );
  if (!looksLikePatch) return patch.replace(/^\uFEFF/, "");
  // A hunk with no file op is not a valid Codex patch. Do not invent Begin/End around it.
  if (!hasCodexFileOp(lines)) return lines.join("\n");
  if (!hasNonEmptyCodexOp(lines)) return patch.replace(/^\uFEFF/, "");
  return [PATCH_BEGIN, ...lines, PATCH_END].join("\n");
}

function coercePatchInput(value: unknown): string | undefined {
  if (typeof value === "string") {
    const trimmed = value.trim();
    if (trimmed.startsWith("{")) {
      try {
        const inner: unknown = JSON.parse(trimmed);
        if (inner && typeof inner === "object" && !Array.isArray(inner)) {
          const record = inner as Record<string, unknown>;
          if (typeof record.input === "string") return record.input;
          if (Array.isArray(record.input) && record.input.every(item => typeof item === "string")) {
            return record.input.join("\n");
          }
        }
      } catch {
        // The string is the patch, not nested JSON.
      }
    }
    return value;
  }
  if (Array.isArray(value) && value.every(item => typeof item === "string")) return value.join("\n");
  return undefined;
}

export function sanitizeEmittedApplyPatchArgs(argsText: string): string {
  try {
    const parsed: unknown = JSON.parse(argsText);
    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
      const record = parsed as Record<string, unknown>;
      const raw = coercePatchInput(record.input) ?? coercePatchInput(record.patch) ?? coercePatchInput(record.content);
      if (raw !== undefined) {
        const input = sanitizeCodexApplyPatch(raw);
        if (input !== record.input) {
          const next: Record<string, unknown> = { ...record, input };
          delete next.patch;
          delete next.content;
          return JSON.stringify(next);
        }
      }
    }
  } catch {
    if (
      argsText.includes("@@")
      || argsText.includes("***")
      || argsText.includes("diff --git")
      || argsText.includes("--- a/")
      || argsText.includes("+++ b/")
      || argsText.includes("--- /dev/null")
    ) {
      return JSON.stringify({ input: sanitizeCodexApplyPatch(argsText) });
    }
  }
  return argsText;
}

function firstStringArg(args: Record<string, unknown>, keys: readonly string[]): string | undefined {
  for (const key of keys) {
    const value = args[key];
    if (typeof value === "string") return value;
  }
  return undefined;
}

function firstStringOrLines(args: Record<string, unknown>, keys: readonly string[]): string | undefined {
  for (const key of keys) {
    const value = args[key];
    if (typeof value === "string") return value;
    if (Array.isArray(value) && value.length > 0 && value.every(item => typeof item === "string")) {
      return value.join("\n");
    }
  }
  return undefined;
}

/** Split a replacement into patch lines, ignoring one trailing newline (line-based patch semantics). */
function patchLines(text: string): string[] {
  const lines = text.split("\n");
  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
  return lines;
}

/**
 * Models often copy indent in old_string and omit it in new_string. Codex trim-matches the
 * old line and writes new_string verbatim, which strips indent. Copy old leading whitespace
 * onto a flush-left new line of the same line count. Do not change a new line that already
 * has indent (intentional dedent stays possible).
 */
function restoreFlushLeftIndent(oldString: string, newString: string): string {
  const oldLines = patchLines(oldString);
  const newLines = patchLines(newString);
  if (oldLines.length !== newLines.length || oldLines.length === 0) return newString;
  // If the only difference is leading whitespace, the edit IS a deliberate
  // indent change — restoring old indent would erase the user's intent.
  const contentSame = oldLines.every((ol, i) => ol.trimStart() === newLines[i].trimStart());
  const whitespaceDiffers = oldLines.some((ol, i) => {
    const oldLead = /^[ \t]*/.exec(ol)?.[0] ?? "";
    const newLead = /^[ \t]*/.exec(newLines[i])?.[0] ?? "";
    return oldLead !== newLead;
  });
  if (contentSame && whitespaceDiffers) return newString;
  return newLines.map((line, i) => {
    const oldLead = /^[ \t]*/.exec(oldLines[i])?.[0] ?? "";
    const newLead = /^[ \t]*/.exec(line)?.[0] ?? "";
    if (oldLead.length > 0 && newLead.length === 0 && line.length > 0) return oldLead + line;
    return line;
  }).join("\n");
}

function addFilePatch(path: string, newString: string): StructuredEditTranslation {
  const newLines = patchLines(newString);
  if (newLines.length === 0) {
    return { error: "structured edit requires a non-empty old_string; an empty replacement is not a valid edit" };
  }
  return { patch: [PATCH_BEGIN, `*** Add File: ${path}`, ...newLines.map(line => `+${line}`), PATCH_END].join("\n") };
}

/** One `@@` hunk replacing `oldString` with `newString`. */
function replacementHunk(oldString: string, newString: string): { hunk: string } | { error: string } {
  if (oldString.length === 0) {
    return {
      error:
        "structured edit requires a non-empty old_string to locate the replacement; for new files or insertions without existing text, call apply_patch with an `*** Add File` / context hunk or use the shell bridge",
    };
  }
  const oldLines = patchLines(oldString);
  const rawNewLines = patchLines(newString);
  // Line-based patch semantics cannot express an edit that only adds or removes the file's
  // final newline, and an old/new pair that normalizes to the same lines is a silent no-op —
  // reject it rather than emitting an empty hunk that apply_patch would drop.
  if (oldLines.length === 0 && rawNewLines.length === 0) {
    return { error: "structured edit requires a non-empty old_string; an empty replacement is not a valid edit" };
  }
  // Check for no-op against the RAW new_string (before indent restoration) so that
  // intentional dedent edits are not falsely classified as identical.
  if (oldLines.length === rawNewLines.length && oldLines.every((line, i) => line === rawNewLines[i])) {
    return { error: "structured edit old_string and new_string are identical after line normalization; the replacement is a no-op and was dropped" };
  }
  const restoredNew = restoreFlushLeftIndent(oldString, newString);
  const newLines = patchLines(restoredNew);
  const removed = oldLines.map(line => `-${line}`);
  const added = newLines.map(line => `+${line}`);
  return { hunk: ["@@", ...removed, ...added].join("\n") };
}

/**
 * Convert a completed Cursor structured edit call (`edit_file` / `multi_edit`) into a valid Codex
 * apply_patch freeform payload (#1017). Cursor-trained models cannot emit Codex's freeform patch
 * grammar, so the adapter advertises exact-match replacement tools and performs the grammar here.
 * Returns `{ patch }` for a valid conversion, `{ error }` for a malformed call (which must never be
 * relayed verbatim: Codex would reject it locally after the HTTP 200, the reported failure mode),
 * and `undefined` for tools that are not structured edits.
 */
export type StructuredEditTranslation =
  | { patch: string; error?: undefined }
  | { error: string; patch?: undefined };

export function translateStructuredEditCall(
  toolName: string,
  argsText: string,
): StructuredEditTranslation | undefined {
  if (!isCursorStructuredEditToolName(toolName)) return undefined;
  let parsed: unknown;
  try {
    parsed = JSON.parse(argsText);
    if (typeof parsed === "string") parsed = JSON.parse(parsed);
  } catch {
    return {
      error: `${toolName} arguments were not valid JSON; the call was dropped. ${
        toolName === CURSOR_MULTI_EDIT_TOOL
          ? "Use file_path and edits[] (each edit with old_string and new_string)."
          : "Use file_path, old_string and new_string."
      }`,
    };
  }
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
    return { error: `${toolName} arguments must be a JSON object; the call was dropped.` };
  }
  const args = parsed as Record<string, unknown>;
  const rawPath = firstStringArg(args, PATH_ARG_KEYS);
  const path = rawPath ? normalizePatchPath(rawPath) : undefined;
  if (!path) {
    return { error: `${toolName} is missing a non-empty file_path; the call was dropped.` };
  }
  if (/[\n\r\0]/.test(path)) {
    return { error: `${toolName} file_path must not contain a newline, CR, or NUL; the call was dropped.` };
  }
  if (args.replace_all === true || args.replaceAll === true) {
    return {
      error:
        `${toolName} replace_all is not supported; Codex apply_patch first-matches only. Split into unique old_string hunks or include more surrounding lines.`,
    };
  }
  if (args.delete_file === true || args.deleteFile === true) {
    return { patch: [PATCH_BEGIN, `*** Delete File: ${path}`, PATCH_END].join("\n") };
  }
  const hunks: string[] = [];
  const addReplacement = (record: Record<string, unknown>): StructuredEditTranslation => {
    const oldString = firstStringOrLines(record, OLD_STRING_KEYS);
    const newString = firstStringOrLines(record, NEW_STRING_KEYS);
    if (oldString === undefined || newString === undefined) {
      return { error: `${toolName} requires old_string and new_string; the call was dropped.` };
    }
    const hunk = replacementHunk(oldString, newString);
    if ("error" in hunk) return { error: hunk.error };
    return { patch: hunk.hunk };
  };
  if (toolName === CURSOR_MULTI_EDIT_TOOL) {
    let edits: unknown = args.edits;
    if (typeof edits === "string") {
      try {
        edits = JSON.parse(edits);
      } catch {
        return { error: "multi_edit edits were not valid JSON; the call was dropped." };
      }
    }
    if (!Array.isArray(edits) || edits.length === 0) {
      return { error: "multi_edit requires a non-empty edits array; the call was dropped." };
    }
    // Cap edit count to prevent quadratic CPU exhaustion in the fold and overlap scans.
    if (edits.length > 500) {
      return { error: "multi_edit exceeds the 500-edit limit; split into smaller batches." };
    }
    const pairs: StructuredEditPair[] = [];
    for (const edit of edits) {
      if (!edit || typeof edit !== "object" || Array.isArray(edit)) {
        return { error: "multi_edit edits entries must be objects with old_string and new_string; the call was dropped." };
      }
      const record = edit as Record<string, unknown>;
      if (record.replace_all === true || record.replaceAll === true) {
        return {
          error:
            "multi_edit replace_all is not supported; Codex apply_patch first-matches only. Split into unique old_string hunks or include more surrounding lines.",
        };
      }
      const oldString = firstStringOrLines(record, OLD_STRING_KEYS);
      const newString = firstStringOrLines(record, NEW_STRING_KEYS);
      if (oldString === undefined || newString === undefined) {
        return { error: `${toolName} requires old_string and new_string; the call was dropped.` };
      }
      pairs.push({ old_string: oldString, new_string: newString });
    }
    const folded = foldSequentialStructuredEdits(pairs);
    const seenOld = new Set<string>();
    for (const edit of folded) {
      const oldKey = patchLines(edit.old_string).join("\n");
      if (seenOld.has(oldKey)) {
        return {
          error:
            "multi_edit has two edits with the same old_string after line normalization; Codex apply_patch first-matches, so both hunks would hit the same location. Include more surrounding lines to disambiguate.",
        };
      }
      seenOld.add(oldKey);
    }
    for (let i = 0; i < folded.length; i++) {
      for (let j = 0; j < folded.length; j++) {
        if (i === j || folded[j].old_string.length === 0) continue;
        if (lineBlockIndex(folded[i].old_string, folded[j].old_string) >= 0) {
          return {
            error:
              "multi_edit hunks overlap: one old_string is a whole-line subset of another. Codex apply_patch matches every hunk against the original file, so both would first-match the same region. Include more surrounding lines to disambiguate.",
          };
        }
      }
    }
    if (folded.length === 1 && folded[0].old_string.length === 0) {
      return addFilePatch(path, folded[0].new_string);
    }
    if (folded.some(edit => edit.old_string.length === 0)) {
      return {
        error:
          "multi_edit cannot mix an Add File (empty old_string) with an independent Update hunk on the same path; put the full new-file contents in one empty-old_string edit, or create the file first.",
      };
    }
    for (const edit of folded) {
      const hunk = replacementHunk(edit.old_string, edit.new_string);
      if ("error" in hunk) return { error: hunk.error };
      hunks.push(hunk.hunk);
    }
  } else {
    const oldString = firstStringOrLines(args, OLD_STRING_KEYS);
    const newString = firstStringOrLines(args, NEW_STRING_KEYS);
    if (oldString === "") {
      if (newString === undefined) {
        return { error: `${toolName} requires old_string and new_string; the call was dropped.` };
      }
      return addFilePatch(path, newString);
    }
    const editResult = addReplacement(args);
    if (editResult.error !== undefined) return editResult;
    hunks.push(editResult.patch);
  }
  return { patch: [PATCH_BEGIN, `*** Update File: ${path}`, ...hunks, PATCH_END].join("\n") };
}

export function mapSyntheticMcpExecToToolEvents(
  args: McpArgs,
  fallbackCallId = "cursor_mcp_exec",
  options: { allowEmptyArgs?: boolean; state?: CursorProtobufEventState } = {},
): CursorServerMessage[] {
  if (args.providerIdentifier !== OCX_RESPONSES_TOOL_PROVIDER) return [];
  if (options.state?.terminated) return [];
  if (options.state) {
    discardBufferedTextToolCalls(options.state);
    options.state.sawRealClientToolCall = true;
  }
  if (options.allowEmptyArgs !== true && !hasMcpArgBytes(args)) return [];
  const cursorWireName = mcpWireNameFromArgs(args);
  if (!cursorWireName) return [{ type: "error", message: "Cursor requested a Responses tool without a tool name" }];
  const callId = args.toolCallId || fallbackCallId;
  if (options.state?.completedToolCalls.has(callId)) return [];
  if (options.state) {
    // Native-exec delivers the whole client tool call at once. Record it (no-op if already opened by
    // an earlier started/partial event), then emit the atomic start -> delta -> end unit.
    const out: CursorServerMessage[] = [...recordToolCall(options.state, callId, cursorWireName)];
    if (out.some(event => event.type === "error")) return out;
    const open = options.state.openToolCalls.get(callId);
    const finalArgs = resolveCompletedArgs(open?.args ?? "", args, options.state, open?.name);
    out.push(...commitToolCall(options.state, callId, finalArgs));
    return out;
  }
  const responsesName = responsesToolNameFromCursorWire(cursorWireName);
  const normSchema = defaultShellBridgeArgNormalizeSchema(responsesName);
  const normalizedArgs = JSON.stringify(normalizeArgKeys(decodeCursorArgsMap(args?.args), normSchema));
  if (!cursorShellBridgeArgsValid(normalizedArgs, responsesName, normSchema)) {
    if (isCodexShellBridgeToolName(responsesName)) {
      return [{ type: "error", message: cursorShellBridgeDropError(responsesName) }];
    }
  }
  // Stateless fallback (no shared event state): emit a complete, self-contained tool call.
  //
  // No conversion happens here by design (#1036 review). Structured-edit translation is gated on
  // provenance — did WE advertise this bare name on THIS request — and that record lives on the
  // request state, which this branch does not have. Converting anyway would reinstate the exact
  // hazard the gate exists to close: a client or MCP tool legitimately named `edit_file` would be
  // rewritten into an apply_patch it never asked for. The live path always carries state
  // (live-transport seeds it), so this only affects direct/unit callers.
  const emittedName = responsesName;
  const emittedArgs = normalizedArgs;
  return [
    { type: "tool_call_start", id: callId, name: emittedName },
    ...(emittedArgs.length > 2
      ? [{ type: "tool_call_delta" as const, arguments: emittedArgs }]
      : []),
    { type: "tool_call_end", id: callId },
  ];
}

/**
 * Record (open) a client tool call WITHOUT emitting `tool_call_start`. The outward start is deferred
 * to completion (see commitToolCall) so each Cursor tool call surfaces to the bridge as one atomic,
 * self-contained start -> delta -> end unit. This lets Cursor open several tool calls in parallel
 * (or interleave their partial-arg streams) without cross-wiring: nothing reaches the single-current-
 * call bridge until a call completes, and completed calls are emitted whole, one after another.
 * Returns an error only for a genuinely unknown (un-advertised) tool name.
 */
function recordToolCall(state: CursorProtobufEventState, callId: string, cursorWireName: string): CursorServerMessage[] {
  if (state.completedToolCalls.has(callId)) return [];
  if (state.openToolCalls.has(callId)) return [];
  const advertisedName = resolveAdvertisedClientToolName(state, cursorWireName);
  if (state.clientToolNames && !advertisedName) {
    return [{ type: "error", message: `Cursor requested unknown Responses tool: ${cursorWireName}` }];
  }
  if (state.startedClientToolCalls >= state.maxClientToolCalls) {
    return [{ type: "error", message: `Cursor exceeded client tool-call limit (${state.maxClientToolCalls})` }];
  }
  // Prefer the advertised catalog name for Responses mapping so shell_command/exec_command aliases
  // land on the tool Codex actually exposed this turn (#399).
  const mapKey = advertisedName ?? normalizeCursorWireName(cursorWireName);
  state.openToolCalls.set(callId, { name: responsesToolNameFromCursorWire(mapKey, state.cursorToolNameMap), args: "" });
  state.translatorBudget?.openCall(callId);
  state.startedClientToolCalls++;
  return [];
}

function recordRealToolCall(state: CursorProtobufEventState, callId: string, cursorWireName: string): CursorServerMessage[] {
  discardBufferedTextToolCalls(state);
  state.sawRealClientToolCall = true;
  return recordToolCall(state, callId, cursorWireName);
}

function discardBufferedTextToolCalls(state: CursorProtobufEventState): void {
  for (const call of state.bufferedTextToolCalls ?? []) state.translatorBudget?.closeCall(call.callId);
  delete state.bufferedTextToolCalls;
}

/**
 * Emit a completed client tool call as one atomic unit: `tool_call_start` (deferred from open time),
 * the full normalized arguments delta when present, then `tool_call_end`. The call must already be
 * recorded in `openToolCalls`. Because each completion emits a whole non-interleaved unit, the bridge
 * (which tracks a single current tool call) serializes parallel Cursor calls correctly.
 */
/** True when the args already carry a body this call can commit, canonical or repairable (#7049). */
function cursorFreeformArgsCommittable(args: string, toolName: string): boolean {
  return canonicalCursorFreeformArgs(args, toolName).ok;
}

function dropInvalidFreeformCall(state: CursorProtobufEventState, callId: string, toolName: string, reason: string): CursorServerMessage[] {
  state.openToolCalls.delete(callId);
  state.translatorBudget?.closeCall(callId);
  state.completedToolCalls.add(callId);
  return [{ type: "error", message: `${toolName} call had invalid freeform arguments; expected {input:string} (${reason})` }];
}

function dropShellBridgeCall(state: CursorProtobufEventState, callId: string, toolName: string): CursorServerMessage[] {
  state.openToolCalls.delete(callId);
  state.translatorBudget?.closeCall(callId);
  state.completedToolCalls.add(callId);
  return [{ type: "error", message: cursorShellBridgeDropError(toolName) }];
}

function dropStructuredEditCall(state: CursorProtobufEventState, callId: string, toolName: string, reason: string): CursorServerMessage[] {
  state.openToolCalls.delete(callId);
  state.translatorBudget?.closeCall(callId);
  state.completedToolCalls.add(callId);
  // Recoverable: a fatal adapter error becomes response.failed / upstream_server_error and
  // the model never sees the reason. Completing with text keeps the turn alive (#1388).
  return [{ type: "text", text: `\n${toolName} call was not converted to apply_patch: ${reason}` }];
}

function commitToolCall(state: CursorProtobufEventState, callId: string, committedArgs: string): CursorServerMessage[] {
  const open = state.openToolCalls.get(callId);
  if (!open) return [];
  let finalArgs = committedArgs;
  if (isFreeformCall(state, open.name)) {
    const freeform = canonicalCursorFreeformArgs(finalArgs, open.name);
    if (!freeform.ok) return dropInvalidFreeformCall(state, callId, open.name, freeform.reason);
    finalArgs = freeform.args;
  }
  const schema = toolSchemaForWireName(state, open.name);
  if (!cursorShellBridgeArgsValid(finalArgs, open.name, schema)) {
    if (isCodexShellBridgeToolName(open.name)) return dropShellBridgeCall(state, callId, open.name);
  }
  // Structured edit calls are converted to apply_patch here so both the interactionUpdate and the
  // native-exec mcpArgs paths emit the same valid freeform payload (#1017).
  const translation = structuredEditCallIsOurs(state.syntheticStructuredEditToolNames, open.name)
    ? translateStructuredEditCall(open.name, finalArgs)
    : undefined;
  if (translation?.error !== undefined) {
    return dropStructuredEditCall(state, callId, open.name, translation.error);
  }
  if (finalArgs !== open.args) {
    const previousBytes = Buffer.byteLength(open.args);
    const reservation = state.translatorBudget?.reserveTransient(
      Buffer.byteLength(finalArgs),
      { kind: "tool_args", callId },
    );
    open.args = finalArgs;
    reservation?.commitRetained();
    state.translatorBudget?.releaseRetained(previousBytes, { kind: "tool_args", callId });
  }
  const emittedName = translation ? CODEX_APPLY_PATCH_TOOL : open.name;
  const rawArgs = translation ? JSON.stringify({ input: translation.patch }) : finalArgs;
  const emittedArgs = emittedName === CODEX_APPLY_PATCH_TOOL ? sanitizeEmittedApplyPatchArgs(rawArgs) : rawArgs;
  const out: CursorServerMessage[] = [{ type: "tool_call_start", id: callId, name: emittedName }];
  if (emittedArgs.length > 0) out.push({ type: "tool_call_delta", arguments: emittedArgs });
  out.push(...endToolCall(state, callId));
  return out;
}

/**
 * Buffer Cursor's cumulative `argsTextDelta` into the open call WITHOUT emitting a delta. Args are
 * emitted once, normalized, at completion (see resolveCompletedArgs), so a mis-keyed or
 * non-canonical streamed blob can still be repaired before Codex sees it. `argsTextDelta` is
 * cumulative; keep the longest value seen.
 */
function bufferToolArgs(state: CursorProtobufEventState, callId: string, cumulative: string): void {
  const open = state.openToolCalls.get(callId);
  if (!open) return;
  if (cumulative.length >= open.args.length) {
    const encoder = new TextEncoder();
    const previousBytes = encoder.encode(open.args).byteLength;
    const reservation = state.translatorBudget?.reserveTransient(
      encoder.encode(cumulative).byteLength,
      { kind: "tool_args", callId },
    );
    open.args = cumulative;
    reservation?.commitRetained();
    state.translatorBudget?.releaseRetained(previousBytes, { kind: "tool_args", callId });
  }
}

function endToolCall(state: CursorProtobufEventState, callId: string): CursorServerMessage[] {
  if (!state.openToolCalls.has(callId)) return [];
  state.openToolCalls.delete(callId);
  state.translatorBudget?.closeCall(callId);
  state.completedToolCalls.add(callId);
  return [{ type: "tool_call_end", id: callId }];
}

export function mapCursorProtobufServerMessage(
  serverMessage: AgentServerMessage,
  state: CursorProtobufEventState,
): CursorServerMessage[] {
  if (state.terminated) return [];

  if (serverMessage.message.case === "conversationCheckpointUpdate") {
    const tokenDetails = serverMessage.message.value.tokenDetails;
    const usedTokens = tokenDetails?.usedTokens ?? 0;
    // `usedTokens` is the ABSOLUTE conversation context size, not a per-turn output delta. Track it
    // separately (monotonic max) and surface it as `done.usage.totalTokens`; folding it into
    // `outputTokens` (which also accumulates `tokenDelta`) double-counts in Codex. See contextTokens.
    observeContextTokens(state, usedTokens);
    // First checkpoints often send maxTokens=0 (senpi). Only a positive ceiling
    // replaces the id heuristic for the next turn's overflow vs 429 size prior.
    if (state.wireModelId) {
      recordObservedCursorContextWindow(state.wireModelId, tokenDetails?.maxTokens, {
        identityScope: state.identityScope,
      });
    }
    return [];
  }

  if (serverMessage.message.case !== "interactionUpdate") return [];
  const update = serverMessage.message.value.message;
  switch (update.case) {
    case "textDelta": {
      // Textual `[TOOL_CALL]name[ARGS]{…}` is not assistant prose. Leaving it in
      // the text channel (even after #2305 renamed the display alias) leaks a
      // synthetic protocol marker that later turns few-shot-mimic as inert text.
      // Strip complete markers, buffer advertised fallbacks until finalize,
      // and hold or suppress-scan an incomplete opener across deltas.
      const chunk = update.value.text ?? "";
      if (!chunk && !state.pendingTextToolCall && !state.suppressedTextToolCall) return [];
      const drained = drainCursorTextToolCalls(
        state.pendingTextToolCall ?? "",
        chunk,
        state.suppressedTextToolCall,
      );
      if (drained.pending) state.pendingTextToolCall = drained.pending;
      else delete state.pendingTextToolCall;
      if (drained.suppressed) state.suppressedTextToolCall = drained.suppressed;
      else delete state.suppressedTextToolCall;
      const out: CursorServerMessage[] = [];
      if (drained.text) out.push({ type: "text", text: drained.text });
      for (const call of drained.calls) {
        const advertised = resolveAdvertisedClientToolName(state, call.name);
        if (
          state.sawRealClientToolCall
          || !state.clientToolNames
          || !advertised
          || (state.bufferedTextToolCalls?.length ?? 0) >= state.maxClientToolCalls
        ) continue;
        const args = normalizeJsonText(call.args, advertised, state);
        state.textToolCallSeq = (state.textToolCallSeq ?? 0) + 1;
        const callId = `textcall_${state.textToolCallSeq}`;
        state.translatorBudget?.openCall(callId);
        try {
          const reservation = state.translatorBudget?.reserveTransient(
            Buffer.byteLength(args),
            { kind: "tool_args", callId },
          );
          reservation?.commitRetained();
          (state.bufferedTextToolCalls ??= []).push({ name: advertised, args, callId });
        } catch (error) {
          state.translatorBudget?.closeCall(callId);
          throw error;
        }
      }
      return out;
    }
    case "thinkingDelta":
      return update.value.text ? [{ type: "thinking", thinking: update.value.text }] : [];
    case "toolCallStarted": {
      const name = mcpCursorWireName(update.value.toolCall);
      // Record the open call but defer the outward tool_call_start to completion (atomic emission).
      return name ? recordRealToolCall(state, update.value.callId, name) : [];
    }
    case "partialToolCall": {
      const out: CursorServerMessage[] = [];
      const name = mcpCursorWireName(update.value.toolCall);
      if (name) out.push(...recordRealToolCall(state, update.value.callId, name));
      if (out.some(event => event.type === "error")) return out;
      // Buffer cumulative args; do not emit a delta. Args are emitted once, normalized, at completion.
      if (state.openToolCalls.has(update.value.callId)) {
        bufferToolArgs(state, update.value.callId, update.value.argsTextDelta);
      }
      return out;
    }
    case "toolCallDelta":
      // Cursor's typed deltas currently cover native exec internals (shell/task/edit). Client
      // Responses tools return as McpToolCall plus partial args text, so native deltas stay internal.
      return [];
    case "toolCallCompleted": {
      const out: CursorServerMessage[] = [];
      if (state.completedToolCalls.has(update.value.callId)) return [];
      const name = mcpCursorWireName(update.value.toolCall);
      if (name) {
        discardBufferedTextToolCalls(state);
        state.sawRealClientToolCall = true;
      }
      const args = mcpArgsFromToolCall(update.value.toolCall);
      const openBeforeStart = state.openToolCalls.get(update.value.callId);
      // Empty-arg completion handling:
      //  - already-open named ordinary call with no buffered or structured args -> wait for native exec.
      //  - request-declared freeform completion -> wait while its required input wrapper is absent or
      //    incomplete, whether the completion repeats the name or is compact callId-only. A valid
      //    buffered wrapper can commit immediately.
      //    A compact ordinary no-arg call remains legitimate and commits below.
      //  - never started + not advertised -> Cursor prelude noise, drop it.
      //  - advertised client tool, not yet open -> a legitimate no-arg call: commit it (start+end)
      //    so it is not silently dropped; the bridge serializes empty args as "{}".
      if (
        openBeforeStart && !hasMcpArgBytes(args)
        && (
          (name !== undefined && openBeforeStart.args.length === 0)
          || (state.freeformToolNames?.has(openBeforeStart.name) === true
            && !cursorFreeformArgsCommittable(openBeforeStart.args, openBeforeStart.name)
          )
        )
      ) {
        openBeforeStart.awaitingNativeArgs = true;
        return [];
      }
      if (name && !hasMcpArgBytes(args)) {
        // Only commit a no-arg call when the tool is *explicitly* advertised. Without an advertised
        // tool list we cannot tell a real no-arg call from a Cursor prelude, so we keep dropping it.
        const advertised = state.clientToolNames?.has(name) ?? false;
        if (!openBeforeStart && !advertised) return [];
      }
      // Ensure the call is recorded (covers a completion with no prior started/partial event), then
      // emit it as one atomic start -> delta -> end unit so parallel Cursor calls serialize cleanly.
      if (name) out.push(...recordToolCall(state, update.value.callId, name));
      if (out.some(event => event.type === "error")) return out;
      const open = state.openToolCalls.get(update.value.callId);
      // A request-declared freeform call may first appear only in its completion frame. Record it so
      // later same-ID native mcpArgs can supply the authoritative wrapper, but do not broaden the
      // wait to ordinary advertised no-arg tools: those still commit immediately below.
      if (
        !openBeforeStart && open && !hasMcpArgBytes(args)
        && state.freeformToolNames?.has(open.name) === true
        && !cursorFreeformArgsCommittable(open.args, open.name)
      ) {
        open.awaitingNativeArgs = true;
        return [];
      }
      if (open) {
        const finalArgs = resolveCompletedArgs(open.args, args, state, open.name);
        out.push(...commitToolCall(state, update.value.callId, finalArgs));
      }
      return out;
    }
    case "tokenDelta":
      state.usage.outputTokens += update.value.tokens;
      return [];
    case "turnEnded":
      return finalizeTurnEvents(state);
    default:
      return [];
  }
}

/**
 * Resolve the usage to report for a turn, in order of trustworthiness: a checkpoint
 * observed this turn, then the session carry-forward, then the request-local estimate,
 * then the raw per-turn counters. Shared with the partial-usage path in live-transport
 * so a failed turn reports the same input side as a clean one (#373).
 */
export function resolvedTurnUsage(state: CursorProtobufEventState): OcxUsage {
  const contextTokens = reportableContextTokens(state);
  if (contextTokens !== undefined) return usageFromContextTokens(state, contextTokens);
  const estimate = state.estimatedInputTokens;
  if (estimate !== undefined) {
    return {
      ...state.usage,
      inputTokens: estimate,
      totalTokens: estimate + state.usage.outputTokens,
      estimated: true,
    };
  }
  return { ...state.usage };
}

/**
 * Finalize a Cursor turn. If any client tool call is still open (started but never completed),
 * the stream was truncated and the partial tool call must not reach Codex as a completed call
 * with corrupt/empty arguments. Emit an explicit error instead of done (fail-closed).
 * Mirrors kiro-truncation.ts behavior.
 */
/**
 * True when this turn holds textual fallback tool calls that only turn finalization can emit.
 *
 * Cursor can close a stream with a clean Connect END_STREAM and no turnEnded frame. The transport
 * finalizes that path only for a turn it can see is unfinished, and a turn whose entire visible
 * text was a stripped marker looks empty from the outside. Without this the deferred fallback
 * would be dropped exactly when the marker was the turn's only content.
 */
export function hasBufferedTextToolCalls(state: CursorProtobufEventState): boolean {
  return (state.bufferedTextToolCalls?.length ?? 0) > 0;
}

export function finalizeTurnEvents(state: CursorProtobufEventState): CursorServerMessage[] {
  state.terminated = true;
  delete state.pendingTextToolCall;
  delete state.suppressedTextToolCall;
  const bufferedTextToolCalls = state.bufferedTextToolCalls ?? [];
  delete state.bufferedTextToolCalls;
  if (state.openToolCalls.size > 0) {
    for (const call of bufferedTextToolCalls) state.translatorBudget?.closeCall(call.callId);
    const openCallIds = [...state.openToolCalls.keys()];
    const openIds = openCallIds.join(", ");
    // Clear so a second turnEnded (should not happen, but defensive) doesn't re-emit.
    for (const callId of openCallIds) state.translatorBudget?.closeCall(callId);
    state.openToolCalls.clear();
    return [{ type: "error", message: `${CURSOR_INCOMPLETE_TOOL_CALL_MESSAGE_PREFIX} ${openIds}. Arguments may be truncated; the call was not committed.` }];
  }
  const out: CursorServerMessage[] = [];
  if (!state.sawRealClientToolCall) {
    for (const call of bufferedTextToolCalls) {
      out.push(...recordToolCall(state, call.callId, call.name));
      const open = state.openToolCalls.get(call.callId);
      if (open) {
        open.args = call.args;
        out.push(...commitToolCall(state, call.callId, call.args));
      } else state.translatorBudget?.closeCall(call.callId);
    }
  } else {
    for (const call of bufferedTextToolCalls) state.translatorBudget?.closeCall(call.callId);
  }
  // Surface the absolute context size (when Cursor reported a checkpoint) as both totalTokens and
  // the estimated input side of Codex's visible `input + output` counter. Codex status lines can
  // render the additive pair instead of total_tokens, so leaving inputTokens at 0 makes a 16k-context
  // first turn display as "9 used". Keep outputTokens as the per-turn delta and clamp the inferred
  // input to 0 in case Cursor reports a checkpoint smaller than the streamed output delta.
  out.push({ type: "done", usage: resolvedTurnUsage(state) });
  return out;
}
