import type { KiroOAuthMetadata } from "../oauth/types";
import type { NativeReasoningOwner } from "../responses/reasoning-replay-cache";
import type { OcxTool, OcxToolChoice } from "./tools";
import type { TierDecision, TierObservationContext } from "./provider";
import type { TranslatorBudget } from "../lib/translator-budget";

/** Exact provider/credential namespace for process-local reasoning replay. */
export interface OcxReasoningReplayIdentity {
  providerName: string;
  /** Opaque process-local digest of the exact upstream destination. */
  providerDestinationIdentity: string;
  /**
   * The same destination, digested WITHOUT the process-local random key, so it can key a
   * durable store. Absent when no base URL was resolvable.
   */
  providerDestinationDurableIdentity?: string;
  adapterName: string;
  modelId: string;
  /** Opaque process-local credential identity; never a raw token or API key. */
  credentialIdentity: string;
  /**
   * Salted-HMAC credential identity that survives restarts, for the durable
   * thought-signature store (#1926). Absent when no durable identity could be
   * derived — the durable store then refuses to key the entry (fail closed).
   */
  credentialDurableIdentity?: string;
}

/**
 * Stable holder shared by parsed-request copies and already-created bridges.
 * Credential/provider rotation replaces `current` atomically without replacing
 * the holder, so late tool-call cache writes see the active physical identity.
 */
export interface OcxReasoningReplayScopeRef {
  /**
   * Process-local caller principal from resolveContextPrincipal. Absent when the caller presented
   * no identity (keyless loopback); replay state keyed by it then fails closed.
   */
  readonly clientPrincipalId?: string;
  /**
   * Conversation namespace for replay state. The request's own thread-id wins so a child agent
   * cannot write its route into the parent's record (#8632); otherwise this is the Codex
   * parent-thread id, and headerless Responses callers use a raw sanitized thread/Cursor/session
   * fallback, never the hashed request-log conversation id.
   */
  readonly clientThreadId: string;
  current?: Readonly<OcxReasoningReplayIdentity>;
}

/** One replayed hosted search cell, rebuilt as the `web_search` call/result pair `callId`. */
export interface OcxReplayedWebSearchCell {
  /** The client-visible cell id; absent when the cell carried no usable id (no recorded result). */
  cellId?: string;
  callId: string;
  failed: boolean;
}

