import type { ClientFacingModelLabel } from "../../lib/error-destination";
import type { HostedAdvisorSelection } from "../../claude/inbound-content-options";
import type { CodexAccountModelRefusal } from "../../combos/failover";
import type { NativeResponseControl } from "./native-response-control";
import type { AdapterEvent, OcxUsage, OcxProviderContinuationState, OcxConfig, OcxProviderConfig, OcxVisionSidecarConfig } from "../../types";
import type { RouteResult } from "../../router";
import type { SingleUseDispatchPermit } from "../../lib/request-execution-budget";
import type { CodexAuthPolicyConfig, CodexAuthContext } from "../../codex/auth-context";
import type { AdmissionLease } from "../../lib/admission";
import type { DataPlaneAdmission } from "../auth-cors";
import type { AdmissionModelScope } from "../admission-model-scope";
import type { resolveCodexModelEntitlements } from "../../codex/model-entitlements";
import type { ResponsesTerminalStatus } from "../../bridge";
import type { ResponsesTerminalRepairScheduler } from "../responses-terminal-repair";
import type { BunRuntimeGateInput } from "./ws-upstream";
import type { NativeMainRefreshDependencies } from "../../codex/main-account";
import type { InboundWire } from "../../providers/registry";
import type { ExplicitOpenAiCallerAuth } from "../../providers/openai-sidecar";
import type { CallerDirectAuth } from "../../providers/caller-authorization";
import type { CompactionRoutingOverride } from "./compaction-routing";
import type { MainHardLockFallbackOverride } from "./main-hard-lock-routing";
import type { TranslatorBudget } from "../../lib/translator-budget";
import type { NativeReasoningOwner } from "../../responses/reasoning-replay-cache";
import type { TransientSendBudget } from "../../lib/upstream-retry";
import type { RequestLogContext } from "../request-log";
import type { UpstreamHostAdmissionLease } from "../../codex/upstream-host-health";
import type { AccountLease } from "../../oauth/kiro-account-load";
import type { PolicyRequestScope } from "./policy-request-scope";
import type { SpendAdmissionPolicy } from "../../lib/spend-reservation-ledger";
import type { OcxParsedRequest } from "../../types";
import type { PolicyRequestEvidence } from "../../routing/evaluator";
import type { ConnectionReplayScope } from "../../responses/state/connection-scope";

export interface HostedAdvisorSpendScope {
  readonly ceilings: SpendAdmissionPolicy;
  optionalWithheld: boolean;
}

export interface ConsumedComboFailure {
  response: Response;
  classificationText: string;
  /** Complete bounded-envelope evidence captured before display truncation; never serialized. */
  codexModelRefusal?: CodexAccountModelRefusal;
  /** Complete bounded-envelope malformed response_format diagnostic verdict captured before display truncation. */
  malformedResponseFormat?: boolean;
  /** Complete bounded-envelope OpenRouter opaque-400 verdict captured before display truncation. */
  openRouterOpaque400?: boolean;
  /** Complete bounded-envelope unoffered-tool-call verdict captured before display truncation. */
  unofferedToolCallRefusal?: boolean;
  /** Complete bounded-envelope provider moderation verdict captured before display truncation. */
  providerModerationRefusal?: boolean;
  /** Complete bounded-envelope provider-413 intake verdict captured before display truncation. */
  providerIntakeRefusal?: boolean;
  /** Structured upstream `error.code` when present in the failure body. */
  upstreamCode?: string;
  /**
   * The envelope root's own structured code when it differs from {@link upstreamCode}.
   *
   * `normalizeUpstreamErrorText` selects the nested record first, so a root verdict would
   * otherwise never reach the combo decision. Both transports pass it, and the decision hops
   * only when the root and the record each would.
   */
  upstreamRootCode?: string;
  /** Sanitized structured `error.message`; compared only against proxy-owned constants, never emitted. */
  upstreamMessage?: string;
  /** Complete structured provider type, retained for conservative recovery classification. */
  upstreamType?: string;
  /** Valid numeric/date value used only for cooldown calculation. */
  retryAfter?: string;
  /** Upstream Codex quota-window reset timestamps used for combo cooldowns. */
  resetAt?: string[];
  /** Reserved for 040 usage attribution without adding another body read. */
  usage?: OcxUsage;
  /**
   * The failed attempt's response was marked non-replayable, such as the answer to a spent
   * ambiguous-reset replacement. The re-wrapped {@link response} cannot carry that in-memory
   * marker, so the combo loop reads it here and stops instead of sending the turn to a later target.
   */
  nonReplayable?: boolean;
  /** The failed attempt was an adapter-normalized plan refusal; only this grants its combo hop. */
  verifiedPlanRefusal?: boolean;
}




