Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
138 KB
Raw Blame
import { randomUUID, timingSafeEqual } from "node:crypto";
import { createReadStream, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
import { dirname } from "node:path";

import { SESSION_UPLOAD_BUDGET, SESSION_UPLOAD_ENDPOINT_PATH, sessionUploadTimeoutMs, type SessionUploadBudget } from "./session-upload-budget.js";
import { externalFetch } from "./server-fetch.js";
import type { OmniRushGatewayCredentials } from "./types.js";
import type { TraceCapabilities, UploadRequestOptions } from "./session-uploader.js";
import {
  SUBAGENT_FALLBACK_EFFORT_HEADER,
  SUBAGENT_FALLBACK_MODEL_HEADER,
  SUBAGENT_ROOT_SESSION_HEADER,
  PARENT_SESSION_HEADER,
} from "./omnirush-swarm.js";
import { builtinOmniRushModelCatalog, omnirushModelWantsReasoningSummary } from "./omnirush-model-catalog.js";
import { RejectedAttachments, isRejectedAttachmentError, type Attachment } from "./rejected-attachments.js";
import { gatewayUrlAllowed, RELEASE_GATEWAY_ERROR } from "./release-guard.js";
import { BOX_HEADER, MODEL_NOT_IN_MODE, notInModeMessage, projectMode } from "./model-modes/model-modes.mjs";
import { MODE_NOT_BOUND, MODEL_NOT_BOUND, REFUSED_HEADER, SESSION_BIND_UNCONFIRMED, STRICT_SESSION_HEADER, SESSION_BINDING_CONFLICT, SESSION_MODEL_USED, VERIFICATION_REQUIRED, sessionBinder, strictSessions, type StrictSessions } from "./model-modes/strict-sessions.mjs";
import { ClaudeDeviceAccess, type ClaudeAuthorization, type ClaudeDeviceRequest } from "./claude-code/access.js";
import { stockMode } from "./stock-mode/stock-mode.mjs";
import { WORK_PATH } from "./work/work.js";

/** A main chat's request on another model than the one it started on (one model per chat). */
const SESSION_MODEL_FIXED = "session_model_fixed";
/** The gateway's retryable strict-session refusal (503, Retry-After), and how often the same request is sent again. */
const STRICT_UNAVAILABLE = "strict_session_unavailable";
const STRICT_RETRIES = 3;
/** An unknown strict switch: capabilities asked again at most this often, each wait at most this long. */
const STRICT_ASK_MS = 2_000;
const STRICT_ASK_WAIT_MS = 5_000;
/** A chat's title request (opencode-plugins/omnirush-title-recovery.ts marks it) and the chat's own model. */
const TITLE_HEADER = "x-omnirush-title";
const CHAT_MODEL_HEADER = "x-omnirush-chat-model";
/** A refused attachment is left out and the model request sent again, at most this often per request. */
const MAX_ATTACHMENT_RETRIES = 2;
const MAX_ATTACHMENT_ERROR_BYTES = 256 * 1024;

const TRACE_CAPABILITY_TTL_MS = 5 * 60_000;
/** A failed capabilities check is not asked again sooner than this (the uploader keeps what it knew meanwhile). */
const TRACE_CAPABILITY_RETRY_MS = 30_000;

/** Without the account's catalog (a standalone broker): the built-in catalog decides. */
function defaultReasoningSummaryFor(model: string): boolean {
  return omnirushModelWantsReasoningSummary(builtinOmniRushModelCatalog(), model);
}

/** A sub-agent request the gateway refused on the picked model and that was sent again on the main model. */
export type SubagentModelFallbackEvent = {
  /** The sub-agent session (x-omnirush-session-id), when the request named it. */
  sessionId: string | null;
  /** The main session above it, when the swarm plugin named it. */
  rootSessionId: string | null;
  /** The engine message id of the prompt (x-omnirush-task-id). */
  messageId: string | null;
  requested: string;
  used: string;
  effort: string | null;
  /** The gateway's error code, or `http_<status>` without one. */
  reason: string;
  status: number;
  /** Whether the main model answered. */
  ok: boolean;
  clientRequestId?: string;
  at: number;
};

type BrokerOptions = {
  /** Every model response forwarded for a chat (the 2.x engine's quota wrap, engine-v2-budget-wrap.ts). */
  onModelResponse?: (sessionId: string, headers: Headers) => void;
  /** Whether a chat's compaction is an accepted wrap: the gateway then holds it as the wrap. */
  contextWrap?: (sessionId: string) => boolean;
  credentials?: OmniRushGatewayCredentials;
  engineToken?: string;
  /** Durable model pins; production supplies the runtime-local state file. */
  sessionModelsFile?: string;
  fetch?: typeof externalFetch;
  /** Electron's file-aware transport. Standalone runtimes use the bounded Node stream fallback. */
  uploadFile?: (url: string, init: {
    method: "POST";
    headers: Record<string, string>;
    path: string;
    size: number;
    signal?: AbortSignal;
  }) => Promise<Response>;
  log?: (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
  /** uploadSession()'s deadline parameters; SESSION_UPLOAD_BUDGET unless a test shrinks it. */
  sessionUploadBudget?: SessionUploadBudget;
  /** Hears every sub-agent request moved to the main model (see subagentFallback). */
  onSubagentFallback?: (event: SubagentModelFallbackEvent) => void;
  /**
   * A chat's title request once answered: the trace record ({ schema, kind: "title", route, model, status,
   * request, text, completed }), the request as the engine sent it and the title as the model wrote it.
   */
  onModelRequest?: (sessionId: string, data: Record<string, unknown>) => void;
  /**
   * Whether a catalog model may run in a box (sandbox) chat or a native one
   * (model-modes/). False: the request gets a 400 model_not_in_mode here and
   * is never sent. Unset: every model goes to the gateway, which judges.
   */
  modelInMode?: (model: string, box: boolean) => boolean | Promise<boolean>;
  /**
   * Whether a chat on `bound` may go on with `asked`: two catalog models of
   * one provider (the catalog's switch_group, model-modes/strict-sessions.mjs).
   * Unset: only the same model.
   */
  switchable?: (bound: string, asked: string) => boolean | Promise<boolean>;
  /** The pause before a busy picked model is tried once more; tests shrink it. */
  subagentRetryDelayMs?: number;
  /** Whether a picked sub-agent model is in its refusal cooldown (sent straight to the main model). */
  subagentModelRefused?: (model: string) => boolean;
  /**
   * Whether a Responses request for this model asks for reasoning summaries
   * (the account's catalog decides; the built-in catalog when unset).
   */
  reasoningSummaryFor?: (model: string) => boolean | Promise<boolean>;
  /** Hears the gateway's mandatory-update signals (see GatewayUpdateSignal). */
  onUpdateSignal?: (signal: GatewayUpdateSignal) => void;
  /** A chat's box pin ({ box, revision }, box/service.ts chatPin): the revision a strict-session bind names. */
  chatPin?: (sessionId: string) => { box: boolean; revision: string | null; capturePolicy?: string } | null;
  /** The capture policy the server's binding stored for a chat, when it is not the pinned one: its pin and uploads follow it. */
  onCapturePolicy?: (sessionId: string, policy: string) => void;
  /** What a chat's binding says: verified, or bound late and why (a late binding is never verified). */
  onBinding?: (sessionId: string, binding: { verified: boolean; lateReason?: string }) => void;
  /**
   * Strict sessions (enforce, or the switch not known yet): a chat's uploads are held from its first model request
   * until its binding is confirmed; `seq` is this broker's order of the calls for the chat.
   */
  onUploadHold?: (sessionId: string, state: "pending" | "refused" | "confirmed", seq: number) => void;
  /** The last strict_sessions answer per server, kept on disk: it stands while capabilities cannot be fetched. */
  strictStateFile?: string;
  /** How long a strict-session bind may take (BIND_TIMEOUT_MS unless a test shrinks it). */
  bindTimeoutMs?: number;
  /**
   * The desktop app's version: every request to omnirush.ai then names it in
   * `X-OmniRush-Client: gui/<version>`, so the backend knows an updated app
   * from its first call. Unset (a standalone server) sends no header.
   */
  clientVersion?: string;
};

export const CLIENT_HEADER = "X-OmniRush-Client";

/** `gui/<version>` for a plain version string, or null. */
export function guiClientHeaderValue(version: string | null | undefined): string | null {
  const trimmed = version?.trim().replace(/^v/i, "") ?? "";
  return /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/.test(trimmed) ? `gui/${trimmed}` : null;
}

/** `init` with the client header added; every other header and option is kept. */
function withClientHeader(init: RequestInit | undefined, value: string): RequestInit {
  const headers = new Headers(init?.headers);
  headers.set(CLIENT_HEADER, value);
  return { ...init, headers };
}

/**
 * omnirush.ai asking this app to update: before the deadline every gateway
 * answer carries `x-omnirush-update-required: <minimum>; deadline=<iso>`;
 * after it, model requests from an outdated app get HTTP 426
 * `update_required`. Session uploads, project archives, sign-in, refresh and
 * the profile are never refused, so nothing here stops them.
 */
export type GatewayUpdateSignal =
  | { kind: "header"; value: string }
  | { kind: "rejection"; message: string | null };

export const UPDATE_REQUIRED_HEADER = "x-omnirush-update-required";
export const UPDATE_REQUIRED_CODE = "update_required";

/**
 * Upstream model streams have been observed to end mid-response (the proxy
 * closes the connection while a function call is still streaming). Without a
 * terminal event the engine keeps the turn open forever and the UI shows
 * nothing. The guard appends a synthetic Responses-API error event when the
 * upstream closes early or stalls, so the turn fails visibly and can be retried.
 *
 * Terminal is decided per SSE event, on its data: a Responses
 * `response.completed`, `response.incomplete` or `response.failed`, the bare
 * `data: [DONE]` sentinel (every Muse stream ends with one), or an error
 * frame. Comment lines such as `: keepalive` carry no data and are never
 * terminal.
 */
/** The uploader's "every held chat" (a strict switch known not to enforce releases them all). */
export const ALL_HELD_CHATS = "*";

/** How much of an answer's end is kept to tell whether it ran to its normal end (strict switch unknown). */
const STRICT_TAIL_CHARS = 64 * 1024;

/** Whether an answer ran to its normal end: no error or refusal event, and a completed event (or a JSON body). */
export function answerCompleted(tail: string, contentType: string): boolean {
  if (/"type"\s*:\s*"(?:error|response\.failed|response\.incomplete)"/.test(tail) || /^event:\s*error\b/m.test(tail)) return false;
  if (!contentType.includes("event-stream")) return tail.trim().length > 0;
  return /"type"\s*:\s*"(?:response\.completed|response\.done|message_stop)"|^data:\s*\[DONE\]/m.test(tail);
}

/**
 * The text a model reply carries, as the model wrote it: the Responses API's
 * output_text deltas (else the completed response's output text), chat
 * completions' content deltas, or a plain JSON reply's. Null when none.
 */
export function replyText(raw: string, contentType: string): string | null {
  const fromResponse = (r: any): string | null => {
    if (typeof r?.output_text === "string") return r.output_text;
    const parts = (Array.isArray(r?.output) ? r.output : []).flatMap((item: any) => (Array.isArray(item?.content) ? item.content : []));
    const joined = parts.filter((p: any) => typeof p?.text === "string").map((p: any) => p.text).join("");
    if (joined) return joined;
    const content = r?.choices?.[0]?.message?.content;
    return typeof content === "string" ? content : null;
  };
  if (!contentType.includes("event-stream")) {
    try { return fromResponse(JSON.parse(raw)); } catch { return null; }
  }
  let deltas: string | null = null;
  let completed: string | null = null;
  for (const line of raw.split(/\r?\n/)) {
    if (!line.startsWith("data:")) continue;
    let event: any;
    try { event = JSON.parse(line.slice(5).trim()); } catch { continue; }
    const chat = event?.choices?.[0]?.delta?.content;
    if (event?.type === "response.output_text.delta" && typeof event.delta === "string") deltas = (deltas ?? "") + event.delta;
    else if (typeof chat === "string") deltas = (deltas ?? "") + chat;
    else if ((event?.type === "response.completed" || event?.type === "response.done") && event.response) completed = fromResponse(event.response);
  }
  return deltas ?? completed;
}

/** A title reply is a few words; one past this is not kept whole. */
const MAX_TITLE_REPLY_BYTES = 1024 * 1024;

const TERMINAL_RESPONSE_EVENTS = new Set(["response.completed", "response.incomplete", "response.failed"]);
const TERMINAL_OR_ERROR_MARKER = /"(?:response\.(?:completed|incomplete|failed)|error)"/;
/** An event larger than this passes through unread; the marker scan below then decides terminality. */
const MAX_EVENT_BYTES = 16 * 1024 * 1024;
const TERMINAL_EVENT_PATTERN = /"type":"(?:response\.(?:completed|failed|incomplete)|error)"|(?:^|[\r\n])data: ?\[DONE\][\r\n]/;
export const STREAM_IDLE_TIMEOUT_MS = 180_000;
export type StreamInterruption = "truncated" | "idle";

const LF = 0x0a;
const CR = 0x0d;

function interruptedEvent(reason: StreamInterruption, requestId?: string): Uint8Array {
  const message = reason === "idle"
    ? "omnirush.ai: the model stream stalled and was closed. Retry the request."
    : "omnirush.ai: the model stream ended before the response completed. Retry the request.";
  const payload = {
    type: "error",
    sequence_number: -1,
    error: { type: "server_error", code: "upstream_stream_interrupted", message, ...(requestId ? { client_request_id: requestId } : {}) },
  };
  return new TextEncoder().encode(`event: error\ndata: ${JSON.stringify(payload)}\n\n`);
}

const UNAVAILABLE_COPY = "this model is temporarily unavailable. Try again in a minute, or pick another model.";
const BUSY_COPY = "this model is busy right now. Try again in a moment.";
const STALLED_COPY = "the model stopped responding before it finished. Retry the request, or pick a lower effort.";
const SETUP_COPY = "the model route is being set up. Try again later.";

/**
 * What the user reads for an omnirush.ai gateway error: the backend's own
 * codes, and the relay codes it passes through (mid-stream as
 * `upstream_<code>`). Kept in step with the console's chat copy.
 */
const GATEWAY_ERROR_COPY: Record<string, string> = {
  model_unavailable: "this model is not available on your account right now. Pick another model.",
  model_not_allowed: "this model is not available to your account. Pick another model.",
  model_not_found: "this model is not available right now. Pick another model.",
  model_input_not_supported: "this model cannot read that attachment. Remove the image or PDF, or pick another model.",
  model_concurrency_limited: "too many answers are already running on this model. Wait for one to finish, then try again.",
  model_request_too_large: "this request is too large to send. Remove an attachment or start a new session.",
  reasoning_effort_not_allowed: "this model does not offer the selected effort. Pick another effort.",
  unsupported_model_endpoint: "this model cannot run this kind of request. Pick another model.",
  daily_grant_exhausted: "you have used today's model allowance. It refills at 00:00 UTC.",
  grant_check_unavailable: "your model allowance could not be checked. Try again in a moment.",
  account_inactive: "model access is paused for this account. Open your omnirush.ai dashboard to see why.",
  consent_required: "accept the omnirush.ai data terms on your dashboard, then try again.",
  consent_version_outdated: "the omnirush.ai data terms were updated. Accept the new version on your dashboard, then try again.",
  internal_proxy_unavailable: "the model service did not respond. Try again in a moment.",
  internal_proxy_not_configured: SETUP_COPY,
  internal_proxy_ca_missing: SETUP_COPY,
  muse_relay_not_configured: UNAVAILABLE_COPY,
  model_upstream_auth_failed: UNAVAILABLE_COPY,
  model_upstream_misconfigured: UNAVAILABLE_COPY,
  model_upstream_unavailable: "the model service could not be reached. Try again in a moment.",
  stream_interrupted: "the model stream ended before the response completed. Retry the request.",
  idle_timeout: STALLED_COPY,
  first_byte_timeout: STALLED_COPY,
  request_timeout: STALLED_COPY,
  provider_error: "the model provider could not complete this request.",
  provider_unavailable: UNAVAILABLE_COPY,
  provider_auth_error: UNAVAILABLE_COPY,
  capacity_unavailable: UNAVAILABLE_COPY,
  circuit_open: UNAVAILABLE_COPY,
  maintenance: UNAVAILABLE_COPY,
  draining: UNAVAILABLE_COPY,
  auth_unavailable: UNAVAILABLE_COPY,
  token_capacity: BUSY_COPY,
  gateway_overload: BUSY_COPY,
  queue_timeout: BUSY_COPY,
  omni_queue_timeout: "every model seat is taken right now, and this turn waited in line too long. Send your message again; your place in line is kept for a few minutes.",
  provider_rate_limited: BUSY_COPY,
  voice_unavailable: "voice input is not available on this account yet.",
  transcription_unavailable: "the transcription service did not answer. Try again in a moment.",
  audio_unreadable: "the recording could not be read. Try again.",
  update_required: "this version of OmniRush.ai is no longer supported. Update the app to keep using models; your sessions are kept.",
  // A model outside the project's mode (model-modes/): the gateway's refusal, or the broker's own before sending.
  [MODEL_NOT_IN_MODE]: notInModeMessage().replace(/^T/, "t"),
  [SESSION_MODEL_FIXED]: "this chat keeps the model it started on. Start a new chat to use another model.",
  // Strict sessions (model-modes/strict-sessions.mjs): the gateway holds a bound chat to its model and mode.
  [MODEL_NOT_BOUND]: "this chat keeps the model it started on. Start a new chat to use another model.",
  [MODE_NOT_BOUND]: "this chat keeps the project mode it started in. Start a new chat to change it.",
  [SESSION_MODEL_USED]: "this chat already ran on another model. Start a new chat to use this one.",
};
/** Refusals whose own message is shown as it is (the server's or the broker's words). */
const OWN_WORDS = new Set([UPDATE_REQUIRED_CODE, MODEL_NOT_IN_MODE, SESSION_MODEL_FIXED, MODEL_NOT_BOUND, MODE_NOT_BOUND, SESSION_BINDING_CONFLICT, SESSION_MODEL_USED, VERIFICATION_REQUIRED, SESSION_BIND_UNCONFIRMED]);

/** Readable copy for a gateway error code, or null for a code it does not know. */
export function gatewayErrorMessage(code: string, detail?: string | null): string | null {
  const copy = GATEWAY_ERROR_COPY[code] ?? GATEWAY_ERROR_COPY[code.replace(/^upstream_/, "")];
  if (!copy) return null;
  // A provider error names what it refused ("Upstream returned an error: <why>").
  const why = code.endsWith("provider_error")
    ? detail?.replace(/^\s*upstream returned an error:?/i, "").trim().slice(0, 300)
    : "";
  return why ? `omnirush.ai: ${copy} (${why})` : `omnirush.ai: ${copy}`;
}

/** The user's clock for a grant reset; tests pin it, the app uses the system's. */
export type GrantClock = { now?: number; timeZone?: string; hourCycle?: Intl.DateTimeFormatOptions["hourCycle"] };

/**
 * What a `daily_grant_exhausted` refusal ran out of, from the gateway's
 * `x-omnirush-grant-scope` ('day' | 'week' | 'empty') and
 * `x-omnirush-grant-resets-at` (UTC ISO 8601), with the reset on the user's
 * clock: "Today's tokens are used up. They refill at 5:30 AM (in 3 h)."
 * Null without a known scope (an older gateway): the caller keeps its
 * general copy.
 */
export function grantExhaustedCopy(headers: Headers, consoleUrl: string | null, clock: GrantClock = {}): string | null {
  const scope = headers.get("x-omnirush-grant-scope")?.trim().toLowerCase();
  if (scope === "empty") {
    return `You have no tokens left. Link Discord or connect GitHub in the console to earn tokens every day${consoleUrl ? `: ${consoleUrl}` : "."}`;
  }
  if (scope !== "day" && scope !== "week") return null;
  const at = Date.parse(headers.get("x-omnirush-grant-resets-at") ?? "");
  const when = Number.isFinite(at) ? localReset(at, scope, clock) : scope === "day" ? "00:00 UTC" : "Monday 00:00 UTC";
  return scope === "day" ? `Today's tokens are used up. They refill at ${when}.` : `This week's cap is reached. It resets ${when}.`;
}

/** "5:30 AM (in 3 h)", or "Monday 5:30 AM (in 4 days)" for the week: English words, the user's time zone and 12/24-hour style. */
function localReset(at: number, scope: "day" | "week", clock: GrantClock): string {
  const { timeZone } = clock;
  const hourCycle = clock.hourCycle ?? new Intl.DateTimeFormat(undefined, { hour: "numeric" }).resolvedOptions().hourCycle;
  const time = new Intl.DateTimeFormat("en-US", { hour: "numeric", minute: "2-digit", hourCycle, timeZone }).format(at);
  const local = scope === "week" ? `${new Intl.DateTimeFormat("en-US", { weekday: "long", timeZone }).format(at)} ${time}` : time;
  const left = at - (clock.now ?? Date.now());
  if (left <= 0) return local;
  const minutes = Math.max(1, Math.round(left / 60_000));
  const hours = Math.round(minutes / 60);
  const relative = minutes < 60 ? `${minutes} min` : hours < 48 ? `${hours} h` : `${Math.round(hours / 24)} days`;
  return `${local} (in ${relative})`;
}

function stringField(value: unknown): string | null {
  return typeof value === "string" && value.trim() ? value.trim() : null;
}

/**
 * omnirush.ai's stable error object, `error.omnirush`
 * (`{code, scope?, resets_at?, retry, retry_after?}`), as a field to spread
 * into an error the broker rewrites: passed on exactly as it came, so the
 * app can key on it. Empty when the gateway sent none (an older backend,
 * or an error relayed from upstream).
 */
function omnirushField(error: Record<string, unknown> | null): { omnirush?: Record<string, unknown> } {
  return error && isRecord(error.omnirush) ? { omnirush: error.omnirush } : {};
}

/** The gateway says the same request cannot succeed if sent again (`error.omnirush.retry === false`). */
function retryRefused(error: Record<string, unknown> | null): boolean {
  return Boolean(error && isRecord(error.omnirush) && error.omnirush.retry === false);
}

/**
 * What the engine (1.18.32, session/retry.ts) retries an API error on: any
 * of these in its message or response body, a 5xx, or a status the AI SDK
 * marks retryable (408, 409, 429). It never reads `x-should-retry`.
 */
const ENGINE_RETRY_PATTERNS = [
  /429|500|502|503|504|524/i,
  /rate increased too quickly|rate limit|rate-limit|rate_limit|too many requests/i,
  /overloaded|service unavailable|service_unavailable|service-unavailable|internal error|internal_error|internal server error|server error|server_error|server-error|provider returned error|provider_returned_error|provider-returned-error/i,
  /terminated|fetch failed|failed to fetch|network[-_\s]error|upstream connect|connection error|connection refused|connection lost|socket connection was closed|socket hang up|reset before headers|getaddrinfo|enotfound|eai_again|econnrefused|econnreset|etimedout/i,
  /^timeout$|\b(?:request|response|connection|network|stream|read) (?:timeout|timed out|time out)\b/i,
  /try your request again|retry your request|resource exhausted|resource_exhausted/i,
  /\btry again (?:later|in\b)|\b(?:currently|temporarily) at capacity\b/i,
];
const ENGINE_RETRY_STATUSES = new Set([408, 409, 429]);
/** The status a final refusal reaches the engine with when its own would be retried; the gateway's is kept in this header. */
const FINAL_REFUSAL_STATUS = 403;
const GATEWAY_STATUS_HEADER = "x-omnirush-gateway-status";

function engineWouldRetry(text: string): boolean {
  return ENGINE_RETRY_PATTERNS.some((pattern) => pattern.test(text));
}

/**
 * A final refusal's error body the engine shows once: `error.omnirush` is
 * passed on as it came unless one of its timing fields (`retry_after`,
 * `resets_at`, both also in the response headers) happens to spell a
 * pattern the engine retries on (`retry_after: 15000` holds "500"); only
 * that field is then left out, so `code`, `scope` and `retry` always arrive.
 */
function finalErrorBody(error: Record<string, unknown>): string {
  const body = JSON.stringify({ error });
  if (!isRecord(error.omnirush) || !engineWouldRetry(body)) return body;
  return JSON.stringify({ error: { ...error, omnirush: withoutRetryWords(error.omnirush) } });
}

/** `error.omnirush` without a timing field that spells one of the engine's retry patterns. */
function withoutRetryWords(omnirush: Record<string, unknown>): Record<string, unknown> {
  const kept = { ...omnirush };
  for (const field of ["retry_after", "resets_at"]) {
    if (field in kept && engineWouldRetry(JSON.stringify(kept[field]))) delete kept[field];
  }
  return kept;
}

/**
 * What a stream `error` frame carries that the engine would drop: its AI
 * SDK keeps only an error's type, code, message and param, so the gateway's
 * `detail` and `error.omnirush` ride in `param` (as JSON) when the frame has
 * none. Null when there is nothing to carry or `param` is taken.
 */
function carriedParam(payload: Record<string, unknown>, nested: Record<string, unknown> | null): string | null {
  if (stringField(nested ? nested.param : payload.param)) return null;
  return carriedFields(payload, nested, {});
}

function carriedFields(payload: Record<string, unknown>, nested: Record<string, unknown> | null, extra: Record<string, unknown>): string | null {
  const detail = stringField(payload.detail);
  const omnirush = nested && isRecord(nested.omnirush) ? nested.omnirush : null;
  if (!detail && !omnirush && Object.keys(extra).length === 0) return null;
  const final = omnirush?.retry === false;
  return JSON.stringify({ ...extra, ...(detail ? { detail } : {}), ...(omnirush ? { omnirush: final ? withoutRetryWords(omnirush) : omnirush } : {}) });
}

/**
 * Stream refusals the same request meets again: the request policy cutting
 * a stream, a capped session, a spent allowance, the model's own safety
 * check. Inside a stream (after any output) the engine takes an error frame
 * for a passing fault and sends the request again, up to five times.
 */
const FINAL_STREAM_CODES = new Set(["request_policy_refused", "session_quality_cap", "daily_grant_exhausted", "cyber_policy", MODEL_NOT_IN_MODE, MODEL_NOT_BOUND, MODE_NOT_BOUND, SESSION_MODEL_USED]);

/**
 * A final refusal inside a stream as the frame the engine shows once and
 * never retries (`invalid_prompt`, like the queue timeout): its message as
 * the user would have read it, and its own code, `detail` and
 * `error.omnirush` in `param` (JSON) for the app.
 */
function finalStreamEvent(payload: Record<string, unknown>, nested: Record<string, unknown> | null, code: string | null, message: string): Uint8Array {
  const param = stringField(nested ? nested.param : payload.param);
  const sequence = payload.sequence_number;
  const frame = {
    type: "error",
    sequence_number: typeof sequence === "number" && Number.isFinite(sequence) ? sequence : -1,
    error: {
      type: "invalid_request_error",
      code: "invalid_prompt",
      message,
      param: carriedFields(payload, nested, { code: code ?? "omnirush_refused", ...(param ? { param } : {}) }),
      ...(nested && isRecord(nested.omnirush) ? { omnirush: withoutRetryWords(nested.omnirush) } : {}),
    },
  };
  return new TextEncoder().encode(`event: error\ndata: ${JSON.stringify(frame)}\n\n`);
}

/**
 * An error frame the engine can show: the gateway's
 * `{type:"error",sequence_number,error:{...}}`, OpenAI's flat
 * `{type:"error",sequence_number,code,message}`, or a relay `event: error` /
 * `{"error":{...}}` that reached the broker unrewritten. A frame the engine's
 * AI SDK already parses and that has no readable copy passes unchanged;
 * anything else becomes the nested shape with the copy. The SDK drops an
 * error chunk without a numeric sequence_number (or with a non-string error
 * type, code or message), which would end the turn silently, and the engine
 * shows only a nested error's message.
 */
/**
 * Codes that end the turn instead of being retried by the engine. A turn the
 * gateway's omni queue held past its maximum wait (`omni_queue_timeout`,
 * sent inside the committed stream) would otherwise be retried up to five
 * times by the engine, each retry waiting in line again: the chat shows
 * "running" for many minutes with nothing happening. The engine retries any
 * stream error except a few codes; `invalid_prompt` is one it shows as it is
 * and never retries (provider/error.ts, session/retry.ts), as long as the
 * message names nothing its retry patterns match.
 */
const TURN_ENDING_STREAM_CODES = new Set(["omni_queue_timeout"]);
const QUEUE_TIMEOUT_COPY = "omnirush.ai: every model seat is taken right now, and this turn waited in line too long. Send your message again; your place in line is kept for a few minutes.";

function turnEndingEvent(code: string, sequence: unknown, omnirush: { omnirush?: Record<string, unknown> }): Uint8Array {
  const frame = {
    type: "error",
    sequence_number: typeof sequence === "number" && Number.isFinite(sequence) ? sequence : -1,
    error: { type: "invalid_request_error", code: "invalid_prompt", message: QUEUE_TIMEOUT_COPY, param: code, ...omnirush },
  };
  return new TextEncoder().encode(`event: error\ndata: ${JSON.stringify(frame)}\n\n`);
}

function errorEvent(block: Uint8Array, payload: Record<string, unknown>): Uint8Array {
  const nested = isRecord(payload.error) ? payload.error : null;
  const code = stringField(nested ? nested.code : payload.code);
  const baseCode = code?.replace(/^upstream_/, "") ?? null;
  const omnirush = omnirushField(nested);
  if (baseCode && TURN_ENDING_STREAM_CODES.has(baseCode)) return turnEndingEvent(baseCode, payload.sequence_number, omnirush);
  const original = stringField(nested ? nested.message : payload.message);
  // model_not_in_mode names the kind of project the model runs in: the gateway's words.
  const readable = baseCode === MODEL_NOT_IN_MODE && original ? original : code ? gatewayErrorMessage(code, original) : null;
  const detail = stringField(payload.detail);
  if (retryRefused(nested) || (detail && FINAL_STREAM_CODES.has(detail)) || (baseCode && FINAL_STREAM_CODES.has(baseCode))) {
    const named = detail ?? baseCode ?? "omnirush_refused";
    return finalStreamEvent(payload, nested, code, readable ?? original ?? `omnirush.ai could not complete the model request (${named}).`);
  }
  const sequence = payload.sequence_number;
  const parsed = payload.type === "error"
    && typeof sequence === "number"
    && (nested
      ? typeof nested.type === "string" && typeof nested.code === "string" && typeof nested.message === "string"
      : typeof payload.message === "string");
  const carried = carriedParam(payload, nested);
  if (parsed && !readable && !carried) return block;
  const param = stringField(nested ? nested.param : payload.param) ?? carried;
  const frame = {
    type: "error",
    sequence_number: typeof sequence === "number" && Number.isFinite(sequence) ? sequence : -1,
    error: {
      type: stringField(nested?.type) ?? "server_error",
      code: code ?? "upstream_error",
      message: readable ?? original ?? `omnirush.ai: the model request failed (${code ?? "upstream_error"}).`,
      ...(param ? { param } : {}),
      ...omnirush,
    },
  };
  return new TextEncoder().encode(`event: error\ndata: ${JSON.stringify(frame)}\n\n`);
}

function sseEventFields(block: Uint8Array): { name: string | null; data: string | null } {
  let name: string | null = null;
  const data: string[] = [];
  for (const line of new TextDecoder().decode(block).split(/\r\n|\r|\n/)) {
    if (!line || line.startsWith(":")) continue;
    const colon = line.indexOf(":");
    const field = colon < 0 ? line : line.slice(0, colon);
    const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
    if (field === "event") name = value;
    else if (field === "data") data.push(value);
  }
  return { name, data: data.length > 0 ? data.join("\n") : null };
}

/**
 * Splits an SSE byte stream into whole events, forwarding each unchanged
 * except error frames, which are normalized (errorEvent). A partial event is
 * held until its blank line arrives; the engine cannot act on it earlier.
 */
class SseEventFramer {
  terminal = false;
  private buffer = new Uint8Array(4096);
  private length = 0;
  /** Where the blank-line scan resumes, and whether that offset starts a line. */
  private scanned = 0;
  private lineStart = true;
  private unframed = false;
  private tail = "";
  private readonly decoder = new TextDecoder();

  push(chunk: Uint8Array): Uint8Array[] {
    if (this.unframed) {
      this.scanUnframed(chunk);
      return [chunk];
    }
    this.append(chunk);
    const events: Uint8Array[] = [];
    let start = 0;
    for (let end = this.nextBoundary(); end >= 0; end = this.nextBoundary()) {
      events.push(this.event(this.buffer.slice(start, end)));
      start = end;
    }
    if (start > 0) {
      this.buffer.copyWithin(0, start, this.length);
      this.length -= start;
      this.scanned -= start;
    }
    if (this.length > MAX_EVENT_BYTES) {
      const oversized = this.buffer.slice(0, this.length);
      this.length = 0;
      this.unframed = true;
      this.scanUnframed(oversized);
      events.push(oversized);
    }
    return events;
  }

  /**
   * The upstream closed: an event still missing its blank line is kept only
   * when the stream already ended (a final `data: [DONE]` without one);
   * otherwise it is dropped so the interruption frame stays well formed.
   */
  finish(): Uint8Array | null {
    if (this.length === 0) return null;
    const rest = this.buffer.slice(0, this.length);
    this.length = 0;
    const event = this.event(rest);
    return this.terminal ? event : null;
  }

  private append(chunk: Uint8Array): void {
    if (this.length + chunk.length > this.buffer.length) {
      const grown = new Uint8Array(Math.max(this.buffer.length * 2, this.length + chunk.length));
      grown.set(this.buffer.subarray(0, this.length));
      this.buffer = grown;
    }
    this.buffer.set(chunk, this.length);
    this.length += chunk.length;
  }

  /** The offset just past the next blank line (CRLF, LF or CR line endings), or -1. */
  private nextBoundary(): number {
    let index = this.scanned;
    while (index < this.length) {
      const byte = this.buffer[index];
      if (byte !== LF && byte !== CR) {
        this.lineStart = false;
        index += 1;
        continue;
      }
      let end = index + 1;
      if (byte === CR) {
        // CR or CRLF: the next byte decides.
        if (end === this.length) break;
        if (this.buffer[end] === LF) end += 1;
      }
      if (this.lineStart) {
        this.scanned = end;
        return end;
      }
      this.lineStart = true;
      index = end;
    }
    this.scanned = index;
    return -1;
  }

  private event(block: Uint8Array): Uint8Array {
    const { name, data } = sseEventFields(block);
    if (data === null) return block;
    if (data.trim() === "[DONE]") {
      this.terminal = true;
      return block;
    }
    // Only a terminal or error payload can hold one of these as raw JSON (a
    // quote inside a string value is escaped), so the text deltas that make
    // up most of a stream are never parsed.
    if (name !== "error" && !TERMINAL_OR_ERROR_MARKER.test(data)) return block;
    let payload: unknown;
    try {
      payload = JSON.parse(data);
    } catch {
      return block;
    }
    if (!isRecord(payload)) return block;
    const type = payload.type;
    if (typeof type === "string" && TERMINAL_RESPONSE_EVENTS.has(type)) {
      this.terminal = true;
      return block;
    }
    if (type === "error" || (type === undefined && (name === "error" || isRecord(payload.error)))) {
      this.terminal = true;
      return errorEvent(block, payload);
    }
    return block;
  }

  private scanUnframed(chunk: Uint8Array): void {
    if (this.terminal) return;
    // Test the join of the previous tail and the whole new chunk BEFORE
    // trimming, so a marker split across chunks is still seen.
    const window = this.tail + this.decoder.decode(chunk, { stream: true });
    if (TERMINAL_EVENT_PATTERN.test(window)) this.terminal = true;
    this.tail = window.slice(-4096);
  }
}

export function guardEventStream(
  body: ReadableStream<Uint8Array>,
  options: { idleMs?: number; requestId?: string; onInterrupted?: (reason: StreamInterruption) => void } = {},
): ReadableStream<Uint8Array> {
  const reader = body.getReader();
  const idleMs = options.idleMs ?? STREAM_IDLE_TIMEOUT_MS;
  const events = new SseEventFramer();
  const interrupt = (controller: ReadableStreamDefaultController<Uint8Array>, reason: StreamInterruption) => {
    options.onInterrupted?.(reason);
    controller.enqueue(interruptedEvent(reason, options.requestId));
    controller.close();
  };
  const read = async () => {
    let timer: ReturnType<typeof setTimeout> | undefined;
    const idle = new Promise<{ idle: true }>((resolve) => {
      timer = setTimeout(() => resolve({ idle: true }), idleMs);
      timer.unref?.();
    });
    try {
      return await Promise.race([reader.read(), idle]);
    } finally {
      if (timer) clearTimeout(timer);
    }
  };
  return new ReadableStream<Uint8Array>({
    async pull(controller) {
      // Read until at least one whole event can be forwarded: a pull that
      // enqueues nothing would not be called again.
      for (;;) {
        let result: Awaited<ReturnType<typeof read>>;
        try {
          result = await read();
        } catch {
          // The upstream connection failed mid-stream (reset, network change):
          // end with the same readable, retryable error as an early close.
          await reader.cancel().catch(() => undefined);
          interrupt(controller, "truncated");
          return;
        }
        if ("idle" in result) {
          await reader.cancel().catch(() => undefined);
          interrupt(controller, "idle");
          return;
        }
        if (result.done) {
          const rest = events.finish();
          if (!events.terminal) {
            interrupt(controller, "truncated");
            return;
          }
          if (rest) controller.enqueue(rest);
          controller.close();
          return;
        }
        const ready = events.push(result.value);
        for (const event of ready) controller.enqueue(event);
        if (ready.length > 0) return;
      }
    },
    cancel(reason) {
      return reader.cancel(reason);
    },
  });
}

/**
 * A gateway error body with readable copy for the codes the gateway and the
 * relay use (`{"detail":"<code>"}` from the gateway itself, or an
 * OpenAI-shaped `{"error":{code,message}}`), in the OpenAI shape the engine
 * reads its message from. Null leaves the body as it came. `grant` is a
 * spent grant's copy (grantExhaustedCopy), used for `daily_grant_exhausted`.
 */
function readableErrorBody(text: string, grant: string | null): { error: Record<string, unknown>; code: string; final: boolean } | null {
  let payload: unknown;
  try {
    payload = JSON.parse(text);
  } catch {
    return null;
  }
  if (!isRecord(payload)) return null;
  const nested = isRecord(payload.error) ? payload.error : null;
  const bareCode = stringField(payload.detail) ?? stringField(payload.error);
  const code = bareCode ?? stringField(nested?.code);
  if (!code) return null;
  const message = (grant && code === "daily_grant_exhausted" ? `omnirush.ai: ${grant.charAt(0).toLowerCase()}${grant.slice(1)}` : null)
    // The server names the version to install, or the kind of project the model runs in; keep its words.
    ?? (OWN_WORDS.has(code) ? stringField(nested?.message) ?? stringField(payload.message) : null)
    ?? gatewayErrorMessage(code, stringField(nested?.message))
    ?? (bareCode ? `omnirush.ai could not complete the model request (${code}).` : null);
  if (!message) return null;
  const param = stringField(nested?.param);
  return {
    error: { message, type: stringField(nested?.type) ?? "omnirush_error", code, ...(param ? { param } : {}), ...omnirushField(nested) },
    code,
    final: retryRefused(nested),
  };
}

/** Whether a JSON error body carries `error.omnirush.retry === false`. */
function errorBodyRefusesRetry(text: string): boolean {
  try {
    const payload: unknown = JSON.parse(text);
    return isRecord(payload) && retryRefused(isRecord(payload.error) ? payload.error : null);
  } catch {
    return false;
  }
}

async function readableErrorResponse(response: Response, consoleUrl: string | null): Promise<Response> {
  const text = await response.text().catch(() => "");
  const readable = readableErrorBody(text, grantExhaustedCopy(response.headers, consoleUrl));
  const headers = responseHeaders(response.headers);
  // A spent grant stays spent until its reset: the engine would otherwise
  // resend the request ten times, each after the 429's Retry-After (60 s).
  // An outdated app stays refused until it is updated. Whatever the
  // gateway marks final (`x-should-retry: false`, `error.omnirush.retry`
  // false) is never sent again either.
  const final = readable?.code === "daily_grant_exhausted" || readable?.code === UPDATE_REQUIRED_CODE || response.status === 426
    || Boolean(readable?.final) || response.headers.get("x-should-retry") === "false" || (!readable && errorBodyRefusesRetry(text));
  if (!final) {
    return new Response(readable ? JSON.stringify({ error: readable.error }) : text, { status: response.status, statusText: response.statusText, headers });
  }
  headers.set("x-should-retry", "false");
  // The engine never reads that header and retries a 429 (or 408, 409, 5xx)
  // whatever it says, after its Retry-After: a spent grant then sat as
  // "retrying in 3 h". Such a final refusal goes on as a 403, like a
  // streamed one, with the gateway's status in its own header.
  const retriedStatus = ENGINE_RETRY_STATUSES.has(response.status) || response.status >= 500;
  if (retriedStatus) headers.set(GATEWAY_STATUS_HEADER, String(response.status));
  return new Response(readable ? finalErrorBody(readable.error) : text, {
    status: retriedStatus ? FINAL_REFUSAL_STATUS : response.status,
    statusText: retriedStatus ? "Forbidden" : response.statusText,
    headers,
  });
}

/** A streamed refusal is one small error frame; anything longer is a real stream. */
const MAX_STREAMED_REFUSAL_BYTES = 64 * 1024;

/**
 * A streamed refusal as a 403 the engine shows once: the gateway refuses a
 * capped session or a Windows cut-off with HTTP 200, one `event: error`
 * frame naming its `detail`, and `x-should-retry: false`. The engine
 * retries any stream error it does not recognise (and never sees that
 * header), so the same refusal would be sent again and again. The message
 * is kept word for word: one ending on the console link keeps the app's
 * "Open console" button. Null for anything but exactly one such frame.
 */
function streamedRefusalResponse(text: string, headers: Headers): Response | null {
  const events = text.split(/\r\n\r\n|\n\n|\r\r/).filter((block) => block.trim());
  if (events.length !== 1) return null;
  const { name, data } = sseEventFields(new TextEncoder().encode(events[0]));
  if (data === null) return null;
  let payload: unknown;
  try {
    payload = JSON.parse(data);
  } catch {
    return null;
  }
  if (!isRecord(payload) || (name !== "error" && payload.type !== "error")) return null;
  const detail = stringField(payload.detail);
  if (!detail) return null;
  const nested = isRecord(payload.error) ? payload.error : null;
  const message = stringField(nested?.message) ?? stringField(payload.message)
    ?? gatewayErrorMessage(detail) ?? `omnirush.ai could not complete the model request (${detail}).`;
  const result = responseHeaders(headers);
  result.set("content-type", "application/json");
  result.set("x-should-retry", "false");
  const error = { message, type: stringField(nested?.type) ?? "invalid_request_error", code: detail, ...omnirushField(nested) };
  return new Response(finalErrorBody(error), {
    status: 403,
    headers: result,
  });
}

/**
 * A stream marked `x-should-retry: false`: the refusal as a 403
 * (streamedRefusalResponse), or the stream's bytes unchanged.
 */
async function streamedRefusalOrBody(response: Response, body: ReadableStream<Uint8Array>): Promise<Response | ReadableStream<Uint8Array>> {
  const reader = body.getReader();
  const chunks: Uint8Array[] = [];
  let total = 0;
  let done = false;
  while (total <= MAX_STREAMED_REFUSAL_BYTES) {
    const result = await reader.read();
    if (result.done) {
      done = true;
      break;
    }
    chunks.push(result.value);
    total += result.value.byteLength;
  }
  if (done) {
    const decoder = new TextDecoder();
    const text = chunks.map((chunk) => decoder.decode(chunk, { stream: true })).join("") + decoder.decode();
    const refusal = streamedRefusalResponse(text, response.headers);
    if (refusal) return refusal;
  }
  return new ReadableStream<Uint8Array>({
    start(controller) {
      for (const chunk of chunks) controller.enqueue(chunk);
      if (done) controller.close();
    },
    async pull(controller) {
      const result = await reader.read();
      if (result.done) controller.close();
      else controller.enqueue(result.value);
    },
    cancel(reason) {
      return reader.cancel(reason);
    },
  });
}

async function boundedText(response: Response, maxBytes: number): Promise<string | null> {
  if (!response.body) return "";
  const reader = response.body.getReader();
  const chunks: Uint8Array[] = [];
  let total = 0;
  try {
    while (true) {
      const result = await reader.read();
      if (result.done) break;
      total += result.value.byteLength;
      if (total > maxBytes) {
        await reader.cancel("response too large").catch(() => undefined);
        return null;
      }
      chunks.push(result.value);
    }
  } finally {
    reader.releaseLock();
  }
  const body = new Uint8Array(total);
  let offset = 0;
  for (const chunk of chunks) {
    body.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return new TextDecoder().decode(body);
}

type CredentialState = {
  gatewayUrl: string;
  accessToken: string;
  /** Spent only without a refresh owner (see OmniRushGatewayCredentials.refresh). */
  refreshToken: string;
};

/** What the refresh endpoint said about the token that was spent. */
type RefreshOutcome =
  | { kind: "rotated" }
  /** 401/403: the server retired or revoked the token. */
  | { kind: "retired" }
  /** 409 refresh_token_already_used: this very token is being rotated right now. */
  | { kind: "contended" }
  /** Anything else (5xx, malformed payload): nothing is known about the session. */
  | { kind: "unavailable" };

function normalizedGatewayUrl(value: string): string | null {
  try {
    const url = new URL(value.trim());
    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "::1"].includes(url.hostname))) {
      return null;
    }
    // A release build talks to omnirush.ai only (release-guard.ts): another address is no account.
    if (!gatewayUrlAllowed(url.toString())) {
      console.error(`[omnirush] ${RELEASE_GATEWAY_ERROR} The sign-in names another account server; sign in again.`);
      return null;
    }
    return url.toString().replace(/\/+$/, "");
  } catch {
    return null;
  }
}