export interface OcxParsedRequest {
  modelId: string;
  /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */
  _responseModelId?: string;
  /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
  _openAiVirtualSelectedModelId?: string;
  /** Serialized-only model id (xAI OAuth Fast lane); policy keeps reading `modelId`. */
  _wireModelOverride?: string;
  previousResponseId?: string;
  context: OcxContext;
  stream: boolean;
  options: OcxRequestOptions;
  _rawBody?: unknown;
  /** Trusted ingress provenance: preserve Chat's tool defaults only on the final Responses wire. */
  _chatCompletionsInput?: boolean;
  /** Server-owned request provenance. All system text on this turn belongs at system priority. */
  _proxyOwnedSystemPrompt?: true;
  /** Claude replay tags, retained only until each route binding verifies them. */
  _nativeReasoningReplay?: ReadonlyMap<string, string>;
  _nativeReasoningBoundOwner?: NativeReasoningOwner;
  _nativeReasoningMint?: { owner?: NativeReasoningOwner };
  /**
   * The Claude client's typed Anthropic web tools, as declared. Only the anthropic adapter reads
   * them, and only for api.anthropic.com; every other destination never sees them.
   */
  _anthropicServerTools?: readonly Record<string, unknown>[];
  /**
   * Routed Anthropic compaction summary: build tools and system exactly as the ordinary request
   * would (prompt-cache prefix), then send tool_choice none so no client or hosted tool runs.
   */
  _summaryProhibitsToolCalls?: boolean;
  /**
   * Completed server-tool exchanges from the Claude client's history, keyed by the block that
   * followed them (`call:<tool_use id>` / `text:<text>`). Same audience as `_anthropicServerTools`.
   */
  _anthropicServerReplay?: ReadonlyMap<string, readonly Record<string, unknown>[]>;
  /**
   * The caller's `instructions` prefix through its last cache-marked system block. The anthropic
   * adapter ends a system block there so the breakpoint stays off the per-turn tail.
   */
  _anthropicSystemCachePrefix?: string;
  /** The request arrived on the Anthropic Messages surface (Claude Code, Claude Desktop). */
  _anthropicInbound?: boolean;
  /**
   * Boundary between replayed history and this turn's newly appended input. Usually the
   * items the proxy restored from local previous_response_id state; also set when the
   * CLIENT already carried that history verbatim and the proxy skipped the prepend.
   */
  _replayPrefixLen?: number;
  /** Parsed-message index before the first conversational item in a continuation's current delta. */
  _continuationConversationMessageIndex?: number;
  /**
   * True when the full history for a previous_response_id request is present in the input —
   * whether the proxy expanded it or the client already sent it. Consumers read this as
   * "this request is self-contained", never as "the proxy mutated it".
   */
  _previousResponseInputExpanded?: boolean;
  /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
  _cursorConversationId?: string;
  /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
  _clientThreadId?: string;
  /**
   * This request's OWN Codex thread id (`thread-id`), as opposed to `_clientThreadId`, which
   * carries `x-codex-parent-thread-id` and is therefore shared by every parallel child of one
   * parent. Only a surface that must distinguish siblings should read it.
   */
  _codexOwnThreadId?: string;
  /** True when promptCacheKey identifies a shared cache cohort rather than one conversation. */
  _promptCacheKeyIsSharedCohort?: boolean;
  /** Cursor-only thread owner; may be an opaque process-local Desktop session/thread identity. */
  _cursorClientThreadId?: string;
  /** Conversation/provider/account/model-bound namespace for reasoning replay state. */
  _reasoningReplayScope?: OcxReasoningReplayScopeRef;
  /** Trusted configuration snapshot; never read from the client's request body. */
  _nativeReasoningRetention?: Readonly<{ modelSwitch: boolean; accountSwitch: boolean }>;
  /**
   * Set by bindRouteReasoningReplayScope after a proven serving-identity change, or by
   * prepareOpaqueBlobRecovery after an authoritative rejection; consumers strip replayed blobs.
   */
  _stripReasoningEncryptedContent?: boolean;
  /** Native compaction remains nonportable even when reasoning-only retention is enabled. */
  _stripNativeCompactionEncryptedContent?: boolean;
  /** Retention kept reasoning ciphertext across a model/account change; arms streamed rejection recovery. */
  _nativeReasoningRetainedAcrossRoute?: boolean;
  /**
   * Set when replayed reasoning item ids name items in a store this destination cannot read: by
   * prepareOpaqueBlobRecovery before the one recovery rebuild, and by bindRouteReasoningReplayScope
   * while the rejection memo is live or after a proven switch to a different destination or
   * credential. The Responses passthrough then removes the `id` of every replayed reasoning item,
   * whether or not it carries a blob. A stateful destination resolves a replayed id against its own
   * store, so keeping it turns the send into `Item with id 'rs_…' not found` (#5583). A model
   * change on the same destination and credential does not set this.
   */
  _dropForeignReasoningItemIds?: boolean;
  /** Final-route opt-in: emit v2 collaboration message arguments as plaintext on ChatGPT. */
  _plaintextV2AgentMessages?: boolean;
  _plaintextV2Decision?: boolean;
  _plaintextV2EverPrepared?: boolean;
  /**
   * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation.
   * When absent (single-operator local proxy), derivation stays local-scoped.
   */
  _cursorIdentityScope?: string;
  /**
   * True for helper/shadow/compaction turns that must not append into the main Cursor conversation
   * derived from the parent thread id.
   */
  _cursorIsolateConversation?: boolean;
  /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion" | "authType">;
  /** Account-scoped Zed user identity paired with the long-lived access token. */
  _zedAuthContext?: { userId: string };
  _workbuddyAuthContext?: import("../oauth/types").WorkBuddyOAuthMetadata;
  /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
  _providerContinuation?: OcxProviderContinuationState;
  /** Persisted continuation considered only after the final physical route is known. */
  _providerContinuationCandidate?: OcxProviderContinuationState;
  /** Exact process-local route owner attached to newly persisted provider state. */
  _providerContinuationOwner?: OcxProviderContinuationOwner;
  /** Serving owner of image history that was summarized within this request. */
  _anthropicImageOwner?: OcxProviderContinuationOwner;
  /** Internal image recovery summary that must bypass native adaptive thinking defaults. */
  _anthropicImageSummary?: true;
  /**
   * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
   * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
   * executes searches via the gpt-5.6-luna sidecar (see src/web-search). Absent when not requested.
   */
  _webSearch?: Record<string, unknown>;
  /**
   * Replayed hosted `web_search_call` cells the parser rebuilt as `web_search` call/result pairs
   * (src/responses/web-search-replay.ts). The web-search sidecar swaps in the result it recorded for
   * a cell, or removes the pairs when it does not run (src/web-search/sidecar-search-replay.ts).
   */
  _replayedWebSearchCells?: OcxReplayedWebSearchCell[];
  /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
  _imageGeneration?: { toolNames: Set<string>; originalTool?: Record<string, unknown> };
  /**
   * True when Codex requested structured output (`text.format` = json_schema/json_object). The
   * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
   * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
   */
  _structuredOutput?: boolean;
  /**
   * True for a Claude Messages `output_config.format` json_schema. Anthropic promises an answer
   * that conforms to that schema, whatever `strict` the Responses translation states for
   * OpenAI-compatible destinations, so an emulating adapter (Kiro) holds it to full conformance.
   * Process-local; never forwarded.
   */
  _structuredOutputConformance?: boolean;
  /**
   * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking
   * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively;
   * the server runs the model as a summarizer and the bridge emits a synthetic compaction item
   * (see src/responses/compaction.ts).
   */
  _compactionRequest?: boolean;
  /** Request-owned encoding of readable routed v2 retention; never used for native ciphertext. */
  _compactionRetention?: { encode(summary: string): string; commit(): void };
  /** Manual compaction moved to another provider: summarize portably even on a canonical ChatGPT target. */
  _portableCompaction?: boolean;
  /**
   * Codex memory pipeline phase this turn belongs to, when `memoryModels` routes it
   * (src/server/responses/memory-models.ts). Read at the effort choke point, which runs after the
   * route is known.
   */
  _memoryModelPhase?: "extract" | "consolidation";
  /**
   * True when the current request newly introduced a stored compaction summary/marker. Historical
   * markers restored by previous_response_id expansion were already acknowledged and do not reset
   * provider-private continuation caches again on every later turn.
   */
  _contextCompactionBoundary?: boolean;
  /**
   * Codex's own per-turn metadata for this request says `history_initialization: "New"` (HTTP header,
   * or a WebSocket frame's own `client_metadata`). Read once in request preparation; the experimental
   * Anthropic `perMessageEffort` option takes it as the new-transcript receipt (#6895).
   */
  _codexNewHistory?: boolean;
  /** This turn's per-message effort bookkeeping (src/adapters/anthropic/per-message-effort.ts). */
  _perMessageEffort?: PerMessageEffortTurn;
  /**
   * Core-owned registration slot for the optional advisor subsystem (src/advisor). Set per request
   * by the sidecar planner, never at module load: the core Responses path only sees this
   * structural shape, so an advisor-disabled install imports no advisor module. When present, the
   * adapter delivery wraps the worker's event stream with it — the guard holds synthetic
   * `advisor` tool calls, consults the configured expert model, and re-dispatches the worker.
   */
  _advisorGuard?: (options: {
    parsed: OcxParsedRequest;
    translatorBudget?: TranslatorBudget;
    firstEvents: AsyncIterable<AdapterEvent>;
    /** One bounded worker continuation re-dispatch (same machinery as the terminal guard). */
    continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
  }) => AsyncGenerator<AdapterEvent>;
}