/**
 * Direct client encoding for a translated Chat or Messages turn (PF-09). `model` is the model
 * string the client asked for, which every client frame carries; `inputTokenFloor` is the
 * Messages prompt estimate `message_start` reports when no usage arrived first (#4857).
 */
export interface ClientEncoderOption {
  protocol: "chat" | "messages";
  stream: boolean;
  model: string;
  inputTokenFloor?: number;
  /** Chat only: the client set `stream_options.include_usage`. */
  includeUsage?: boolean;
  /**
   * `direct` when the request side also skipped the internal Responses body (the Antigravity
   * direct lane), so the attempt's request path is traced as `[inbound, ir, upstream]`.
   */
  requestLane?: "bridge" | "direct";
}

/**
 * The Antigravity direct lane (`protocols.rollout.antigravityDirect`). The ingress sends the core
 * a Responses body that carries only the request settings; the conversation is decoded straight
 * from the client body. Request preparation applies `decode` at the parse seam, reads routing
 * evidence from `evidence`, and calls `restoreBridgeConversation` if the final route is not the
 * one the lane was decided for, so every `_rawBody` reader of another adapter sees the full
 * bridge body.
 */
export interface DirectRequestOption {
  protocol: "chat" | "messages";
  /** The concrete route the ingress decided the lane for. */
  providerName: string;
  modelId: string;
  /** Policy-routing evidence from the client body; the settings-only body has no `input`. */
  evidence: PolicyRequestEvidence;
  /** The settings-only parse with the directly decoded conversation in place of its empty one. */
  decode(base: OcxParsedRequest): OcxParsedRequest;
  /** The bridge projection's conversation fields (`input`, `instructions`, `tools`). */
  bridgeConversation(): Record<string, unknown>;
}