function bearerToken(request: Request): string {
  const authorization = request.headers.get("authorization") ?? "";
  return authorization.startsWith("Bearer ") ? authorization.slice(7).trim() : "";
}

function clientRequestId(request: Request): string {
  const supplied = request.headers.get("x-omnirush-client-request-id")?.trim();
  return supplied && /^[A-Za-z0-9._:-]{1,128}$/.test(supplied)
    ? supplied
    : randomUUID().replaceAll("-", "");
}

function secureEqual(left: string, right: string): boolean {
  const a = Buffer.from(left);
  const b = Buffer.from(right);
  return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
}

/**
 * The Linux sandbox block of a /collect/capabilities answer: the default, the turn cap, the backends
 * allowlist (null: any), whether the sandbox is required for new chats (and what a machine that cannot
 * run it does), and whether images are fetched at start.
 */
function localBoxCapability(block: Record<string, unknown>): NonNullable<TraceCapabilities["local_box"]> {
  const backends = Array.isArray(block.backends) ? block.backends.filter((item): item is string => typeof item === "string") : null;
  const setup = isRecord(block.setup) ? block.setup : {};
  return {
    default: String(block.default ?? "off"),
    max_turn_bytes: typeof block.max_turn_bytes === "number" ? block.max_turn_bytes : null,
    backends,
    required: block.required === true,
    required_fallback: typeof block.required_fallback === "string" ? block.required_fallback : null,
    setup: { prefetch: setup.prefetch === true },
  };
}