export interface OcxContext {
  systemPrompt?: string[];
  /** Proxy-authored suffixes in systemPrompt (including any joining separator). Keeping their
   * provenance lets adapters relocate caller text while preserving the original system layout. */
  proxySystemPrompt?: { blockIndex: number; suffix: string }[];
  messages: OcxMessage[];
  tools?: OcxTool[];
}

export type OcxMessage =
  | OcxUserMessage
  | OcxAssistantMessage
  | OcxDeveloperMessage
  | OcxToolResultMessage;

export interface OcxUserMessage {
  role: "user";
  content: string | OcxContentPart[];
  timestamp: number;
}

export interface OcxAssistantMessage {
  role: "assistant";
  content: OcxAssistantContentPart[];
  /** Responses message phase, preserved when replaying translated provider output. */
  phase?: OcxMessagePhase;
  model?: string;
  timestamp: number;
  /**
   * Kiro's encrypted reasoning blob for THIS assistant turn — the opaque value from the turn's
   * `reasoningContentEvent` (`signature` for the GPT-5.6 family, `redactedContent` for the base64
   * shape), tagged with the wire field it must be replayed on (see kiro/reasoning.ts). Kiro
   * replays it to preserve model reasoning across turns. Provider-specific and unrenderable, so it
   * rides the message rather than a content part: any other adapter simply ignores it.
   */
  kiroRedactedReasoning?: string;
}