export interface HandleResponsesOptions {
  /** Original caller label, carried through synthetic children without route substitution. */
  clientModelLabel?: ClientFacingModelLabel;
  /** Original client envelope label when a combo was selected by a synthetic rewrite. */
  clientResponseModelLabel?: ClientFacingModelLabel;
  /** Immutable caller scope inherited by a capability-authenticated internal sidecar request. */
  admissionScope?: AdmissionModelScope;
  /** Captured synchronously at ingress, before parsing or child replay can suspend. */
  advisorAdmissionPolicy?: import("../../types/admission-policy").CapturedAdmissionPolicy;
  /** Internal request-owned policy authorization; never read from client headers or body. */
  policyRequestScope?: PolicyRequestScope;
  /** Internal concrete selector chosen from the original policy evaluation. */
  policyFallbackCandidate?: { provider: string; model: string };
  /** Internal routed-compaction recovery: one logical request, one emergency target. */
  compactionRecoveryAttempted?: boolean;
  compactionRecoveryPermit?: SingleUseDispatchPermit;
  compactionRecoveryKind?: "compaction-v1" | "compaction-v2";
  onCompactionRecoveryRoute?: (route: RouteResult) => void;
  onCompactionRecoveryAdapterEvent?: (event: AdapterEvent) => void;
  /** Physical-send reports already delivered to the shared ledger, including exact booking settlement. */
  onCompactionRecoverySendsReported?: (count: number) => void;
  /** Private holder for the Kiro serving-account lease. */
  accountLoad?: { lease: AccountLease | null; cancelled: boolean };
  /** Internal Claude replay identity; consumed only by the final canonical Go transport. */
  claudeGoAffinity?: { sessionLane?: string };
  /** Validated Claude metadata identity; projected only into final canonical attempt headers. */
  claudeNativeSessionId?: string;
  /** Private Claude bridge pool identity (validated, principal-scoped when derived); completes session-id/thread-id only on Codex account-selection headers. */
  claudeBridgePoolSession?: string;
  /** Original live policy owner; separate from caller-specific routing/sidecar snapshots. */
  codexAuthPolicy?: CodexAuthPolicyConfig;
  turnAdmissionLease?: AdmissionLease;
  /**
   * A JEV decision-model call issued by a combo. It never carries caller credentials, is never
   * rewritten by memory or shadow-call routing, and may not dispatch into a JEV combo.
   */
  internalDecisionCall?: boolean;
  /**
   * How the caller proved data-plane admission (#1686).
   *
   * A bearer-presented admission secret is one of OUR OWN secrets, so a Direct turn must
   * SUBSTITUTE the stored main credential rather than forward it. Without this fact at the
   * decision point, Direct cannot tell an admission bearer from the user own ChatGPT bearer,
   * which is why it refused the whole env_key flow instead of serving it.
   */
  admission?: DataPlaneAdmission;
  /**
   * Internal caller identity captured before Combo strips provisional credentials. An existing
   * holder with no principal preserves keyless replay; never populate it from client data.
   */
  replayPrincipal?: Readonly<{ clientPrincipalId: string | undefined }>;
  /**
   * Internal connection-owned replay scope minted by the /v1/responses WebSocket upgrade for an
   * unidentified loopback caller (src/responses/state/connection-scope.ts). Memory-only, bound to
   * that socket's handshake thread, never sent to the client. It backfills only the replay owner
   * key when no caller principal resolved; it is not a credential, grants no data-plane, history
   * or notes authority, and must never be populated from client data.
   */
  replayScope?: ConnectionReplayScope;
  /** Captured for the logical request and inherited by retries and combo children. */
  readonly plaintextV2Decision?: boolean;
  /** Called at most once after the complete client body is read and accepted for dispatch. */
  onRequestBodyRead?: () => void;
  /** Internal handoff for retry wrappers that must reuse the already-accounted request body. */
  onRequestBodyParsed?: (body: unknown) => void;
  forceEmptyResponseId?: boolean;
  /** Internal, connection-owned control channel; never reconstructed from headers. */
  nativeControl?: NativeResponseControl;
  /** A Remote Link WebSocket turn: told the expanded input and the terminal (src/server/link-turn.ts). */
  linkTurn?: import("../link-turn").LinkTurnObserver;
  abortSignal?: AbortSignal;
  /** One-shot TTFT callback: first non-empty model output observed (WP4). */
  onFirstOutput?: () => void;
  onCodexAuthContextResolved?: (context: CodexAuthContext | undefined) => void;
  /** Internal deterministic seam for account-gated native fallback tests. */
  resolveCodexModelEntitlements?: typeof resolveCodexModelEntitlements;
  /** Internal: validated final client-visible model, after completed terminal success only. */
  onResponseComplete?: (model: string) => void;
  recordTerminalOutcomes?: boolean;
  setTerminalOutcomeRecorder?: (recorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined) => void;
  onNativePassthroughTerminal?: (status: ResponsesTerminalStatus) => void;
  onNativePassthroughCancel?: () => void;
  /** Internal deterministic clock/timer seam for provider terminal repair. */
  responsesTerminalRepairScheduler?: ResponsesTerminalRepairScheduler;
  /** Internal deterministic runtime-identity seam for Codex upstream WS selection tests. */
  codexWsRuntimeIdentity?: BunRuntimeGateInput;
  /** Test seam for native main refresh without live OAuth traffic. */
  nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
  /**
   * When true, body `prompt_cache_key` is a Claude Desktop shared cache cohort
   * (system/tools hash), not a per-session id — do not use it for Anthropic pool affinity.
   */
  promptCacheKeyIsSharedCohort?: boolean;
  /**
   * Wire protocol the ORIGINAL client spoke. The Chat and Anthropic surfaces translate
   * their body into a Responses shape and replay through this function, so without an
   * explicit value the replay would look like a native Responses request and an
   * inbound-scoped registry wire default would fire for a client that never asked for
   * it. Omitted means a genuine Responses inbound.
   */
  inboundWire?: InboundWire;
  /**
   * Set by a translating ingress (Chat / Anthropic) when the client sent an explicit empty
   * tool catalog. Those wires may defer tool delivery, so their translated body carries no
   * readable catalog boundary; an explicit `[]` is still a deny-all declaration and the
   * undeclared-tool guard enforces it. Absent catalogs and partial catalogs stay deferred.
   */
  clientDeclaredEmptyToolCatalog?: boolean;
  nativeReasoningReplay?: ReadonlyMap<string, string>;
  nativeReasoningMint?: { owner?: NativeReasoningOwner };
  /** The Claude client's typed `web_search_*` / `web_fetch_*` declarations; kept only for `inboundWire: "anthropic"`. */
  anthropicServerTools?: readonly Record<string, unknown>[];
  /** The original Messages choice names a typed hosted Advisor, possibly with a duplicate name. */
  anthropicHostedAdvisorSelection?: HostedAdvisorSelection;
  /** Hosted work shares this state across routing candidates and translated combo children. */
  hostedAdvisorSpendScope?: HostedAdvisorSpendScope;
  /** The Claude client's replayable server-tool exchanges (`replayedAnthropicServerBlocks`); same scope. */
  anthropicServerReplay?: ReadonlyMap<string, readonly Record<string, unknown>[]>;
  /** The caller's cached system prefix (`systemCachePrefix`); same scope. */
  anthropicSystemCachePrefix?: string;
  /** Metadata-qualified Messages discovery evidence, never caller JSON or a preselected destination. */
  anthropicToolLoadingSource?: Readonly<Record<string, unknown>>;
  /** Droid's per-request effort default; each concrete combo or policy target applies it only if its ladder allows it. */
  droidDefaultEffort?: string;
  /** The Chat or Messages source a combo child may send natively; set only by that ingress. */
  protocolSource?: import("./core-combo-native").ComboProtocolSource;
  /** Internal transport identity for route-scoped upstream compatibility policy. */
  inboundTransport?: "websocket";
  /** ACP refusal signal captured from the original HTTP request, before any bridge translation. */
  agyAcpUnattendedHttpTurn?: boolean;
  /**
   * Set by the HTTP `/v1/responses` ingress only: a streaming combo turn whose target selection
   * outlasts `COMBO_SELECTION_KEEPALIVE_THRESHOLD_MS` commits a 200 SSE head and sends keepalive
   * comments (#8326). `clock` is a test seam; production uses the global timers.
   */
  comboSelectionKeepalive?: {
    clock?: { setTimeout(callback: () => void, ms: number): unknown; clearTimeout(handle: unknown): void };
  };
  /**
   * Claude replay may add native-main auth so OpenAI sidecars remain available.
   * Strip only that internal credential when the final route is a noncanonical
   * forward/caller-auth destination; final routing can differ from Claude's preflight route.
   */
  stripClaudeMainAuthForNoncanonicalForward?: boolean;
  /** In-memory credential proven by Claude's native-main turn claim; never persist or log. */
  trustedClaudeMainAuth?: { authorization: string; chatgptAccountId?: string };
  /** Sidecar-only auth captured before route changes; null means no usable original pair. */
  openAiSidecarAuth?: ExplicitOpenAiCallerAuth | null;
  /** Internal Chat bridge permission to obtain claimed stored auth only for a final Direct sidecar. */
  allowStoredOpenAiSidecarAuth?: boolean;
  /** Original caller-owned native pair; separate from any claimed sidecar enrichment. */
  nativeCallerAuth?: ExplicitOpenAiCallerAuth | null;
  /** Caller Direct credential under Direct\'s own predicate; restored only for the canonical OpenAI final route. */
  callerDirectAuth?: CallerDirectAuth | null;
  /** Internal recursion guard; callers outside this module must not set it. */
  comboAttempt?: boolean;
  /** `union` combo with no member whose window fits: the child keeps the loose direct admission. */
  comboContextDegraded?: boolean;
  /** A union combo admitted this image-bearing child through a dispatchable vision plan. */
  comboRequiresVisionPlan?: boolean;
  /** The union combo exhausted its image-serving targets and selected omission. */
  comboOmitImages?: boolean;
  /**
   * The request-start Vision Sidecar settings the combo admitted this request under. Vision
   * planning reads `settings` instead of the live `visionSidecar`, so an edit made while the
   * request is in flight applies to the next request. Credentials still resolve from live config.
   */
  comboVisionSidecar?: { settings: OcxVisionSidecarConfig | undefined };
  /**
   * Set by the combo loop for each child. A child logs into its own context, which the combo
   * copies once when the child commits, and the bridge reports usage after that, at the terminal
   * frame. The transport calls this when it binds that usage on the child's context, so the combo
   * can carry the binding to the context that writes the row.
   */
  onBridgeUsageBound?: () => void;
  /** A web-search deadline has been recorded on the child before its failure is emitted. */
  onWebSearchLocalFailure?: () => void;
  onHostedWebSearchStream?: () => void;
  /** Child-owned prepaid initial send; capacity remains charged until dispatch or unsent release. */
  comboInitialSend?: { permit: SingleUseDispatchPermit; producerOwned?: boolean };
  /** Exact externally booked combo hop, used for its child's spend preflight and send reports. */
  comboDispatchPermit?: SingleUseDispatchPermit;
  /** Internal handoff: this combo was selected by shadow-call interception. */
  shadowCallIntercepted?: boolean;
  /** Internal handoff: the memory phase this turn belongs to, so combo children keep its routing. */
  memoryModelPhase?: "extract" | "consolidation";
  compactionRoutingOverride?: CompactionRoutingOverride | null;
  /** Internal handoff: the hard-lock fallback rewrote this turn; the log shows `sourceModel`. */
  mainHardLockFallbackOverride?: MainHardLockFallbackOverride | null;
  /** Internal combo handoff for one parent-validated continuation snapshot. */
  comboReplaySnapshot?: {
    sourceBody: unknown;
    previousResponseInputExpanded: boolean;
    providerContinuation: OcxProviderContinuationState | undefined;
    recoveredPlaintext: boolean;
  };
  /** Internal combo handoff: allow a later same-provider model after a reset-derived 429/402. */
  deferCodexResetDerivedCooldown?: boolean;
  /** 030-owned handoff when a child consumed the original failure under bounds. */
  onConsumedComboFailure?: (failure: ConsumedComboFailure) => void;
  /** A stored Pool credential was refreshed and its one allowed same-account replay was sent. */
  onStoredPool401ReplayDispatched?: () => void;
  /** Caller-owned for Chat/Claude replay; omitted only at genuine Responses ingress. */
  translatorBudget?: TranslatorBudget;
  /**
   * Transient sends already spent by this logical request. Combo children inherit the parent's
   * holder through the options spread, so a fan-out shares one allowance instead of taking a
   * fresh one per target (#4546).
   */
  sendBudget?: TransientSendBudget;
  /**
   * Terminal vision-describe marker (roadmap 180): true when the inbound
   * request IS the vision sidecar's own loopback describe call. The plan site
   * then STRIPS images instead of planning another describe — a depth cap of 1
   * that holds under predicate drift and combo re-resolution. The Chat surface
   * detects the raw `x-opencodex-vision-describe` header before its bridge
   * rebuilds headers and carries the fact through this flag.
   */
  visionDescribeTerminal?: boolean;
  /**
   * Terminal advisor marker: true when the inbound request IS the advisor sidecar's own loopback
   * consultation. The advisor planner then never plans a consultation — a depth cap of 1 that
   * keeps Worker → Advisor → Advisor recursion impossible (same structure as
   * {@linkcode visionDescribeTerminal}). The Chat surface validates the capability and registered
   * policy before its bridge rebuilds headers and carries the fact through this flag.
   */
  advisorInternal?: boolean;
  /** A local Chat helper authenticated through its registered process capability. */
  internalSidecarCall?: boolean;
  /**
   * Set only by the Chat and Messages ingresses when `protocols.rollout.directEncoders` is on and
   * the settled route is one non-Responses target. Adapter delivery then encodes the adapter
   * events straight into the client's wire and returns a response marked with `markClientWire`.
   * Passthrough, run-turn adapters, combo children and compaction turns ignore it and keep
   * returning a Responses body, which the ingress converts as before.
   */
  clientEncoder?: ClientEncoderOption;
  /** Chat ingress raw-channel delivery preference; never an upstream generation option. */
  chatRawReasoningVisible?: boolean;
  /** Value-free fact retained before Chat instruction content is projected to text. */
  chatInstructionImage?: boolean;
  /** Original Responses instruction image, retained across preprocessing and combo replay. */
  responsesInstructionImage?: boolean;
  /** File-backed Responses image retained before parsing and replay. */
  responsesFileImage?: boolean;
  /** Set only by the Chat or Messages ingress on an eligible Antigravity route; see {@link DirectRequestOption}. */
  directRequest?: DirectRequestOption;
}