/** The feature flags of a /collect/capabilities answer, each true only when the backend says so. */
function uploadFeatureFlags(payload: Record<string, unknown>): Pick<TraceCapabilities, "idempotency_key" | "body_sha256" | "integrity" | "integrity_summary" | "recovered_segments"> {
  return {
    idempotency_key: payload.idempotency_key === true,
    body_sha256: payload.body_sha256 === true,
    integrity: payload.integrity === true,
    integrity_summary: payload.integrity_summary === true,
    recovered_segments: payload.recovered_segments === true,
  };
}

/** Integrity reads per minute this device makes, under the route's 30 per account. */
const INTEGRITY_CALLS_PER_MINUTE = 24;

export type SessionIntegrityOptions = { summary?: boolean; turns?: number };

function refreshUrl(gatewayUrl: string): string {
  const url = new URL(gatewayUrl);
  url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "") + "/device/refresh";
  url.search = "";
  url.hash = "";
  return url.toString();
}

function upstreamUrl(gatewayUrl: string, path: string): string {
  const url = new URL(gatewayUrl);
  url.pathname = `${url.pathname.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
  url.search = "";
  url.hash = "";
  return url.toString();
}

/** `<gateway root>/<path>`: the gateway URL with its trailing `/` and `/v1` stripped, as for every omnirush.ai API route. */
function originOf(gatewayUrl: string): string {
  try { return new URL(gatewayUrl).origin; } catch { return gatewayUrl; }
}

function apiUrl(gatewayUrl: string, path: string): string {
  const url = new URL(gatewayUrl);
  url.pathname = `${url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "")}/${path}`;
  url.search = "";
  url.hash = "";
  return url.toString();
}

/** How long a finished model stream is still read after the engine stops reading it. */
const SETTLE_DRAIN_MS = 60_000;
const FINAL_EVENT = /"type":\s*"response\.completed"|event:\s*response\.completed|data:\s*\[DONE\]/;

/** Whether a model stream reached its final event; set by settleOnFinish, read when the engine goes away. */
type StreamTail = { completed: boolean; abort: () => void };

/**
 * A model stream as the engine reads it. The 2.x engine stops reading once it has the answer (after
 * `response.completed`): the stream is then read to its end in the background (at most SETTLE_DRAIN_MS), so the
 * gateway settles the request as served instead of as a disconnect. Stopped before the final event (the person's
 * Stop), the upstream request is cancelled as before.
 */
export function settleOnFinish(stream: ReadableStream<Uint8Array>, tail: StreamTail, drainMs = SETTLE_DRAIN_MS): ReadableStream<Uint8Array> {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  let carry = "";
  return new ReadableStream<Uint8Array>({
    pull: async (controller) => {
      try {
        const { done, value } = await reader.read();
        if (done) { controller.close(); return; }
        if (!tail.completed) {
          const text = carry + decoder.decode(value, { stream: true });
          if (FINAL_EVENT.test(text)) tail.completed = true;
          carry = text.slice(-64);
        }
        controller.enqueue(value);
      } catch (error) {
        controller.error(error);
      }
    },
    cancel: (reason) => {
      if (!tail.completed) {
        tail.abort();
        return reader.cancel(reason).catch(() => undefined);
      }
      const timer = setTimeout(() => { tail.abort(); void reader.cancel().catch(() => undefined); }, drainMs);
      (timer as { unref?: () => void }).unref?.();
      void (async () => {
        try { for (;;) { if ((await reader.read()).done) break; } } catch { /* gone */ } finally { clearTimeout(timer); }
      })();
      return undefined;
    },
  });
}

function untilAborted(response: Promise<Response>, signal: AbortSignal): Promise<Response> {
  if (signal.aborted) return Promise.reject(signal.reason);
  return new Promise((resolvePromise, reject) => {
    const onAbort = () => reject(signal.reason);
    signal.addEventListener("abort", onAbort, { once: true });
    response.then((value) => {
      signal.removeEventListener("abort", onAbort);
      if (signal.aborted) void value.body?.cancel().catch(() => undefined);
      resolvePromise(value);
    }, (error: unknown) => {
      signal.removeEventListener("abort", onAbort);
      reject(error);
    });
  });
}

function fileReadableBody(path: string, signal: AbortSignal): ReadableStream<Uint8Array> {
  const source = createReadStream(path, { highWaterMark: 64 * 1024 });
  const abort = () => source.destroy(signal.reason instanceof Error ? signal.reason : undefined);
  const cleanup = () => signal.removeEventListener("abort", abort);
  return new globalThis.ReadableStream<Uint8Array>({
    start(controller) {
      if (signal.aborted) {
        abort();
        return;
      }
      signal.addEventListener("abort", abort, { once: true });
      source.on("data", (chunk: string | Buffer) => {
        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
        controller.enqueue(new Uint8Array(bytes));
      });
      source.on("end", () => {
        cleanup();
        controller.close();
      });
      source.on("error", (error: Error) => {
        cleanup();
        controller.error(error);
      });
    },
    cancel(reason) {
      cleanup();
      source.destroy(reason instanceof Error ? reason : undefined);
    },
  });
}

/** The backend's voice route, relative to the gateway URL (…/omnirush/v1/audio/transcriptions). */
export const VOICE_TRANSCRIPTIONS_PATH = "audio/transcriptions";
/** The backend allows 20 s for its primary provider and 30 s for the fallback. */
const VOICE_TRANSCRIBE_TIMEOUT_MS = 35_000;

/** The project archive routes the session archiver calls (archives, archives/key, archives/<id>/parts|complete|abort). */
const ARCHIVE_API_PATH = /^archives(?:\/key|\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/(?:parts|complete|abort))?$/;
/** The session check the archiver reads a lost chain back from (`archive.chain`), summary only. */
const ARCHIVE_CHAIN_PATH = /^me\/sessions\/[A-Za-z0-9._%:-]{8,400}\/integrity\?summary=1$/;

/**
 * Set by the omnirush-reasoning-effort engine plugin; keep the two
 * definitions identical. The header is consumed here and never forwarded.
 */
const REASONING_EFFORT_HEADER = "x-omnirush-reasoning-effort";
const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "ultra", "max"]);

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function requestedReasoningEffort(request: Request): string | null {
  const effort = request.headers.get(REASONING_EFFORT_HEADER)?.trim().toLowerCase() ?? "";
  return REASONING_EFFORTS.has(effort) ? effort : null;
}

/**
 * Guarantee the selected effort reaches omnirush.ai as Responses-API
 * `reasoning.effort`. The engine's OpenAI adapter only emits it for model ids
 * it recognises as reasoning models; an effort it already emitted (or a legacy
 * top-level `reasoning_effort`) is left untouched.
 */
function withReasoningEffort(body: ArrayBuffer, effort: string): ArrayBuffer | string {
  let parsed: unknown;
  try {
    parsed = JSON.parse(new TextDecoder().decode(body));
  } catch {
    return body;
  }
  if (!isRecord(parsed) || typeof parsed.reasoning_effort === "string") return body;
  const reasoning = isRecord(parsed.reasoning) ? parsed.reasoning : {};
  if (typeof reasoning.effort === "string") return body;
  return JSON.stringify({ ...parsed, reasoning: { ...reasoning, effort } });
}

/**
 * OpenCode currently opts into OpenAI summaries only for GPT-5 model IDs.
 * Ask for the summaries the transcript displays for every catalog model that
 * wants them (`wantsSummary`: the account's catalog decides, see
 * omnirushModelWantsReasoningSummary), preserving any explicit summary
 * option. Apply this at the final forwarding boundary so sub-agent fallbacks
 * use the destination model's options.
 */
async function withReasoningSummary(
  body: ArrayBuffer | string,
  wantsSummary: (model: string) => boolean | Promise<boolean>,
): Promise<ArrayBuffer | string> {
  let parsed: unknown;
  try {
    parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
  } catch {
    return body;
  }
  if (!isRecord(parsed) || typeof parsed.model !== "string") return body;
  let wanted = false;
  try {
    wanted = await wantsSummary(parsed.model);
  } catch {
    wanted = false;
  }
  if (!wanted) return body;
  if (parsed.reasoning != null && !isRecord(parsed.reasoning)) return body;
  const reasoning = isRecord(parsed.reasoning) ? parsed.reasoning : {};
  if ("summary" in reasoning) return body;
  return JSON.stringify({ ...parsed, reasoning: { ...reasoning, summary: "auto" } });
}

/**
 * Gateway refusals of a sub-agent's picked model that move the request to
 * the main model at once: the model is not served to this account (or at
 * all), cannot take this request, or its route is not set up.
 */
const SUBAGENT_MODEL_REFUSED = new Set([
  "model_unavailable",
  "model_not_allowed",
  "model_not_found",
  "model_input_not_supported",
  "reasoning_effort_not_allowed",
  "unsupported_model_endpoint",
  "muse_relay_not_configured",
  "model_upstream_auth_failed",
  "model_upstream_misconfigured",
]);
/** Busy or down: the picked model is tried once more, then the request moves to the main model. */
const SUBAGENT_MODEL_BUSY = new Set([
  "model_concurrency_limited",
  "model_upstream_unavailable",
  "internal_proxy_unavailable",
  "provider_unavailable",
  "provider_rate_limited",
  "capacity_unavailable",
  "circuit_open",
  "maintenance",
  "draining",
  "auth_unavailable",
  "token_capacity",
  "gateway_overload",
  "queue_timeout",
]);
/** Account-wide refusals: another model would be refused the same way, so nothing moves. */
const ACCOUNT_REFUSED = new Set([
  "daily_grant_exhausted",
  "grant_check_unavailable",
  "account_inactive",
  "consent_required",
  "consent_version_outdated",
  "omnirush_account_required",
  "model_request_too_large",
  "update_required",
]);
const SUBAGENT_BUSY_STATUSES = new Set([429, 502, 503, 504]);

/**
 * Pauses before a model request whose connection to omnirush.ai failed
 * (no response at all: reset, refused, network change, TLS or HTTP/2 session
 * failure) is sent again. Once they are spent the engine gets a retryable
 * 503 with readable copy instead of a bare 500.
 */
const UNREACHABLE_RETRY_DELAYS_MS = [500, 2_000];

/** The failure's name, code and cause code, for the log: never a URL, header or body. */
function fetchFailure(error: unknown): { name: string; message: string; code: string | null } {
  const value = error instanceof Error ? error : new Error(String(error));
  const code = (value as { code?: unknown }).code;
  const cause = (value as { cause?: { code?: unknown; message?: unknown } }).cause;
  const causeCode = cause && typeof cause.code === "string" ? cause.code : null;
  const causeMessage = cause && typeof cause.message === "string" ? cause.message : "";
  return {
    name: value.name,
    message: `${value.message}${causeMessage && !value.message.includes(causeMessage) ? ` (${causeMessage})` : ""}`.slice(0, 300),
    code: typeof code === "string" ? code : causeCode,
  };
}

function unreachableResponse(code: string, message: string, requestId: string): Response {
  const body = message + " (request id: " + requestId + ")";
  return new Response(JSON.stringify({ error: { message: body, type: "omnirush_error", code, client_request_id: requestId } }), {
    status: 503,
    headers: { "content-type": "application/json", "retry-after": "2", "x-omnirush-client-request-id": requestId },
  });
}
const SUBAGENT_RETRY_DELAY_MS = 1_500;
const FALLBACK_MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;

type SubagentRefusal = { move: "now" | "after_retry" | "never"; reason: string };

/** The gateway error code of a refused response, read from a clone so the body stays readable. */
async function refusalCode(response: Response): Promise<{ code: string | null; final: boolean }> {
  const marked = response.headers.get("x-should-retry") === "false";
  if (!(response.headers.get("content-type") ?? "").includes("application/json")) return { code: null, final: marked };
  const text = await response.clone().text().catch(() => "");
  let payload: unknown;
  try {
    payload = JSON.parse(text);
  } catch {
    return { code: null, final: marked };
  }
  if (!isRecord(payload)) return { code: null, final: marked };
  const nested = isRecord(payload.error) ? payload.error : null;
  const code = stringField(payload.detail) ?? stringField(payload.error) ?? stringField(nested?.code) ?? stringField(payload.code);
  return { code: code ? code.replace(/^upstream_/, "") : null, final: marked || retryRefused(nested) };
}

async function subagentRefusal(response: Response): Promise<SubagentRefusal> {
  const { code, final } = await refusalCode(response);
  const reason = code ?? `http_${response.status}`;
  // Final for this model only: outside the chat's mode, the main model may still run here.
  if (code === MODEL_NOT_IN_MODE) return { move: "now", reason };
  // Marked final by the gateway: not sent again, on this model or another.
  if (final || (code && ACCOUNT_REFUSED.has(code))) return { move: "never", reason };
  if (code && SUBAGENT_MODEL_REFUSED.has(code)) return { move: "now", reason };
  if ((code && SUBAGENT_MODEL_BUSY.has(code)) || SUBAGENT_BUSY_STATUSES.has(response.status)) return { move: "after_retry", reason };
  return { move: "never", reason };
}

function requestedModel(body: ArrayBuffer | string): string | null {
  try {
    const parsed: unknown = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
    return isRecord(parsed) ? stringField(parsed.model) : null;
  } catch {
    return null;
  }
}

/** The same request on another model: its effort replaced (or dropped for the model's default). */
function withModel(body: ArrayBuffer | string, model: string, effort: string | null): string | null {
  let parsed: unknown;
  try {
    parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
  } catch {
    return null;
  }
  if (!isRecord(parsed)) return null;
  const { reasoning_effort: _legacy, ...rest } = parsed;
  const reasoning = isRecord(rest.reasoning) ? { ...rest.reasoning } : null;
  if (reasoning) delete reasoning.effort;
  const nextReasoning = effort ? { ...(reasoning ?? {}), effort } : reasoning;
  return JSON.stringify({ ...rest, model, ...(nextReasoning ? { reasoning: nextReasoning } : {}) });
}

function pause(ms: number, signal: AbortSignal): Promise<void> {
  return new Promise((resolve) => {
    if (signal.aborted) return resolve();
    const timer = setTimeout(done, ms);
    function done() {
      clearTimeout(timer);
      signal.removeEventListener("abort", done);
      resolve();
    }
    signal.addEventListener("abort", done, { once: true });
  });
}

function responseHeaders(headers: Headers, requestId?: string): Headers {
  const result = new Headers();
  for (const [name, value] of headers) {
    if (["content-type", "cache-control", "x-request-id", "openai-processing-ms", "retry-after"].includes(name)
      || name.startsWith("x-ratelimit-")
      || name.startsWith("x-omnirush-")) {
      result.set(name, value);
    }
  }
  if (requestId) result.set("x-omnirush-client-request-id", requestId);
  return result;
}

export class OmniRushGatewayBroker {
  private state: CredentialState | null;
  private knownAccountId: string | null = null;
  /** When the last integrity reads went out (one minute's worth), and a Retry-After the route gave. */
  private integrityCalls: number[] = [];
  private integrityBlockedUntil = 0;
  private accountIdLookup: Promise<string | null> | null = null;
  private readonly engineToken: string;
  private readonly invalidate?: OmniRushGatewayCredentials["invalidate"];
  private readonly refreshOwner?: OmniRushGatewayCredentials["refresh"];
  private readonly fetcher: typeof externalFetch;
  private readonly fileUploader?: BrokerOptions["uploadFile"];
  private readonly log?: BrokerOptions["log"];
  private readonly sessionUploadBudget: SessionUploadBudget;
  private readonly onSubagentFallback?: BrokerOptions["onSubagentFallback"];
  private readonly onModelRequest?: BrokerOptions["onModelRequest"];
  private readonly subagentRetryDelayMs: number;
  private readonly subagentModelRefused?: (model: string) => boolean;
  private readonly modelInMode?: BrokerOptions["modelInMode"];
  private readonly switchable: NonNullable<BrokerOptions["switchable"]>;
  /**
   * Chats seen with X-OmniRush-Box (the box engine plugin marks a box chat's
   * requests): a later request of one without the mark (a compaction, a side
   * question) still goes out as a box request. Oldest first, bounded.
   */
  private readonly boxSessions = new Set<string>();
  /** Each chat's model, from its first context-bearing request; pins are not evicted. */
  private readonly sessionModels = new Map<string, string>();
  private readonly sessionModelsFile?: string;
  private readonly onUpdateSignal?: (signal: GatewayUpdateSignal) => void;
  private readonly chatPin?: BrokerOptions["chatPin"];
  /** The strict sessions ({ path, header }) of the last capabilities answer (null: off, or an older server). */
  private strictBind: StrictSessions | null = null;
  /** The server whose capabilities answer `strictBind` is (null: none in this process yet). */
  private strictOrigin: string | null = null;
  /** When capabilities were last asked again for an unknown switch. */
  private strictAskedAt = 0;
  /** A capabilities check failed and none answered since. */
  private capabilitiesFailed = false;
  private readonly strictStateFile?: string;
  private readonly onCapturePolicy?: BrokerOptions["onCapturePolicy"];
  private readonly onBinding?: BrokerOptions["onBinding"];
  private readonly onUploadHold?: BrokerOptions["onUploadHold"];
  /** Chats whose binding is confirmed in this process (bound, or not bindable): their uploads may go out. */
  private readonly bindsConfirmed = new Set<string>();
  private holdSeq = 0;
  /** Strict sessions: each chat binds its model and mode once per process (model-modes/strict-sessions.mjs). */
  private readonly reasoningSummaryFor: (model: string) => boolean | Promise<boolean>;
  private readonly clientHeader: string | null;
  private readonly claudeFetcher: typeof externalFetch;
  private refreshInFlight: Promise<boolean> | null = null;
  /** Whether the last failed refresh left the session as it was (unreachable, 5xx, contended). */
  private lastRefreshTransient = false;
  /**
   * Attachments the model refused (a corrupt PDF the read tool returned, an
   * image that is not one): replaced by "[file could not be read: <name>]" in
   * every later request, so one bad file cannot fail the rest of a session.
   */
  private readonly rejectedAttachments = new RejectedAttachments();
  /** Each upstream model answer's tail (settleOnFinish): whether it finished, and how to cancel it. */
  private readonly streamTails = new WeakMap<Response, StreamTail>();
  private capabilityCache: { gatewayUrl: string; accountKey: string; capabilities: TraceCapabilities; expiresAt: number } | null = null;
  private capabilityProbe: { key: string; promise: Promise<TraceCapabilities | null> } | null = null;
  private capabilityFailure: { gatewayUrl: string; accountKey: string; until: number } | null = null;

  private readonly bindSession: ReturnType<typeof sessionBinder>;
  private makeBinder(timeoutMs?: number): ReturnType<typeof sessionBinder> {
    return sessionBinder((path, payload, signal) => this.withDeviceBearer((state) => this.fetcher(new URL(path, state.gatewayUrl).toString(), {
    method: "POST",
    headers: { Authorization: `Bearer ${state.accessToken}`, "Content-Type": "application/json", Accept: "application/json" },
    body: JSON.stringify(payload),
    signal,
  })).then(async (response) => ({ status: response.status, body: await response.json().catch(() => null) })), timeoutMs ? { timeoutMs } : {});
  }

  private readonly onModelResponse?: BrokerOptions["onModelResponse"];
  private readonly contextWrap?: BrokerOptions["contextWrap"];

  constructor(options: BrokerOptions) {
    const gatewayUrl = options.credentials ? normalizedGatewayUrl(options.credentials.gatewayUrl) : null;
    this.state = gatewayUrl && options.credentials?.accessToken && options.credentials.refreshToken
      ? {
          gatewayUrl,
          accessToken: options.credentials.accessToken,
          refreshToken: options.credentials.refreshToken,
        }
      : null;
    this.engineToken = options.engineToken?.trim() ?? "";
    this.onModelResponse = options.onModelResponse;
    this.contextWrap = options.contextWrap;
    this.sessionModelsFile = options.sessionModelsFile;
    if (this.sessionModelsFile) {
      try {
        const saved: unknown = JSON.parse(readFileSync(this.sessionModelsFile, "utf8"));
        if (!isRecord(saved) || Object.values(saved).some(model => typeof model !== "string" || !model)) throw new Error("Invalid saved session model pins");
        for (const [session, model] of Object.entries(saved)) if (typeof model === "string") this.sessionModels.set(session, model);
      } catch (error) {
        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
      }
    }
    this.invalidate = options.credentials?.invalidate;
    this.refreshOwner = options.credentials?.refresh;
    const fetcher = options.fetch ?? externalFetch;
    this.claudeFetcher = fetcher;
    this.clientHeader = guiClientHeaderValue(options.clientVersion);
    const clientHeader = this.clientHeader;
    // Every call the broker makes goes to omnirush.ai (model, upload, archive
    // API, catalog, voice, refresh); presigned S3 part uploads never pass here.
    this.fetcher = clientHeader ? (input, init) => fetcher(input, withClientHeader(init, clientHeader)) : fetcher;
    this.fileUploader = options.uploadFile;
    this.log = options.log;
    this.sessionUploadBudget = options.sessionUploadBudget ?? SESSION_UPLOAD_BUDGET;
    this.onSubagentFallback = options.onSubagentFallback;
    this.onModelRequest = options.onModelRequest;
    this.subagentRetryDelayMs = options.subagentRetryDelayMs ?? SUBAGENT_RETRY_DELAY_MS;
    this.subagentModelRefused = options.subagentModelRefused;
    this.modelInMode = options.modelInMode;
    this.switchable = options.switchable ?? ((bound, asked) => bound === asked);
    this.onUpdateSignal = options.onUpdateSignal;
    this.chatPin = options.chatPin;
    this.bindSession = this.makeBinder(options.bindTimeoutMs);
    this.onCapturePolicy = options.onCapturePolicy;
    this.onBinding = options.onBinding;
    this.onUploadHold = options.onUploadHold;
    this.strictStateFile = options.strictStateFile;

    this.reasoningSummaryFor = options.reasoningSummaryFor ?? defaultReasoningSummaryFor;
  }

  /**
   * Passes the gateway's update signals on: the header from any answer, and
   * a 426 / `update_required` refusal of a model request. Read from a clone,
   * so the response itself is untouched; a listener that throws is ignored.
   */
  private async noteUpdateSignals(response: Response, modelRequest: boolean): Promise<void> {
    if (!this.onUpdateSignal) return;
    try {
      const header = response.headers.get(UPDATE_REQUIRED_HEADER)?.trim();
      if (header) this.onUpdateSignal({ kind: "header", value: header });
      if (!modelRequest || response.ok) return;
      let code = response.status === 426 ? UPDATE_REQUIRED_CODE : null;
      let message: string | null = null;
      if ((response.headers.get("content-type") ?? "").includes("application/json")) {
        const text = await response.clone().text().catch(() => "");
        try {
          const payload: unknown = JSON.parse(text);
          if (isRecord(payload)) {
            const nested = isRecord(payload.error) ? payload.error : null;
            const bodyCode = stringField(nested?.code) ?? stringField(payload.detail) ?? stringField(payload.error);
            if (bodyCode === UPDATE_REQUIRED_CODE) code = bodyCode;
            message = stringField(nested?.message) ?? stringField(payload.message);
          }
        } catch {
          // Not JSON: the status alone decides.
        }
      }
      if (code === UPDATE_REQUIRED_CODE) {
        this.log?.("warn", "omnirush.ai refused a model request: this app version must be updated", { status: response.status });
        this.onUpdateSignal({ kind: "rejection", message });
      }
    } catch {
      // The update gate is advisory; the response goes on as it came.
    }
  }

  get enabled(): boolean {
    return Boolean(this.state && this.engineToken);
  }

  /** The console's Account page on the account's server (where Discord and GitHub are linked). */
  get consoleUrl(): string | null {
    return this.state ? new URL("/console/account", this.state.gatewayUrl).toString() : null;
  }

  async handle(request: Request, path: string): Promise<Response> {
    if (!this.enabled || !this.state) return Response.json({ error: "omnirush_account_required" }, { status: 401 });
    if (!secureEqual(bearerToken(request), this.engineToken)) {
      return Response.json({ error: "invalid_local_gateway_credential" }, { status: 401 });
    }
    const normalizedPath = path.replace(/^\/+/, "");
    // The 2.x engine names its session in x-session-id on every request (the CLI's token proxy maps it the same way).
    const stockSession = request.headers.get("x-session-id");
    if (!request.headers.has("x-omnirush-session-id") && stockSession && /^ses_[A-Za-z0-9]{1,64}$/.test(stockSession)) {
      const headers = new Headers(request.headers);
      headers.set("x-omnirush-session-id", stockSession);
      request = new Request(request, { headers });
    }
    const allowed = (request.method === "GET" && (normalizedPath === "models" || normalizedPath === VOICE_TRANSCRIPTIONS_PATH))
      || (request.method === "POST" && (normalizedPath === "responses" || normalizedPath === "responses/compact" || normalizedPath === VOICE_TRANSCRIPTIONS_PATH));
    if (!allowed) return Response.json({ error: "unsupported_gateway_path" }, { status: 404 });
    const requestId = clientRequestId(request);

    const requestBody = request.method === "GET"
      ? undefined
      : await this.requestBody(request, normalizedPath);
    // A picked sub-agent model the gateway refused moments ago is not tried
    // again for every step of a running sub-agent: it goes to the main model.
    const sessionBound = request.headers.has("x-omnirush-session-id") || request.headers.has(PARENT_SESSION_HEADER) || request.headers.has(SUBAGENT_ROOT_SESSION_HEADER);
    const skipped = requestBody === undefined || sessionBound ? null : this.skipRefusedSubagentModel(request, normalizedPath, requestBody);
    let body = skipped?.body ?? requestBody;
    const attachments = this.leaveOutRefusedAttachments(normalizedPath, body, requestId);
    if (attachments) body = attachments.body;
    let spent = this.state.accessToken;
    let response = await this.forwardModelRequest(request, normalizedPath, body, spent, requestId);
    // Two rounds at most: the first may only adopt a pair the desktop rotated,
    // whose own access token can have expired while the app was idle.
    let refreshUnavailable = false;
    for (let round = 0; round < 2 && response.status === 401 && this.state; round += 1) {
      const credentialAlreadyRotated = this.state.accessToken !== spent;
      if (!credentialAlreadyRotated && !(await this.refresh(spent))) {
        refreshUnavailable = this.state !== null && this.lastRefreshTransient;
        break;
      }
      if (!this.state) break;
      await response.body?.cancel().catch(() => undefined);
      spent = this.state.accessToken;
      response = await this.forwardModelRequest(request, normalizedPath, body, spent, requestId);
    }
    if (response.status === 401 && refreshUnavailable) {
      // The session is intact but the refresh could not reach omnirush.ai:
      // a retryable answer, not a sign-in error that ends the turn.
      await response.body?.cancel().catch(() => undefined);
      return unreachableResponse(
        "device_refresh_unavailable",
        "omnirush.ai: the session could not be renewed right now (the service did not answer). Retrying shortly.",
        requestId
      );
    }
    if (response.status === 401 && !this.state) {
      await response.body?.cancel().catch(() => undefined);
      return Response.json({
        error: {
          message: "Your omnirush.ai session has expired. Sign in again from Settings.",
          type: "authentication_error",
          code: "omnirush_account_required",
        },
      }, { status: 401 });
    }
    if (attachments) {
      const retried = await this.retryWithoutRefusedAttachments(request, normalizedPath, attachments, response, requestId);
      response = retried.response;
      body = retried.body;
    }
    if (skipped) {
      this.reportSubagentFallback(request, { ...skipped.event, status: response.status, ok: response.ok, clientRequestId: requestId });
    } else if (!sessionBound && !response.ok && response.status !== 401 && body !== undefined) {
      response = await this.subagentFallback(request, normalizedPath, body, response, requestId);
    }
    await this.noteUpdateSignals(response, true);
    const chat = request.headers.get("x-omnirush-session-id");
    if (chat && this.onModelResponse) {
      try { this.onModelResponse(chat, response.headers); } catch { /* the wrap offer is best effort */ }
    }
    const contentType = response.headers.get("content-type") ?? "";
    // Sign-in failures keep their own answer above; every other gateway
    // refusal reaches the user as readable copy instead of a bare code.
    if (!response.ok && response.status !== 401 && contentType.includes("application/json")) {
      return await readableErrorResponse(response, this.consoleUrl);
    }
    const streamed = response.ok && response.body && contentType.includes("text/event-stream");
    let upstreamBody: ReadableStream<Uint8Array> | null = response.body;
    if (streamed && upstreamBody && response.headers.get("x-should-retry") === "false") {
      const refusal = await streamedRefusalOrBody(response, upstreamBody);
      if (refusal instanceof Response) return refusal;
      upstreamBody = refusal;
    }
    const tail = this.streamTails.get(response);
    if (streamed && upstreamBody && tail) upstreamBody = settleOnFinish(upstreamBody, tail);
    const responseBody = streamed && upstreamBody
      ? guardEventStream(upstreamBody, {
          requestId,
          onInterrupted: (reason) => this.log?.("warn", "omnirush.ai model stream interrupted", {
            reason, path: normalizedPath, clientRequestId: requestId,
          }),
        })
      : upstreamBody;
    return new Response(this.titleRecord(request, normalizedPath, body, response, responseBody), {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders(response.headers, requestId),
    });
  }

  /**
   * A model request's attachments, with the ones the model refused earlier
   * replaced; null for a request that is not JSON or carries none.
   */
  private leaveOutRefusedAttachments(path: string, body: ArrayBuffer | string | undefined, requestId: string): { parsed: unknown; attachments: Attachment[]; body: ArrayBuffer | string } | null {
    if (body === undefined || (path !== "responses" && path !== "responses/compact")) return null;
    let parsed: unknown;
    try {
      parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
    } catch {
      return null;
    }
    if (!parsed || typeof parsed !== "object") return null;
    const prepared = this.rejectedAttachments.prepare(parsed);
    if (prepared.attachments.length === 0) return null;
    if (prepared.replaced.length > 0) {
      this.log?.("info", "omnirush.ai: left out attachments the model refused earlier", { count: prepared.replaced.length, clientRequestId: requestId });
      return { parsed, attachments: prepared.attachments, body: JSON.stringify(prepared.body) };
    }
    return { parsed, attachments: prepared.attachments, body };
  }

  /**
   * The model refused an attachment (400 "The file you uploaded is badly
   * formatted or corrupted"): the suspects are left out and the request sent
   * again, so the turn goes on with a "[file could not be read: x]" note. An
   * answer the model accepted marks its attachments as good.
   */
  private async retryWithoutRefusedAttachments(
    request: Request,
    path: string,
    state: { parsed: unknown; attachments: Attachment[]; body: ArrayBuffer | string },
    first: Response,
    requestId: string,
  ): Promise<{ response: Response; body: ArrayBuffer | string }> {
    let response = first;
    let { attachments, body } = state;
    for (let round = 0; response.status === 400 && round < MAX_ATTACHMENT_RETRIES && this.state; round += 1) {
      const raw = new Uint8Array(await response.arrayBuffer().catch(() => new ArrayBuffer(0)));
      const kept = new Response(raw.byteLength ? raw : null, { status: response.status, statusText: response.statusText, headers: response.headers });
      const message = new TextDecoder().decode(raw.subarray(0, MAX_ATTACHMENT_ERROR_BYTES));
      const suspects = isRejectedAttachmentError(response.status, message) ? this.rejectedAttachments.reject(attachments, message) : [];
      if (suspects.length === 0) return { response: kept, body };
      const prepared = this.rejectedAttachments.prepare(state.parsed);
      attachments = prepared.attachments;
      body = JSON.stringify(prepared.body);
      this.log?.("warn", "omnirush.ai: the model refused an attachment; sending the request again without it", { path, left_out: suspects.length, clientRequestId: requestId });
      response = await this.forwardModelRequest(request, path, body, this.state.accessToken, requestId);
    }
    if (response.ok) this.rejectedAttachments.accept(attachments.filter((item) => !this.rejectedAttachments.isBad(item.fingerprint)));
    return { response, body };
  }

  /**
   * One session uploader envelope. The deadline grows with the envelope's size
   * (session-upload-budget.ts), and the retry with a refreshed bearer gets a
   * deadline of its own; `signal`, the session uploader's own deadline or cancel,
   * ends either sooner.
   */
  uploadSession(sessionId: string, body: Uint8Array, signal?: AbortSignal, options: UploadRequestOptions = {}): Promise<Response> {
    const timeoutMs = sessionUploadTimeoutMs(body.byteLength, this.sessionUploadBudget);
    return this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, SESSION_UPLOAD_ENDPOINT_PATH), {
      method: "POST",
      headers: {
        Authorization: `Bearer ${state.accessToken}`,
        "Content-Type": "application/zstd",
        "X-OmniRush-Session-ID": sessionId,
        ...(options.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : {}),
      },
      body: body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer,
      signal: signal ? AbortSignal.any([AbortSignal.timeout(timeoutMs), signal]) : AbortSignal.timeout(timeoutMs),
    }));
  }

  uploadSessionFile(sessionId: string, path: string, size: number, signal?: AbortSignal, options: UploadRequestOptions = {}): Promise<Response> {
    const timeoutMs = sessionUploadTimeoutMs(size, this.sessionUploadBudget);
    return this.withDeviceBearer(async (state) => {
      const requestSignal = signal ? AbortSignal.any([AbortSignal.timeout(timeoutMs), signal]) : AbortSignal.timeout(timeoutMs);
      const url = apiUrl(state.gatewayUrl, SESSION_UPLOAD_ENDPOINT_PATH);
      const headers: Record<string, string> = {
        Authorization: `Bearer ${state.accessToken}`,
        "Content-Type": "application/zstd",
        "X-OmniRush-Session-ID": sessionId,
        ...(options.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : {}),
      };
      // The Electron file transport bypasses this.fetcher.
      if (this.clientHeader) headers[CLIENT_HEADER] = this.clientHeader;
      if (this.fileUploader) {
        return untilAborted(this.fileUploader(url, { method: "POST", headers, path, size, signal: requestSignal }), requestSignal);
      }
      const bodyAbort = new AbortController();
      const bodySignal = AbortSignal.any([requestSignal, bodyAbort.signal]);
      const body = fileReadableBody(path, bodySignal);
      try {
        const init: RequestInit & { duplex: "half" } = {
          method: "POST",
          headers,
          body,
          duplex: "half",
          signal: requestSignal,
        };
        return await this.fetcher(url, init);
      } finally {
        bodyAbort.abort(new DOMException("The upload response arrived", "AbortError"));
      }
    });
  }

  /**
   * The backend's upload capabilities, cached for TRACE_CAPABILITY_TTL_MS. A
   * check that got no usable answer (a 401 after the refresh, a 5xx, a
   * timeout) is not an answer: with `strict` (the session uploader, which
   * then keeps the format the server last advertised) it throws; otherwise
   * it reads as the oldest backend. Either way it is asked again after
   * TRACE_CAPABILITY_RETRY_MS, not after the full TTL.
   */
  async sessionUploadCapabilities(options: { strict?: boolean; maxAgeMs?: number } = {}): Promise<TraceCapabilities> {
    const none: TraceCapabilities = { schema_versions: [1, 2], canonical_trace: false };
    if (!this.state) {
      if (options.strict) throw new Error("capabilities unavailable: signed out");
      return { schema_versions: [1, 2, 3], canonical_trace: false };
    }
    const state = this.state;
    const gatewayUrl = state.gatewayUrl;
    const key = this.capabilityKey(state);
    // `maxAgeMs`: an answer older than that is asked again (the automatic compaction's check before it compacts).
    if (this.capabilityCache?.gatewayUrl === gatewayUrl
      && this.capabilityCache.accountKey === key
      && this.capabilityCache.expiresAt > Date.now()
      && (options.maxAgeMs === undefined || Date.now() - (this.capabilityCache.expiresAt - TRACE_CAPABILITY_TTL_MS) < options.maxAgeMs)) {
      return this.capabilityCache.capabilities;
    }
    const failed = () => {
      if (options.strict) throw new Error("capabilities request failed");
      return none;
    };
    if (this.capabilityFailure?.gatewayUrl === gatewayUrl
      && this.capabilityFailure.accountKey === key
      && this.capabilityFailure.until > Date.now()) {
      return failed();
    }
    const pending = this.capabilityProbe?.key === key
      ? this.capabilityProbe.promise
      : this.probeSessionUploadCapabilities(gatewayUrl);
    if (!this.capabilityProbe || this.capabilityProbe.key !== key) {
      this.capabilityProbe = { key, promise: pending };
      void pending.finally(() => {
        if (this.capabilityProbe?.promise === pending) this.capabilityProbe = null;
      }).catch(() => undefined);
    }
    const capabilities = await pending;
    // The key after the probe: a 401 inside it may have rotated the pair.
    const settledKey = this.state ? this.capabilityKey(this.state) : null;
    if (capabilities === null) {
      this.capabilitiesFailed = true;
      if (settledKey) this.capabilityFailure = { gatewayUrl, accountKey: settledKey, until: Date.now() + TRACE_CAPABILITY_RETRY_MS };
      return failed();
    }
    if (settledKey && this.state?.gatewayUrl === gatewayUrl) {
      this.capabilityFailure = null;
      this.capabilitiesFailed = false;
      this.capabilityCache = { gatewayUrl, accountKey: settledKey, capabilities, expiresAt: Date.now() + TRACE_CAPABILITY_TTL_MS };
      this.rememberStrict(gatewayUrl, capabilities);
    }
    return capabilities;
  }

  resetCapabilities(): void {
    this.claudeDevice = undefined;
    this.capabilityCache = null;
    this.capabilityProbe = null;
    this.capabilityFailure = null;
  }

  /**
   * The server's integrity record of one chat (GET
   * `<gateway root>/me/sessions/{id}/integrity`), with the device bearer and
   * the same bounded 401 refresh as uploadSession(). `turns` is the client's
   * count of completed turns; `summary` leaves out the per-upload rows. The
   * route allows 30 calls a minute per account: past INTEGRITY_CALLS_PER_MINUTE
   * here, or before a Retry-After it gave, the answer is a local 429.
   */
  async sessionIntegrity(sessionId: string, options: SessionIntegrityOptions = {}): Promise<Response> {
    // A backend without the route answers like one that holds nothing (the callers' "pending").
    const features = await this.sessionUploadCapabilities();
    if (features.integrity !== true) return Response.json({ detail: "integrity_unavailable" }, { status: 404 });
    const summary = options.summary === true && features.integrity_summary === true;
    const now = Date.now();
    this.integrityCalls = this.integrityCalls.filter((at) => now - at < 60_000);
    const waitMs = Math.max(this.integrityBlockedUntil - now, this.integrityCalls.length >= INTEGRITY_CALLS_PER_MINUTE ? this.integrityCalls[0]! + 60_000 - now : 0);
    if (waitMs > 0) {
      return Response.json({ detail: "rate_limited" }, { status: 429, headers: { "Retry-After": String(Math.ceil(waitMs / 1_000)) } });
    }
    this.integrityCalls.push(now);
    const response = await this.withDeviceBearer((state) => {
      const url = new URL(apiUrl(state.gatewayUrl, `me/sessions/${encodeURIComponent(sessionId)}/integrity`));
      if (summary) url.searchParams.set("summary", "1");
      if (options.turns !== undefined && Number.isSafeInteger(options.turns) && options.turns >= 0) url.searchParams.set("turns", String(options.turns));
      return this.fetcher(url.toString(), {
        method: "GET",
        headers: { Authorization: `Bearer ${state.accessToken}`, Accept: "application/json" },
        signal: AbortSignal.timeout(10_000),
      });
    });
    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("retry-after"));
      this.integrityBlockedUntil = Date.now() + (Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 3_600) * 1_000 : 60_000);
    }
    return response;
  }

  /**
   * The id of the account behind the device bearer (`<gateway root>/device/me`),
   * learned once: an account change restarts the server. Null while it
   * cannot be learned (signed out, offline, an unexpected answer).
   */
  accountId(): Promise<string | null> {
    if (this.knownAccountId) return Promise.resolve(this.knownAccountId);
    this.accountIdLookup ??= (async () => {
      try {
        const response = await this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, "device/me"), {
          method: "GET",
          headers: { Authorization: `Bearer ${state.accessToken}`, Accept: "application/json" },
          signal: AbortSignal.timeout(8_000),
        }));
        if (!response.ok) {
          await response.body?.cancel().catch(() => undefined);
          return null;
        }
        // device/me lists every device row of the account: thousands on a long-used test or farm account.
        const text = await boundedText(response, 16 * 1024 * 1024);
        const payload: unknown = text === null ? null : JSON.parse(text);
        const id = isRecord(payload) && typeof payload.id === "string" ? payload.id.trim() : "";
        if (id) this.knownAccountId = id;
        return id || null;
      } catch {
        return null;
      } finally {
        this.accountIdLookup = null;
      }
    })();
    return this.accountIdLookup;
  }

  private capabilityKey(state: CredentialState): string {
    return `${state.gatewayUrl}\0${state.refreshToken}`;
  }

  /**
   * The backend's /collect/capabilities: the trace schema and the features
   * it has (a key it does not name is false). Null when no usable answer
   * came (a 401 after the refresh, a 5xx, a timeout, an unreadable body):
   * that says nothing about what the backend takes.
   */
  private async probeSessionUploadCapabilities(gatewayUrl: string): Promise<TraceCapabilities | null> {
    try {
      if (this.state?.gatewayUrl !== gatewayUrl) return null;
      const response = await this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, "collect/capabilities"), {
        method: "GET",
        headers: { Authorization: `Bearer ${state.accessToken}`, Accept: "application/json" },
        signal: AbortSignal.timeout(8_000),
      }));
      if (!response.ok) {
        await response.body?.cancel().catch(() => undefined);
        // A backend without the route is the oldest one: that is an answer.
        return response.status === 404 ? { schema_versions: [1, 2], canonical_trace: false } : null;
      }
      const text = await boundedText(response, 64 * 1024);
      if (text === null) return null;
      const payload: unknown = JSON.parse(text);
      if (!isRecord(payload)) return null;
      const v3 = payload.canonical_trace === true && Array.isArray(payload.schema_versions) && payload.schema_versions.some((version) => version === 3);
      const triggers = Array.isArray(payload.triggers) ? payload.triggers.filter((item): item is string => typeof item === "string") : null;
      const installLog = isRecord(payload.install_log) ? payload.install_log : null;
      return {
        schema_versions: v3 ? [1, 2, 3] : [1, 2],
        canonical_trace: v3,
        ...uploadFeatureFlags(payload),
        ...(triggers ? { triggers } : {}),
        // The install log switch, passed on as the server said it (context/install-log.ts reads it).
        ...(installLog ? { install_log: { enabled: installLog.enabled === true, sample_percent: typeof installLog.sample_percent === "number" ? installLog.sample_percent : 100 } } : {}),
        ...(isRecord(payload.local_box) ? { local_box: localBoxCapability(payload.local_box) } : {}),
        // The MCP list, passed on as the server said it (mcp-allow/state.ts remembers it; absent is off).
        ...(isRecord(payload.mcp) ? { mcp: payload.mcp } : {}),
        // Automatic compaction (session-archive/auto-compact.ts reads it; absent is off).
        ...(isRecord(payload.auto_compact) && typeof payload.auto_compact.enabled === "boolean" && typeof payload.auto_compact.after_turns === "number"
          ? { auto_compact: { enabled: payload.auto_compact.enabled, after_turns: payload.auto_compact.after_turns, ...(typeof payload.auto_compact.min_context_tokens === "number" ? { min_context_tokens: payload.auto_compact.min_context_tokens } : {}) } }
          : {}),
        // The model's own web search (web-search.ts reads it; absent is off).
        ...(isRecord(payload.web_search) ? { web_search: payload.web_search } : {}),
        // Computer use (computer-use/desktop.ts reads it; absent is off).
        ...(isRecord(payload.computer_use) ? { computer_use: payload.computer_use } : {}),
        // Work mode (work/work.ts reads it; absent is off).
        ...(isRecord(payload.work) ? { work: payload.work } : {}),
        // The model provider lock (provider-lock.ts reads it; absent is locked).
        ...(isRecord(payload.providers) ? { providers: payload.providers } : {}),
        // Strict sessions (model-modes/strict-sessions.mjs reads it; absent is no bind).
        ...(isRecord(payload.strict_sessions) ? { strict_sessions: payload.strict_sessions } : {}),
      };
    } catch {
      return null;
    }
  }

  /**
   * A project archive API call for the session archiver (`archives/key`,
   * `archives`, `archives/<id>/parts|complete|abort`), authenticated like
   * uploadSession(): the device bearer and the same bounded 401 refresh. S3 part
   * uploads never come through here; they go to their presigned URLs. With
   * `refresh: false` (the archiver's all-folders policy probe) it is one
   * request: a 401 is returned as it is, with no refresh and no second try.
   */
  /**
   * A Work mode call (`/omnirush/work/<path>[?query]`: connectors, knowledge, health, the hosted MCP server), with the device bearer and
   * the same bounded 401 refresh. Only the contract's paths; the answer is returned as it came.
   */
  workRequest(path: string, init: { method: "GET" | "POST" | "PATCH"; body?: string; headers?: Record<string, string>; signal?: AbortSignal }): Promise<Response> {
    const [bare = "", query] = path.split("?", 2);
    if (!WORK_PATH.test(bare)) {
      return Promise.resolve(Response.json({ detail: "unsupported_work_path" }, { status: 404 }));
    }
    return this.withDeviceBearer((state) => this.fetcher(`${apiUrl(state.gatewayUrl, `work/${bare}`)}${query ? `?${new URLSearchParams(query)}` : ""}`, {
      method: init.method,
      headers: {
        Accept: "application/json",
        ...init.headers,
        Authorization: `Bearer ${state.accessToken}`,
        ...(init.body === undefined ? {} : { "Content-Type": "application/json" }),
      },
      ...(init.body === undefined ? {} : { body: init.body }),
      signal: init.signal ?? AbortSignal.timeout(60_000),
    }));
  }

  archiveRequest(path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal; refresh?: false }): Promise<Response> {
    const chain = ARCHIVE_CHAIN_PATH.test(path);
    if (!chain && !ARCHIVE_API_PATH.test(path)) return Promise.resolve(Response.json({ error: "unsupported_archive_path" }, { status: 404 }));
    return this.withDeviceBearer((state) => this.fetcher(chain ? `${apiUrl(state.gatewayUrl, path.slice(0, path.indexOf("?")))}?summary=1` : apiUrl(state.gatewayUrl, path), {
      method: init.method,
      headers: {
        Authorization: `Bearer ${state.accessToken}`,
        Accept: "application/json",
        ...(init.body === undefined ? {} : { "Content-Type": "application/json" }),
      },
      ...(init.body === undefined ? {} : { body: init.body }),
      ...(init.signal ? { signal: init.signal } : {}),
    }), { refresh: init.refresh !== false });
  }

  /**
   * The account's model catalog (`<gateway>/models`, the backend's
   * GET /omnirush/v1/models), authenticated like uploadSession(): the device bearer
   * and the same bounded 401 refresh. Read by the model catalog sync.
   */
  modelCatalog(): Promise<Response> {
    return this.withDeviceBearer((state) => this.fetcher(upstreamUrl(state.gatewayUrl, "models"), {
      method: "GET",
      headers: { Authorization: `Bearer ${state.accessToken}`, Accept: "application/json", "X-OmniRush-Stock": stockMode() ? "1" : "0" },
      signal: AbortSignal.timeout(8_000),
    }));
  }

  private claudeDevice?: ClaudeDeviceAccess;
  private claudeAccessClient() {
    this.claudeDevice ??= new ClaudeDeviceAccess(this.claudeDeviceRequest, (this.clientHeader ?? "desktop/unknown").replace(/^gui\//, "desktop/"));
    return this.claudeDevice;
  }
  private readonly claudeDeviceRequest: ClaudeDeviceRequest = (route, init, owner) => this.withDeviceBearer(async state => {
    const client = (this.clientHeader ?? "desktop/unknown").replace(/^gui\//, "desktop/");
    if (owner) {
      const identity = await this.fetcher(apiUrl(state.gatewayUrl, "device/me"), {headers: {Authorization: `Bearer ${state.accessToken}`}, signal: AbortSignal.timeout(8_000)});
      if (!identity.ok) return identity;
      const account: unknown = await identity.json();
      if (!isRecord(account) || account.id !== owner) return new Response(null, {status: 403});
    }
    return this.claudeFetcher(apiUrl(state.gatewayUrl, route), {
      method: init?.method ?? "GET", body: init?.body,
      headers: {Authorization: `Bearer ${state.accessToken}`, Accept: "application/json", "Content-Type": "application/json", "X-OmniRush-Client": client},
      signal: AbortSignal.timeout(8_000),
    });
  });
  claudeAccess(options: { fresh?: boolean } = {}) { return this.claudeAccessClient().access(options); }
  /** Session-bound tokens stay in this host process, outside the renderer and Docker. */
  async claudeGrant(context: ClaudeAuthorization) {
    const client = this.claudeAccessClient(), grant = await client.authorize(context);
    if (client !== this.claudeDevice) throw new Error("OmniRush account routing changed; retry with the current account");
    return grant;
  }
  revokeClaudeGrant(context: ClaudeAuthorization) { return this.claudeAccessClient().revoke(context); }

  /** A chat's fixed model (one model per chat), null before its first request. */
  chatModel(session: string): string | null { return this.sessionModels.get(session) ?? null; }

  /** Pins a chat to its first model, kept on disk so a reopened chat keeps it (a Claude chat pins here too). */
  pinChatModel(session: string, model: string): void {
    if (this.sessionModelsFile) {
      mkdirSync(dirname(this.sessionModelsFile), {recursive: true, mode: 0o700});
      const tmp = `${this.sessionModelsFile}.${randomUUID()}.tmp`;
      writeFileSync(tmp, JSON.stringify({...Object.fromEntries(this.sessionModels), [session]: model}), {mode: 0o600});
      renameSync(tmp, this.sessionModelsFile);
    }
    this.sessionModels.set(session, model);
  }

  nativeCaptureRequest(owner: string, route: string, init: {method: "GET" | "POST"; body?: string; signal?: AbortSignal; refresh?: false}): Promise<Response> {
    if (route !== "collect/capabilities" && !ARCHIVE_API_PATH.test(route)) return Promise.resolve(new Response(null, {status: 404}));
    return this.withDeviceBearer(async state => {
      const identity = await this.fetcher(apiUrl(state.gatewayUrl, "device/me"), {headers: {Authorization: `Bearer ${state.accessToken}`}, signal: AbortSignal.timeout(8_000)});
      if (!identity.ok) return identity;
      const account: unknown = await identity.json();
      if (!isRecord(account) || account.id !== owner) return new Response(null, {status: 403});
      return this.fetcher(apiUrl(state.gatewayUrl, route), {
      method: init.method, headers: {Authorization: `Bearer ${state.accessToken}`, "content-type": "application/json"},
      body: init.body, signal: init.signal ?? AbortSignal.timeout(30_000),
      });
    }, {refresh: init.refresh !== false});
  }

  /**
   * One voice segment for the backend's POST /omnirush/v1/audio/transcriptions,
   * authenticated like uploadSession(): the device bearer and the same bounded 401
   * refresh. The multipart body goes through as it came and is held only
   * for this call.
   */
  /** GET /omnirush/v1/audio/transcriptions: whether this account may dictate, its limits and today's usage. */
  voiceStatus(): Promise<Response> {
    return this.withDeviceBearer((state) => this.fetcher(upstreamUrl(state.gatewayUrl, VOICE_TRANSCRIPTIONS_PATH), {
      method: "GET",
      headers: { Authorization: `Bearer ${state.accessToken}`, Accept: "application/json" },
      signal: AbortSignal.timeout(8_000),
    }));
  }

  transcribe(body: ArrayBuffer, contentType: string, signal?: AbortSignal): Promise<Response> {
    const timeout = AbortSignal.timeout(VOICE_TRANSCRIBE_TIMEOUT_MS);
    return this.withDeviceBearer((state) => this.fetcher(upstreamUrl(state.gatewayUrl, VOICE_TRANSCRIPTIONS_PATH), {
      method: "POST",
      headers: { Authorization: `Bearer ${state.accessToken}`, "Content-Type": contentType, Accept: "application/json" },
      body,
      signal: signal ? AbortSignal.any([timeout, signal]) : timeout,
    }));
  }

  /**
   * Sends with the current device bearer; a 401 is retried bounded like
   * handle(): adopt, then spend the adopted refresh token. `refresh: false`
   * sends once and returns whatever came back.
   */
  private async withDeviceBearer(send: (state: CredentialState) => Promise<Response>, options: { refresh: boolean } = { refresh: true }): Promise<Response> {
    if (!this.state) return Response.json({ error: "omnirush_account_required" }, { status: 401 });
    let spent = this.state.accessToken;
    let response = await send(this.state);
    if (!options.refresh) return response;
    for (let round = 0; round < 2 && response.status === 401 && this.state; round += 1) {
      const credentialAlreadyRotated = this.state.accessToken !== spent;
      if (!credentialAlreadyRotated && !(await this.refresh(spent))) break;
      if (!this.state) break;
      await response.body?.cancel().catch(() => undefined);
      spent = this.state.accessToken;
      response = await send(this.state);
    }
    // Uploads and archives are never refused for the version; only the header counts here.
    await this.noteUpdateSignals(response, false);
    return response;
  }

  /**
   * Rotates the device access token through the refresh endpoint and returns
   * the bearer to use next, or null once the account is signed out. The
   * session uploader asks for this when an upload comes back unauthorized
   * after the retry inside uploadSession() has already failed to rotate it.
   */
  async refreshAccessToken(): Promise<string | null> {
    if (!this.state) return null;
    const refreshed = await this.refresh(this.state.accessToken);
    return refreshed ? this.state?.accessToken ?? null : null;
  }

  private async requestBody(request: Request, path: string): Promise<ArrayBuffer | string> {
    const body = await request.arrayBuffer();
    const effort = requestedReasoningEffort(request);
    if (!effort || (path !== "responses" && path !== "responses/compact")) return body;
    return withReasoningEffort(body, effort);
  }

  /**
   * A sub-agent runs on a model picked for sub-agents, and the swarm plugin
   * names the main model it falls back to (SUBAGENT_FALLBACK_MODEL_HEADER).
   * When the gateway refuses the picked model before answering (the model is
   * not served, or it stays busy or down on a second try), the same request
   * goes to the main model instead, so the sub-agent's task continues rather
   * than failing. Account-wide refusals and every other error pass through.
   */
  private async subagentFallback(request: Request, path: string, body: ArrayBuffer | string, response: Response, requestId: string): Promise<Response> {
    const fallback = request.headers.get(SUBAGENT_FALLBACK_MODEL_HEADER)?.trim() ?? "";
    if (!fallback || !FALLBACK_MODEL_ID.test(fallback) || (path !== "responses" && path !== "responses/compact")) return response;
    const requested = requestedModel(body);
    if (!requested || requested === fallback) return response;
    let refusal = await subagentRefusal(response);
    if (refusal.move === "never") return response;
    if (refusal.move === "after_retry") {
      await response.body?.cancel().catch(() => undefined);
      await pause(this.subagentRetryDelayMs, request.signal);
      if (request.signal.aborted || !this.state) return response;
      const again = await this.forwardModelRequest(request, path, body, undefined, requestId);
      if (again.ok || again.status === 401) return again;
      refusal = await subagentRefusal(again);
      if (refusal.move === "never") return again;
      response = again;
    }
    const effortHeader = request.headers.get(SUBAGENT_FALLBACK_EFFORT_HEADER)?.trim().toLowerCase() ?? "";
    const effort = REASONING_EFFORTS.has(effortHeader) ? effortHeader : null;
    const moved = withModel(body, fallback, effort);
    if (moved === null || !this.state) return response;
    await response.body?.cancel().catch(() => undefined);
    const next = await this.forwardModelRequest(request, path, moved, undefined, requestId);
    this.log?.("warn", "omnirush.ai sub-agent model refused; sent on the main model", {
      requested,
      used: fallback,
      reason: refusal.reason,
      status: next.status,
      clientRequestId: requestId,
    });
    this.reportSubagentFallback(request, { requested, used: fallback, effort, reason: refusal.reason, status: next.status, ok: next.ok, clientRequestId: requestId });
    return next;
  }

  /** The request moved to the main model up front when its picked model is in its refusal cooldown. */
  private skipRefusedSubagentModel(
    request: Request,
    path: string,
    body: ArrayBuffer | string,
  ): { body: string; event: { requested: string; used: string; effort: string | null; reason: string } } | null {
    const fallback = request.headers.get(SUBAGENT_FALLBACK_MODEL_HEADER)?.trim() ?? "";
    if (!fallback || !FALLBACK_MODEL_ID.test(fallback) || !this.subagentModelRefused || (path !== "responses" && path !== "responses/compact")) return null;
    const requested = requestedModel(body);
    if (!requested || requested === fallback || !this.subagentModelRefused(requested)) return null;
    const effortHeader = request.headers.get(SUBAGENT_FALLBACK_EFFORT_HEADER)?.trim().toLowerCase() ?? "";
    const effort = REASONING_EFFORTS.has(effortHeader) ? effortHeader : null;
    const moved = withModel(body, fallback, effort);
    return moved === null ? null : { body: moved, event: { requested, used: fallback, effort, reason: "refused_recently" } };
  }

  private reportSubagentFallback(
    request: Request,
    event: { requested: string; used: string; effort: string | null; reason: string; status: number; ok: boolean; clientRequestId?: string },
  ): void {
    try {
      this.onSubagentFallback?.({
        sessionId: request.headers.get("x-omnirush-session-id"),
        rootSessionId: request.headers.get(SUBAGENT_ROOT_SESSION_HEADER),
        messageId: request.headers.get("x-omnirush-task-id"),
        ...event,
        at: Date.now(),
      });
    } catch {
      // A listener never breaks the request.
    }
  }

  /**
   * forward() for a model request, never throwing: a connection that fails
   * before any response is sent again after a short pause (the request never
   * reached, or never got an answer from, omnirush.ai), and once the retries
   * are spent the engine gets a retryable 503 with readable copy. Previously
   * the exception escaped the route and the engine saw a bare
   * `500 {"error":"internal_error"}` from the local server.
   */
  private async forwardModelRequest(
    request: Request,
    path: string,
    body: ArrayBuffer | string | undefined,
    accessToken: string | undefined,
    requestId: string,
  ): Promise<Response> {
    // Stock mode (stock-mode.mjs): the engine's request bodies go out as the engine wrote them (auth and routing only).
    const stock = stockMode();
    if (!stock) body = this.titleOnChatModel(request, path, body);
    // A model the chat's mode does not allow: refused here as the gateway would, never sent.
    if (this.modelInMode && body !== undefined && (path === "responses" || path === "responses/compact")) {
      const model = requestedModel(body);
      if (model && !(await this.modelInMode(model, this.boxRequest(request)))) {
        this.log?.("info", "omnirush.ai model not available in this chat's mode; not sent", { model, box: this.boxRequest(request), clientRequestId: requestId });
        const message = notInModeMessage(projectMode(this.boxRequest(request)));
        return Response.json({ detail: MODEL_NOT_IN_MODE, error: { type: "invalid_request_error", code: MODEL_NOT_IN_MODE, message } }, { status: 400, headers: { "x-should-retry": "false", [REFUSED_HEADER]: "1" } });
      }
    }
    // One model per chat: a main chat's agent request on another model than its first is refused here.
    const fixed = await this.fixedModelRefusal(request, path, body);
    if (fixed) return fixed;
    // The last capabilities answer's switch (this server's, kept on disk until it answers): a model request never waits for one.
    // The switch not known yet (capabilities failed, nothing kept): asked again, bounded, before this request.
    if (this.strictUnknown()) await this.askStrictAgain(request.headers.get("x-omnirush-session-id"));
    const strict = this.currentStrict();
    const strictHeader = strict?.header ?? (this.strictUnknown() ? STRICT_SESSION_HEADER : null);
    const unbound = strict ? await this.strictBindRefusal(strict, request, path, body) : null;
    if (unbound) return unbound;
    // Switch not known: the chat is held from this request until an answer that ran to its end confirms it.
    const unknownSession = !strict && strictHeader && body !== undefined && (path === "responses" || path === "responses/compact")
      ? request.headers.get("x-omnirush-session-id")
      : null;
    if (unknownSession && !this.bindsConfirmed.has(unknownSession)) this.uploadHold(unknownSession, "pending");
    const confirmed = (response: Response) => (unknownSession ? this.confirmOnCompletion(response, unknownSession) : response);
    const forwardedBody = !stock && path === "responses" && body !== undefined
      ? await withReasoningSummary(body, this.reasoningSummaryFor)
      : body;
    let failure: ReturnType<typeof fetchFailure> | null = null;
    for (let attempt = 0; attempt <= UNREACHABLE_RETRY_DELAYS_MS.length; attempt += 1) {
      if (attempt > 0) {
        await pause(UNREACHABLE_RETRY_DELAYS_MS[attempt - 1]!, request.signal);
        if (request.signal.aborted) break;
      }
      if (!this.state) break;
      try {
        const response = await this.forward(request, path, forwardedBody, attempt === 0 ? accessToken : this.state.accessToken, requestId, strictHeader);
        return confirmed(await this.strictRetry(response, async () => {
          // The gateway could not confirm the chat: it is bound again before the same request goes up.
          const session = request.headers.get("x-omnirush-session-id");
          if (strict && session) {
            this.bindSession.forget(session);
            const refused = await this.strictBindRefusal(strict, request, path, body);
            if (refused) return refused;
          }
          return this.forward(request, path, forwardedBody, this.state?.accessToken, requestId, strictHeader);
        }, request.signal));
      } catch (error) {
        if (request.signal.aborted) throw error;
        failure = fetchFailure(error);
        this.log?.("warn", "omnirush.ai model request failed before an answer", {
          path,
          attempt: attempt + 1,
          error: failure.name,
          code: failure.code,
          message: failure.message,
        });
      }
    }
    if (request.signal.aborted) throw new DOMException("The operation was aborted", "AbortError");
    if (!this.state) return Response.json({ error: "omnirush_account_required" }, { status: 401 });
    return unreachableResponse(
      "gateway_unreachable",
      `omnirush.ai: the model service could not be reached${failure?.code ? ` (${failure.code})` : ""}. Retrying shortly.`,
      requestId
    );
  }

  private forward(request: Request, path: string, body: ArrayBuffer | string | undefined, accessToken: string | undefined, requestId: string, strictHeader: string | null = null): Promise<Response> {
    if (!this.state) throw new Error("OmniRush gateway credentials are unavailable");
    const headers = new Headers();
    headers.set("Authorization", `Bearer ${accessToken ?? this.state.accessToken}`);
    headers.set("Content-Type", request.headers.get("content-type") || "application/json");
    headers.set("Accept", request.headers.get("accept") || "application/json");
    headers.set("x-omnirush-client-request-id", requestId);
    // x-omnirush-context-wrap: the handoff plugin marks an accepted wrap's
    // compaction so the gateway can hold it as the wrap (and confirm it).
    for (const name of ["x-omnirush-session-id", "x-omnirush-task-id", PARENT_SESSION_HEADER, "x-omnirush-context-wrap"]) {
      const value = request.headers.get(name);
      if (value) headers.set(name, value);
    }
    // The 2.x engine's compaction of a chat whose wrap was accepted (its session plugin names the request's kind).
    const wrapSession = request.headers.get("x-omnirush-session-id");
    if (wrapSession && request.headers.get("x-omnirush-request-kind") === "compaction" && this.contextWrap?.(wrapSession)) headers.set("x-omnirush-context-wrap", "1");
    // A box (sandbox) chat's request: the gateway judges its model in the box mode.
    if (this.boxRequest(request)) headers.set(BOX_HEADER, "1");
    // Whether this app runs stock (stock-mode.mjs), on every model request: the gateway checks it for event chats.
    headers.set("X-OmniRush-Stock", stockMode() ? "1" : "0");
    // Strict sessions: every request of a chat says so (the gateway binds it itself if ours failed).
    if (strictHeader && headers.has("x-omnirush-session-id")) headers.set(strictHeader, "1");
    // The engine going away cancels the request, unless its answer already finished (settleOnFinish reads it to its end).
    const upstream = new AbortController();
    const tail: StreamTail = { completed: false, abort: () => upstream.abort() };
    const onAbort = () => { if (!tail.completed) upstream.abort(request.signal.reason); };
    if (request.signal.aborted) upstream.abort(request.signal.reason);
    else request.signal.addEventListener("abort", onAbort, { once: true });
    return this.fetcher(upstreamUrl(this.state.gatewayUrl, path), {
      method: request.method,
      headers,
      ...(body ? { body } : {}),
      signal: upstream.signal,
    }).then((response) => {
      this.streamTails.set(response, tail);
      return response;
    }, (error: unknown) => {
      request.signal.removeEventListener("abort", onAbort);
      throw error;
    });
  }

  /**
   * A chat's switch to `model` on the 2.x engine (POST /api/session/:id/model): refused as its next request would
   * be (fixedModelRefusal) when the chat is pinned to another provider, so the engine session keeps its own model.
   * A chat not pinned yet, the same model, or one of its provider: null.
   */
  async modelSwitchRefusal(session: string, model: string): Promise<Response | null> {
    const pin = this.sessionModels.get(session);
    const asked = model.replace(/^omnirush\//, "");
    if (!pin || pin === asked || (await this.switchable(pin, asked))) return null;
    this.log?.("info", "omnirush.ai chat model switch refused (another provider)", { pin, asked });
    return Response.json({ detail: SESSION_MODEL_FIXED, error: { type: "invalid_request_error", code: SESSION_MODEL_FIXED, message: `This chat runs on ${pin}. Start a new chat to use ${asked}.` } }, { status: 400, headers: { "x-should-retry": "false", [REFUSED_HEADER]: "1" } });
  }

  /**
   * Every context-bearing request keeps the chat's provider, including
   * summaries, compaction and children: a model of another provider never
   * reaches the gateway. One of the same provider (`switchable`) goes as asked;
   * the chat's pin keeps its first model.
   */
  private async fixedModelRefusal(request: Request, path: string, body: ArrayBuffer | string | undefined): Promise<Response | null> {
    if (body === undefined || (path !== "responses" && path !== "responses/compact")) return null;
    const session = request.headers.get("x-omnirush-session-id");
    if (!session) return request.headers.has(PARENT_SESSION_HEADER) || request.headers.has(SUBAGENT_ROOT_SESSION_HEADER)
      ? Response.json({error: {type: "invalid_request_error", code: SESSION_MODEL_FIXED, message: "A sub-agent request must name its session and pinned parent."}}, {status: 400, headers: {"x-should-retry": "false", [REFUSED_HEADER]: "1"}})
      : null;
    let parsed: unknown;
    try {
      parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
    } catch {
      return null;
    }
    if (!isRecord(parsed) || typeof parsed.model !== "string" || !parsed.model.replace(/^omnirush\//, "").trim()) return Response.json({error: {type: "invalid_request_error", code: SESSION_MODEL_FIXED, message: "A session request must name its fixed model."}}, {status: 400, headers: {"x-should-retry": "false", [REFUSED_HEADER]: "1"}});
    const model = parsed.model.replace(/^omnirush\//, "");
    const parents = [request.headers.get(SUBAGENT_ROOT_SESSION_HEADER), request.headers.get(PARENT_SESSION_HEADER)].filter((id): id is string => Boolean(id));
    const pins = [session, ...parents].map(id => this.sessionModels.get(id)).filter((pin): pin is string => Boolean(pin));
    let first: string | undefined;
    for (const pin of pins) if (!(await this.switchable(pin, model))) { first = pin; break; }
    if (!first && !parents.some(id => !this.sessionModels.has(id))) {
      if (!this.sessionModels.has(session)) this.pinChatModel(session, model);
      return null;
    }
    this.log?.("info", "omnirush.ai chat model change refused (another provider)", { first, model });
    return Response.json({ detail: SESSION_MODEL_FIXED, error: { type: "invalid_request_error", code: SESSION_MODEL_FIXED, message: first ? `This chat runs on ${first}. Start a new chat to use ${model}.` : "Resume the parent chat before continuing this sub-agent; its fixed model is unavailable." } }, { status: 400, headers: { "x-should-retry": "false", [REFUSED_HEADER]: "1" } });
  }

  /**
   * A chat's title request (the title plugin marks it, with the chat's own
   * model) goes on the chat's model: the engine picks its cheapest model for
   * titles, and a chat runs on one model only.
   */
  private titleOnChatModel(request: Request, path: string, body: ArrayBuffer | string | undefined): ArrayBuffer | string | undefined {
    const session = request.headers.get("x-omnirush-session-id");
    if (body === undefined || path !== "responses" || !session || request.headers.get(TITLE_HEADER) !== "1") return body;
    const named = (request.headers.get(CHAT_MODEL_HEADER) ?? "").replace(/^omnirush\//, "");
    const chat = this.sessionModels.get(session) ?? (FALLBACK_MODEL_ID.test(named) ? named : null);
    const asked = requestedModel(body);
    if (!chat || !asked || asked.replace(/^omnirush\//, "") === chat) return body;
    return withModel(body, asked.startsWith("omnirush/") ? `omnirush/${chat}` : chat, null) ?? body;
  }

  /**
   * A chat's title request: its reply passes through unchanged and, once it ends, goes to onModelRequest
   * with the request as the engine sent it (on the chat's model) and the title text.
   */
  private titleRecord(request: Request, path: string, body: ArrayBuffer | string | undefined, response: Response, stream: ReadableStream<Uint8Array> | null): ReadableStream<Uint8Array> | null {
    const session = request.headers.get("x-omnirush-session-id");
    if (!this.onModelRequest || !stream || !session || body === undefined || path !== "responses" || request.headers.get(TITLE_HEADER) !== "1") return stream;
    const sent = this.titleOnChatModel(request, path, body) ?? body;
    const contentType = response.headers.get("content-type") ?? "";
    const decoder = new TextDecoder();
    let reply = "";
    let bytes = 0;
    const record = (completed: boolean) => {
      reply += decoder.decode();
      let parsed: unknown = null;
      try { parsed = JSON.parse(typeof sent === "string" ? sent : new TextDecoder().decode(sent)); } catch { /* not JSON: kept as null */ }
      const model = isRecord(parsed) && typeof parsed.model === "string" ? parsed.model : null;
      try {
        this.onModelRequest?.(session, { schema: 1, kind: "title", route: path, model, status: response.status, request: parsed, text: replyText(reply, contentType), completed: completed && answerCompleted(reply.slice(-STRICT_TAIL_CHARS), contentType), ...(bytes >= MAX_TITLE_REPLY_BYTES ? { reply_truncated: true } : {}) });
      } catch { /* a listener never breaks the request */ }
    };
    // Recorded once: at the end of the reply, or when the engine stops reading it (the 2.x engine cancels the
    // title stream once it has the title); the reply's own tail says whether the answer finished.
    let recorded = false;
    const once = (completed: boolean) => { if (!recorded) { recorded = true; record(completed); } };
    const reader = stream.getReader();
    return new ReadableStream<Uint8Array>({
      pull: async (controller) => {
        try {
          const { done, value } = await reader.read();
          if (done) { once(true); controller.close(); return; }
          if (bytes < MAX_TITLE_REPLY_BYTES) { reply += decoder.decode(value, { stream: true }); bytes += value.byteLength; }
          controller.enqueue(value);
        } catch (error) {
          once(false);
          controller.error(error);
        }
      },
      cancel: (reason) => { once(true); return reader.cancel(reason); },
    });
  }

  /**
   * A chat's first agent request binds the chat (its pinned model, its mode,
   * the box revision and the uploader's redaction policy); a sub-agent names
   * its main chat. A conflict or a verification refusal is answered here and
   * never sent; anything else goes on (model-modes/strict-sessions.mjs).
   */
  private async strictBindRefusal(strict: StrictSessions, request: Request, path: string, body: ArrayBuffer | string | undefined): Promise<Response | null> {
    const session = request.headers.get("x-omnirush-session-id");
    if (body === undefined || (path !== "responses" && path !== "responses/compact") || !session) return null;
    let parsed: unknown;
    try {
      parsed = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
    } catch {
      return null;
    }
    if (!isRecord(parsed) || typeof parsed.model !== "string") return null;
    const model = parsed.model.replace(/^omnirush\//, "");
    const rootId = request.headers.get(PARENT_SESSION_HEADER);
    const rootModel = rootId ? this.sessionModels.get(rootId) : null;
    const rootPin = rootId ? this.chatPin?.(rootId) ?? null : null;
    const ownPin = this.chatPin?.(session) ?? null;
    // A sub-agent has no prompt of its own: it takes its main chat's capture policy, as the server does.
    const capturePolicy = ownPin?.capturePolicy ?? rootPin?.capturePolicy ?? null;
    // Under enforce nothing of an unconfirmed chat is uploaded until its binding is (the server's late check).
    const enforce = strict.mode === "enforce";
    if (enforce && !this.bindsConfirmed.has(session)) this.uploadHold(session, "pending");
    const outcome = await this.bindSession({
      path: strict.path,
      enforce,
      sessionId: session,
      rootId,
      model: this.sessionModels.get(session) ?? model,
      mode: projectMode(this.boxRequest(request)),
      revision: ownPin?.revision ?? rootPin?.revision ?? null,
      capturePolicy,
      root: rootId && rootModel ? { model: rootModel, mode: projectMode(rootPin?.box ?? this.boxSessions.has(rootId)), revision: rootPin?.revision ?? null, capturePolicy: rootPin?.capturePolicy ?? null } : null,
    });
    // The server keeps a chat's first capture policy: its pin and uploads follow the stored one.
    const stored = "binding" in outcome ? outcome.binding?.capture_policy : undefined;
    if (typeof stored === "string" && stored && stored !== capturePolicy) {
      try { this.onCapturePolicy?.(session, stored); } catch { /* a listener never breaks the request */ }
    }
    if ("binding" in outcome && outcome.binding) {
      const binding = outcome.binding;
      const late = typeof binding.late_reason === "string" && binding.late_reason ? binding.late_reason : binding.bound_late === true ? "bound_late" : null;
      try { this.onBinding?.(session, { verified: binding.verified === true && !late, ...(late ? { lateReason: late } : {}) }); } catch { /* a listener never breaks the request */ }
    }
    if (!("refused" in outcome)) {
      this.bindConfirmed(session, enforce);
      return null;
    }
    if (enforce && !this.bindsConfirmed.has(session)) this.uploadHold(session, "refused");
    this.log?.("info", "omnirush.ai refused this chat's binding; not sent", { code: outcome.refused.code });
    const { code, message, retry } = outcome.refused;
    if (retry) return Response.json({ detail: code, error: { type: "server_error", code, message } }, { status: 503, headers: { "x-should-retry": "true", [REFUSED_HEADER]: "1" } });
    return Response.json({ detail: code, error: { type: "invalid_request_error", code, message } }, { status: code === VERIFICATION_REQUIRED ? 403 : 400, headers: { "x-should-retry": "false", [REFUSED_HEADER]: "1" } });
  }

  private uploadHold(sessionId: string, state: "pending" | "refused" | "confirmed"): void {
    this.holdSeq += 1;
    try { this.onUploadHold?.(sessionId, state, this.holdSeq); } catch { /* a listener never breaks the request */ }
  }

  /** The chat's binding is confirmed in this process: its held uploads may go out. */
  private bindConfirmed(sessionId: string, release: boolean): void {
    if (this.bindsConfirmed.has(sessionId)) return;
    this.bindsConfirmed.add(sessionId);
    while (this.bindsConfirmed.size > 4000) this.bindsConfirmed.delete(this.bindsConfirmed.values().next().value!);
    if (release) this.uploadHold(sessionId, "confirmed");
  }

  /**
   * Switch not known yet: the gateway binds the chat itself on its first request (the strict header). Only an
   * answer that ran to its normal end confirms it; an error, a refusal, a non-2xx (426 included) or a stream cut
   * short does not, and the chat's uploads stay held.
   */
  private confirmOnCompletion(response: Response, sessionId: string): Response {
    if (!response.ok || !response.body || this.bindsConfirmed.has(sessionId)) return response;
    const contentType = response.headers.get("content-type") ?? "";
    const decoder = new TextDecoder();
    let tail = "";
    const watch = new TransformStream<Uint8Array, Uint8Array>({
      transform: (chunk, controller) => {
        tail = (tail + decoder.decode(chunk, { stream: true })).slice(-STRICT_TAIL_CHARS);
        controller.enqueue(chunk);
      },
      flush: () => {
        tail = (tail + decoder.decode()).slice(-STRICT_TAIL_CHARS);
        if (answerCompleted(tail, contentType)) this.bindConfirmed(sessionId, true);
      },
    });
    return new Response(response.body.pipeThrough(watch), { status: response.status, statusText: response.statusText, headers: response.headers });
  }

  /**
   * strict_session_unavailable (503 under enforce: the server could not look up or bind the chat): the same
   * request again after its Retry-After, at most STRICT_RETRIES times, never on another model or unbound;
   * the engine gets one answer, so the prompt stays one turn.
   */
  private async strictRetry(response: Response, again: () => Promise<Response>, signal: AbortSignal): Promise<Response> {
    for (let attempt = 0; response.status === 503 && attempt < STRICT_RETRIES; attempt += 1) {
      const text = await response.clone().text().catch(() => "");
      if (!text.includes(`"${STRICT_UNAVAILABLE}"`)) break;
      const after = response.headers.has("retry-after") ? Number(response.headers.get("retry-after")) : Number.NaN;
      const wait = (Number.isFinite(after) && after >= 0 ? Math.min(after, 30) : 3) * 1000;
      await response.body?.cancel().catch(() => undefined);
      this.log?.("info", "omnirush.ai could not confirm this chat yet; the same request again", { attempt: attempt + 1, waitMs: wait });
      await pause(wait, signal);
      if (signal.aborted || !this.state) return response;
      response = await again();
    }
    return response;
  }

  /** Whether this server's strict-session switch is unknown: its capabilities check failed, no answer since and none kept on disk. */
  private strictUnknown(): boolean {
    if (!this.state || !this.capabilitiesFailed) return false;
    const origin = originOf(this.state.gatewayUrl);
    return this.strictOrigin !== origin && !Object.hasOwn(this.savedStrict(), origin);
  }

  /**
   * Capabilities asked again past their failure cooldown (at most once per STRICT_ASK_MS, waited for at
   * most STRICT_ASK_WAIT_MS): a turn after a failed check binds explicitly as soon as the server answers.
   * A chat not confirmed yet (its first turn, and that turn's retry right after a failed ask) always asks:
   * sent on the unknown switch it would go out with no binding and no capture policy.
   */
  private async askStrictAgain(session: string | null): Promise<void> {
    if (Date.now() - this.strictAskedAt < STRICT_ASK_MS && (!session || this.bindsConfirmed.has(session))) return;
    this.strictAskedAt = Date.now();
    this.capabilityFailure = null;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const late = new Promise<void>((resolve) => { timer = setTimeout(resolve, STRICT_ASK_WAIT_MS); });
    await Promise.race([this.sessionUploadCapabilities().then(() => undefined, () => undefined), late]);
    clearTimeout(timer);
  }

  /** The strict sessions in force for the current server: its last answer in this process, else the one kept on disk. */
  private currentStrict(): StrictSessions | null {
    if (!this.state) return null;
    const origin = originOf(this.state.gatewayUrl);
    if (this.strictOrigin === origin) return this.strictBind;
    return this.savedStrict()[origin] ?? null;
  }

  private savedStrict(): Record<string, StrictSessions | null> {
    if (!this.strictStateFile) return {};
    try {
      const saved: unknown = JSON.parse(readFileSync(this.strictStateFile, "utf8"));
      if (!isRecord(saved)) return {};
      return Object.fromEntries(Object.entries(saved).map(([origin, value]) => [origin, isRecord(value) ? strictSessions({ strict_sessions: { ...value, bind: true } }) : null]));
    } catch {
      return {};
    }
  }

  /** A capabilities answer's strict sessions: in force now, and kept on disk for this server. */
  private rememberStrict(gatewayUrl: string, capabilities: TraceCapabilities): void {
    this.strictBind = strictSessions(capabilities);
    this.strictOrigin = originOf(gatewayUrl);
    // The server holds nothing back (strict off or observe): no chat's uploads wait for a binding any more.
    if (this.strictBind?.mode !== "enforce") this.uploadHold(ALL_HELD_CHATS, "confirmed");
    if (!this.strictStateFile) return;
    try {
      mkdirSync(dirname(this.strictStateFile), { recursive: true, mode: 0o700 });
      const tmp = `${this.strictStateFile}.${randomUUID()}.tmp`;
      writeFileSync(tmp, JSON.stringify({ ...this.savedStrict(), [originOf(gatewayUrl)]: this.strictBind }), { mode: 0o600 });
      renameSync(tmp, this.strictStateFile);
    } catch {
      // Kept in memory; the next answer writes again.
    }
  }

  /** Whether a request comes from a box chat: marked so, or from a chat (or its main chat) marked earlier. */
  private boxRequest(request: Request): boolean {
    const sessions = [request.headers.get("x-omnirush-session-id"), request.headers.get(PARENT_SESSION_HEADER)].filter((id): id is string => Boolean(id));
    if (request.headers.get(BOX_HEADER) === "1") {
      for (const id of sessions) {
        this.boxSessions.delete(id);
        this.boxSessions.add(id);
      }
      while (this.boxSessions.size > 1024) this.boxSessions.delete(this.boxSessions.values().next().value!);
      return true;
    }
    // The chat's durable pin (box/service.ts chatPin): a title, a compaction or a request after a restart is unmarked.
    return sessions.some((id) => this.boxSessions.has(id) || this.chatPin?.(id)?.box === true);
  }

  private refresh(expectedAccessToken: string): Promise<boolean> {
    if (this.state?.accessToken !== expectedAccessToken) return Promise.resolve(true);
    this.refreshInFlight ??= (this.refreshOwner
      ? this.refreshFromOwner(this.refreshOwner, expectedAccessToken)
      : this.performRefresh(expectedAccessToken))
      .then((rotated) => {
        if (rotated) this.lastRefreshTransient = false;
        return rotated;
      }, (error: unknown) => {
        // Never shared as a rejection: every request waiting on this refresh
        // would otherwise fail with an unhandled 500 at once.
        this.lastRefreshTransient = true;
        const failure = fetchFailure(error);
        this.log?.("warn", "omnirush.ai device refresh failed; keeping the session", { error: failure.name, code: failure.code, message: failure.message });
        return false;
      })
      .finally(() => {
        this.refreshInFlight = null;
      });
    return this.refreshInFlight;
  }

  /**
   * The desktop account store owns the device session: it alone spends the
   * refresh token, one rotation at a time, and saves the result before it
   * answers. After a 401 the broker hands it the access token that was
   * refused and takes the pair it gets back (one it rotated earlier, or a new
   * rotation): the broker never sends a refresh token, and never acts on a
   * pair of its own that can go stale. A rejection leaves the session as it
   * is (the owner could not rotate right now); null means the session is gone.
   */
  private async refreshFromOwner(owner: NonNullable<OmniRushGatewayCredentials["refresh"]>, rejectedAccessToken: string): Promise<boolean> {
    const asked = this.state;
    if (!asked) return false;
    const current = await owner(rejectedAccessToken);
    if (this.state !== asked) return Boolean(this.state);
    if (!current) {
      this.state = null;
      this.resetCapabilities();
      void this.invalidate?.().catch(() => undefined);
      return false;
    }
    if (current.accessToken === rejectedAccessToken) {
      this.lastRefreshTransient = true;
      return false;
    }
    this.state = {
      gatewayUrl: normalizedGatewayUrl(current.gatewayUrl) ?? asked.gatewayUrl,
      accessToken: current.accessToken,
      refreshToken: current.refreshToken,
    };
    if (this.state.gatewayUrl !== asked.gatewayUrl) this.resetCapabilities();
    return true;
  }

  /**
   * One refresh round trip of a broker that holds its credentials alone (the
   * standalone server with credentials from the environment): sign out only
   * when the server retired the token.
   */
  private async performRefresh(expectedAccessToken: string): Promise<boolean> {
    if (!this.state) return false;
    if (this.state.accessToken !== expectedAccessToken) return true;
    const spent = this.state;
    const outcome = await this.rotate(spent);
    if (outcome.kind === "rotated") return true;
    this.lastRefreshTransient = outcome.kind === "unavailable" || outcome.kind === "contended";
    if (outcome.kind !== "retired") return false;
    if (this.state !== spent) return Boolean(this.state);
    this.state = null;
    this.resetCapabilities();
    void this.invalidate?.().catch(() => undefined);
    return false;
  }

  /** Spends `from.refreshToken`; on success the state is the rotated pair. */
  private async rotate(from: CredentialState): Promise<RefreshOutcome> {
    const response = await this.fetcher(refreshUrl(from.gatewayUrl), {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refresh_token: from.refreshToken }),
      signal: AbortSignal.timeout(20_000),
    });
    if (!response.ok) {
      await response.body?.cancel().catch(() => undefined);
      if (response.status === 401 || response.status === 403) return { kind: "retired" };
      if (response.status === 409) return { kind: "contended" };
      return { kind: "unavailable" };
    }
    const payload: unknown = await response.json();
    if (!payload || typeof payload !== "object") return { kind: "unavailable" };
    const accessToken = Reflect.get(payload, "access_token");
    const refreshToken = Reflect.get(payload, "refresh_token");
    const gatewayUrl = normalizedGatewayUrl(String(Reflect.get(payload, "gateway_url") ?? from.gatewayUrl));
    if (typeof accessToken !== "string" || typeof refreshToken !== "string" || !gatewayUrl) return { kind: "unavailable" };
    if (!this.state) return { kind: "unavailable" };
    this.state = { accessToken, refreshToken, gatewayUrl };
    if (gatewayUrl !== from.gatewayUrl) this.resetCapabilities();
    return { kind: "rotated" };
  }
}