export interface OcxDeveloperMessage {
  role: "developer";
  content: string | OcxContentPart[];
  timestamp: number;
}

export interface OcxToolResultMessage {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  /** MCP namespace from the originating tool call, if any. */
  toolNamespace?: string;
  /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
  content: string | OcxContentPart[];
  /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */
  containsEncryptedContent?: boolean;
  isError: boolean;
  timestamp: number;
}

export interface OcxTextContent {
  type: "text";
  text: string;
}

export interface OcxImageContent {
  type: "image";
  /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
  imageUrl: string;
  /** Fidelity hint from Codex: "low" | "high" | "auto". */
  detail?: string;
}

export interface OcxVideoContent {
  type: "video";
  /**
   * A base64 `data:` URL from an OpenAI-compatible `video_url` part, or a URI
   * the upstream can fetch itself (a YouTube watch URL, a Files API uri).
   */
  videoUrl: string;
  /**
   * Gemini's agentic video mode, carried verbatim from the caller's
   * `video_url.processing` (#3271). Absent for every request that does not ask
   * for it, so no existing traffic gains a field.
   */
  processing?: string;
}

/**
 * An attached document carried as bytes rather than as a description of itself.
 *
 * Both inbound parsers used to reduce an attachment to a title before any adapter ran, so no
 * adapter could forward one even to a target that has a representation for it, and the caller
 * could not tell "the model read the document" from "the model was told a document existed"
 * (#5212).
 *
 * `text` is that marker, derived once from what the part knows and kept on the part itself.
 * Every text-only consumer in the tree reaches a `.text` fallback for a part it does not
 * recognize, so carrying it here means a wire with no document representation still states the
 * attachment instead of emitting `undefined` or a mislabelled `[video]`. Only the wires that
 * have a counterpart read `data`.
 */
export interface OcxDocumentContent {
  type: "document";
  /** `[document: name]` marker, for every wire with no document representation. */
  text: string;
  /** IANA media type of the payload, for example `application/pdf`. */
  mediaType: string;
  /** Base64 payload with no `data:` prefix. */
  data: string;
  /** The document's own name: an Anthropic document title or a Chat file part's filename. */
  filename?: string;
}

/**
 * Inline audio carried by Codex's Responses input. Chat Completions accepts this as an
 * `input_audio` content part only for WAV and MP3 payloads, so the normalized form keeps the
 * base64 bytes and a wire-safe format label rather than the original data URL.
 */
export interface OcxAudioContent {
  type: "audio";
  /** Base64 payload with no `data:` prefix. */
  data: string;
  /** Chat Completions input_audio supports WAV and MP3. */
  format: "mp3" | "wav";
  /** Text marker for wires that cannot carry the bytes. */
  text: string;
}

/** A user/developer message content part: text, native media, or an attached document. */
export type OcxContentPart = OcxTextContent | OcxImageContent | OcxVideoContent | OcxDocumentContent | OcxAudioContent;

export interface OcxThinkingContent {
  type: "thinking";
  thinking: string;
  signature?: string;
  itemId?: string;
  /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */
  redacted?: string[];
}

export interface OcxToolCall {
  type: "toolCall";
  id: string;
  name: string;
  arguments: Record<string, unknown>;
  customWireName?: string;
  thoughtSignature?: string;
  /**
   * Provider-issued opaque metadata that must survive the whole round trip unchanged
   * (issue #1735). A signed Gemini part is only valid when its signature comes back on the
   * SAME part it was issued for, so this travels with the individual tool call rather than
   * being matched by name/arguments after the fact.
   */
  providerMetadata?: OcxProviderOpaqueToolCallMetadata;
  /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
  namespace?: string;
}

/**
 * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or
 * synthesized — they are carried verbatim or not at all.
 */