/** The internal Responses handoff for /responses/compact keeps the endpoint's global budgets. */
export function responsesTimeoutProvider(options: HandleResponsesOptions, provider: OcxProviderConfig): OcxProviderConfig | undefined {
  return options.compactionRecoveryKind === "compaction-v1" ? undefined : provider;
}

/** Values shared by the call, not a bag of mutable pipeline state. */
export interface ResponsesRequestContext {
  req: Request;
  config: OcxConfig;
  logCtx: RequestLogContext;
  options: HandleResponsesOptions & { translatorBudget: TranslatorBudget };
}

/** Admission leases remain owned by the outer finally until explicitly transferred. */
export interface ResponsesAdmissionState {
  pendingHostAdmissionLease: UpstreamHostAdmissionLease | null;
  authCtx: CodexAuthContext;
}

export interface PassthroughAdmissionState {
  lease: UpstreamHostAdmissionLease | null;
}

/** Recursive combo children enter the same ingress without a runtime import cycle. */
export interface ResponsesDispatchers {
  handleResponses(req: Request, config: OcxConfig, logCtx: RequestLogContext, options?: HandleResponsesOptions): Promise<Response>;
  handleComboResponses(req: Request, body: unknown, comboId: string, config: OcxConfig, logCtx: RequestLogContext, options: HandleResponsesOptions & { translatorBudget: TranslatorBudget }): Promise<Response>;
}