export interface OcxProviderOpaqueToolCallMetadata {
  google?: {
    thoughtSignature?: string;
  };
}

export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
export interface OcxRequestOptions {
  maxOutputTokens?: number;
  temperature?: number;
  topP?: number;
  stopSequences?: string[];
  toolChoice?: OcxToolChoice;
  /** Root functions explicitly selected by the caller. An empty list permits no synthetic root function. */
  explicitRootFunctionChoices?: readonly string[];
  /** Caller-owned function and custom selectors before hosted tools are lowered for the provider. */
  explicitClientToolChoices?: readonly { type: "function" | "custom"; name: string; namespace?: string }[];
  parallelToolCalls?: boolean;
  reasoning?: string;
  /**
   * Independent reasoning toggle resolved at client-compatibility ingress. This is distinct from
   * the strength-like `reasoning` effort: toggle-only models consume this value as `thinking.type`.
   */
  thinkingEnabled?: boolean;
  hideThinkingSummary?: boolean;
  /** Provider policy: suppress raw content-channel reasoning while summaries stay visible. */
  hideRawReasoning?: boolean;
  /** Final-route Chat-to-Responses display compatibility, off unless explicitly enabled. */
  rawReasoningAsSummary?: boolean;
  serviceTier?: string;
  /** Final outbound tier action, resolved after the provider/model wire is settled. */
  tierDecision?: TierDecision;
  /** Internal B0 observation inputs; adapters combine these with the wire they actually serialize. */
  tierObservation?: TierObservationContext;
  presencePenalty?: number;
  frequencyPenalty?: number;
  /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
  promptCacheKey?: string;
  /**
   * Responses `text.format` (json_schema / json_object), preserved for adapters whose
   * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat
   * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts.
   * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro
   * emulates it through a private structured-output tool (src/adapters/kiro/structured-output.ts).
   */
  textFormat?: {
    type: "json_schema" | "json_object";
    name?: string;
    description?: string;
    schema?: Record<string, unknown>;
    strict?: boolean;
  };
}

export type OcxMessagePhase = "commentary" | "final_answer";

/** Non-secret, process-local owner fence for provider-private continuation state. */
export interface OcxProviderContinuationOwner {
  [field: string]: string | number;
  version: 1;
  providerName: string;
  providerDestinationIdentity: string;
  adapterName: string;
  modelId: string;
  credentialIdentity: string;
}

/**
 * Provider-private state that must follow a locally expanded `previous_response_id` chain.
 * Kept out of public Responses output and persisted only in the bounded local continuation cache.
 */
export interface OcxProviderContinuationState {
  /** Proxy-authored owner metadata; stripped before provider adapters receive the state. */
  __ocxOwner?: OcxProviderContinuationOwner;
  cursor?: {
    [field: string]: unknown;
    conversationId?: string;
    checkpointUsable?: boolean;
    /** Opaque process-local Cursor ConversationStateStructure snapshot ref. Never raw protobuf. */
    checkpointRef?: string;
  };
  kiro?: {
    [field: string]: unknown;
    conversationId?: string;
  };
  [provider: string]: Record<string, unknown> | undefined;
}

/** One Anthropic server-side call as the API returned it: `server_tool_use` + its `*_tool_result`. */
export interface AnthropicServerBlocks { use: Record<string, unknown>; result: Record<string, unknown> }

export type AdapterEvent =
  | { type: "heartbeat"; replayUnsafe?: true; preflightReady?: true }
  | { type: "text_delta"; text: string; phase?: OcxMessagePhase;
      /** Complete documented Anthropic progress block: text remains signed thinking on replay. */
      anthropicThinkingSignature?: string }
  | { type: "thinking_delta"; thinking: string }
  // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and
  // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
  // afterOutput marks a turn-level attestation emitted after text/tools, not a new thinking block.
  | { type: "thinking_signature"; signature: string; afterOutput?: true }
  | { type: "redacted_thinking"; data: string }
  // Kiro reasoning round-trip: the encrypted reasoning blob for the CURRENT assistant turn, tagged
  // with the wire field it arrived on. Never rendered — it only rides the reasoning item's envelope
  // so the next request can replay it verbatim.
  | { type: "kiro_redacted_reasoning"; data: string }
  | { type: "reasoning_raw_delta"; text: string }
  | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }
  | { type: "tool_call_delta"; arguments: string }
  | { type: "tool_call_end"; incomplete?: true }
  /** Internal boundary between a guarded first pass and its one-shot continuation. */
  | { type: "assistant_boundary" }
  // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the
  // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts
  // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the
  // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an
  // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under
  // the SAME output index, so the activity animates instead of flashing completed instantly.
  // `itemId` lets the loop name the client-visible cell so it can record the result for replay.
  | { type: "web_search_call_begin"; id: string; itemId?: string }
  | {
      type: "web_search_call_end"; id: string; itemId?: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[];
      /** Anthropic's server-side call (adapters/anthropic.ts): its `server_tool_use` and result block, verbatim. */
      anthropic?: AnthropicServerBlocks;
    }
  | {
      type: "done";
      usage?: OcxUsage;
      /** Native opaque compaction ciphertext returned by a Responses backend. */
      compactionEncryptedContent?: string;
      stopReason?: string;
      endTurn?: boolean;
      providerState?: OcxProviderContinuationState;
    }
  | {
      type: "incomplete";
      reason: string;
      message?: string;
      usage?: OcxUsage;
      retryable?: boolean;
      endTurn?: boolean;
      providerState?: OcxProviderContinuationState;
    }
  // `usage` carries best-effort partial consumption when a turn dies before a clean done
  // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts.
  | {
      type: "error";
      message: string;
      usage?: OcxUsage;
      /** Authoritative upstream/proxy status when known; avoids message-based classification. */
      status?: number;
      /** Responses error type and code when the adapter has a structured provider failure. */
      errorType?: string;
      code?: string;
      /** Proxy-internal permission to consider API-key recovery; never serialized. */
      apiKeyRecovery?: true;
      retryable?: boolean;
      /**
       * Proxy-internal, never serialized: the upstream failed the turn before producing text or a
       * tool call, so the opt-in empty-completion guard may replay the identical request once.
       */
      replaySafeBeforeOutput?: boolean;
    };

/**
 * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge
 * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip
 * reads these; the TUI ignores annotations, so this is additive).
 */
export interface OcxUrlCitation {
  url: string;
  title?: string;
}

/**
 * One turn's per-message effort state (#6895). Spread copies of the parsed request share it, so a
 * rebuild of the same turn is seen as a second build.
 */
export interface PerMessageEffortTurn {
  /** The pending decision this turn owns, until it commits or is abandoned. */
  token?: string;
  generation: string;
  builds: number;
}

/**
 * Canonical usage convention (devlog/260711_claude_inbound/070):
 * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
 *   (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
 * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
 * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
 *   the provider reports both; reads mirror `cachedInputTokens`.
 * - `cacheCreation1hInputTokens` is the 1-hour-TTL subset of `cacheCreationInputTokens`
 *   (Anthropic `cache_creation.ephemeral_1h_input_tokens`), priced at the 1h write tier.
 * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
 */
export interface OcxUsage {
  /** Provider-reported credit spend, independent of token estimates and USD pricing. */
  providerCredits?: number;
  inputTokens: number;
  outputTokens: number;
  /**
   * Absolute active-context size after the response. Stateful providers can expose this separately
   * from their per-attempt usage. Responses serialization derives the input side from
   * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
   */
  contextTotalTokens?: number;
  totalTokens?: number;
  cachedInputTokens?: number;
  cacheReadInputTokens?: number;
  cacheCreationInputTokens?: number;
  cacheCreation1hInputTokens?: number;
  reasoningOutputTokens?: number;
  estimated?: boolean;
  /**
   * The adapter read these counts off the upstream's own usage frame. Only an adapter whose
   * provider is estimated by default (usageForFinalLog) sets it, and a merge keeps it only when
   * every leg had it. A figure taken off a bridged wire or guessed never carries it, so the
   * provider default still marks those as estimated.
   */
  upstreamReported?: true;
  /**
   * The raw upstream usage object for Responses-shaped upstreams (openai/codex#41980 parity):
   * codex-rs preserves the complete `response.usage` object through its own pipeline, so fields
   * the proxy does not model (subscription metadata, future counters) must survive the bridged /
   * rebuilt `response.completed` too. Accounting paths read only the canonical fields above; the
   * wire rebuild merges this object's unknown keys back under the normalized values.
   */
  rawUsage?: Record<string, unknown>;
}
