Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

238 KB
Raw Blame
/**
 * OpenCode plugin for the OmniRoute AI Gateway.
 *
 * Implements the official `@opencode-ai/plugin` Plugin contract (auth +
 * provider + config hooks) to drive a running OmniRoute instance from
 * OpenCode without hand-curated `provider.<id>.models` blocks in
 * opencode.json[c]:
 *
 *   - `auth`     — registers `/connect <providerId>` flow (API key prompt)
 *   - `provider` — dynamic `/v1/models` fetch with TTL cache, capabilities
 *                  pass-through (OmniRoute is the source of truth — no
 *                  client-side variant synthesis)
 *   - `config`   — backward-compat shim for OC versions that predate the
 *                  `provider.models` hook (≤ 1.14.48)
 *
 * Two ways to consume the plugin:
 *
 *  1. Single-instance (default `providerId: "omniroute"`):
 *
 *     ```json
 *     {
 *       "$schema": "https://opencode.ai/config.json",
 *       "plugin": ["@omniroute/opencode-plugin"]
 *     }
 *     ```
 *
 *  2. Multi-instance via plugin options (prod + preprod side by side):
 *
 *     ```json
 *     {
 *       "$schema": "https://opencode.ai/config.json",
 *       "plugin": [
 *         ["@omniroute/opencode-plugin", { "providerId": "omniroute" }],
 *         ["@omniroute/opencode-plugin", { "providerId": "omniroute-preprod" }]
 *       ]
 *     }
 *     ```
 *
 * Then `opencode connect <providerId>` to provision the API key per instance.
 *
 * Companion library: `@omniroute/opencode-provider` (build-time config generator)
 * remains supported for users who can't run plugins (CI, scripted scaffolding).
 *
 * @see https://opencode.ai/docs/plugins for the OpenCode plugin contract.
 * @see https://github.com/diegosouzapw/OmniRoute for the AI Gateway.
 */

import { createHash } from "node:crypto";
import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
import * as os from "node:os";
import * as path from "node:path";
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { randomUUID } from "node:crypto";
import type { AuthHook, Config, Plugin, PluginOptions, ProviderHook } from "@opencode-ai/plugin";
import { tool } from "@opencode-ai/plugin";
import type { Model as ModelV2 } from "@opencode-ai/sdk/v2";
import { z } from "zod";
import {
  createLogger,
  logger as _logger,
  type Logger as _Logger,
  type LogLevel as _LogLevel,
} from "./logger.js";
import {
  PROVIDER_TAG_SEPARATOR as _PROVIDER_TAG_SEPARATOR,
  shortProviderLabel as _shortProviderLabel,
  normaliseFreeLabel as _normaliseFreeLabel,
  formatFreeBudget,
  type FreeModelFreeType,
} from "./naming.js";
import { applyOmniRouteInferenceTelemetry } from "./telemetry.js";

/**
 * Minimal leveled logger sink accepted by the default fetchers and the static
 * catalog builder. A full `Logger` satisfies it structurally; the config hook
 * injects the same partial shape (see `createOmniRouteConfigHook` deps).
 */
type OmniRouteLoggerSink = {
  error?: (message: string, ...args: unknown[]) => void;
  warn: (message: string, ...args: unknown[]) => void;
  debug?: (message: string, ...args: unknown[]) => void;
};

/**
 * Zod schema for plugin options accepted as the second element of the
 * `plugin: [name, opts]` tuple in opencode.json. Strict by design — unknown
 * keys are rejected so typos in opencode.json surface immediately at plugin
 * construction time instead of silently being dropped.
 *
 * Doc per field:
 *
 *  - `providerId`     OpenCode provider id this plugin instance binds to.
 *                     Multiple plugin instances coexist by giving each a
 *                     different `providerId` ("omniroute", "omniroute-preprod",
 *                     "omniroute-local"). Maps to `ProviderHook.id` and
 *                     `AuthHook.provider` in the @opencode-ai/plugin contract.
 *                     Default: "omniroute".
 *  - `displayName`    Label rendered in the OpenCode UI. Default derives
 *                     from providerId.
 *  - `modelCacheTtl`  `/v1/models` TTL cache duration in milliseconds.
 *                     Default: 300_000 (5 min).
 *  - `autoSyncIntervalMs` Background catalog re-discovery while OpenCode is
 *                     running. Default: 300_000 (5 min). Minimum: 60_000.
 *                     Set `0` to disable background auto-sync (TTL on-demand
 *                     discovery still applies via `modelCacheTtl`).
 *  - `baseURL`        Override base URL for this OmniRoute instance. When
 *                     absent, the loader falls back to a credential-attached
 *                     baseURL set by `/connect`.
 *  - `managementReadToken` Optional read-only management-plane bearer token.
 *                     Used only for catalog GETs under `/api/*`; `/v1/*`
 *                     inference continues to use the connected `apiKey`.
 *                     Falls back to `apiKey` when unset.
 */
/**
 * Optional feature toggles. Every field is opt-in/out per call; defaults
 * mirror the v0.1.0 behaviour so existing opencode.json files do not need
 * to change.
 *
 *  - `combos`               Discover `/api/combos` and surface them as
 *                           pseudo-models with LCD capabilities. Default true.
 *  - `enrichment`           Pull display names + pricing from
 *                           `/api/pricing/models` and overlay them onto the
 *                           ModelV2 entries derived from `/v1/models`. Solves
 *                           the "raw id in UI" complaint without client-side
 *                           heuristics. Default true.
 *  - `compressionMetadata`  Pull `/api/context/combos` so combo entries can
 *                           be tagged with their compression pipeline
 *                           (e.g. `rtk:standard → caveman:full`). Off by
 *                           default — adds one network call per refresh and
 *                           the data is only useful for combo entries.
 *  - `geminiSanitization`   Strip `$schema`/`$ref`/`additionalProperties`
 *                           from `tools[].function.parameters` when the
 *                           model id contains "gemini". Default true.
 *  - `mcpAutoEmit`          Auto-write an `mcp.<providerId>` remote entry
 *                           into the OC config pointing at
 *                           `<baseURL>/api/mcp/stream` with the resolved
 *                           Bearer token. Default false — keeps opencode.json
 *                           in control unless explicitly opted in.
 *  - `mcpToken`             Optional separate Bearer token to use in the
 *                           auto-emitted MCP entry. Falls back to the
 *                           provider's API key (from auth.json) when unset.
 *                           Useful when a narrower-scoped MCP-only key is
 *                           preferred over the chat/inference key.
 *  - `fetchInterceptor`     Inject Authorization: Bearer + Content-Type only
 *                           on same-origin `/v1/chat/completions` and
 *                           `/v1/models` requests. Default true.
 *  - `debugLog`             Capture every outbound request + response to a
 *                           JSONL file at
 *                           `~/.local/share/opencode/plugins/omniroute-debug-{providerId}.jsonl`.
 *                           Each line: `{ reqId, ts, url, method, reqBody,
 *                           resStatus, resBody, durationMs }`.
 *                           Default false. Opt-in.
 *  - `apiFormat`            Per-provider-prefix API format routing. Model IDs
 *                           whose prefix (the part before `/`) matches an entry
 *                           in `anthropicPrefixes` are served via the Anthropic
 *                           SDK (`@ai-sdk/anthropic`, sends to `/v1/messages`
 *                           with native cache_control, tool_choice, etc.).
 *                           All other models fall back to `openai-compatible`.
 *
 *                           Default `anthropicPrefixes`:
 *                             ["cc", "claude", "anthropic", "kiro", "kr"]
 *                           (covers OmniRoute's canonical Anthropic aliases).
 *
 *                           Set `anthropicPrefixes: []` to disable and force
 *                           everything through OpenAI-compat.
 *
 *                           Example:
 *                           ```json
 *                           "apiFormat": { "anthropicPrefixes": ["cc","claude","anthropic","kiro"] }
 *                           ```
 */
const apiFormatSchema = z
  .object({
    anthropicPrefixes: z.array(z.string()).optional(),
  })
  .strict()
  .optional();

const featuresSchema = z
  .object({
    combos: z.boolean().optional(),
    autoCombos: z.boolean().optional(),
    enrichment: z.boolean().optional(),
    compressionMetadata: z.boolean().optional(),
    geminiSanitization: z.boolean().optional(),
    mcpAutoEmit: z.boolean().optional(),
    mcpToken: z.string().min(1).optional(),
    fetchInterceptor: z.boolean().optional(),
    usableOnly: z.boolean().optional(),
    visibleModels: z.array(z.string().min(1)).optional(),
    hiddenModels: z.array(z.string().min(1)).optional(),
    diskCache: z.boolean().optional(),
    /**
     * Opt-in max age for a disk-cache fallback snapshot, in milliseconds.
     * Unset or `0` keeps the historical unbounded default: a stale snapshot
     * is still served. A positive bound does not refuse the snapshot; the
     * fallback log escalates from warn to error once the snapshot is older.
     */
    diskCacheMaxAgeMs: z.number().nonnegative().optional(),
    providerTag: z.boolean().optional(),
    debugLog: z.boolean().optional(),
    startupDebug: z.boolean().optional(),
    logLevel: z.enum(["error", "warn", "info", "debug"]).optional(),
    apiFormat: apiFormatSchema,
  })
  .strict();

const optionsSchema = z
  .object({
    providerId: z
      .string()
      .min(1)
      .regex(/^[a-z0-9-]+$/i, "providerId must be a slug")
      .optional(),
    displayName: z.string().min(1).optional(),
    modelCacheTtl: z.number().positive().optional(),
    /**
     * Background auto-discovery interval while the harness is running.
     * `0` disables background polling. Values in (0, 60000) are clamped up
     * to 60000. Default when unset: 300000.
     */
    autoSyncIntervalMs: z.number().int().nonnegative().optional(),
    baseURL: z
      .string()
      .trim()
      .refine(isHttpUrl, "baseURL must be an http(s) URL, for example http://localhost:20128")
      .optional(),
    managementReadToken: z.string().min(1).optional(),
    features: featuresSchema.optional(),
  })
  .strict();

/**
 * Plugin options shape — inferred directly from the Zod schema so the
 * validator and the static type can never drift. Replaces the standalone
 * interface previously declared here (T-02). Every consumer continues to
 * import `OmniRoutePluginOptions` as before; only the source of truth
 * shifted from a hand-written interface to `z.infer<typeof optionsSchema>`.
 */
export type OmniRoutePluginOptions = z.infer<typeof optionsSchema>;

/**
 * Explicit default state for every boolean `features.*` toggle.
 *
 * #7624: `featuresSchema` marks every flag `.optional()` with no default, and
 * the effective value is applied implicitly at each read site (default-ON flags
 * use the `features.X !== false` convention, default-OFF flags use
 * `features.X === true`). That implicit convention is scattered across the file,
 * so an operator who omits the `features` block cannot tell whether
 * combos / enrichment are enabled — they think features are
 * disabled when they are actually on. Centralising the declared defaults here
 * (mirroring the read-site conventions exactly, so runtime behaviour is
 * unchanged) makes the effective flags introspectable and self-documenting.
 *
 * `features.autoCombos` is accepted but ignored: it stays in the schema (and
 * in the defaults below) so existing configurations still validate, but no
 * read site consults it anymore and it is hidden from startup diagnostics.
 */
export const OMNIROUTE_FEATURE_DEFAULTS = {
  // default-ON (read sites use `features.X !== false`)
  combos: true,
  autoCombos: true,
  enrichment: true,
  diskCache: true,
  providerTag: true,
  fetchInterceptor: true,
  geminiSanitization: true,
  // default-OFF (read sites use `features.X === true`)
  compressionMetadata: false,
  usableOnly: false,
  // Array flags: unset/empty = no filter. These are not boolean toggles —
  // they are operator-curated model-ID lists applied in the dynamic and static
  // hooks alongside usableOnly (all filters AND together).
  // visibleModels: undefined,  // allowlist — only listed IDs pass
  // hiddenModels: undefined,  // blocklist — listed IDs are dropped
  mcpAutoEmit: false,
  debugLog: false,
  startupDebug: false,
} as const;

/** Union of the boolean feature-flag keys declared in `OMNIROUTE_FEATURE_DEFAULTS`. */
export type OmniRouteFeatureFlag = keyof typeof OMNIROUTE_FEATURE_DEFAULTS;

/**
 * Resolve the EFFECTIVE boolean state of every feature toggle, applying the
 * declared default for any flag the operator omitted. A missing `features`
 * block (or an empty one) yields the full default set — so callers and the
 * startup diagnostics can surface exactly which features are active instead of
 * relying on the implicit `!== false` / `=== true` conventions. Purely
 * derived: it does not mutate options nor change any read-site behaviour.
 */
export function resolveEffectiveFeatureFlags(
  features?: OmniRoutePluginOptions["features"]
): Record<OmniRouteFeatureFlag, boolean> {
  const f: Partial<Record<OmniRouteFeatureFlag, boolean>> = features ?? {};
  const out = {} as Record<OmniRouteFeatureFlag, boolean>;
  for (const key of Object.keys(OMNIROUTE_FEATURE_DEFAULTS) as OmniRouteFeatureFlag[]) {
    const val = f[key];
    out[key] = typeof val === "boolean" ? val : OMNIROUTE_FEATURE_DEFAULTS[key];
  }
  return out;
}

export const OMNIROUTE_PROVIDER_KEY = "omniroute" as const;

/** Deployed plugin version (injected at build time by tsup define). */
export const PLUGIN_VERSION: string =
  ((globalThis as Record<string, unknown>).__PLUGIN_VERSION__ as string) ?? "dev";

/** Deployed plugin git commit hash (injected at build time by tsup define). */
export const PLUGIN_GIT_HASH: string =
  ((globalThis as Record<string, unknown>).__PLUGIN_GIT_HASH__ as string) ?? "unknown";

export const DEFAULT_MODEL_CACHE_TTL_MS = 300_000 as const;

/** Default background auto-discovery interval (matches modelCacheTtl default). */
export const DEFAULT_AUTO_SYNC_INTERVAL_MS = 300_000 as const;

/** Minimum positive background auto-discovery interval. */
export const MIN_AUTO_SYNC_INTERVAL_MS = 60_000 as const;

/**
 * Sanitize background auto-sync interval.
 *  - unset/invalid → default 300_000
 *  - explicit 0 → disabled
 *  - (0, 60000) → clamped to 60000
 *  - ≥ 60000 → kept as integer ms
 */
export function sanitizeAutoSyncIntervalMs(value: unknown): number {
  if (value === undefined || value === null) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
  const n = Math.trunc(value);
  if (n === 0) return 0;
  if (n < 0) return DEFAULT_AUTO_SYNC_INTERVAL_MS;
  if (n < MIN_AUTO_SYNC_INTERVAL_MS) return MIN_AUTO_SYNC_INTERVAL_MS;
  return n;
}

// Manual trim helpers avoid polynomial-regex CodeQL warnings on
// user-supplied baseURL strings (string.replace(/\/+$/, "")). The same
// behaviour, no backtracking.
function trimTrailingSlashes(value: string): string {
  let i = value.length;
  while (i > 0 && value.charCodeAt(i - 1) === 0x2f /* "/" */) i--;
  return i === value.length ? value : value.slice(0, i);
}

function trimTrailingDashes(value: string): string {
  let i = value.length;
  while (i > 0 && value.charCodeAt(i - 1) === 0x2d /* "-" */) i--;
  return i === value.length ? value : value.slice(0, i);
}
function trimLeadingDashes(value: string): string {
  let i = 0;
  while (i < value.length && value.charCodeAt(i) === 0x2d /* "-" */) i++;
  return i === 0 ? value : value.slice(i);
}

/**
 * Resolve effective options from the optional plugin-options object,
 * applying defaults. Centralises the providerId fallback so every hook
 * sees a consistent identifier.
 */
export function resolveOmniRoutePluginOptions(opts?: OmniRoutePluginOptions): Required<
  Pick<
    OmniRoutePluginOptions,
    "providerId" | "displayName" | "modelCacheTtl" | "autoSyncIntervalMs"
  >
> & {
  /**
   * #6859: the UNPREFIXED provider id ("omniroute", "omniroute-preprod", …).
   * `providerId` above is auto-prefixed with "opencode-" ONLY to satisfy OC
   * 1.17.8+'s native-adapter gate ({openai, anthropic, opencode*}) — that
   * prefixed value is OC-internal and must be used ONLY for AuthHook.provider
   * and provider-registration keys (the OC config-hook top-level
   * `provider.<id>` block). `omnirouteProviderId` MUST be used everywhere an
   * identifier reaches or represents something OmniRoute's own server parses
   * (model `id` prefix, `ModelV2.providerID`, combo catalog keys in the
   * dynamic provider hook) — OmniRoute's `parseModel()` has no alias for
   * "opencode-<x>", so a prefixed id there is unrecoverable and credential
   * lookup fails with "No credentials for opencode-<x>".
   */
  omnirouteProviderId: string;
} & Pick<OmniRoutePluginOptions, "baseURL" | "managementReadToken" | "features"> {
  const rawProviderId = opts?.providerId ?? OMNIROUTE_PROVIDER_KEY;
  const omnirouteProviderId = trimLeadingOpencodePrefix(rawProviderId);
  // OC 1.17.8+ native-adapter gate rejects providerID not in
  // {openai, anthropic, opencode*}. Silently prefix so existing
  // configs (providerId: "omniroute") keep working.
  const providerId = rawProviderId.startsWith("opencode-")
    ? rawProviderId
    : `opencode-${rawProviderId}`;
  const displayName =
    opts?.displayName ??
    (providerId === `opencode-${OMNIROUTE_PROVIDER_KEY}`
      ? "OmniRoute"
      : `OmniRoute (${providerId})`);
  const modelCacheTtl =
    typeof opts?.modelCacheTtl === "number" && opts.modelCacheTtl > 0
      ? opts.modelCacheTtl
      : DEFAULT_MODEL_CACHE_TTL_MS;
  const autoSyncIntervalMs = sanitizeAutoSyncIntervalMs(opts?.autoSyncIntervalMs);
  return {
    providerId,
    omnirouteProviderId,
    displayName,
    modelCacheTtl,
    autoSyncIntervalMs,
    baseURL: opts?.baseURL,
    managementReadToken: opts?.managementReadToken,
    features: opts?.features,
  };
}

/** Fully resolved plugin options (defaults applied). */
export type ResolvedOmniRoutePluginOptions = ReturnType<typeof resolveOmniRoutePluginOptions>;

/**
 * Strip a leading "opencode-" prefix (added only for the OC native-adapter
 * gate — see `resolveOmniRoutePluginOptions`) so the returned id is safe to
 * embed in anything OmniRoute's own server parses. A user-supplied
 * `providerId: "opencode-omniroute"` (already prefixed) resolves to the same
 * unprefixed "omniroute" as the default, matching `providerId`'s own
 * idempotent-prefix handling above.
 */
function trimLeadingOpencodePrefix(rawProviderId: string): string {
  return rawProviderId.startsWith("opencode-")
    ? rawProviderId.slice("opencode-".length)
    : rawProviderId;
}

/**
 * Strict parse of raw plugin options (as received from opencode.json or a
 * direct factory call) into the validated `OmniRoutePluginOptions` shape.
 *
 *   - `null` / `undefined` → `{}` (no opts is valid, defaults take over).
 *   - Unknown keys → throws (strict schema catches typos in opencode.json).
 *   - Empty / malformed values (e.g. empty providerId, non-URL baseURL,
 *     negative modelCacheTtl) → throws.
 *
 * Validation happens at plugin invocation time (inside `OmniRoutePlugin`),
 * NOT at module import — so a bad opencode.json fails the affected plugin
 * instance with an actionable message instead of crashing the whole TUI on
 * startup.
 *
 * Exported so callers and tests can validate options independent of the
 * full plugin factory invocation.
 */
export function parseOmniRoutePluginOptions(opts: unknown): OmniRoutePluginOptions {
  if (opts === null || opts === undefined) return {};
  const result = optionsSchema.safeParse(opts);
  if (!result.success) {
    const errs = result.error.issues
      .map((i) => {
        const path = i.path.length > 0 ? i.path.join(".") : "<root>";
        return `${path}: ${i.message}`;
      })
      .join("; ");
    throw new Error(`Invalid @omniroute/opencode-plugin options: ${errs}`);
  }
  return result.data;
}

/**
 * Internal coercion shim. Delegates to `parseOmniRoutePluginOptions` to keep
 * the public surface stable while routing all validation through the Zod
 * schema. Always returns an object (never undefined) so downstream hooks see
 * the same shape regardless of whether opencode.json passed `null`,
 * `undefined`, or an empty bag.
 */
function coercePluginOptions(opts?: PluginOptions): OmniRoutePluginOptions {
  return parseOmniRoutePluginOptions(opts);
}

// ────────────────────────────────────────────────────────────────────────────
// Per-prefix API format routing (apiFormat feature)
// ────────────────────────────────────────────────────────────────────────────

/**
 * Default provider-prefix list that triggers the Anthropic SDK format.
 * Covers OmniRoute's canonical Anthropic aliases: `cc/`, `claude/`,
 * `anthropic/`, plus the user-configured `kiro/` and `kr/` upstream
 * connections that proxy Anthropic models.
 */
export const DEFAULT_ANTHROPIC_PREFIXES = ["cc", "claude", "anthropic", "kiro", "kr"];

/**
 * First-class OmniRoute catalog suffixes (`GET /v1/models`). The Anthropic
 * Messages translator looks these up as `claude-<model>` on provider
 * `claude` and 404s. Keep them on openai-compatible `/v1` so the full
 * catalog id (`cc/claude-haiku-4-5-20251001-low`) is sent unchanged.
 */
export const OPENAI_COMPAT_EFFORT_TIER_SUFFIXES = [
  "-low",
  "-medium",
  "-high",
  "-xhigh",
  "-thinking",
  "-minimal",
  "-max",
] as const;

function hasOpenAiCompatEffortTierSuffix(modelId: string): boolean {
  const lower = modelId.toLowerCase();
  return OPENAI_COMPAT_EFFORT_TIER_SUFFIXES.some((suffix) => lower.endsWith(suffix));
}

/**
 * Ensure a baseURL ends with `/v1` so the OpenAI-compat SDK constructs
 * `/v1/chat/completions` correctly. The Anthropic SDK does NOT want `/v1`
 * (it appends `/v1/messages` automatically), so callers should branch on
 * format first.
 */
/**
 * A url the AI SDK can actually call. `new URL()` alone is not enough: it
 * parses `localhost:20128` as the scheme `localhost:` and `ftp://host` as ftp,
 * both of which reach `fetch` and fail there. Mirrors the `isHttpUrl` guard the
 * settings schema applies to `headroomUrl`.
 */
export function isHttpUrl(value: unknown): boolean {
  if (typeof value !== "string") return false;
  try {
    const { protocol } = new URL(value);
    return protocol === "http:" || protocol === "https:";
  } catch {
    return false;
  }
}

export function ensureV1Suffix(url: string): string {
  const trimmed = trimTrailingSlashes(url);
  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
}

/**
 * Resolve the API block (id + url + npm package) for a given model id.
 *
 * Decision matrix:
 * - If the model id ends with a first-class OmniRoute effort-tier suffix
 *   (`-low` / `-medium` / `-high` / `-xhigh` / `-thinking` / `-minimal` /
 *   `-max`), return the OpenAI-compat block even when the prefix is
 *   Anthropic. Those ids exist only in `GET /v1/models`; the Anthropic
 *   Messages path 404s them as `claude-<name>` on provider `claude`.
 * - Else if the model id's prefix (the substring before the first `/`) is in
 *   `apiFormat.anthropicPrefixes` (or the default list), return the
 *   Anthropic SDK block: `id: "anthropic"`, `url: baseURL` (no `/v1`),
 *   `npm: "@ai-sdk/anthropic"`.
 * - Otherwise return the OpenAI-compat block: `id: "openai-compatible"`,
 *   `url: baseURL + "/v1"`, `npm: "@ai-sdk/openai-compatible"`.
 *
 * Combos span multiple providers. Callers should pass each combo member's
 * id through this function and pick the LCD format (lowest common
 * denominator that every upstream actually understands).
 */
export function resolveApiBlock(
  modelId: string,
  baseURL: string,
  apiFormat?: { anthropicPrefixes?: string[] }
): { id: string; url: string; npm: string } {
  const prefixes = apiFormat?.anthropicPrefixes ?? DEFAULT_ANTHROPIC_PREFIXES;
  const slash = modelId.indexOf("/");
  const prefix = slash === -1 ? modelId : modelId.slice(0, slash);
  const isAnthropic = prefixes.includes(prefix) && !hasOpenAiCompatEffortTierSuffix(modelId);
  return isAnthropic
    ? {
        id: "anthropic",
        url: trimTrailingSlashes(baseURL),
        npm: "@ai-sdk/anthropic",
      }
    : {
        id: "openai-compatible",
        url: ensureV1Suffix(baseURL),
        npm: "@ai-sdk/openai-compatible",
      };
}

/**
 * Build the AuthHook portion of the plugin for a given options bag. Exported
 * standalone so the auth contract can be unit-tested without faking the full
 * PluginInput / Hooks surface.
 *
 * Contract notes:
 *   - `provider` binds to `providerId` (NOT a hardcoded module constant — fixes
 *     the multi-instance bug in [email protected] which pinned
 *     `OMNIROUTE_PROVIDER_ID = "omniroute"` at module scope).
 *   - `methods[0]` is the `api` flavor (no OAuth flow; OmniRoute issues bearer
 *     keys directly). Label includes the resolved displayName so multi-instance
 *     setups stay distinguishable in the OC TUI.
 *   - `methods[0].prompts` uses the official `{type:"text", key, message}`
 *     shape from `@opencode-ai/[email protected]`. The contract does NOT expose
 *     a `mask: true` flag on text prompts — the OC TUI is expected to handle
 *     credential masking by itself (per OC's `auth login` UX).
 *   - `loader` reads the stored credentials via `getAuth()` and projects them
 *     into the AI-SDK `openai-compatible` options shape (`apiKey`, `baseURL`).
 *     The fetch interceptor (`fetch`) is wired in T-04; left absent here so
 *     downstream code falls back to the SDK default fetch.
 *   - The loader rejects non-`api` auth flavors (oauth / wellknown) and empty
 *     keys by returning `{}` — OC then surfaces the `/connect` flow to the
 *     user instead of dispatching a request with bogus credentials.
 */
export function createOmniRouteAuthHook(opts?: OmniRoutePluginOptions): AuthHook {
  const { providerId, displayName, baseURL, features } = resolveOmniRoutePluginOptions(opts);
  // Both fetch-layer features default ON (parity with the rest of the plugin's
  // `features.X !== false` convention). Honoring them here lets users disable
  // the interceptor/sanitizer from opencode.json — previously these flags were
  // documented and schema-validated but silently ignored.
  const wantFetchInterceptor = (features ?? {}).fetchInterceptor !== false;
  const wantGeminiSanitization = (features ?? {}).geminiSanitization !== false;
  const wantDebugLog = (features ?? {}).debugLog === true;

  const hook: AuthHook = {
    provider: providerId,
    methods: [
      {
        type: "api",
        label: `${displayName} API Key`,
        prompts: [
          {
            type: "text",
            key: "apiKey",
            message: `OmniRoute API key (${providerId})`,
          },
        ],
      },
    ],
    loader: async (getAuth, _provider) => {
      const auth = await getAuth();
      if (
        auth &&
        typeof auth === "object" &&
        (auth as { type?: unknown }).type === "api" &&
        typeof (auth as { key?: unknown }).key === "string" &&
        (auth as { key: string }).key.length > 0
      ) {
        const apiKey = (auth as { key: string }).key;
        // baseURL resolution: plugin opts win, then a credential-attached
        // baseURL (some auth backends stash it alongside the key), else empty.
        // Re-cast through `unknown` first: Auth is a discriminated union
        // (api | oauth | wellknown) and TS refuses a direct narrowing to a
        // hypothetical `{ baseURL: string }` shape because WellKnownAuth has
        // no `baseURL`. We've already checked the runtime type via typeof so
        // the unknown-bridge is a safe assertion, not a lie.
        const authBaseURL = (auth as unknown as { baseURL?: unknown }).baseURL;
        const resolvedBaseURL = baseURL ?? (typeof authBaseURL === "string" ? authBaseURL : "");
        // Without a baseURL the interceptor can't tell which requests to
        // intercept (it would either gate-keep nothing or, worse, all
        // outbound traffic). Fall back to apiKey-only and let the SDK use
        // its default fetch. The /connect flow + plugin opts should make
        // this branch unreachable in practice.
        if (!resolvedBaseURL) {
          return { apiKey };
        }
        // Composition: sanitise Gemini tool schemas FIRST (T-06), then inject
        // Bearer (T-04). Both layers are pure with respect to the other's
        // concern (body vs headers) so order is logically free; wrapping the
        // pure body-transform around the header-injecting interceptor reads
        // cleaner and keeps T-06 testable in isolation against any inner fetch
        // (real or stub). Each layer is gated by its feature flag; when both
        // are disabled we fall back to the SDK's default fetch (apiKey only).
        let composedFetch: typeof fetch | undefined;
        if (wantFetchInterceptor) {
          composedFetch = createOmniRouteFetchInterceptor({
            apiKey,
            baseURL: resolvedBaseURL,
          });
        }
        if (wantGeminiSanitization) {
          composedFetch = createGeminiSanitizingFetch(composedFetch ?? fetch);
        }
        if (wantDebugLog || debugLogEnabled(providerId)) {
          composedFetch = createDebugLoggingFetch(composedFetch ?? fetch, providerId, wantDebugLog);
        }
        return composedFetch
          ? { apiKey, baseURL: resolvedBaseURL, fetch: composedFetch }
          : { apiKey, baseURL: resolvedBaseURL };
      }
      return {};
    },
  };

  return hook;
}

/**
 * Plugin factory. Returns the OpenCode Plugin object wired with the three
 * hooks. Concrete hook bodies land in subsequent tickets (T-03 provider.models,
 * T-04 fetch interceptor, T-06 Gemini sanitization, T-07 config backward-compat).
 *
 * Per `@opencode-ai/[email protected]`, the Plugin signature is
 * `(input: PluginInput, options?: PluginOptions) => Promise<Hooks>` — opts
 * arrive as the SECOND argument (from the `[name, opts]` tuple in
 * opencode.json), NOT as a closure binding. Multi-instance support follows
 * from each plugin tuple invoking the factory with its own opts.
 */
/**
 * Invalidate in-memory fetch cache entries for a baseURL (all credential keys).
 * Returns number of entries removed.
 */
export function invalidateOmniRouteFetchCache(
  cache: OmniRouteFetchCache,
  baseURL?: string
): number {
  if (!baseURL) {
    const n = cache.size;
    cache.clear();
    return n;
  }
  const prefix = `${baseURL}::`;
  let removed = 0;
  for (const key of [...cache.keys()]) {
    if (key.startsWith(prefix) || key === baseURL) {
      cache.delete(key);
      removed += 1;
    }
  }
  return removed;
}

/**
 * Resolve API credentials for force-sync / background refresh without
 * depending on the provider.models auth context.
 */
export async function resolveOmniRouteRuntimeAuth(
  resolved: ResolvedOmniRoutePluginOptions,
  readAuthJson?: OmniRouteReadAuthJson
): Promise<{ apiKey: string; baseURL: string; managementReadToken: string } | null> {
  const reader = readAuthJson ?? defaultReadAuthJson;
  let authJson: AuthJsonShape | undefined | null;
  try {
    authJson = await reader();
  } catch {
    authJson = undefined;
  }
  if (authJson === null) authJson = undefined;

  const bareKey = resolved.providerId.startsWith("opencode-")
    ? resolved.providerId.slice("opencode-".length)
    : resolved.providerId;
  const lookupKeys = [resolved.providerId];
  if (bareKey !== resolved.providerId) lookupKeys.push(bareKey);
  if (resolved.omnirouteProviderId && !lookupKeys.includes(resolved.omnirouteProviderId)) {
    lookupKeys.push(resolved.omnirouteProviderId);
  }

  let entry: AuthJsonApiEntry | undefined;
  for (const k of lookupKeys) {
    const e = authJson?.[k];
    if (
      e &&
      (e as { type?: unknown }).type === "api" &&
      typeof (e as { key?: unknown }).key === "string" &&
      (e as { key: string }).key.length > 0
    ) {
      entry = e as AuthJsonApiEntry;
      break;
    }
  }
  const apiKey = entry?.key ?? "";
  if (!apiKey) return null;

  const authBaseURL =
    entry && typeof (entry as { baseURL?: unknown }).baseURL === "string"
      ? (entry as { baseURL: string }).baseURL
      : "";
  const baseURL = resolved.baseURL ?? (authBaseURL || "");
  if (!baseURL) return null;
  const managementReadToken = resolved.managementReadToken ?? apiKey;
  return { apiKey, baseURL, managementReadToken };
}

/**
 * Force-refresh OmniRoute catalog: re-fetch /v1/models (and optional management
 * endpoints) and, only once the models fetch succeeds, replace the memory and
 * disk caches. A failed models fetch leaves both caches untouched (#14926).
 * OpenCode equivalent of Pi `/omni sync`.
 */
export async function forceSyncOmniRouteModels(args: {
  resolved: ResolvedOmniRoutePluginOptions;
  cache: OmniRouteFetchCache;
  readAuthJson?: OmniRouteReadAuthJson;
  fetcher?: OmniRouteModelsFetcher;
  combosFetcher?: OmniRouteCombosFetcher;
  enrichmentFetcher?: OmniRouteEnrichmentFetcher;
  compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
  providersFetcher?: OmniRouteProvidersFetcher;
  now?: () => number;
  logger?: _Logger;
}): Promise<{
  ok: boolean;
  count: number;
  combos: number;
  provider: string;
  baseURL?: string;
  clearedMemory: number;
  clearedDisk: boolean;
  error?: string;
}> {
  const resolved = args.resolved;
  const cache = args.cache;
  const now = args.now ?? Date.now;
  const fetcher = args.fetcher ?? defaultOmniRouteModelsFetcher;
  const combosFetcher = args.combosFetcher ?? defaultOmniRouteCombosFetcher;
  const enrichmentFetcher = args.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
  const compressionMetaFetcher =
    args.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
  const providersFetcher = args.providersFetcher ?? defaultOmniRouteProvidersFetcher;
  const logger =
    args.logger ??
    createLogger(
      resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
    );
  const features = resolved.features ?? {};
  const wantCombos = features.combos !== false;
  const wantEnrichment = features.enrichment !== false;
  const wantCompressionMeta = features.compressionMetadata === true;
  const wantUsableOnly = features.usableOnly === true;
  const wantDiskCache = features.diskCache !== false;

  const auth = await resolveOmniRouteRuntimeAuth(
    resolved,
    args.readAuthJson ?? defaultReadAuthJson
  );
  if (!auth) {
    return {
      ok: false,
      count: 0,
      combos: 0,
      provider: resolved.omnirouteProviderId,
      clearedMemory: 0,
      clearedDisk: false,
      error:
        "No OmniRoute credentials/baseURL available. Run `opencode connect omniroute` or set plugin baseURL.",
    };
  }

  // The models fetch is the only required call. Run it BEFORE touching any
  // cache: invalidating memory or unlinking the disk snapshot first meant a
  // single transient failure (e.g. the 10s abort) destroyed the last good
  // catalog and left every later read hitting a server that was already
  // slow (#14926). On failure both caches stay exactly as they were.
  let rawModels: OmniRouteRawModelEntry[];
  try {
    rawModels = await fetcher(auth.baseURL, auth.apiKey, 10_000);
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    logger.warn(
      `force sync: /v1/models fetch failed providerId=${resolved.providerId}; ` +
        `keeping existing memory and disk cache: ${message}`
    );
    return {
      ok: false,
      count: 0,
      combos: 0,
      provider: resolved.omnirouteProviderId,
      baseURL: auth.baseURL,
      clearedMemory: 0,
      clearedDisk: false,
      error: message,
    };
  }

  let clearedMemory = 0;
  let clearedAll = 0;
  let clearedDisk = false;
  try {
    let rawCombos: OmniRouteRawCombo[] = [];
    if (wantCombos) {
      try {
        rawCombos = await combosFetcher(auth.baseURL, auth.managementReadToken, 10_000);
      } catch (err) {
        logger.warn("force sync: combos fetch failed", err);
      }
    }
    let rawEnrichment: OmniRouteEnrichmentMap = new Map();
    if (wantEnrichment) {
      try {
        rawEnrichment = await enrichmentFetcher(auth.baseURL, auth.managementReadToken, 10_000);
      } catch {
        rawEnrichment = new Map();
      }
    }
    let rawCompressionCombos: OmniRouteCompressionCombo[] = [];
    if (wantCompressionMeta) {
      try {
        rawCompressionCombos = await compressionMetaFetcher(
          auth.baseURL,
          auth.managementReadToken,
          10_000
        );
      } catch {
        rawCompressionCombos = [];
      }
    }
    let rawConnections: OmniRouteProviderConnection[] = [];
    if (wantUsableOnly) {
      try {
        rawConnections = await providersFetcher(auth.baseURL, auth.managementReadToken, 10_000);
      } catch {
        rawConnections = [];
      }
    }

    const t = now();
    const entry = {
      rawModels,
      rawCombos,
      rawEnrichment,
      rawCompressionCombos,
      rawConnections,
      expiresAt: t + resolved.modelCacheTtl,
    };
    const cacheKey = modelsCacheKey(auth.baseURL, `${auth.apiKey}\0${auth.managementReadToken}`);
    // Only now, with a fresh catalog in hand, drop the old entries.
    clearedMemory = invalidateOmniRouteFetchCache(cache, auth.baseURL);
    // Clear residual entries from prior baseURL history as well.
    clearedAll = invalidateOmniRouteFetchCache(cache);
    cache.set(cacheKey, entry);

    if (wantDiskCache) {
      // Overwrite the snapshot instead of unlinking it first, so the old file
      // is only replaced once a fresh catalog exists. The writer soft-fails.
      try {
        const fingerprint = diskSnapshotIdentityFingerprint(
          auth.baseURL,
          auth.apiKey,
          auth.managementReadToken
        );
        const { expiresAt: _expiresAt, ...diskEntry } = entry;
        await defaultDiskSnapshotWriter(resolved.providerId, diskEntry, fingerprint);
        clearedDisk = true;
      } catch {
        /* soft-fail disk write */
      }
      if (resolved.omnirouteProviderId !== resolved.providerId) {
        clearedDisk = (await clearDiskSnapshot(resolved.omnirouteProviderId)) || clearedDisk;
      }
    }

    logger.info(
      `force sync ok providerId=${resolved.providerId} ` +
        `models=${rawModels.length} combos=${rawCombos.length} ` +
        `clearedMemory=${clearedMemory + clearedAll} disk=${clearedDisk}`
    );

    return {
      ok: true,
      count: rawModels.length,
      combos: rawCombos.length,
      provider: resolved.omnirouteProviderId,
      baseURL: auth.baseURL,
      clearedMemory: clearedMemory + clearedAll,
      clearedDisk,
    };
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    return {
      ok: false,
      count: 0,
      combos: 0,
      provider: resolved.omnirouteProviderId,
      baseURL: auth.baseURL,
      clearedMemory: clearedMemory + clearedAll,
      clearedDisk,
      error: message,
    };
  }
}

export function createOmniRouteSyncModelsTool(args: {
  resolved: ResolvedOmniRoutePluginOptions;
  cache: OmniRouteFetchCache;
  logger?: _Logger;
}): ReturnType<typeof tool> {
  const { resolved, cache } = args;
  return tool({
    description:
      "Force-refresh the OmniRoute model catalog (OpenCode equivalent of Pi `/omni sync`). " +
      "Re-fetches GET /v1/models (and combos when enabled), then replaces the in-memory and disk " +
      "caches; a failed fetch keeps the existing caches.",
    args: {
      reason: tool.schema
        .string()
        .optional()
        .describe("Optional reason for the sync (logging only)"),
    },
    async execute(toolArgs) {
      const result = await forceSyncOmniRouteModels({ resolved, cache, logger: args.logger });
      const reason = toolArgs.reason ? ` reason=${toolArgs.reason}` : "";
      if (!result.ok) {
        return {
          title: "OmniRoute sync failed",
          output:
            `OmniRoute model sync failed for provider=${result.provider}.${reason}\n` +
            `${result.error ?? "unknown error"}`,
          metadata: result,
        };
      }
      return {
        title: `OmniRoute sync: ${result.count} models`,
        output:
          `OmniRoute models synced.` +
          `\nprovider: ${result.provider}` +
          `\nbaseURL: ${result.baseURL}` +
          `\nmodels: ${result.count}` +
          `\ncombos: ${result.combos}` +
          `\nclearedMemoryEntries: ${result.clearedMemory}` +
          `\nclearedDiskSnapshot: ${result.clearedDisk}` +
          `\nTTL: ${resolved.modelCacheTtl}ms` +
          `\nautoSyncIntervalMs: ${resolved.autoSyncIntervalMs}` +
          reason,
        metadata: result,
      };
    },
  });
}

/**
 * Start background auto-discovery while the harness is running.
 * Quiet: only logs when the model count changes or on errors.
 * Returns a stop function.
 */
export function startOmniRouteAutoSync(args: {
  resolved: ResolvedOmniRoutePluginOptions;
  cache: OmniRouteFetchCache;
  intervalMs?: number;
  logger?: _Logger;
}): () => void {
  const resolved = args.resolved;
  const cache = args.cache;
  const intervalMs = args.intervalMs ?? resolved.autoSyncIntervalMs;
  const logger =
    args.logger ??
    createLogger(
      resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
    );
  if (!intervalMs || intervalMs <= 0) {
    return () => {};
  }

  let stopped = false;
  let inFlight: Promise<void> | null = null;
  let lastCount: number | undefined;

  const tick = () => {
    if (stopped) return;
    if (inFlight) return;
    inFlight = (async () => {
      const result = await forceSyncOmniRouteModels({ resolved, cache, logger });
      if (!result.ok) {
        logger.error(`auto-sync failed providerId=${resolved.providerId}: ${result.error}`);
        return;
      }
      if (lastCount === undefined) {
        lastCount = result.count;
        return;
      }
      if (result.count !== lastCount) {
        logger.info(
          `auto-sync catalog size changed ${lastCount} → ${result.count} ` +
            `(providerId=${resolved.providerId})`
        );
        lastCount = result.count;
      }
    })()
      .catch((err) => {
        logger.error(`auto-sync tick error: ${err instanceof Error ? err.message : String(err)}`);
      })
      .finally(() => {
        inFlight = null;
      });
  };

  // Delay first background tick by one interval so session start is not doubled
  // with the normal provider.models cold fetch. Manual tool remains immediate.
  const timer = setInterval(tick, intervalMs);
  if (typeof timer === "object" && timer && "unref" in timer && typeof timer.unref === "function") {
    timer.unref();
  }

  logger.info(`auto-sync enabled intervalMs=${intervalMs} providerId=${resolved.providerId}`);

  return () => {
    stopped = true;
    clearInterval(timer);
  };
}

export const OmniRoutePlugin: Plugin = async (_input, options) => {
  const resolved = resolveOmniRoutePluginOptions(coercePluginOptions(options));
  const logger = createLogger(
    resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
  );
  // T-07: a single per-plugin-instance cache shared between the provider
  // hook (T-03/T-05) and the config-shim hook (T-07). On OC ≥1.14.49 both
  // hooks fire within the same Plugin invocation, so a shared cache keeps
  // /v1/models + /api/combos at exactly one round-trip per TTL refresh
  // instead of two. On OC ≤1.14.48 only the config hook runs; the cache
  // still works (single producer + single consumer through the same map).
  // Each `OmniRoutePlugin(...)` invocation gets its OWN cache via closure,
  // so prod + preprod side-by-side instances do NOT collide.
  const sharedCache: OmniRouteFetchCache = new Map();
  // Debug breadcrumb: confirm server() invocation + resolved options.
  // Useful when diagnosing "is the plugin even running" from OC logs.
  const _ver: string =
    ((globalThis as Record<string, unknown>).__PLUGIN_VERSION__ as string) ?? "dev";
  const _hash: string =
    ((globalThis as Record<string, unknown>).__PLUGIN_GIT_HASH__ as string) ?? "unknown";
  const _prefixes = resolved.features?.apiFormat?.anthropicPrefixes ?? DEFAULT_ANTHROPIC_PREFIXES;
  logger.info(
    `v${_ver} (${_hash}) initialized` +
      ` providerId=${resolved.providerId}` +
      ` baseURL=${resolved.baseURL ?? "(from auth.json)"}` +
      ` modelCacheTtl=${resolved.modelCacheTtl}ms` +
      ` apiFormat=anthropic:[${_prefixes.join(",")}]` +
      ` debugLog=${resolved.features?.debugLog ?? false}` +
      ` logLevel=${resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")}`
  );

  // Background auto-discovery while the harness is running (Pi parity).
  // Interval 0 disables. TTL on-demand discovery still works via modelCacheTtl.
  startOmniRouteAutoSync({ resolved, cache: sharedCache, logger });

  const syncTool = createOmniRouteSyncModelsTool({ resolved, cache: sharedCache, logger });
  const bareProviderId = resolved.omnirouteProviderId;

  // Config hook: keep existing catalog shim, and register slash command
  // templates that ask the agent to call the force-sync tool (OpenCode has no
  // Pi-style registerCommand API; tools + command templates are the native path).
  const baseConfigHook = createOmniRouteConfigHook(resolved, {
    cache: sharedCache,
    logger,
    diskSnapshotReader: defaultDiskSnapshotReader,
    diskSnapshotWriter: defaultDiskSnapshotWriter,
  });
  const configWithSyncCommand = async (input: Config) => {
    await baseConfigHook(input);
    const cfg = input as Config & {
      command?: Record<
        string,
        {
          template: string;
          description?: string;
          agent?: string;
          model?: string;
          subtask?: boolean;
        }
      >;
    };
    if (!cfg.command) cfg.command = {};
    if (!cfg.command["omni-sync"]) {
      cfg.command["omni-sync"] = {
        description: "Force-refresh OmniRoute model catalog (like Pi /omni sync)",
        template:
          `Force-refresh the OmniRoute model catalog now using the omniroute_sync_models tool ` +
          `(provider ${bareProviderId}). After the tool returns, briefly report model count and whether the sync succeeded.`,
      };
    }
    if (!cfg.command["omni-autosync"]) {
      cfg.command["omni-autosync"] = {
        description: "Show OmniRoute auto-sync / cache status",
        template:
          `Report OmniRoute discovery status for provider ${bareProviderId}: ` +
          `autoSyncIntervalMs=${resolved.autoSyncIntervalMs}, modelCacheTtl=${resolved.modelCacheTtl}. ` +
          `If the user asked to refresh now, call omniroute_sync_models.`,
      };
    }
  };

  return {
    auth: createOmniRouteAuthHook(resolved),
    provider: createOmniRouteProviderHook(resolved, { cache: sharedCache, logger }),
    config: configWithSyncCommand,
    tool: {
      omniroute_sync_models: syncTool,
    },
  };
};

/**
 * v1 plugin shape per OC plugin loader (`packages/opencode/src/plugin/shared.ts:readV1Plugin`).
 * OC checks the default export for an object with `{id, server}` shape FIRST.
 * If that fails it falls back to legacy `getLegacyPlugins` which walks every
 * named export and rejects any non-function value — our package has
 * constants (OMNIROUTE_PROVIDER_KEY, DEFAULT_MODEL_CACHE_TTL_MS) + types +
 * schemas as named exports, so the legacy path always fails for us.
 *
 * Using v1 shape skips the legacy walk entirely. The `id` field is the
 * plugin MODULE identifier (one per published package); per-instance
 * `providerId` still flows through `options.providerId` as before.
 */
const OmniRouteV1Plugin = {
  id: "@omniroute/opencode-plugin",
  server: OmniRoutePlugin,
};

export default OmniRouteV1Plugin;

// ────────────────────────────────────────────────────────────────────────────
// Provider hook (T-03) — /v1/models pass-through with TTL cache
// ────────────────────────────────────────────────────────────────────────────

/**
 * Raw shape of a `/v1/models` entry from OmniRoute. Captured verbatim from
 * the prod gateway response (sample at /tmp/prod-v1-models.json: 455 entries).
 * STRICT source-of-truth (OQ-3): every field that lands in ModelV2 traces
 * back to this shape — no client-side variant synthesis.
 */
export interface OmniRouteRawModelEntry {
  id: string;
  object?: string;
  owned_by?: string;
  root?: string | null;
  parent?: string | null;
  context_length?: number;
  max_input_tokens?: number;
  max_output_tokens?: number;
  input_modalities?: string[];
  output_modalities?: string[];
  capabilities?: {
    tool_calling?: boolean;
    reasoning?: boolean;
    vision?: boolean;
    thinking?: boolean;
    attachment?: boolean;
    structured_output?: boolean;
    temperature?: boolean;
    /** Runtime-learned or synced reasoning tiers (server-gated, blind-mapped). */
    effort_tiers?: string[];
  };
  release_date?: string;
  last_updated?: string;
  api_format?: string;
}

/**
 * Fetcher contract: returns the raw `/v1/models` entry list from a running
 * OmniRoute instance. Surfaced as a dependency so unit tests can inject a
 * stub without monkey-patching global `fetch`.
 *
 * Why we inline this instead of using `@omniroute/opencode-provider`'s
 * `fetchLiveModels`: the sibling helper returns a stripped `{id, name,
 * contextLength?}` shape (see opencode-provider/src/index.ts:480-569) that
 * drops the `capabilities` / `*_modalities` / `max_*_tokens` blocks T-03
 * needs for ModelV2 pass-through. Adopting the sibling here would force a
 * client-side re-fetch or re-introduce the synthesis we explicitly rejected
 * in OQ-3. A 30-line raw fetcher is cheaper than mutating the sibling's
 * stable v0.1.0 contract.
 */
export type OmniRouteModelsFetcher = (
  baseURL: string,
  apiKey: string,
  timeoutMs?: number
) => Promise<OmniRouteRawModelEntry[]>;

/**
 * Default fetcher: `GET <baseURL>/v1/models` with bearer auth + AbortController
 * timeout. Accepts both the `{object:"list", data:[…]}` envelope OmniRoute
 * emits today and a bare-array envelope (defensive — keeps the plugin
 * working if a future OmniRoute build trims the wrapper). Anything that
 * isn't an object with a string `id` is filtered out silently.
 */
export const defaultOmniRouteModelsFetcher: OmniRouteModelsFetcher = async (
  baseURL,
  apiKey,
  timeoutMs = 30_000
) => {
  if (!apiKey) throw new Error("@omniroute/opencode-plugin: apiKey required to fetch /v1/models");
  if (!baseURL) throw new Error("@omniroute/opencode-plugin: baseURL required to fetch /v1/models");

  const trimmed = trimTrailingSlashes(baseURL);
  // Tolerate both `https://host` and `https://host/v1` forms — the gateway
  // exposes /v1/models either way; we just don't want a double `/v1/v1`.
  const url = /\/v\d+$/.test(trimmed) ? `${trimmed}/models` : `${trimmed}/v1/models`;

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const res = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
      signal: controller.signal,
    });
    if (!res.ok) {
      const err = new Error(
        `@omniroute/opencode-plugin: GET ${url} failed: ${res.status} ${res.statusText}`
      ) as Error & { statusCode: number; status: number };
      err.statusCode = res.status;
      err.status = res.status;
      throw err;
    }
    const body = (await res.json()) as unknown;
    const rawList: unknown[] = Array.isArray(body)
      ? body
      : body && typeof body === "object" && Array.isArray((body as { data?: unknown }).data)
        ? ((body as { data: unknown[] }).data as unknown[])
        : [];
    const out: OmniRouteRawModelEntry[] = [];
    for (const r of rawList) {
      if (r && typeof r === "object" && typeof (r as { id?: unknown }).id === "string") {
        out.push(r as OmniRouteRawModelEntry);
      }
    }
    return out;
  } finally {
    clearTimeout(timer);
  }
};

/**
 * Map a raw `/v1/models` entry → `ModelV2` (the type @opencode-ai/sdk/v2
 * exports as `Model`, re-exported by @opencode-ai/plugin as `ModelV2`).
 *
 * ModelV2 (as of @opencode-ai/sdk@v2 — see node_modules path
 * `@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts:964-1043`) requires a much
 * richer shape than the T-03 spec's mapping table assumed. Concretely it
 * expects:
 *   - flat `id`, `name`, `providerID`, `api: {id,url,npm}`
 *   - nested `capabilities: { temperature, reasoning, attachment, toolcall,
 *     input:{text,audio,image,video,pdf}, output:{…}, interleaved }`
 *   - `cost: { input, output, cache:{read,write} }` (NOT optional)
 *   - `limit: { context, input?, output }`
 *   - `status: "alpha"|"beta"|"deprecated"|"active"`, `options:{}`, `headers:{}`
 *   - `release_date: string`
 *
 * Deviations from the T-03 spec (documented per ticket §2 "CRITICAL: Check
 * the actual ModelV2 type and adapt if field names differ"):
 *   1. Spec's flat `tool_call` / `reasoning` / `attachment` / `modalities`
 *      top-level fields don't exist in ModelV2 — folded into
 *      `capabilities.{toolcall, reasoning, attachment, input.*, output.*}`.
 *   2. `cost: undefined` is illegal (cost is required). OmniRoute doesn't
 *      surface pricing on /v1/models, so we emit a zeroed cost block.
 *      Downstream OC reads this for display only — the live pricing is
 *      OmniRoute's responsibility at routing time.
 *   3. `tool_call` (spec) → `toolcall` (ModelV2 field name; one word).
 *   4. `attachment` (spec) maps from `capabilities.vision` per OmniRoute
 *      convention: vision = ability to receive image attachments. If the
 *      raw entry happens to expose an explicit `capabilities.attachment`
 *      (some combo entries do), that wins.
 *   5. `thinking` from OmniRoute has no 1:1 ModelV2 slot. We OR it into
 *      `reasoning` so thinking-only models still surface a non-false
 *      reasoning flag.
 *   6. `last_updated` from OmniRoute has no ModelV2 slot — dropped (the
 *      spec also flagged this as "may not exist", and the prod sample
 *      confirms it's optional). `release_date` lands in ModelV2.release_date
 *      with `""` fallback (the field is required as `string`).
 *   7. `temperature: true` per OmniRoute convention (OpenAI-compat mode
 *      always supports the temperature knob). If a raw entry sets
 *      `capabilities.temperature` explicitly, that wins.
 *   8. Input/output modality arrays: each known modality flips its boolean.
 *      Unknown strings (future OmniRoute additions) are ignored — when the
 *      server adds new modalities we can map them here without breaking
 *      existing entries.
 *   9. `status: "active"` — OmniRoute doesn't tier models alpha/beta on
 *      /v1/models, and OC needs a non-deprecated status to expose the
 *      model in the picker. If a future entry surfaces an explicit
 *      lifecycle hint we can map it then.
 *  10. `options: {}` and `headers: {}` left empty — they're escape hatches
 *      for OC users to attach per-model overrides; the provider plugin
 *      must not preempt them.
 *  11. `limit.input` is OPTIONAL on ModelV2 (the `?` modifier). We only
 *      emit it when OmniRoute supplies `max_input_tokens` — keeps the
 *      shape clean for combo entries that only carry context_length.
 */

export function mapRawModelToModelV2(
  raw: OmniRouteRawModelEntry,
  ctx: { providerId: string; baseURL: string; apiFormat?: { anthropicPrefixes?: string[] } }
): ModelV2 {
  const caps = raw.capabilities ?? {};
  // effort_tiers loop: server-declared tiers become ModelV2 variants so the
  // UI offers exactly the tiers OmniRoute vouches for (instead of opencode's
  // invented [low, medium, high] fallback). Blind: filtering/exclusion rules
  // live server-side. Absent/empty/malformed => key omitted ENTIRELY (an
  // empty variants object would suppress opencode's fallback for this model).
  const declaredTiers = Array.isArray(caps.effort_tiers)
    ? caps.effort_tiers.filter((t): t is string => typeof t === "string" && t.length > 0)
    : [];
  const variants =
    declaredTiers.length > 0
      ? Object.fromEntries(declaredTiers.map((tier) => [tier, { reasoningEffort: tier }]))
      : undefined;
  const inMods = new Set(raw.input_modalities ?? ["text"]);
  const outMods = new Set(raw.output_modalities ?? ["text"]);

  return {
    // OC's static-catalog reader parses the key on `/` to recover
    // `(providerID, modelID)`. If the raw id is already provider-prefixed
    // (e.g. `cc/claude-opus-4-7` from the `cc` Claude Code alias, or
    // `nvidia/llama-3-70b` from a provider that ships prefixed ids), leave
    // it as-is — double-prefixing breaks OC's lookup. Bare **combo** ids
    // (`owned_by: "combo"`, e.g. `gpt-5.6-sol`) must also stay unprefixed:
    // OpenCode looks up `-m <plugin>/<combo>` as model id `<combo>` under
    // the plugin provider (#10345). Other bare ids still prefix with
    // `providerId` so credentials resolve as `(omniroute, model)`.
    id: raw.id.includes("/") || raw.owned_by === "combo" ? raw.id : `${ctx.providerId}/${raw.id}`,
    /**
     * Display name. Falls back to raw.id when no enrichment is available;
     * the caller (`createOmniRouteProviderHook`) overlays
     * `/api/pricing/models` data via `applyEnrichment` when
     * `features.enrichment` is true.
     */
    name: _normaliseFreeLabel(raw.id),
    capabilities: {
      temperature: caps.temperature ?? true,
      reasoning: Boolean(caps.reasoning || caps.thinking),
      attachment: Boolean(caps.attachment ?? caps.vision ?? false),
      toolcall: Boolean(caps.tool_calling ?? false),
      input: {
        text: inMods.has("text"),
        audio: inMods.has("audio"),
        image: inMods.has("image"),
        video: inMods.has("video"),
        pdf: inMods.has("pdf"),
      },
      output: {
        text: outMods.has("text"),
        audio: outMods.has("audio"),
        image: outMods.has("image"),
        video: outMods.has("video"),
        pdf: outMods.has("pdf"),
      },
      interleaved: Boolean(caps.thinking),
    },
    cost: {
      input: 0,
      output: 0,
      cache: { read: 0, write: 0 },
    },
    limit: {
      context: typeof raw.context_length === "number" ? raw.context_length : 0,
      ...(typeof raw.max_input_tokens === "number" ? { input: raw.max_input_tokens } : {}),
      output: typeof raw.max_output_tokens === "number" ? raw.max_output_tokens : 0,
    },
    ...(variants ? { variants } : {}),
    status: "active",
    options: {},
    headers: {},
    release_date: raw.release_date ?? "",
    providerID: ctx.providerId,
    api: resolveApiBlock(raw.id, ctx.baseURL, ctx.apiFormat),
  };
}

// ────────────────────────────────────────────────────────────────────────────
// Combo discovery (T-05) — /api/combos pass-through with LCD capability roll-up
// ────────────────────────────────────────────────────────────────────────────

/**
 * Raw shape of a single combo entry as returned by OmniRoute's `/api/combos`.
 *
 * Schema established via a live probe against
 * an OmniRoute `/api/combos` endpoint with a management-scoped key
 * (response saved at /tmp/t05-combos.json) cross-referenced against the
 * source-of-truth in this repo:
 *
 *   - `src/app/api/combos/route.ts` GET handler — emits `{combos: [...]}`
 *     envelope after `getCombos()`.
 *   - `src/lib/db/combos.ts` `getCombos()` — returns rows persisted via
 *     `createCombo` / `updateCombo`, each shaped by `normalizeStoredCombo`.
 *   - `src/lib/combos/steps.ts` `ComboModelStep` + `ComboRefStep` — define
 *     the `models[]` array entry shape (a step references a member model
 *     by its full provider-prefixed id, e.g. `"claude-opus-4-5-thinking"`).
 *
 * Note: the preprod gateway returned `{combos: []}` at probe time (no combos
 * provisioned). The defensive parser accepts both `{combos:[...]}` and a
 * bare array envelope so the plugin keeps working if a future OmniRoute
 * build trims the wrapper (mirrors the same pattern in the sibling
 * `@omniroute/opencode-provider#listCombos`).
 *
 * STRICT source-of-truth (OQ-3, per T-03): every ModelV2 field a combo
 * surfaces traces back to either (a) this raw combo entry or (b) the LCD
 * roll-up across its raw member models. No client-side variant synthesis.
 */
export interface OmniRouteRawComboMemberRef {
  /** Step kind: "model" references a raw model id; "combo-ref" nests another combo. */
  kind?: "model" | "combo-ref";
  /** Full model id referenced by this step (when kind === "model"). */
  model?: string;
  /** Nested combo name (when kind === "combo-ref"). */
  comboName?: string;
  /** Routing weight inside the combo (0–100, advisory at LCD time). */
  weight?: number;
  /** Step-local label, distinct from the parent combo's display name. */
  label?: string;
}

export interface OmniRouteRawCombo {
  id: string;
  name?: string;
  /** Routing strategy. Surfaced for forward-compat but not consumed by LCD. */
  strategy?: string;
  /** Member step list. Only `kind: "model"` steps participate in LCD. */
  models?: OmniRouteRawComboMemberRef[];
  /** Hidden combos are excluded from the OC model picker. */
  isHidden?: boolean;
  /** When OmniRoute attaches a lifecycle hint we forward it; today it doesn't. */
  release_date?: string;
  /**
   * Server-computed context window for this combo (aggregated from member
   * models using the same logic as /v1/models). When present, the client
   * uses this value directly instead of re-aggregating from member models.
   *
   * Added in 3.9.x — old servers do not send it.
   */
  computed_context_length?: number;
}

/**
 * Fetcher contract for `/api/combos`. Same DI shape as
 * `OmniRouteModelsFetcher` so unit tests can inject a stub instead of
 * monkey-patching global `fetch`.
 */
export type OmniRouteCombosFetcher = (
  baseURL: string,
  apiKey: string,
  timeoutMs?: number
) => Promise<OmniRouteRawCombo[]>;

/**
 * Default fetcher: `GET <baseURL>/api/combos` with bearer auth +
 * AbortController timeout. Accepts both the `{combos: [...]}` envelope the
 * gateway emits today and a bare-array envelope (defensive — keeps the
 * plugin working if a future OmniRoute build trims the wrapper).
 *
 * Differences from `defaultOmniRouteModelsFetcher`:
 *   - URL is `/api/combos`, NOT `/v1/combos`. The `/v1/...` namespace is the
 *     OpenAI-compatible surface (chat completions, models); combo discovery
 *     lives on the management plane under `/api/...`. We tolerate both
 *     `https://host` and `https://host/v1` baseURL forms by stripping the
 *     trailing `/v1` segment before appending `/api/combos`.
 *   - Combos endpoint requires a management-scoped API key when
 *     `REQUIRE_API_KEY` is enabled. We don't enforce that here; the
 *     gateway returns 401/403 with an actionable error which we propagate.
 *
 * Anything that isn't an object with a string `id` is filtered out silently.
 */
export const defaultOmniRouteCombosFetcher: OmniRouteCombosFetcher = async (
  baseURL,
  apiKey,
  timeoutMs = 10_000
) => {
  if (!apiKey) throw new Error("@omniroute/opencode-plugin: apiKey required to fetch /api/combos");
  if (!baseURL)
    throw new Error("@omniroute/opencode-plugin: baseURL required to fetch /api/combos");

  // Strip trailing slashes, then strip a trailing `/v1` so we land on the
  // management plane. Models live under `/v1/models`; combos live under
  // `/api/combos` from the same gateway root.
  const trimmed = trimTrailingSlashes(baseURL);
  const root = trimmed.replace(/\/v\d+$/, "");
  const url = `${root}/api/combos`;

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const res = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
      signal: controller.signal,
    });
    if (!res.ok) {
      throw new Error(
        `@omniroute/opencode-plugin: GET ${url} failed: ${res.status} ${res.statusText}`
      );
    }
    const body = (await res.json()) as unknown;
    const rawList: unknown[] = Array.isArray(body)
      ? body
      : body && typeof body === "object" && Array.isArray((body as { combos?: unknown }).combos)
        ? ((body as { combos: unknown[] }).combos as unknown[])
        : [];
    const out: OmniRouteRawCombo[] = [];
    for (const r of rawList) {
      if (r && typeof r === "object" && typeof (r as { id?: unknown }).id === "string") {
        out.push(r as OmniRouteRawCombo);
      }
    }
    return out;
  } finally {
    clearTimeout(timer);
  }
};

/**
 * Map a raw combo entry → `ModelV2` by computing the lowest-common-denominator
 * (LCD) of its underlying member models. The LCD policy is the only way to
 * surface a single capability vector to OpenCode without lying: if any member
 * lacks a capability, the combo as a whole cannot guarantee it.
 *
 * LCD rules:
 *   - `limit.context` = `min(...members.context_length)`.
 *   - `limit.output` = `min(...members.max_output_tokens)`.
 *   - `limit.input` = `min(...members.max_input_tokens)` ONLY when every
 *     member declares one (ModelV2.limit.input is optional — better to
 *     omit than to fabricate a min over partial data).
 *   - `capabilities.toolcall` / `reasoning` / `attachment` / `temperature`:
 *     `every(member ⇒ supports?)`. The `reasoning` axis ORs across
 *     `reasoning` and `thinking` per member before AND-ing across the
 *     combo (mirrors `mapRawModelToModelV2`). The `attachment` axis ORs
 *     across `attachment` and `vision` per member. The `temperature` axis
 *     uses default-true semantics: a member supports temperature unless
 *     it explicitly declares `temperature: false`.
 *   - `capabilities.input.*` / `output.*`: flattened AND across members'
 *     modality flags. Missing arrays default to `["text"]` (same default
 *     as `mapRawModelToModelV2`).
 *
 * Defensive: empty members array → ALL capabilities `false`, limits zero.
 * That's an intentional safety posture (you can't route through an empty
 * combo, so OC should grey it out in the picker).
 *
 * Spec mapping (T-05 §Scope.3): `cost` zeroed; `status = "active"`;
 * `release_date = combo.release_date ?? ""`; `api.id = "openai-compatible"`;
 * `name = combo.name ?? combo.id`.
 *
 * @param combo Raw `/api/combos` entry.
 * @param members Raw `/v1/models` entries for THIS combo's member ids.
 *                Caller resolves `combo.models[].model` ids; unknown ids
 *                are silently dropped before this call.
 * @param providerId OpenCode provider id (multi-instance aware).
 * @param baseURL Resolved gateway base URL for ModelV2.api.url.
 */
export function mapComboToModelV2(
  combo: OmniRouteRawCombo,
  members: OmniRouteRawModelEntry[],
  providerId: string,
  baseURL: string,
  apiFormat?: { anthropicPrefixes?: string[] }
): ModelV2 {
  // `every` over an empty array returns true (would lie about an empty
  // combo's capabilities) — short-circuit to all-false when no members.
  const hasMembers = members.length > 0;

  const memberInMods = members.map((m) => new Set(m.input_modalities ?? ["text"]));
  const memberOutMods = members.map((m) => new Set(m.output_modalities ?? ["text"]));

  const modalityAllHave = (sets: Array<Set<string>>, key: string): boolean =>
    hasMembers && sets.every((s) => s.has(key));

  const contextValues = members
    .map((m) => m.context_length)
    .filter((v): v is number => typeof v === "number" && v > 0);
  const outputValues = members
    .map((m) => m.max_output_tokens)
    .filter((v): v is number => typeof v === "number" && v > 0);
  const inputValues = members
    .map((m) => m.max_input_tokens)
    .filter((v): v is number => typeof v === "number" && v > 0);

  const everyDeclaresInput = hasMembers && inputValues.length === members.length;

  const capabilities: ModelV2["capabilities"] = {
    temperature:
      hasMembers && members.every((m) => (m.capabilities?.temperature ?? true) !== false),
    reasoning:
      hasMembers &&
      members.every((m) => Boolean(m.capabilities?.reasoning || m.capabilities?.thinking)),
    attachment:
      hasMembers &&
      members.every((m) => Boolean(m.capabilities?.attachment ?? m.capabilities?.vision ?? false)),
    toolcall: hasMembers && members.every((m) => Boolean(m.capabilities?.tool_calling ?? false)),
    input: {
      text: modalityAllHave(memberInMods, "text"),
      audio: modalityAllHave(memberInMods, "audio"),
      image: modalityAllHave(memberInMods, "image"),
      video: modalityAllHave(memberInMods, "video"),
      pdf: modalityAllHave(memberInMods, "pdf"),
    },
    output: {
      text: modalityAllHave(memberOutMods, "text"),
      audio: modalityAllHave(memberOutMods, "audio"),
      image: modalityAllHave(memberOutMods, "image"),
      video: modalityAllHave(memberOutMods, "video"),
      pdf: modalityAllHave(memberOutMods, "pdf"),
    },
    interleaved: hasMembers && members.every((m) => Boolean(m.capabilities?.thinking)),
  };

  // Combos span multiple providers. Use Anthropic format only when ALL
  // members resolve to Anthropic — otherwise fall back to OpenAI-compat
  // (lowest common denominator that every upstream understands).
  const comboApiBlock = (() => {
    if (!hasMembers) return resolveApiBlock("", baseURL, apiFormat);
    const allAnthropic = members.every(
      (m) => resolveApiBlock(m.id, baseURL, apiFormat).id === "anthropic"
    );
    return allAnthropic
      ? resolveApiBlock(members[0].id, baseURL, apiFormat)
      : {
          id: "openai-compatible",
          url: ensureV1Suffix(baseURL),
          npm: "@ai-sdk/openai-compatible",
        };
  })();

  return {
    id: combo.id,
    providerID: providerId,
    api: comboApiBlock,
    name: combo.name && combo.name.trim().length > 0 ? combo.name : combo.id,
    capabilities,
    cost: {
      input: 0,
      output: 0,
      cache: { read: 0, write: 0 },
    },
    limit: {
      context:
        typeof combo.computed_context_length === "number" && combo.computed_context_length > 0
          ? combo.computed_context_length
          : contextValues.length > 0
            ? Math.min(...contextValues)
            : 0,
      ...(everyDeclaresInput ? { input: Math.min(...inputValues) } : {}),
      output: outputValues.length > 0 ? Math.min(...outputValues) : 0,
    },
    status: "active",
    options: {},
    headers: {},
    release_date: combo.release_date ?? "",
  };
}

// ─────────────────────────────────────────────────────────────────────────
// ENRICHMENT — pull display names + pricing from /api/pricing/models so
// the UI doesn't have to render raw model ids. Gated by features.enrichment.
// ─────────────────────────────────────────────────────────────────────────

/**
 * Per-model enrichment overlay derived from OmniRoute's
 * `/api/pricing/models` endpoint. The endpoint returns a per-provider
 * catalog with curated `name` strings (e.g. `Claude 4.7 Opus`,
 * `GPT 5.5 Pro`, `Gemini 3.1 Pro`) and per-million-token pricing
 * (`pricing.input`, `pricing.output`, `pricing.cacheRead`,
 * `pricing.cacheWrite`). These overlay the ModelV2 entries produced by
 * `mapRawModelToModelV2`.
 */
export interface OmniRouteEnrichmentEntry {
  /** Human-readable display name. Replaces ModelV2.name when present. */
  name?: string;
  /** Per-million-token cost overlay onto ModelV2.cost. */
  pricing?: {
    input?: number;
    output?: number;
    cacheRead?: number;
    cacheWrite?: number;
  };
  /**
   * Provider alias prefix seen in `/v1/models` ids (e.g. `cc`, `gemini`).
   * Populated by `defaultOmniRouteEnrichmentFetcher` from
   * `/api/pricing/models` keys. Drives the `usableOnly` alias↔canonical
   * resolution.
   */
  providerAlias?: string;
  /**
   * Canonical provider id used by `/api/providers` connections (e.g.
   * `claude`, `gemini`, `kiro`). Populated from the per-provider
   * `entry.id` field inside `/api/pricing/models`.
   */
  providerCanonical?: string;
  /**
   * Human-readable upstream provider label (e.g. `Claude`, `Kiro`,
   * `Windsurf`, `GitHub Models`). Populated from the per-provider
   * `entry.name` field inside `/api/pricing/models`. Used by the
   * `providerTag` feature to suffix `ModelV2.name` with the routing
   * destination so the OC TUI picker can differentiate the same
   * model id sold through different upstream connections.
   */
  providerDisplayName?: string;
  /** Free-model budget type (from freeModelCatalog). */
  freeType?: FreeModelFreeType;
  /** Monthly token budget for recurring free models. */
  monthlyTokens?: number;
  /** Credit token budget for credit-based free models. */
  creditTokens?: number;
}

/** Map keyed by full model id (possibly namespaced, e.g. `cc/claude-sonnet-4-6`). */
export type OmniRouteEnrichmentMap = Map<string, OmniRouteEnrichmentEntry>;

export type OmniRouteEnrichmentFetcher = (
  baseURL: string,
  apiKey: string,
  timeoutMs?: number
) => Promise<OmniRouteEnrichmentMap>;

/**
 * Default enrichment fetcher — pulls nice display names from
 * `GET /api/pricing/models` and merges per-million-token pricing from
 * `GET /api/pricing` (the actual pricing source — `/api/pricing/models` is
 * a catalog endpoint whose entries are `{id, name, custom}` only).
 *
 * `/api/pricing/models` shape (catalog):
 *  - `{ [providerAlias]: { id, alias, name, models: [{ id, name, custom }] } }`
 *
 * `/api/pricing` shape (pricing only):
 *  - `{ [providerAlias]: { [modelId]: { input, output, cached, reasoning, cache_creation } } }`
 *    where values are USD per million tokens.
 *
 * The two responses are joined on `(providerAlias, modelId)` and the merged
 * entries are stored under both `${providerAlias}/${modelId}` and bare
 * `${modelId}` keys so downstream lookups against either form succeed.
 *
 * Soft-fails (returns whatever was collected) on non-2xx or parse errors;
 * the two fetches are independent so one missing source still surfaces the
 * other.
 */
export const defaultOmniRouteEnrichmentFetcher: OmniRouteEnrichmentFetcher = async (
  baseURL,
  apiKey,
  timeoutMs = 10_000
) => {
  const out: OmniRouteEnrichmentMap = new Map();
  if (!baseURL || !apiKey) return out;
  const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
  const headers = {
    Authorization: `Bearer ${apiKey}`,
    Accept: "application/json",
  };

  // ── 1. Catalog with nice display names ────────────────────────────────
  const catalogAc = new AbortController();
  const catalogTimer = setTimeout(() => catalogAc.abort(), timeoutMs);
  try {
    const res = await fetch(`${root}/api/pricing/models`, {
      method: "GET",
      headers,
      signal: catalogAc.signal,
    });
    if (res.ok) {
      const body = (await res.json()) as unknown;
      const providers =
        (body as { providers?: Record<string, { models?: unknown[] }> })?.providers ??
        (body as Record<string, { models?: unknown[] }>);
      if (providers && typeof providers === "object") {
        for (const [providerAlias, slot] of Object.entries(providers)) {
          if (!slot || typeof slot !== "object") continue;
          const models = (slot as { models?: unknown[] }).models;
          if (!Array.isArray(models)) continue;
          // Canonical id sits at the per-provider top level (e.g.
          // `pricing-models.cc.id === 'claude'`). Falls back to the alias
          // itself when missing — common case alias===canonical.
          const canonicalRaw = (slot as { id?: unknown }).id;
          const providerCanonical =
            typeof canonicalRaw === "string" && canonicalRaw.length > 0
              ? canonicalRaw
              : providerAlias;
          // Upstream provider human label (e.g. `Claude`, `Kiro`,
          // `GitHub Models`). Optional — falls back to undefined when
          // OmniRoute hasn't curated a label for this slot.
          const slotNameRaw = (slot as { name?: unknown }).name;
          const providerDisplayName =
            typeof slotNameRaw === "string" && slotNameRaw.trim().length > 0
              ? slotNameRaw.trim()
              : undefined;
          for (const m of models) {
            if (!m || typeof m !== "object") continue;
            const id = (m as { id?: unknown }).id;
            if (typeof id !== "string" || id.length === 0) continue;
            const name = (m as { name?: unknown }).name;
            const entry: OmniRouteEnrichmentEntry = {
              providerAlias,
              providerCanonical,
            };
            if (providerDisplayName) entry.providerDisplayName = providerDisplayName;
            if (typeof name === "string" && name.trim().length > 0) entry.name = name;
            const namespaced = `${providerAlias}/${id}`;
            if (!out.has(namespaced)) out.set(namespaced, entry);
            if (!out.has(id)) out.set(id, entry);
          }
        }
      }
    }
  } catch {
    // Soft-fail; keep going to pricing fetch.
  } finally {
    clearTimeout(catalogTimer);
  }

  // ── 2. Pricing values from /api/pricing ───────────────────────────────
  const priceAc = new AbortController();
  const priceTimer = setTimeout(() => priceAc.abort(), timeoutMs);
  try {
    const res = await fetch(`${root}/api/pricing`, {
      method: "GET",
      headers,
      signal: priceAc.signal,
    });
    if (res.ok) {
      const body = (await res.json()) as unknown;
      if (body && typeof body === "object" && !Array.isArray(body)) {
        for (const [providerAlias, slot] of Object.entries(body as Record<string, unknown>)) {
          if (!slot || typeof slot !== "object" || Array.isArray(slot)) continue;
          for (const [modelId, raw] of Object.entries(slot as Record<string, unknown>)) {
            if (!raw || typeof raw !== "object") continue;
            const p = raw as Record<string, unknown>;
            const parsed: NonNullable<OmniRouteEnrichmentEntry["pricing"]> = {};
            // OmniRoute `/api/pricing` keys:
            //   input         → cost.input
            //   output        → cost.output
            //   cached        → cost.cache.read   (alias: cacheRead)
            //   cache_creation → cost.cache.write (alias: cacheWrite)
            // Tolerate alternative spellings for forward-compat.
            if (typeof p.input === "number") parsed.input = p.input;
            if (typeof p.output === "number") parsed.output = p.output;
            const cacheRead =
              typeof p.cached === "number"
                ? p.cached
                : typeof p.cacheRead === "number"
                  ? p.cacheRead
                  : undefined;
            if (typeof cacheRead === "number") parsed.cacheRead = cacheRead;
            const cacheWrite =
              typeof p.cache_creation === "number"
                ? p.cache_creation
                : typeof p.cacheWrite === "number"
                  ? p.cacheWrite
                  : undefined;
            if (typeof cacheWrite === "number") parsed.cacheWrite = cacheWrite;
            if (Object.keys(parsed).length === 0) continue;
            const namespaced = `${providerAlias}/${modelId}`;
            const existingNs = out.get(namespaced);
            if (existingNs)
              existingNs.pricing = {
                ...(existingNs.pricing ?? {}),
                ...parsed,
              };
            else out.set(namespaced, { pricing: parsed });
            const existingBare = out.get(modelId);
            if (existingBare)
              existingBare.pricing = {
                ...(existingBare.pricing ?? {}),
                ...parsed,
              };
            else out.set(modelId, { pricing: parsed });
          }
        }
      }
    }
  } catch {
    // Soft-fail; return whatever names we collected.
  } finally {
    clearTimeout(priceTimer);
  }

  // ── 3. Free model budgets from /api/free-tier/summary ──────────────────
  // Best-effort fetch: populates freeType/monthlyTokens/creditTokens on
  // enrichment entries that match. 404 = endpoint doesn't exist — skip.
  // Uses the EXISTING /api/free-tier/summary endpoint (no new server code).
  const freeAc = new AbortController();
  const freeTimer = setTimeout(() => freeAc.abort(), timeoutMs);
  try {
    const res = await fetch(`${root}/api/free-tier/summary`, {
      method: "GET",
      headers,
      signal: freeAc.signal,
    });
    if (res.ok) {
      const body = (await res.json()) as unknown;
      // Response shape: { perModel: FreeModelBudget[], ... }
      const perModel: unknown[] =
        body && typeof body === "object" && Array.isArray((body as { perModel?: unknown }).perModel)
          ? ((body as { perModel: unknown[] }).perModel as unknown[])
          : Array.isArray(body)
            ? (body as unknown[])
            : [];
      let matched = 0;
      for (const fm of perModel) {
        if (!fm || typeof fm !== "object") continue;
        const fmObj = fm as Record<string, unknown>;
        const provider = typeof fmObj.provider === "string" ? fmObj.provider : "";
        const modelId = typeof fmObj.modelId === "string" ? fmObj.modelId : "";
        const freeType = typeof fmObj.freeType === "string" ? fmObj.freeType : "";
        if (!modelId || !freeType) continue;
        const monthlyTokens =
          typeof fmObj.monthlyTokens === "number" ? fmObj.monthlyTokens : undefined;
        const creditTokens =
          typeof fmObj.creditTokens === "number" ? fmObj.creditTokens : undefined;
        // Match against enrichment entries: namespaced, bare, and displayName
        const displayName = typeof fmObj.displayName === "string" ? fmObj.displayName : "";
        const candidates = [
          `${provider}/${modelId}`,
          modelId,
          ...(displayName ? [displayName] : []),
        ];
        for (const key of candidates) {
          const entry = out.get(key);
          if (entry) {
            entry.freeType = freeType as FreeModelFreeType;
            if (monthlyTokens !== undefined) entry.monthlyTokens = monthlyTokens;
            if (creditTokens !== undefined) entry.creditTokens = creditTokens;
            matched++;
            break;
          }
        }
      }
      _logger.debug(
        `free-tier/summary: ${perModel.length} models returned, ${matched} matched enrichment entries`
      );
    }
  } catch {
    // Soft-fail; free metadata is optional.
  } finally {
    clearTimeout(freeTimer);
  }

  return out;
};

// ── Startup diagnostics writer (file-based) ──────────────────────────────
// OC doesn't capture plugin console.warn in its log file. Write diagnostics
// to a file so they're readable after session starts. Capped at 64KB.
async function writeStartupDiagnostics(params: {
  providerId: string;
  baseURL: string;
  modelCount: number;
  comboCount: number;
  enrichmentSize: number;
  enrichment: OmniRouteEnrichmentMap;
  features?: OmniRoutePluginOptions["features"];
}): Promise<void> {
  const { providerId, baseURL, modelCount, comboCount, enrichmentSize, enrichment, features } =
    params;
  const enriched = [...enrichment.entries()];
  const withName = enriched.filter(([, e]) => e.name);
  const withPricing = enriched.filter(([, e]) => e.pricing);
  const withFree = enriched.filter(([, e]) => e.freeType);

  const lines: string[] = [];
  lines.push(`=== startupDebug ${new Date().toISOString()} ===`);
  lines.push(`providerId=${providerId} baseURL=${baseURL}`);
  lines.push(`models=${modelCount} combos=${comboCount} enrichment=${enrichmentSize}`);
  // #7624: surface the EFFECTIVE feature flags so an operator who omitted the
  // `features` block can see combos/enrichment are on (the counts
  // above can read 0 for reasons unrelated to the flags — e.g. missing auth).
  // `features.autoCombos` is accepted but ignored, so it is hidden here.
  const effectiveFlags = resolveEffectiveFeatureFlags(features);
  lines.push(
    `features(effective): ` +
      (Object.keys(effectiveFlags) as OmniRouteFeatureFlag[])
        .filter((k) => k !== "autoCombos")
        .map((k) => `${k}=${effectiveFlags[k] ? "on" : "off"}`)
        .join(" ")
  );
  lines.push(
    `enrichment: ${withName.length} with name, ${withPricing.length} with pricing, ${withFree.length} free`
  );
  if (withFree.length > 0) {
    lines.push(`free models (${withFree.length}):`);
    for (const [k, e] of withFree.slice(0, 10)) {
      lines.push(
        `  ${k} → name=${e.name ?? "(none)"}, freeType=${e.freeType}, monthly=${e.monthlyTokens ?? 0}, credits=${e.creditTokens ?? 0}`
      );
    }
  } else {
    lines.push(
      `NO free models detected. ` +
        (enrichmentSize === 0
          ? "Enrichment map is EMPTY."
          : `Enrichment has ${enrichmentSize} entries but none have freeType.`)
    );
  }
  const sampleNames = enriched
    .filter(([, e]) => e.name)
    .slice(0, 5)
    .map(([k, e]) => `  ${k} → "${e.name}"`);
  if (sampleNames.length > 0) {
    lines.push(`sample enriched names:`);
    lines.push(sampleNames.join("\n"));
  }
  lines.push(`=== end startupDebug ===\n`);

  const diagnostics = lines.join("\n");
  _logger.debug(diagnostics);

  try {
    const diagDir =
      process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
    const diagPath = path.join(diagDir, "plugins", "omniroute-startup-diagnostics.log");
    let existing = "";
    try {
      existing = await readFile(diagPath, "utf8");
    } catch {
      /* first write */
    }
    const KEEP = 65_536;
    const combined = existing + diagnostics;
    const trimmed = combined.length > KEEP ? combined.slice(combined.length - KEEP) : combined;
    await writeFile(diagPath, trimmed, "utf8");
  } catch {
    /* best effort */
  }
}

/**
 * Separator used by `applyProviderTag` between the upstream provider
 * label (prefix) and the enriched model name. ASCII hyphen with
 * surrounding spaces — terminal-safe everywhere, never collides with
 * a model id (those use slashes / dots / underscores).
 *
 * Layout: `<short-label> - <model name>` (label leads so column scans
 * group by provider — e.g. `Claude - Claude Opus 4.7`,
 * `Kiro - Claude Opus 4.7`).
 */
export const PROVIDER_TAG_SEPARATOR = _PROVIDER_TAG_SEPARATOR;

// Re-export from naming.ts — thin wrapper preserving OmniRouteEnrichmentEntry signature
export function shortProviderLabel(
  enrichment: OmniRouteEnrichmentEntry | undefined
): string | undefined {
  return _shortProviderLabel(enrichment);
}

/**
 * Prepend the upstream provider label to `model.name` so the OC TUI
 * picker can differentiate the same model id sold through different
 * upstream connections (e.g. `cc/claude-opus-4-7` via Anthropic
 * vs `kr/claude-opus-4-7` via Kiro). Result shape:
 *
 *   `<label>${PROVIDER_TAG_SEPARATOR}<enriched name>`
 *   → `Claude - Claude Opus 4.7`
 *   → `Kiro - Claude Opus 4.7`
 *   → `AssemblyAI - Universal 2 (Transcription)` (slot.name fits, used verbatim)
 *   → `GHM - GPT 5`           (slot.name "GitHub Models" > 12 chars → UPPER(alias))
 *
 * Mutates the model in place and is idempotent — running twice never
 * double-prefixes. No-op when:
 *
 *  - `enrichment` is undefined,
 *  - {@link shortProviderLabel} returns `undefined`
 *    (no `providerDisplayName` AND no `providerAlias`),
 *  - the current `model.name` already starts with the prefix.
 *
 * Combos are intentionally skipped by callers (they're multi-upstream
 * by definition; the `Combo: ` prefix conveys that). Raw models call
 * this after `applyEnrichment` so the tag layers on top of the
 * friendly name.
 */
export function applyProviderTag(
  model: ModelV2,
  enrichment: OmniRouteEnrichmentEntry | undefined
): ModelV2 {
  const label = shortProviderLabel(enrichment);
  if (!label) return model;
  const prefix = `${label}${PROVIDER_TAG_SEPARATOR}`;
  if (model.name.startsWith(prefix)) return model;
  // When enrichment already prepended [Free], move it before the provider
  // tag: "[Free] GPT-4.1" → "[Free] GHM - GPT-4.1" not "GHM - [Free] GPT-4.1"
  if (model.name.startsWith("[Free] ")) {
    model.name = `[Free] ${prefix}${model.name.slice(7)}`;
  } else {
    model.name = `${prefix}${model.name}`;
  }
  return model;
}

/**
 * Reverse-index the enrichment map from `providerCanonical → providerAlias`.
 *
 * OmniRoute's `/api/pricing/models` is keyed by short ALIAS (`cc`, `cx`,
 * `pol`). But `/v1/models` exposes some models a SECOND time under their
 * CANONICAL name (`claude/claude-opus-4-7`, `codex/gpt-5.5`,
 * `pollinations/midjourney`). Without a reverse map, those canonical
 * rows miss enrichment entirely and surface as raw ids in the picker.
 *
 * Built once per refresh from the enrichment entries themselves — no
 * hardcoded registry. Only records `canonical → alias` mappings when
 * both are present AND distinct (skips slots where alias === canonical
 * like `kiro`).
 */
export function buildCanonicalToAliasMap(
  enrichment: OmniRouteEnrichmentMap | undefined
): Map<string, string> {
  const out = new Map<string, string>();
  if (!enrichment) return out;
  for (const entry of enrichment.values()) {
    const alias = typeof entry.providerAlias === "string" ? entry.providerAlias.trim() : "";
    const canonical =
      typeof entry.providerCanonical === "string" ? entry.providerCanonical.trim() : "";
    if (alias.length === 0 || canonical.length === 0) continue;
    if (alias === canonical) continue;
    if (!out.has(canonical)) out.set(canonical, alias);
  }
  return out;
}

/**
 * Enrichment lookup with alias-fallback chain.
 *
 * Resolution order (first hit wins):
 *
 *   1. `enrichment.get(rawId)` — direct hit on `<prefix>/<modelId>` or
 *      bare id (the fetcher writes under both forms).
 *   2. If `rawId` is `<canonical>/<modelId>` and `canonicalToAlias` has
 *      a mapping for `canonical`, try `<alias>/<modelId>`. This rescues
 *      duplicate rows like `claude/claude-opus-4-7` (canonical) when
 *      enrichment only indexed under `cc/claude-opus-4-7` (alias).
 *   3. Bare `<modelId>` as a last resort. A bare key matches by model name only,
 *      but its entry describes one provider (label, free budget, pricing). It is
 *      returned whole only when that provider owns the row (`ownedBy` or the id
 *      prefix); otherwise only its model name is kept, so a generic-adapter row
 *      such as `ih/kimi-k3` is not labelled with an unrelated provider (#14966).
 *
 * Returns `undefined` when no lookup hits.
 */
export function lookupEnrichment(
  rawId: string,
  enrichment: OmniRouteEnrichmentMap | undefined,
  canonicalToAlias: Map<string, string>,
  ownedBy?: string
): OmniRouteEnrichmentEntry | undefined {
  if (!enrichment) return undefined;
  const direct = enrichment.get(rawId);
  if (direct) return direct;
  const slash = rawId.indexOf("/");
  if (slash > 0) {
    const prefix = rawId.slice(0, slash);
    const modelId = rawId.slice(slash + 1);
    const alias = canonicalToAlias.get(prefix);
    if (alias && alias !== prefix) {
      const viaAlias = enrichment.get(`${alias}/${modelId}`);
      if (viaAlias) return viaAlias;
    }
    const bare = enrichment.get(modelId);
    if (bare) return bareFallbackEntry(bare, prefix, ownedBy);
  }
  return undefined;
}

/** A bare-key hit keeps its provider metadata only when that provider owns the row. */
function bareFallbackEntry(
  entry: OmniRouteEnrichmentEntry,
  prefix: string,
  ownedBy: string | undefined
): OmniRouteEnrichmentEntry {
  const owners = new Set([prefix, ownedBy].filter((v): v is string => Boolean(v)));
  const entryProviders = [entry.providerAlias, entry.providerCanonical].filter(
    (v): v is string => typeof v === "string" && v.trim().length > 0
  );
  if (entryProviders.length === 0 || entryProviders.some((p) => owners.has(p.trim()))) {
    return entry;
  }
  return entry.name ? { name: entry.name } : {};
}

/**
 * Pre-pass: detect raw rows that are the CANONICAL twin of an ALIAS row
 * already in the catalog. Returns the set of canonical-keyed ids to skip
 * during the raw-model loop so each model surfaces exactly once under
 * its enriched alias key.
 *
 * Example: `/v1/models` returns BOTH `cc/claude-opus-4-7` and
 * `claude/claude-opus-4-7`. The former is enriched (alias `cc` exists
 * in `/api/pricing/models`); the latter is raw. We keep `cc/...` and
 * drop `claude/...`.
 *
 * Built once per refresh. Cheap — O(M) where M = raw model count.
 */
export function canonicalDedupSet(
  rawModels: ReadonlyArray<OmniRouteRawModelEntry>,
  canonicalToAlias: Map<string, string>
): Set<string> {
  const drop = new Set<string>();
  if (canonicalToAlias.size === 0) return drop;
  // Index every alias key present in the raw catalog.
  const aliasKeys = new Set<string>();
  for (const m of rawModels) {
    if (typeof m.id === "string" && m.id.length > 0) aliasKeys.add(m.id);
  }
  for (const m of rawModels) {
    if (typeof m.id !== "string" || m.id.length === 0) continue;
    const slash = m.id.indexOf("/");
    if (slash <= 0) continue;
    const prefix = m.id.slice(0, slash);
    const modelId = m.id.slice(slash + 1);
    const alias = canonicalToAlias.get(prefix);
    if (!alias || alias === prefix) continue;
    // Canonical row only gets suppressed if the alias row actually
    // exists — otherwise we'd hide the model entirely.
    if (aliasKeys.has(`${alias}/${modelId}`)) drop.add(m.id);
  }
  return drop;
}

/**
 * Build a per-alias index of enrichment metadata so we can render the
 * provider prefix even for raw models that don't have their own
 * curated `/api/pricing/models` entry.
 *
 * Real example: OmniRoute's `pricing['cohere']` slot lists 10 curated
 * models but `/v1/models` also returns `cohere/rerank-multilingual-v3.0`
 * and `cohere/rerank-v4.0-fast` (not in the curated 10). Without this
 * index, those rows surface in the picker as `cohere/...` with no
 * `Cohere - ` prefix because the per-model enrichment lookup misses.
 *
 * This index records the first non-empty `providerDisplayName` seen
 * for each alias, plus the alias itself. Callers use it to synthesize
 * a minimal `OmniRouteEnrichmentEntry` whenever the direct lookup
 * misses but the raw id's prefix matches a known alias.
 *
 * Built once per refresh; first-wins on duplicate alias (matches
 * `buildCanonicalToAliasMap` semantics).
 */
export function buildAliasIndex(
  enrichment: OmniRouteEnrichmentMap | undefined
): Map<string, OmniRouteEnrichmentEntry> {
  const out = new Map<string, OmniRouteEnrichmentEntry>();
  if (!enrichment) return out;
  for (const entry of enrichment.values()) {
    const alias = typeof entry.providerAlias === "string" ? entry.providerAlias.trim() : "";
    if (alias.length === 0) continue;
    if (out.has(alias)) {
      // First-wins, but upgrade to the first entry that carries a
      // non-empty providerDisplayName so the prefix renders nicely.
      const existing = out.get(alias);
      if (
        existing &&
        (!existing.providerDisplayName || existing.providerDisplayName.trim().length === 0) &&
        typeof entry.providerDisplayName === "string" &&
        entry.providerDisplayName.trim().length > 0
      ) {
        out.set(alias, entry);
      }
      continue;
    }
    out.set(alias, entry);
  }
  return out;
}

/**
 * Resolve a synthesised enrichment entry for `applyProviderTag` /
 * `shortProviderLabel` consumption, combining two sources:
 *
 *  1. The direct per-model enrichment match (if present).
 *  2. A per-alias fallback derived from `buildAliasIndex` — covers raw
 *     ids whose prefix matches a known alias but the specific model
 *     id wasn't curated in `/api/pricing/models`. Example:
 *     `cohere/rerank-multilingual-v3.0` falls back to the cohere slot's
 *     `providerDisplayName='Cohere'` even though that specific id
 *     isn't in the curated 10-model list.
 *
 * Returns `undefined` when neither source surfaces an alias.
 *
 * NOTE: this function is read-only over its inputs; it never mutates
 * the underlying `direct` entry. When it falls back to the alias
 * index, it constructs a fresh minimal entry exposing only the
 * provider-prefix fields (`providerAlias`, `providerCanonical`,
 * `providerDisplayName`). Other fields (name, pricing) are explicitly
 * left undefined so `applyEnrichment` won't accidentally overwrite a
 * model name with the alias-slot label.
 */
export function resolveProviderTagEntry(
  rawId: string,
  direct: OmniRouteEnrichmentEntry | undefined,
  aliasIndex: Map<string, OmniRouteEnrichmentEntry>,
  canonicalToAlias?: Map<string, string>
): OmniRouteEnrichmentEntry | undefined {
  if (direct) {
    const alias = typeof direct.providerAlias === "string" ? direct.providerAlias.trim() : "";
    const display =
      typeof direct.providerDisplayName === "string" ? direct.providerDisplayName.trim() : "";
    if (alias.length > 0 || display.length > 0) return direct;
  }
  const slash = rawId.indexOf("/");
  if (slash <= 0) return direct;
  const prefix = rawId.slice(0, slash);
  // 1. Direct alias lookup (`cohere/...` → cohere slot keyed by alias=cohere).
  let fromAlias = aliasIndex.get(prefix);
  // 2. Canonical fallback (`pollinations/...` → look up via alias `pol`).
  if (!fromAlias && canonicalToAlias) {
    const alias = canonicalToAlias.get(prefix);
    if (alias) fromAlias = aliasIndex.get(alias);
  }
  if (!fromAlias) return direct;
  // Synthesize: borrow only the provider-prefix metadata.
  return {
    providerAlias: fromAlias.providerAlias,
    providerCanonical: fromAlias.providerCanonical,
    providerDisplayName: fromAlias.providerDisplayName,
  };
}

/**
 * Apply enrichment overlay onto a ModelV2 entry. Mutates and returns the
 * passed entry for convenience.
 */
/**
 * Normalise a model display name so free-tier models always carry a
 * consistent `[Free] ` prefix instead of a trailing `(Free)` suffix or an
 * ad-hoc `free` word anywhere in the name.
 *
 * Examples:
 *   "GPT-4.1 (Free)"          → "[Free] GPT-4.1"
 *   "DeepSeek V4 Flash Free"  → "[Free] DeepSeek V4 Flash"
 *   "Claude Opus 4.7"         → "Claude Opus 4.7"   (unchanged)
 */
export { _normaliseFreeLabel as normaliseFreeLabel };

export function applyEnrichment(
  model: ModelV2,
  enrichment: OmniRouteEnrichmentEntry | undefined
): ModelV2 {
  if (!enrichment) return model;
  if (enrichment.name && enrichment.name.trim().length > 0) {
    model.name = _normaliseFreeLabel(enrichment.name);
  }
  if (enrichment.pricing) {
    if (typeof enrichment.pricing.input === "number") {
      model.cost.input = enrichment.pricing.input;
    }
    if (typeof enrichment.pricing.output === "number") {
      model.cost.output = enrichment.pricing.output;
    }
    if (typeof enrichment.pricing.cacheRead === "number") {
      model.cost.cache.read = enrichment.pricing.cacheRead;
    }
    if (typeof enrichment.pricing.cacheWrite === "number") {
      model.cost.cache.write = enrichment.pricing.cacheWrite;
    }
  }
  return model;
}

// ─────────────────────────────────────────────────────────────────────────
// COMPRESSION METADATA — pull /api/context/combos so combo entries can be
// tagged with their compression pipeline. Gated by
// features.compressionMetadata (off by default).
// ─────────────────────────────────────────────────────────────────────────

/** Single step in a compression combo's pipeline. */
export interface OmniRouteCompressionStep {
  engine: string; // "rtk" | "caveman" | "aggressive" | ...
  intensity?: string; // "minimal" | "lite" | "standard" | "full" | "ultra" | "aggressive"
}

/** Compression combo as returned by /api/context/combos. */
export interface OmniRouteCompressionCombo {
  id: string;
  name?: string;
  description?: string;
  pipeline: OmniRouteCompressionStep[];
  isDefault?: boolean;
}

export type OmniRouteCompressionMetaFetcher = (
  baseURL: string,
  apiKey: string,
  timeoutMs?: number
) => Promise<OmniRouteCompressionCombo[]>;

/**
 * Default compression-metadata fetcher — calls `GET /api/context/combos`.
 * Tolerates envelope shapes `{ combos: [...] }`, `[...]`, or
 * `{ data: [...] }`. Soft-fails (returns []) on non-2xx or parse errors.
 */
export const defaultOmniRouteCompressionMetaFetcher: OmniRouteCompressionMetaFetcher = async (
  baseURL,
  apiKey,
  timeoutMs = 10_000
) => {
  const empty: OmniRouteCompressionCombo[] = [];
  if (!baseURL || !apiKey) return empty;
  const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
  const url = `${root}/api/context/combos`;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), timeoutMs);
  try {
    const res = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
      signal: ac.signal,
    });
    if (!res.ok) return empty;
    const body = (await res.json()) as unknown;
    const list = Array.isArray(body)
      ? body
      : Array.isArray((body as { combos?: unknown[] })?.combos)
        ? (body as { combos: unknown[] }).combos
        : Array.isArray((body as { data?: unknown[] })?.data)
          ? (body as { data: unknown[] }).data
          : [];
    const out: OmniRouteCompressionCombo[] = [];
    for (const raw of list) {
      if (!raw || typeof raw !== "object") continue;
      const id = (raw as { id?: unknown }).id;
      const pipeline = (raw as { pipeline?: unknown }).pipeline;
      if (typeof id !== "string" || id.length === 0) continue;
      if (!Array.isArray(pipeline)) continue;
      const steps: OmniRouteCompressionStep[] = [];
      for (const step of pipeline) {
        if (!step || typeof step !== "object") continue;
        const engine = (step as { engine?: unknown }).engine;
        if (typeof engine !== "string" || engine.length === 0) continue;
        const intensity = (step as { intensity?: unknown }).intensity;
        const entry: OmniRouteCompressionStep = { engine };
        if (typeof intensity === "string" && intensity.length > 0) {
          entry.intensity = intensity;
        }
        steps.push(entry);
      }
      const combo: OmniRouteCompressionCombo = { id, pipeline: steps };
      const name = (raw as { name?: unknown }).name;
      if (typeof name === "string" && name.length > 0) combo.name = name;
      const description = (raw as { description?: unknown }).description;
      if (typeof description === "string") combo.description = description;
      const isDefault = (raw as { isDefault?: unknown }).isDefault;
      if (typeof isDefault === "boolean") combo.isDefault = isDefault;
      out.push(combo);
    }
    return out;
  } catch {
    return empty;
  } finally {
    clearTimeout(timer);
  }
};

/**
 * Map of well-known compression-intensity tokens to a single emoji
 * conveying "how much" compression is applied. Traffic-light palette:
 *
 *   🟢 minimal / lite   — almost no loss
 *   🟡 standard          — balanced
 *   🟠 aggressive / full — heavy
 *   🔴 ultra             — extreme
 *
 * Lookup is case-insensitive. Unknown intensities fall through to the
 * raw text form (`engine:<intensity>`) so we never hide a value that
 * OmniRoute knows but the plugin doesn't.
 *
 * Exported for callers (and tests) that want to assemble their own
 * pipeline strings.
 */
export const COMPRESSION_INTENSITY_EMOJI: Record<string, string> = {
  minimal: "🟢",
  lite: "🟢",
  standard: "🟡",
  aggressive: "🟠",
  full: "🟠",
  ultra: "🔴",
};

/**
 * Format a compression pipeline as a short human-readable string for
 * combo `name` decoration. Intensity tokens render as a traffic-light
 * emoji so a column scan reveals "how compressed" the combo is at a
 * glance:
 *
 *   `[rtk🟡 → caveman🟠]`    (rtk:standard → caveman:full)
 *   `[rtk🔴]`                 (rtk:ultra, single-step)
 *   `[caveman]`               (engine without intensity, no emoji)
 *   `[rtk:custom-thing]`      (unknown intensity, raw-text fallback)
 */
export function formatCompressionPipeline(pipeline: OmniRouteCompressionStep[]): string {
  if (!pipeline || pipeline.length === 0) return "";
  return (
    "[" +
    pipeline
      .map((s) => {
        if (!s.intensity) return s.engine;
        const emoji = COMPRESSION_INTENSITY_EMOJI[s.intensity.toLowerCase()];
        return emoji ? `${s.engine}${emoji}` : `${s.engine}:${s.intensity}`;
      })
      .join(" → ") +
    "]"
  );
}

// ─────────────────────────────────────────────────────────────────────────
// /api/providers (provider-connection status) — optional read used by the
// `features.usableOnly` filter. Returns the operator's installed OmniRoute
// provider connections, each with `provider` (canonical id), `isActive`,
// `testStatus`. We treat a provider as USABLE when at least one of its
// connections is `isActive: true && testStatus: 'active'`. Aliases (e.g.
// `cc → claude`) are resolved through the enrichment map.
// ─────────────────────────────────────────────────────────────────────────

/** Subset of `/api/providers/connections[]` we read. Other fields are kept as a permissive index signature. */
export interface OmniRouteProviderConnection {
  /** Connection UUID. */
  id: string;
  /** Canonical provider id, e.g. `claude`, `gemini`, `kiro`. Matches `entry.id` in `/api/pricing/models`. */
  provider: string;
  /** Connection auth flavor, e.g. `apikey`, `oauth`, `cookie`. */
  authType?: string;
  /** Operator-visible label. */
  name?: string;
  /** Operator toggle — when false, the connection is provisioned but disabled. */
  isActive?: boolean;
  /** Health-check verdict — `active` means routable; `expired`/`error`/`unavailable` mean not. */
  testStatus?: string;
  /** Permissive bag — additional fields (priority, backoffLevel, etc.) pass through untouched. */
  [k: string]: unknown;
}

export type OmniRouteProvidersFetcher = (
  baseURL: string,
  apiKey: string,
  timeoutMs?: number
) => Promise<OmniRouteProviderConnection[]>;

/**
 * Default providers fetcher — calls `GET /api/providers`. Tolerates envelope
 * shapes `{ connections: [...] }`, `[...]`, or `{ data: [...] }`. Soft-fails
 * (returns []) on non-2xx or parse errors so the `usableOnly` filter
 * gracefully degrades to "no filter" instead of hiding the whole catalog.
 */
export const defaultOmniRouteProvidersFetcher: OmniRouteProvidersFetcher = async (
  baseURL,
  apiKey,
  timeoutMs = 10_000
) => {
  const empty: OmniRouteProviderConnection[] = [];
  if (!baseURL || !apiKey) return empty;
  const root = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
  const url = `${root}/api/providers`;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), timeoutMs);
  try {
    const res = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        Accept: "application/json",
      },
      signal: ac.signal,
    });
    if (!res.ok) return empty;
    const body = (await res.json()) as unknown;
    const list = Array.isArray(body)
      ? body
      : Array.isArray((body as { connections?: unknown[] })?.connections)
        ? (body as { connections: unknown[] }).connections
        : Array.isArray((body as { data?: unknown[] })?.data)
          ? (body as { data: unknown[] }).data
          : [];
    const out: OmniRouteProviderConnection[] = [];
    for (const raw of list) {
      if (!raw || typeof raw !== "object") continue;
      const provider = (raw as { provider?: unknown }).provider;
      if (typeof provider !== "string" || provider.length === 0) continue;
      const id = (raw as { id?: unknown }).id;
      const idStr = typeof id === "string" && id.length > 0 ? id : provider;
      out.push({ ...(raw as Record<string, unknown>), id: idStr, provider });
    }
    return out;
  } catch {
    return empty;
  } finally {
    clearTimeout(timer);
  }
};

/**
 * Compute the set of provider aliases that have at least one healthy,
 * active connection. Resolves alias → canonical id through the enrichment
 * map (which is keyed under both `${alias}/${id}` and bare `${id}` — we
 * walk only the namespaced keys to derive the alias↔canonical mapping).
 *
 * Returns:
 *   - `aliases`: set of alias prefixes safe to keep (e.g. `cc`, `gemini`).
 *   - `canonicals`: set of canonical provider ids (e.g. `claude`, `kiro`).
 *
 * Callers should treat membership in EITHER set as "usable" — raw model
 * ids may be `<alias>/<model>` (`cc/claude-opus-4-7`) OR `<canonical>/<model>`
 * (`claude/sonnet-4`) depending on the OmniRoute deployment's `/v1/models`
 * surface shape.
 *
 * Subtract-filter semantics: callers MUST also keep models whose prefix is
 * unknown to BOTH `/api/pricing/models` and `/api/providers` (e.g.
 * agentrouter-style synthetic prefixes). The right boolean is "if I see this
 * prefix in EITHER catalog table AND it's not usable, drop; otherwise keep".
 */
export function usableProviderAliasSet(
  connections: OmniRouteProviderConnection[],
  enrichment: OmniRouteEnrichmentMap | undefined
): {
  aliases: Set<string>;
  canonicals: Set<string>;
  knownAliases: Set<string>;
} {
  const usableCanonicals = new Set<string>();
  for (const c of connections) {
    if (!c || c.isActive !== true) continue;
    if (typeof c.testStatus === "string" && c.testStatus !== "active") continue;
    if (typeof c.provider === "string" && c.provider.length > 0) {
      usableCanonicals.add(c.provider);
    }
  }
  const aliases = new Set<string>();
  const knownAliases = new Set<string>();
  if (enrichment) {
    // Walk enrichment entries to map alias → canonical via the metadata
    // populated by `defaultOmniRouteEnrichmentFetcher`. Every entry carries
    // its providerAlias + providerCanonical so the namespaced/bare key
    // duplication is harmless. Collect EVERY alias we encounter (regardless
    // of usability) into `knownAliases` so the downstream filter can decide
    // "this prefix was in /api/pricing/models" in O(1) instead of O(E).
    for (const entry of enrichment.values()) {
      const alias = entry.providerAlias;
      const canonical = entry.providerCanonical;
      if (typeof alias !== "string" || alias.length === 0) continue;
      knownAliases.add(alias);
      if (typeof canonical !== "string" || canonical.length === 0) continue;
      if (usableCanonicals.has(canonical)) aliases.add(alias);
    }
  }
  // Always include every usable canonical as an alias too — handles the
  // common case where `/v1/models` ids use the canonical id directly
  // (e.g. `gemini/gemini-1.5-pro`).
  for (const canonical of usableCanonicals) aliases.add(canonical);
  return { aliases, canonicals: usableCanonicals, knownAliases };
}

/**
 * Decide whether a raw `/v1/models` id passes the `usableOnly` filter.
 *
 * Rules (subtract-filter — bias toward keep):
 *   - id has no `/` → keep (combos/synthetic entries handled separately).
 *   - prefix matches a known usable alias OR canonical → keep.
 *   - prefix is unknown to BOTH the connection table AND the enrichment
 *     map → keep (we can't prove it's NOT usable; could be agentrouter).
 *   - prefix is known to the enrichment map BUT not in usable set → drop.
 *
 * Pure function — exported so static + dynamic hooks share the same
 * verdict logic without divergence.
 */
export function isUsableRawModelId(
  id: string,
  usable: {
    aliases: Set<string>;
    canonicals: Set<string>;
    knownAliases: Set<string>;
  },
  enrichment: OmniRouteEnrichmentMap | undefined
): boolean {
  const slash = id.indexOf("/");
  if (slash <= 0) return true;
  const prefix = id.slice(0, slash);
  if (usable.aliases.has(prefix) || usable.canonicals.has(prefix)) return true;
  // O(1) "known prefix" check via pre-calculated knownAliases set.
  // If prefix was in /api/pricing/models but is NOT in usable set,
  // drop the model. Unknown prefixes (e.g. agentrouter-style synthetic)
  // pass through (subtract-filter semantics).
  if (usable.knownAliases.has(prefix)) return false;
  return true;
}

/**
 * Decide whether a combo passes the `usableOnly` filter. A combo keeps
 * when AT LEAST ONE of its members maps to a usable canonical provider.
 * Combos with zero resolvable members pass through (already degraded to
 * all-false LCD posture and surfaced as cosmetic-only entries).
 */
export function isUsableCombo(
  combo: OmniRouteRawCombo,
  usable: {
    aliases: Set<string>;
    canonicals: Set<string>;
    knownAliases: Set<string>;
  }
): boolean {
  const steps = Array.isArray(combo.models) ? combo.models : [];
  if (steps.length === 0) return true;
  // The provider id is folded INTO the full model string by OmniRoute's
  // `normalizeComboRecord` (e.g. "cc/claude-opus-4-7") — combo member refs do
  // NOT carry a separate `providerId` field. Derive the prefix from `step.model`
  // and apply the same subtract-filter verdict as `isUsableRawModelId`.
  let sawResolvableMember = false;
  for (const step of steps) {
    // Nested combo refs carry no model id we can resolve to a provider here.
    if (step?.kind === "combo-ref") continue;
    const modelId = typeof step?.model === "string" ? step.model : "";
    const slash = modelId.indexOf("/");
    if (slash <= 0) continue; // no provider prefix to evaluate
    sawResolvableMember = true;
    const prefix = modelId.slice(0, slash);
    if (usable.aliases.has(prefix) || usable.canonicals.has(prefix)) return true;
    // Unknown prefix (not in the known-alias universe) → can't prove
    // unroutable; keep. Known-but-not-usable prefixes keep scanning.
    if (!usable.knownAliases.has(prefix)) return true;
  }
  // No member resolved to a provider prefix → can't prove unroutable; keep.
  if (!sawResolvableMember) return true;
  // Every resolvable member used a known-but-non-usable prefix → drop.
  return false;
}

// ─────────────────────────────────────────────────────────────────────────
// #9473 — Model allowlist / blocklist filter helpers
// ─────────────────────────────────────────────────────────────────────────

/**
 * Pre-compiled filter structure for the model allowlist/blocklist.
 *
 * "exact" holds full raw IDs (e.g. "cc/claude-opus-4-7") for O(1) match.
 * "suffixes" holds bare model IDs (e.g. "claude-opus-4-7") that match any
 * "{prefix}/claude-opus-4-7" — so operators can curate by model name without
 * knowing the provider prefix.
 */
export interface ModelListFilter {
  exact: Set<string>;
  suffixes: Set<string>;
}

/**
 * Compile a string[] of model IDs into a pre-computed filter structure.
 * Returns undefined when the list is empty or undefined — the "no filter"
 * state that callers use as a passthrough.
 *
 * IDs containing a "/" are stored in "exact"; bare IDs (no slash) go into
 * "suffixes" and match any "{prefix}/<suffix>" at check time.
 */
export function compileModelListFilter(list?: string[]): ModelListFilter | undefined {
  if (!list || list.length === 0) return undefined;
  const exact = new Set<string>();
  const suffixes = new Set<string>();
  for (const id of list) {
    if (id.includes("/")) {
      exact.add(id);
    } else {
      suffixes.add(id);
    }
  }
  if (exact.size === 0 && suffixes.size === 0) return undefined;
  return { exact, suffixes };
}

/**
 * Decide whether a raw model ID passes the allowlist/blocklist filter.
 *
 * Rules (all filters AND together with usableOnly):
 *   - No visible filter and no hidden filter → keep (passthrough).
 *   - Visible filter set: id must match either the exact set or the suffix
 *     set (bare suffix "claude-opus-4-7" matches any "{prefix}/claude-opus-4-7").
 *   - Hidden filter set: id must NOT match either the exact or suffix set.
 *   - If id is in BOTH visible and hidden → DROP (deny wins — safer).
 *   - No-slash ids (e.g. combo names like "claude-primary") are checked
 *     against the exact set directly, and against the suffix set as a bare
 *     match.
 *
 * Pure function — exported so static + dynamic hooks share the same
 * verdict logic without divergence.
 */
export function passesModelAllowlist(
  id: string,
  visible?: ModelListFilter,
  hidden?: ModelListFilter
): boolean {
  // Hidden filter takes precedence (deny wins over allow).
  if (hidden) {
    if (hidden.exact.has(id) || matchesSuffix(id, hidden.suffixes)) return false;
  }
  // Visible filter: if set, id must match.
  if (visible) {
    if (!visible.exact.has(id) && !matchesSuffix(id, visible.suffixes)) return false;
  }
  return true;
}

/**
 * Decide whether a combo passes the allowlist filter. A combo keeps when
 * AT LEAST ONE of its members matches the visible filter. When no visible
 * filter is set, all combos pass. Combos with zero resolvable members pass
 * (mirrors `isUsableCombo` semantics).
 */
export function passesComboAllowlist(combo: OmniRouteRawCombo, visible?: ModelListFilter): boolean {
  if (!visible) return true;
  const steps = Array.isArray(combo.models) ? combo.models : [];
  if (steps.length === 0) return true;
  let sawResolvableMember = false;
  for (const step of steps) {
    if (step?.kind === "combo-ref") continue;
    const modelId = typeof step?.model === "string" ? step.model : "";
    if (modelId.length === 0) continue;
    sawResolvableMember = true;
    if (visible.exact.has(modelId) || matchesSuffix(modelId, visible.suffixes)) return true;
  }
  // No resolvable member → can't prove it should be hidden; keep.
  if (!sawResolvableMember) return true;
  // Every resolvable member failed the allowlist → drop.
  return false;
}

/**
 * Check whether a raw model ID matches any suffix in the set.
 * For an id like `cc/claude-opus-4-7`, the suffix after the first `/`
 * is checked against the suffixes set. For a bare id like `claude-primary`,
 * the id itself is checked against the suffixes set.
 */
function matchesSuffix(id: string, suffixes: Set<string>): boolean {
  if (suffixes.size === 0) return false;
  const slash = id.indexOf("/");
  const suffix = slash > 0 ? id.slice(slash + 1) : id;
  return suffixes.has(suffix);
}

/**
 * Slugify a combo display name into a copy/paste-friendly URL-safe segment.
 * Lowercases, replaces any run of non-alphanumeric chars with a single dash,
 * trims leading/trailing dashes. Empty input or all-special input returns
 * the empty string (caller must fall back to the combo's UUID id).
 *
 * Example: `Claude Tier` → `claude-tier`, `GPT 5.5 / Pro` → `gpt-5-5-pro`.
 */
export function slugifyComboName(name: string): string {
  if (typeof name !== "string") return "";
  return trimLeadingDashes(trimTrailingDashes(name.toLowerCase().replace(/[^a-z0-9]+/g, "-")));
}

/**
 * Build a combo's static-block key, provider-prefixed as `<providerId>/<slug>`
 * (e.g. `omniroute/MASTER`, `omniroute/MASTER-LIGHT`), guaranteeing uniqueness
 * across an entire static catalog. If `<providerId>/<slug>` is already present in
 * `used`, suffixes a short UUID-prefix disambiguator from `combo.id` so the second
 * combo doesn't silently overwrite the first. Mutates `used` in place by recording
 * the chosen key. Returns the final `<providerId>/<slug>` key.
 *
 * NOTE: the key MUST carry the OWNING provider prefix (`omniroute/…`), never a
 * `combo/` namespace — OpenCode parses model IDs on `/` to extract the provider,
 * so `combo/MASTER` would resolve provider=`combo` (no credentials) and fail with
 * "Unable to determine provider", whereas `omniroute/MASTER` resolves provider=
 * `omniroute` and the openai-compatible adapter strips the prefix and sends the
 * bare slug upstream, which the server resolves via getComboByName. See PR #4184.
 *
 * Falls back to `<providerId>/<id>` when the friendly name slugifies to the empty
 * string (e.g. a combo named just punctuation).
 */
export function buildComboKey(
  combo: OmniRouteRawCombo,
  used: Set<string>,
  providerId: string
): string {
  const friendlyName = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
  let slug = slugifyComboName(friendlyName);
  if (slug.length === 0) slug = combo.id;
  let key = `${providerId}/${slug}`;
  if (used.has(key)) {
    const tail = combo.id.split("-")[0] ?? combo.id;
    key = `${providerId}/${slug}-${tail}`;
    // Defensive: in the (impossible) event the disambiguated key also
    // collides, append the full id.
    if (used.has(key)) key = `${providerId}/${slug}-${combo.id}`;
  }
  used.add(key);
  return key;
}

/**
 * Internal cache key: `${baseURL}::sha256(credentialId)`. The credential id
 * combines the inference key and effective management-read token so catalog
 * results fetched under different permissions never share an entry. We hash
 * it so the cache key is safe to inspect without leaking either secret.
 * Different credential tuples MUST keep independent cache entries: a single
 * OC user may register prod + preprod OmniRoute side-by-side with distinct
 * keys, and serving one's catalog from the other's cache would be a
 * correctness bug, not just a privacy one.
 */
// codeql[js/insufficient-password-hash]: the input here is an API-key
// identifier we use solely to derive an in-memory cache lookup key — it is
// never stored, transmitted, compared against a hash, or used as a password.
// SHA-256 is intentional: cheap + deterministic, prevents the raw secret
// from sitting in memory dumps alongside the cache map. Slow KDFs (bcrypt/
// argon2) would defeat the purpose (sub-ms lookups on every request).
function modelsCacheKey(baseURL: string, credentialId: string): string {
  const h = createHash("sha256").update(credentialId).digest("hex");
  return `${baseURL}::${h}`;
}

/**
 * Shared fetch-result cache entry. Holds the RAW `/v1/models` + `/api/combos`
 * responses (NOT a pre-derived ModelV2 / static-entry shape) so the provider
 * hook (T-03/T-05) and the config-shim hook (T-07) can derive their own
 * output shapes from the same source without re-fetching.
 *
 * Why raw instead of derived:
 *   - provider hook emits ModelV2 (rich nested capabilities + cost + limits).
 *   - config hook emits the stripped sibling shape
 *     (`{name, attachment, reasoning, tool_call, temperature, limit?}`).
 *   - These overlap but neither is a superset of the other (ModelV2 has no
 *     `tool_call` field — it's `toolcall`; the stripped shape has no
 *     `cost`/`status`/`headers`). Caching the raw responses is the only
 *     lossless option.
 *   - On OC ≥1.14.49 cold start BOTH hooks fire within the same
 *     OmniRoutePlugin instance — sharing the cache means /v1/models +
 *     /api/combos each hit the gateway exactly ONCE per TTL refresh, not
 *     twice.
 */
export interface OmniRouteFetchCacheEntry {
  rawModels: OmniRouteRawModelEntry[];
  rawCombos: OmniRouteRawCombo[];
  /** Display-name + pricing overlay from /api/pricing/models. Empty Map when feature is disabled or fetch failed. */
  rawEnrichment: OmniRouteEnrichmentMap;
  /** Compression combos from /api/context/combos. Empty array when feature is disabled or fetch failed. */
  rawCompressionCombos: OmniRouteCompressionCombo[];
  /** Provider connections from /api/providers. Empty array when feature is disabled or fetch failed. */
  rawConnections: OmniRouteProviderConnection[];
  expiresAt: number;
}

export type OmniRouteFetchCache = Map<string, OmniRouteFetchCacheEntry>;

/**
 * Build the ProviderHook portion of the plugin for a given options bag.
 * Exported standalone so the contract is unit-testable without faking the
 * full PluginInput / Hooks surface, and so multi-instance setups can each
 * own their own cache (a fresh hook closure per plugin tuple).
 *
 * Behavioural contract:
 *   - `id` binds to the resolved `providerId` (multi-instance: each plugin
 *     tuple's hook lists models under its own provider id).
 *   - `models(provider, ctx)` extracts the api key from `ctx.auth` (rejecting
 *     non-`api` flavors with `{}` — same posture as the auth loader); calls
 *     both `/v1/models` and `/api/combos` fetchers; maps raw `/v1/models`
 *     entries through `mapRawModelToModelV2`; maps each `/api/combos` entry
 *     through `mapComboToModelV2` (LCD across its member models); merges
 *     combos into the same map under their combo id; caches the unified
 *     result by `(baseURL, sha256(apiKey))` for `modelCacheTtl`.
 *   - **Combo / model ID collisions: combos win.** OmniRoute treats combos
 *     as the curated routing surface; if a combo and a raw model share an
 *     id the operator's intent is clearly the combo. We emit a
 *     `console.warn` exactly once per `(baseURL, apiKey, comboId)`
 *     collision so the operator can spot the unusual naming choice
 *     without log spam on every cache refresh.
 *   - **Combos fetch failure does NOT break the catalog**: soft-fail with
 *     a `console.warn` and fall back to a models-only catalog. Rationale:
 *     `/api/combos` requires a management-scoped key and OmniRoute may
 *     not have any combos provisioned (preprod returned `{combos: []}`
 *     at probe time). Hard-failing the entire catalog when combos are
 *     optional would silently hide the whole provider from OC's model
 *     picker.
 *   - **`/v1/models` fetch failure DOES propagate.** Without models
 *     there's no catalog at all, so an empty `{}` would just mask the
 *     error.
 *   - Cache is in-memory per hook instance, shared between models and
 *     combos (one fetch pair per (baseURL, apiKey) per TTL refresh).
 *
 * @param opts Plugin options (providerId, baseURL, modelCacheTtl, …).
 * @param deps Dependency injection. `fetcher` defaults to the live
 *             `/v1/models` HTTP fetcher; `combosFetcher` defaults to the
 *             live `/api/combos` HTTP fetcher (override for tests / to
 *             disable combos by injecting one that returns `[]`). `now`
 *             defaults to `Date.now` (overridable for TTL tests). `cache`
 *             lets the caller share state across reconstructions (unused
 *             outside tests today).
 */
export function createOmniRouteProviderHook(
  opts?: OmniRoutePluginOptions,
  deps: {
    fetcher?: OmniRouteModelsFetcher;
    combosFetcher?: OmniRouteCombosFetcher;
    enrichmentFetcher?: OmniRouteEnrichmentFetcher;
    compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
    providersFetcher?: OmniRouteProvidersFetcher;
    now?: () => number;
    cache?: OmniRouteFetchCache;
    logger?: _Logger;
  } = {}
): ProviderHook {
  const resolved = resolveOmniRoutePluginOptions(opts);
  const logger =
    deps.logger ??
    createLogger(
      resolved.features?.startupDebug ? "debug" : (resolved.features?.logLevel ?? "warn")
    );
  const fetcher = deps.fetcher ?? defaultOmniRouteModelsFetcher;
  // T-05: combo discovery merges `/api/combos` entries into the same map as
  // `/v1/models`. Default fetcher is declared further down the file; the
  // reference resolves at hook-invocation time, not at hook-construction
  // time, so source-order beyond hoisting rules has no semantic effect.
  const combosFetcher = deps.combosFetcher ?? defaultOmniRouteCombosFetcher;
  const enrichmentFetcher = deps.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
  const compressionMetaFetcher =
    deps.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
  const providersFetcher = deps.providersFetcher ?? defaultOmniRouteProvidersFetcher;
  // Features defaults (mirror v0.1.0 behavior when unset).
  const features = resolved.features ?? {};
  const wantCombos = features.combos !== false;
  const wantEnrichment = features.enrichment !== false;
  const wantCompressionMeta = features.compressionMetadata === true;
  const wantUsableOnly = features.usableOnly === true;
  const wantProviderTag = features.providerTag !== false;
  // #9473: model allowlist/blocklist — compile once per hook instance.
  const visibleFilter = compileModelListFilter(features.visibleModels);
  const hiddenFilter = compileModelListFilter(features.hiddenModels);
  const now = deps.now ?? Date.now;
  // T-07: cache holds RAW fetch results (not pre-derived ModelV2) so that
  // the config-shim hook can share the same cache and derive its stripped
  // sibling shape from the same source without a second round-trip.
  const cache: OmniRouteFetchCache = deps.cache ?? new Map();
  // T-05: collision-warning deduper. Emit warn once per (cacheKey, comboId)
  // tuple per hook instance so the operator sees the unusual naming choice
  // once per session, not once per cache refresh.
  const collisionWarned = new Set<string>();

  return {
    id: resolved.providerId,
    async models(_provider, ctx) {
      // Auth narrowing — same posture as the auth loader (T-02). Non-api
      // flavors and empty keys → empty catalog. OC then exposes the
      // /connect flow rather than spamming /v1/models with bad creds.
      const auth = ctx?.auth;
      if (
        !auth ||
        typeof auth !== "object" ||
        (auth as { type?: unknown }).type !== "api" ||
        typeof (auth as { key?: unknown }).key !== "string" ||
        (auth as { key: string }).key.length === 0
      ) {
        return {};
      }
      const apiKey = (auth as { key: string }).key;
      // Management-plane catalog reads may use a narrower read-only token.
      // Backward compatibility: when unset, retain the historical apiKey use.
      const managementReadToken = resolved.managementReadToken ?? apiKey;

      // baseURL resolution: plugin opts first, then credential-attached
      // baseURL (auth backends sometimes stash it next to the key), then the
      // provider config itself — a baseURL set via opencode.json provider
      // options (or a config hook) lands on `provider.options` and is not
      // visible through either of the first two links. No silent default to
      // localhost: a misconfigured plugin should surface a clear warning,
      // not phantom /v1/models calls. Cast through unknown because the Auth
      // union (OAuth | ApiAuth | WellKnownAuth) doesn't declare baseURL on
      // any branch — we duck-type it as a defensive extension point.
      const authBaseURL = (auth as unknown as { baseURL?: unknown }).baseURL;
      const providerBaseURL = (_provider as { options?: { baseURL?: unknown } } | undefined)
        ?.options?.baseURL;
      const baseURL =
        resolved.baseURL ??
        (typeof authBaseURL === "string" && authBaseURL.length > 0 ? authBaseURL : undefined) ??
        (typeof providerBaseURL === "string" && providerBaseURL.length > 0
          ? providerBaseURL
          : undefined) ??
        "";
      if (!baseURL) {
        logger.error(
          `provider.models(${resolved.providerId}): ` +
            `no baseURL resolvable — checked plugin opts, auth.json, and provider config. ` +
            `Set baseURL in opencode.json plugin options or run \`opencode connect ${resolved.providerId}\` with a baseURL.`
        );
        return {};
      }

      const cacheKey = modelsCacheKey(baseURL, `${apiKey}\0${managementReadToken}`);
      const t = now();
      const cached = cache.get(cacheKey);

      let rawModels: OmniRouteRawModelEntry[];
      let rawCombos: OmniRouteRawCombo[];
      let rawEnrichment: OmniRouteEnrichmentMap;
      let rawCompressionCombos: OmniRouteCompressionCombo[];
      let rawConnections: OmniRouteProviderConnection[];
      if (cached && cached.expiresAt > t) {
        rawModels = cached.rawModels;
        rawCombos = cached.rawCombos;
        rawEnrichment = cached.rawEnrichment;
        rawCompressionCombos = cached.rawCompressionCombos;
        rawConnections = cached.rawConnections;
      } else {
        // Models fetch is required (no catalog otherwise → silent provider
        // disappearance). We do NOT wrap this in a try; let the error
        // propagate to OC's UI.
        rawModels = await fetcher(baseURL, apiKey, 10_000);

        // T-05: combos fetch is best-effort, gated by features.combos.
        // Soft-fail on any error: emit a warn-level diagnostic and fall back
        // to a models-only catalog. Rationale: /api/combos requires a
        // management-scoped key and OmniRoute may not have any combos
        // provisioned. Hard-failing when combos are optional would
        // silently hide the whole provider from OC's picker.
        rawCombos = [];
        if (wantCombos) {
          try {
            rawCombos = await combosFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logger.warn("combos fetch failed, falling back to models-only catalog", err);
          }
        }

        // Enrichment fetch (nice names + pricing). Best-effort, gated by
        // features.enrichment. Soft-fails to empty map.
        rawEnrichment = new Map();
        if (wantEnrichment) {
          try {
            rawEnrichment = await enrichmentFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logger.warn("enrichment fetch failed, falling back to raw ids", err);
          }
        }

        // Compression metadata fetch. Off by default, gated by
        // features.compressionMetadata. Soft-fails to empty array.
        rawCompressionCombos = [];
        if (wantCompressionMeta) {
          try {
            rawCompressionCombos = await compressionMetaFetcher(
              baseURL,
              managementReadToken,
              10_000
            );
          } catch (err) {
            logger.warn("compression-metadata fetch failed", err);
          }
        }

        // Provider-connections fetch. Off by default, gated by
        // features.usableOnly. Soft-fails to empty array — when the
        // connection table is unreadable we skip the filter entirely
        // (subtract-filter semantics: don't drop everything we couldn't
        // verify).
        rawConnections = [];
        if (wantUsableOnly) {
          try {
            rawConnections = await providersFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logger.warn(
              "/api/providers fetch failed; usableOnly filter disabled for this refresh",
              err
            );
          }
        }

        cache.set(cacheKey, {
          rawModels,
          rawCombos,
          rawEnrichment,
          rawCompressionCombos,
          rawConnections,
          expiresAt: t + resolved.modelCacheTtl,
        });

        // Debug breadcrumb: surface fetch result so operators can confirm
        // the dynamic pipeline fired and how much catalog OmniRoute returned.
        // Emitted once per cache miss (TTL refresh) — quiet on cache hits.
        // Info-level: hidden at the default `warn` level (see #8982).
        logger.info(
          `catalog refreshed for providerId=${resolved.providerId} baseURL=${baseURL}: ` +
            `${rawModels.length} models + ${rawCombos.length} combos + ` +
            `${rawEnrichment.size} enrichment entries + ` +
            `${rawCompressionCombos.length} compression combos + ` +
            `${rawConnections.length} connections ` +
            `(TTL=${resolved.modelCacheTtl}ms)`
        );

        // ── Startup debug: deep-dive into enrichment ────────────────────
        if (resolved.features?.startupDebug === true) {
          await writeStartupDiagnostics({
            providerId: resolved.providerId,
            baseURL,
            modelCount: rawModels.length,
            comboCount: rawCombos.length,
            enrichmentSize: rawEnrichment.size,
            enrichment: rawEnrichment,
            features: resolved.features,
          });
        }
      }

      // Lookup index for LCD member resolution: O(1) per member lookup.
      // Indexed by raw model `id` — combo steps reference this exact
      // string per ComboModelStep in src/lib/combos/steps.ts.
      const rawModelById = new Map<string, OmniRouteRawModelEntry>();
      for (const entry of rawModels) {
        if (entry.id) rawModelById.set(entry.id, entry);
      }

      // usableOnly filter — compute the set of usable alias prefixes once
      // per refresh. Empty when feature is off OR connection fetch failed
      // OR no connections returned, in which case we keep everything
      // (subtract-filter semantics: only drop when we can prove a prefix
      // is NOT usable; never hide the catalog on a soft-fail).
      const usable =
        wantUsableOnly && rawConnections.length > 0
          ? usableProviderAliasSet(rawConnections, rawEnrichment)
          : undefined;

      // Build the canonical→alias reverse map AND the canonical-dedup
      // set once per refresh. Together they fix the dual-keyed
      // `/v1/models` problem where the same model surfaces under BOTH
      // `<alias>/<id>` (enriched) AND `<canonical>/<id>` (raw): we keep
      // the alias key and skip the canonical twin entirely.
      const canonicalToAlias = buildCanonicalToAliasMap(rawEnrichment);
      const canonicalDedup = canonicalDedupSet(rawModels, canonicalToAlias);
      const aliasIndex = buildAliasIndex(rawEnrichment);

      // Map raw models → ModelV2 keyed by id. When enrichment data is
      // present (features.enrichment, default on), overlay the nicer
      // display name + pricing from /api/pricing/models via the
      // alias-fallback lookup chain (covers canonical rows lacking
      // direct pricing entries).
      const models: Record<string, ModelV2> = {};
      for (const entry of rawModels) {
        if (!entry.id) continue;
        if (canonicalDedup.has(entry.id)) continue;
        if (usable && !isUsableRawModelId(entry.id, usable, rawEnrichment)) continue;
        // #9473: allowlist/blocklist filter (AND with usableOnly).
        if (!passesModelAllowlist(entry.id, visibleFilter, hiddenFilter)) continue;
        const model = mapRawModelToModelV2(entry, {
          // #6859: server-facing id — NOT the OC-gate-prefixed `resolved.providerId`.
          providerId: resolved.omnirouteProviderId,
          baseURL,
          apiFormat: resolved.features?.apiFormat,
        });
        const enrichEntry = lookupEnrichment(
          entry.id,
          rawEnrichment,
          canonicalToAlias,
          entry.owned_by
        );
        applyEnrichment(model, enrichEntry);
        // Prepend upstream provider label (e.g. `Claude - Claude Opus 4.7`)
        // so the picker groups same-model rows by upstream connection.
        // Idempotent + gated by `features.providerTag` (default-on).
        // Combos skip this on purpose. The alias-index fallback rescues
        // raw rows like `cohere/rerank-multilingual-v3.0` whose specific
        // model id isn't in `/api/pricing/models` but whose slot is.
        if (wantProviderTag) {
          const tagEntry = resolveProviderTagEntry(
            entry.id,
            enrichEntry,
            aliasIndex,
            canonicalToAlias
          );
          applyProviderTag(model, tagEntry);
        }
        // OC's static-catalog reader parses the key on `/` to recover
        // (providerID, modelID). `mapRawModelToModelV2` already stamps the
        // prefixed id on `model.id` (e.g. `omniroute/claude-primary`), so we
        // must key by `model.id` — not by the raw `entry.id` which would be
        // a bare slug and parse as `providerID=slug, modelID=""`.
        models[model.id] = model;
      }

      // Default compression combo (used to decorate ALL combo names when
      // compression metadata is present). OmniRoute returns at most one
      // entry with `isDefault: true` per /api/context/combos.
      const defaultCompression = wantCompressionMeta
        ? rawCompressionCombos.find((c) => c.isDefault === true)
        : undefined;

      // T-05: map raw combos → ModelV2. Skip hidden combos (operator
      // preference — provisioned but intentionally not surfaced).
      // Resolve each combo's member step list into the matching raw
      // model entries; unknown member ids are silently dropped before
      // mapComboToModelV2 sees them, which then degrades to the
      // all-false LCD posture if zero members remain.
      //
      // Combos are keyed under the `combo/<slug>` namespace so the TUI
      // picker separates them from provider/model pairs and the UUID
      // never surfaces. This mirrors `buildStaticProviderEntry` so the
      // static + dynamic catalogs publish identical keys.
      const comboNames = new Set<string>();
      for (const combo of rawCombos) {
        if (!combo || combo.isHidden === true) continue;
        const n = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
        if (typeof n === "string" && n.length > 0) comboNames.add(n);
      }
      for (const key of Object.keys(models)) {
        if (comboNames.has(key)) delete models[key];
      }

      // ── Combo LCD across nested combo-refs (T-NN) ───────────────────────
      // Combos can nest other combos via `kind: "combo-ref"` members
      // (e.g. MASTER-LIGHT contains LEGACY, KIRO, Opecode Zen FREE). The
      // nested combo's own `limit.context` is computed below in this same
      // loop, so we need a fixpoint iteration: if a combo-ref points at a
      // combo not yet processed, defer this combo and try again after the
      // sibling combos catch up. We bound the retries so a circular combo
      // graph can't deadlock the picker.
      const MAX_COMBO_PASSES = 8;
      const usedComboKeys = new Set<string>();
      // Combos in `rawCombos` that still need (re)processing this round.
      // Shrinks as combos resolve.
      let pending = rawCombos.filter((combo) => {
        if (!combo.id) return false;
        if (combo.isHidden === true) return false;
        if (usable && !isUsableCombo(combo, usable)) return false;
        // #9473: combo allowlist — drop when no member matches visible filter.
        if (visibleFilter && !passesComboAllowlist(combo, visibleFilter)) return false;
        return true;
      });
      // Resolved nested combos keyed by their friendly name, so parent
      // combos that reference them via combo-ref can lift the full
      // capability vector (not just the context window) into their own
      // LCD pass.
      const resolvedComboModelsByName = new Map<string, ModelV2>();

      for (let pass = 0; pass < MAX_COMBO_PASSES && pending.length > 0; pass++) {
        const stillPending: typeof pending = [];
        for (const combo of pending) {
          const memberSteps = Array.isArray(combo.models) ? combo.models : [];
          const memberEntries: OmniRouteRawModelEntry[] = [];
          let deferredThisPass = false;

          for (const step of memberSteps) {
            // Unknown-bridge: ComboMemberRef's DTS type only declares
            // `model?: string`, so verify the runtime shape before reading
            // either `model` (raw member) or `comboName` (nested combo).
            const stepKind = (step as unknown as { kind?: unknown }).kind;

            if (stepKind === "combo-ref") {
              const comboName = (step as unknown as { comboName?: unknown }).comboName;
              if (typeof comboName !== "string" || comboName.length === 0) {
                continue;
              }
              const nestedModel = resolvedComboModelsByName.get(comboName);
              if (!nestedModel) {
                // Nested combo hasn't been processed yet. Defer this
                // combo to the next pass.
                deferredThisPass = true;
                break;
              }
              // Synthesize a member entry that contributes only the
              // nested combo's pre-computed context_length + max_output.
              // Other capability axes default conservatively (no tool
              // calls, no vision) — a nested combo's modalities are an
              // OR, but if we let raw-model defaults leak in we'd
              // over-claim. The combo's own LCD (computed by
              // mapComboToModelV2 from the synthesized entries) will only
              // further restrict capabilities, so this is safe.
              // Synthesize a member entry carrying the nested combo's
              // pre-computed context + capabilities + modalities so the
              // parent combo's LCD is accurate across the whole graph
              // (not just its direct raw-model members).
              const inputModalities: string[] = [];
              if (nestedModel.capabilities.input.text) inputModalities.push("text");
              if (nestedModel.capabilities.input.audio) inputModalities.push("audio");
              if (nestedModel.capabilities.input.image) inputModalities.push("image");
              if (nestedModel.capabilities.input.video) inputModalities.push("video");
              if (nestedModel.capabilities.input.pdf) inputModalities.push("pdf");

              const outputModalities: string[] = [];
              if (nestedModel.capabilities.output.text) outputModalities.push("text");
              if (nestedModel.capabilities.output.audio) outputModalities.push("audio");
              if (nestedModel.capabilities.output.image) outputModalities.push("image");
              if (nestedModel.capabilities.output.video) outputModalities.push("video");
              if (nestedModel.capabilities.output.pdf) outputModalities.push("pdf");

              memberEntries.push({
                id: `combo-ref:${comboName}`,
                context_length: nestedModel.limit.context,
                max_output_tokens: nestedModel.limit.output,
                max_input_tokens: nestedModel.limit.input ?? 0,
                owned_by: "combo",
                input_modalities: inputModalities,
                output_modalities: outputModalities,
                capabilities: {
                  temperature: nestedModel.capabilities.temperature,
                  reasoning: nestedModel.capabilities.reasoning,
                  thinking: nestedModel.capabilities.interleaved,
                  attachment: nestedModel.capabilities.attachment,
                  tool_calling: nestedModel.capabilities.toolcall,
                },
              } as unknown as OmniRouteRawModelEntry);
              continue;
            }

            const modelId = (step as unknown as { model?: unknown }).model;
            if (typeof modelId !== "string" || modelId.length === 0) continue;
            const member = rawModelById.get(modelId);
            if (member) memberEntries.push(member);
          }

          if (deferredThisPass) {
            stillPending.push(combo);
            continue;
          }

          const mapped = mapComboToModelV2(
            combo,
            memberEntries,
            // #6859: server-facing id — NOT the OC-gate-prefixed `resolved.providerId`.
            resolved.omnirouteProviderId,
            baseURL,
            features.apiFormat
          );
          const hasMembers = memberEntries.length > 0;

          // Apply enrichment overlay to combos too (OmniRoute's
          // /api/pricing/models surfaces combos alongside provider-scoped
          // models with curated names).
          applyEnrichment(mapped, rawEnrichment.get(combo.id));

          // unroutable combo would mislead the picker.
          if (hasMembers && defaultCompression && defaultCompression.pipeline.length > 0) {
            const tag = formatCompressionPipeline(defaultCompression.pipeline);
            if (tag.length > 0 && !mapped.name.includes(tag)) {
              mapped.name = `${mapped.name} ${tag}`;
            }
          }

          // #6859: server-facing key — NOT the OC-gate-prefixed `resolved.providerId`.
          const comboKey = buildComboKey(combo, usedComboKeys, resolved.omnirouteProviderId);

          // Collision policy: combos win. Warn ONCE per (cacheKey, comboKey)
          // when overwriting a same-key raw model so the operator can spot
          // the unusual naming choice without log spam. Suppress the warning
          // when the collision is the intentional dedup pattern (combo.name
          // exactly matches an existing raw model's id) — /v1/models
          // pre-mirrors combos as raw entries and the operator's intent is
          // always "combo wins" in that case.
          if (Object.prototype.hasOwnProperty.call(models, comboKey)) {
            const existing = models[comboKey];
            // Intentional dedup: `/v1/models` pre-mirrors combos as raw
            // entries, so the bare combo name appears as the model id in
            // `rawModels`. After our prefixing the existing entry's id is
            // `${providerId}/${raw.id}` — the combo name is a substring of
            // that prefixed id (or, for already-prefixed raw models, the
            // exact id). Use `endsWith` to avoid matching substrings of
            // unrelated prefixed ids.
            const isIntentionalDedup =
              existing &&
              combo.name &&
              combo.name.trim().length > 0 &&
              (existing.id === combo.name.trim() || existing.id.endsWith(`/${combo.name.trim()}`));
            if (!isIntentionalDedup) {
              const dedupeKey = `${cacheKey}::${comboKey}`;
              if (!collisionWarned.has(dedupeKey)) {
                collisionWarned.add(dedupeKey);
                logger.warn(`combo key "${comboKey}" collides with a model id; combo wins.`);
              }
            }
          }
          models[comboKey] = mapped;

          // Make this combo's resolved model available to parent combos
          // that reference it via combo-ref. Use the friendly name
          // (combo.name) since that's the lookup key on the parent side.
          const lookupName =
            combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
          resolvedComboModelsByName.set(lookupName, mapped);
        }
        if (stillPending.length === pending.length) break;
        pending = stillPending;
      }

      if (pending.length > 0) {
        logger.warn(
          `${pending.length} combo(s) could not resolve all nested combo-refs after ${MAX_COMBO_PASSES} passes; they will advertise context=0 to avoid over-claiming.`
        );
      }

      return models;
    },
  };
}

// ────────────────────────────────────────────────────────────────────────────
// Fetch interceptor (T-04) — Bearer + Content-Type injection on intended
// same-origin OmniRoute inference requests only
// ────────────────────────────────────────────────────────────────────────────

/**
 * Build a `fetch`-compatible interceptor that injects `Authorization: Bearer`
 * (and a default `Content-Type`) only onto same-origin requests targeting
 * `<base>/chat/completions` or `<base>/models`, where `<base>` is the
 * configured baseURL path normalized to end in `/v1`. Management, MCP, and
 * unrelated inference paths pass through untouched. The apiKey is treated as
 * a secret bound to both the configured OmniRoute origin and these intended
 * inference endpoints, and MUST NOT leak elsewhere.
 *
 * Ported from Alph4d0g's `[email protected]` `createFetchInterceptor`
 * (their `dist/src/plugin.js:477-516`) with these intentional deviations:
 *
 *   - **`baseURL` is required** here (no `localhost:20128/v1` fallback). T-04
 *     callers always have an authoritative baseURL (from plugin opts or
 *     auth.json); a silent local default would be a footgun.
 *   - **Content-Type defaulting is gated on `init.body` presence**. Their
 *     version unconditionally sets `application/json` even on `GET /v1/models`,
 *     which is harmless but noisy; we only set it when there's a body to
 *     describe.
 *   - **Gemini schema sanitisation is NOT applied here** — that's T-06's
 *     responsibility and will land as a body-transform step inside this
 *     same function (or as a thin wrapper around it).
 *   - **Header merge strategy mirrors theirs**: Request-attached headers
 *     first, then `init.headers` overlay, then our injected
 *     Authorization/Content-Type — so the apiKey we own ALWAYS wins over
 *     any caller-supplied Bearer for the same OmniRoute provider.
 *
 * @see https://opencode.ai/docs/plugins for the AuthLoaderResult.fetch contract
 *      (the returned function is invoked by the AI-SDK in lieu of global fetch).
 */
export function createOmniRouteFetchInterceptor(config: {
  apiKey: string;
  baseURL: string;
}): typeof fetch {
  let baseOrigin: string | undefined;
  const inferencePaths = new Set<string>();
  try {
    const baseUrl = new URL(config.baseURL);
    baseOrigin = baseUrl.origin;
    const basePath = ensureV1Suffix(baseUrl.pathname);
    inferencePaths.add(`${basePath}/chat/completions`);
    inferencePaths.add(`${basePath}/responses`);
    inferencePaths.add(`${basePath}/messages`);
    inferencePaths.add(`${basePath}/models`);
  } catch {
    // Credential-attached base URLs are not schema-validated. A malformed
    // value must disable injection rather than broaden the credential scope.
  }
  return async (input, init = {}) => {
    const url =
      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;

    let requestUrl: URL | undefined;
    try {
      requestUrl = new URL(url);
    } catch {
      // Native fetch will report malformed/relative URLs as usual. We only
      // decline to attach credentials before forwarding the original input.
    }
    const normalizedPath = requestUrl ? trimTrailingSlashes(requestUrl.pathname) || "/" : undefined;
    const targetsInference =
      requestUrl?.origin === baseOrigin &&
      normalizedPath !== undefined &&
      inferencePaths.has(normalizedPath);
    if (!targetsInference) {
      return fetch(input, init);
    }

    // Merge order: Request-attached headers (when input is a Request) →
    // init.headers overlay → our injected headers last (so we win).
    const headers = new Headers(input instanceof Request ? input.headers : undefined);
    if (init.headers) {
      const initHeaders = new Headers(init.headers);
      initHeaders.forEach((value, key) => {
        headers.set(key, value);
      });
    }

    headers.set("Authorization", `Bearer ${config.apiKey}`);
    // Only default Content-Type when the caller actually has a body AND
    // hasn't already declared the media type themselves.
    const hasBody = init.body != null || input instanceof Request;
    if (!headers.has("Content-Type") && hasBody) {
      headers.set("Content-Type", "application/json");
    }

    return applyOmniRouteInferenceTelemetry(await fetch(input, { ...init, headers }));
  };
}

// ────────────────────────────────────────────────────────────────────────────
// Gemini tool-schema sanitisation (T-06) — strip JSON-schema keywords that
// the Gemini API rejects from outbound chat-completion / responses bodies
// when the target model is a Gemini variant.
// ────────────────────────────────────────────────────────────────────────────

/**
 * JSON-Schema keywords that the Gemini API rejects when present anywhere in
 * a function-calling tool definition. Standard OpenAI / Anthropic clients
 * happily emit these (they're valid Draft-07 schema) but Gemini's tool
 * validator throws on them, breaking OmniRoute → Gemini chains transparently.
 *
 * Source: behavioural reverse-engineering from Alph4d0g's
 * [email protected] (dist/src/plugin.js:517).
 */
const GEMINI_SCHEMA_KEYS_TO_REMOVE = new Set(["$schema", "$ref", "ref", "additionalProperties"]);

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

/**
 * Recursively strip `GEMINI_SCHEMA_KEYS_TO_REMOVE` from an arbitrary
 * JSON-Schema-shaped record. Walks both the record's own properties and
 * any nested objects / arrays so deeply nested `properties.x.properties.y`
 * trees are reached without a separate traversal pass. Mutates in place
 * and reports whether any key was deleted so callers can skip a
 * `JSON.stringify` round-trip when nothing changed.
 */
function stripSchemaKeys(schema: Record<string, unknown>): boolean {
  let changed = false;
  for (const key of Object.keys(schema)) {
    if (GEMINI_SCHEMA_KEYS_TO_REMOVE.has(key)) {
      delete schema[key];
      changed = true;
      continue;
    }
    const value = schema[key];
    if (Array.isArray(value)) {
      for (const item of value) {
        if (isRecord(item)) {
          changed = stripSchemaKeys(item) || changed;
        }
      }
      continue;
    }
    if (isRecord(value)) {
      changed = stripSchemaKeys(value) || changed;
    }
  }
  return changed;
}

/**
 * Walk every tool definition in the payload and strip Gemini-incompatible
 * schema keywords. Handles both chat-completion shape
 * (`tools[].function.parameters`) and Responses-API shape
 * (`tools[].input_schema`), plus the Gemini-native `function_declaration`
 * variant some adapters use.
 *
 * Also strips top-level schema keywords from the payload itself — clients
 * occasionally attach a top-level `$schema` declaration when re-serialising
 * tool bundles, and Gemini rejects those too.
 */
function sanitizeToolSchemaContainer(payload: Record<string, unknown>): boolean {
  let changed = false;
  // Top-level keyword strip — covers payload-level `$schema` etc.
  for (const key of Object.keys(payload)) {
    if (GEMINI_SCHEMA_KEYS_TO_REMOVE.has(key)) {
      delete payload[key];
      changed = true;
    }
  }
  const tools = (payload as { tools?: unknown }).tools;
  if (!Array.isArray(tools)) {
    return changed;
  }
  for (const tool of tools) {
    if (!isRecord(tool)) continue;
    const fn = (tool as { function?: unknown }).function;
    if (isRecord(fn) && isRecord((fn as { parameters?: unknown }).parameters)) {
      changed = stripSchemaKeys(fn.parameters as Record<string, unknown>) || changed;
    }
    const fnDecl = (tool as { function_declaration?: unknown }).function_declaration;
    if (isRecord(fnDecl) && isRecord((fnDecl as { parameters?: unknown }).parameters)) {
      changed = stripSchemaKeys(fnDecl.parameters as Record<string, unknown>) || changed;
    }
    const inputSchema = (tool as { input_schema?: unknown }).input_schema;
    if (isRecord(inputSchema)) {
      changed = stripSchemaKeys(inputSchema) || changed;
    }
  }
  return changed;
}

/**
 * Pure function — recursively strip Gemini-incompatible JSON-Schema
 * keywords (`$schema`, `$ref`, `ref`, `additionalProperties`) from the
 * tool definitions on a chat-completions / responses payload.
 *
 * Walks:
 *   - `payload.tools[].function.parameters` (OpenAI chat-completions shape)
 *   - `payload.tools[].function_declaration.parameters` (Gemini-native shape
 *     some adapters round-trip)
 *   - `payload.tools[].input_schema` (Responses-API shape)
 *   - all `properties.<x>` (and `properties.<x>.properties.<y>`…) inside
 *     each container, recursing through nested objects and arrays.
 *   - top-level payload keys (some clients attach a payload-level `$schema`).
 *
 * Returns the cleaned payload. Does NOT mutate input — clones first via
 * `structuredClone` so callers can keep a reference to the original. If
 * the payload is not a record, or carries no tools and no top-level
 * stripped keys, returns a (still cloned) equivalent.
 *
 * Exported so the body-transform layer is unit-testable independent of the
 * fetch wrapper.
 */
export function sanitizeGeminiToolSchemas(payload: unknown): unknown {
  if (!isRecord(payload)) {
    // Non-record payloads (string, array, number, null) can't carry tool
    // schemas. Pass back the same value — there's nothing to clone-and-strip
    // and propagating the original keeps caller semantics simple.
    return payload;
  }
  // structuredClone is available in Node 18+; the package's engines field
  // already requires Node >=22.22.3 so we can rely on it without a
  // JSON round-trip fallback.
  const cloned = structuredClone(payload) as Record<string, unknown>;
  sanitizeToolSchemaContainer(cloned);
  return cloned;
}

/**
 * Detect whether a payload is bound for a Gemini model. Returns true if
 * `payload.model` is a string AND matches any known Gemini routing pattern:
 *
 *   - case-insensitive substring `gemini` (covers bare `gemini-1.5-pro`,
 *     `gemini-2.5-flash`, etc.)
 *   - `models/gemini-…` (Google Generative AI canonical id form)
 *   - `google-vertex/gemini-…` (OpenCode + AI-SDK Vertex routing prefix)
 *
 * Liberal by design: a false positive (cleaning a payload that didn't
 * need cleaning) costs only a structuredClone + one walk; a false negative
 * breaks the whole chain by forwarding $schema/additionalProperties to
 * Gemini which throws 400 INVALID_ARGUMENT. The first three checks
 * collapse into the case-insensitive substring check, but they're
 * documented separately so future maintainers see the intent.
 *
 * Exported so callers and tests can probe detection independent of the
 * fetch wrapper.
 */
export function shouldSanitizeForGemini(payload: unknown): boolean {
  if (!isRecord(payload)) return false;
  const model = (payload as { model?: unknown }).model;
  if (typeof model !== "string") return false;
  return /gemini/i.test(model);
}

/**
 * Module-level latch so the streaming-body warning fires AT MOST once per
 * Node process. ReadableStream bodies can't be safely cloned + JSON-parsed
 * without consuming the stream (and re-creating a stream that survives both
 * read paths is non-trivial), so the sanitiser skips them — but we want
 * the operator to see one heads-up that schema stripping won't run on
 * those requests.
 */
let geminiStreamingWarningEmitted = false;

/**
 * Wrapper over an inner `fetch` that applies Gemini schema sanitisation to
 * outbound chat-completion / responses request bodies.
 *
 * Behaviour:
 *   - URL gate: only inspects requests whose URL path contains
 *     `/chat/completions` or `/responses` (lenient about prefix — works for
 *     `/v1/chat/completions`, `/openai/v1/chat/completions`, …).
 *   - Body extraction handles `string`, `Buffer` / `Uint8Array`,
 *     `URLSearchParams` (calls `.toString()`), `Blob` (`await .text()`),
 *     AND `Request` input where the body lives on the Request not init.
 *     `ReadableStream` bodies are skipped (see below).
 *   - Body must JSON.parse to a record; otherwise pass-through.
 *   - `shouldSanitizeForGemini` gates the actual transform — non-Gemini
 *     payloads pass through unchanged regardless of endpoint.
 *   - Fail-open: ANY error during extraction / parse / sanitise falls back
 *     to forwarding the original `(input, init)` to the inner fetch.
 *     Sanitisation is a best-effort guard, never a hard failure mode.
 *   - `ReadableStream` bodies → skipped with a ONE-TIME `console.warn`.
 *     The Gemini-quirk only manifests with tool calls in the body, and
 *     OC streams plain text deltas; the operator should still know.
 *
 * @param inner The next fetch in the chain (typically the Bearer-injecting
 *              interceptor from `createOmniRouteFetchInterceptor`).
 */
export function createGeminiSanitizingFetch(inner: typeof fetch): typeof fetch {
  return async (input, init) => {
    try {
      const url =
        typeof input === "string"
          ? input
          : input instanceof URL
            ? input.toString()
            : input instanceof Request
              ? input.url
              : "";

      // URL gate — match the path substring with prefix tolerance.
      const targetsCompletions = url.includes("/chat/completions") || url.includes("/responses");
      if (!targetsCompletions) {
        return inner(input, init);
      }

      // Body extraction. Cover the body shapes the AI-SDK + adapter layer
      // actually emit; bail to pass-through on anything we can't read
      // synchronously without consuming a stream.
      let rawBody: string | undefined;
      const initBody = init?.body as unknown;

      if (typeof initBody === "string") {
        rawBody = initBody;
      } else if (initBody instanceof URLSearchParams) {
        // Form-encoded bodies are never chat-completion JSON; pass-through.
        return inner(input, init);
      } else if (typeof Buffer !== "undefined" && initBody instanceof Buffer) {
        rawBody = initBody.toString("utf8");
      } else if (initBody instanceof Uint8Array) {
        rawBody = new TextDecoder().decode(initBody);
      } else if (initBody instanceof ReadableStream) {
        // Streaming body — skip with one-shot warning.
        if (!geminiStreamingWarningEmitted) {
          geminiStreamingWarningEmitted = true;

          console.warn(
            "[omniroute-plugin] sanitizeGemini: streaming Request body, skipping schema strip (Gemini may reject)"
          );
        }
        return inner(input, init);
      } else if (
        initBody !== null &&
        initBody !== undefined &&
        typeof (initBody as { text?: unknown }).text === "function"
      ) {
        // Blob-like (has .text(): Promise<string>). Streaming was already
        // matched above — anything left with a `.text` method we can buffer.
        try {
          rawBody = await (initBody as { text(): Promise<string> }).text();
        } catch {
          return inner(input, init);
        }
      } else if (initBody === undefined && input instanceof Request) {
        // Body lives on the Request object itself, not init. Clone before
        // reading — consuming the original Request body would make it
        // unreadable downstream.
        try {
          rawBody = await (input as Request).clone().text();
        } catch {
          return inner(input, init);
        }
      }

      if (rawBody === undefined || rawBody.length === 0) {
        return inner(input, init);
      }

      let payload: unknown;
      try {
        payload = JSON.parse(rawBody);
      } catch {
        // Non-JSON body → pass-through, never throw.
        return inner(input, init);
      }

      if (!shouldSanitizeForGemini(payload)) {
        return inner(input, init);
      }

      const cleaned = sanitizeGeminiToolSchemas(payload);
      const newBody = JSON.stringify(cleaned);
      // Cloning init: we need to replace `body` without mutating the caller's
      // init bag. If init was undefined (Request-input path), construct one.
      const newInit: RequestInit = { ...(init ?? {}), body: newBody };
      return inner(input, newInit);
    } catch {
      // Total fail-open — never let a sanitiser bug break the request path.
      return inner(input, init);
    }
  };
}

/**
 * Test-only hook: reset the module-level streaming-warning latch so each
 * test can independently assert the one-shot semantics. Not part of the
 * public stability contract — prefixed with `__` per convention to signal
 * "do not depend on this from production code".
 */
export function __resetGeminiStreamingWarning(): void {
  geminiStreamingWarningEmitted = false;
}

// ────────────────────────────────────────────────────────────────────────────
// Config hook (T-07) — backward-compat shim for OC ≤1.14.48
//
// OC ≤1.14.48 does NOT call `provider.models()` at startup; it reads the
// catalog from the static `provider.<id>` config block instead. OC ≥1.14.49
// calls `provider.models()` dynamically AND merges the dynamic catalog over
// any static block (dynamic wins on collision). To support both, the plugin
// publishes a static block via `config` AND a dynamic one via `provider.models`
// — OC's resolution order picks the right one per OC version. This module
// implements the static-publish half.
//
// Sibling shape source-of-truth: see
// `@omniroute/opencode-provider/src/index.ts` (`createOmniRouteProvider`,
// `OpenCodeProviderEntry`, `OpenCodeModelEntry`). We replicate that shape
// here rather than depending on the sibling package — the plugin must stay
// self-contained (npm-installable on its own, no peer dep on the provider
// builder).
// ────────────────────────────────────────────────────────────────────────────

/**
 * Per-model entry shape under `provider.<id>.models[modelId]`. Mirrors
 * `OpenCodeModelEntry` exported by `@omniroute/opencode-provider`. Stripped
 * down to the fields OC's static catalog reader actually consumes — NOT a
 * full ModelV2 (that's the dynamic-hook shape). Optional fields are omitted
 * when OmniRoute didn't surface a value, NOT emitted as `undefined` — the
 * resulting JSON must be diffable across OmniRoute deployments without
 * `undefined` noise.
 */
/** Modalities accepted by OC's static catalog reader (see `@opencode-ai/sdk`). */
export type OmniRouteModalityKind = "text" | "audio" | "image" | "video" | "pdf";

const STATIC_MODALITY_VALUES: ReadonlySet<OmniRouteModalityKind> = new Set([
  "text",
  "audio",
  "image",
  "video",
  "pdf",
]);

/** Normalise + filter raw modality list to the values OC accepts. Deduped. */
function normaliseModalities(raw: unknown): OmniRouteModalityKind[] {
  if (!Array.isArray(raw)) return [];
  const out: OmniRouteModalityKind[] = [];
  const seen = new Set<string>();
  for (const v of raw) {
    if (typeof v !== "string") continue;
    const lower = v.toLowerCase() as OmniRouteModalityKind;
    if (!STATIC_MODALITY_VALUES.has(lower)) continue;
    if (seen.has(lower)) continue;
    seen.add(lower);
    out.push(lower);
  }
  return out;
}

export interface OmniRouteStaticModelEntry {
  /** Owning provider id. SHOULD match the parent `provider.<id>` key so OC's
   * static-catalog reader resolves credentials via `providerID` instead of
   * parsing the model key on `/`. Optional: OC's schema validator may
   * reject the entire provider block when this field is present but the
   * model KEY already carries the provider prefix (e.g. `omniroute/MASTER`),
   * since the prefix makes the field redundant and the field is not part of
   * OC's expected schema. We omit it from entries and rely on the prefix
   * on the KEY alone. See PR #4184. */
  providerID?: string;
  /** Display label rendered in OC's model picker. Defaults to the model id. */
  name: string;

  /** ISO date the model was released. Surfaces in OC's model card when present. */
  release_date?: string;
  /** Model accepts image / file attachments. */
  attachment?: boolean;
  /** Model exposes a reasoning / extended-thinking surface. */
  reasoning?: boolean;
  /** Model honours the `temperature` parameter. */
  temperature?: boolean;
  /** Model supports function / tool calling. */
  tool_call?: boolean;
  /**
   * Per-million-token cost. Maps from OmniRoute `/api/pricing` shape:
   * `input`/`output` pass through; `cached` → `cache_read`;
   * `cache_creation` → `cache_write`. Omitted when no pricing slot resolves.
   */
  cost?: {
    input: number;
    output: number;
    cache_read?: number;
    cache_write?: number;
  };
  /**
   * Context-window limits. OC's static reader requires both `context` AND
   * `output` when `limit` is present, so the field is only emitted when
   * BOTH are known.
   */
  limit?: {
    context: number;
    output: number;
  };
  /**
   * Modality lists the model accepts (input) and emits (output). Maps from
   * OmniRoute's `input_modalities` / `output_modalities` on `/v1/models`.
   * Emitted only when at least one modality is known — without this field
   * OC's runtime catalog defaults `input.image: false` even when the model
   * card has `attachment: true`, which blocks clipboard image paste in the
   * TUI for vision-capable models.
   */
  modalities?: {
    input: OmniRouteModalityKind[];
    output: OmniRouteModalityKind[];
  };
}

/**
 * Static `provider.<id>` block written to `input.provider` by the config hook.
 * Mirrors `OpenCodeProviderEntry` from `@omniroute/opencode-provider`.
 *
 *   - `npm` is always `"@ai-sdk/openai-compatible"` — OmniRoute exposes an
 *     OpenAI-compatible surface and that's the AI-SDK adapter that speaks it.
 *   - `options.baseURL` MUST be the fully-qualified `/v1` URL (the AI-SDK
 *     appends paths like `/chat/completions` directly under it).
 *   - `options.apiKey` is the bearer token; the fetch interceptor (T-04)
 *     also injects it on the dynamic path, but the static block needs it
 *     embedded too so OC ≤1.14.48 can construct the SDK client without
 *     going through the auth hook.
 */
export interface OmniRouteStaticProviderEntry {
  npm: "@ai-sdk/openai-compatible";
  name: string;
  options: {
    baseURL: string;
    apiKey: string;
  };
  models: Record<string, OmniRouteStaticModelEntry>;
}

/**
 * Build the static `provider.<id>` block from raw `/v1/models` + `/api/combos`
 * responses. Pure function — no I/O, no side effects, no dependency on the
 * sibling provider package. Exported so callers and tests can construct the
 * block independently of the auth.json + fetch pipeline.
 *
 * Mapping rules (per the sibling `createOmniRouteProvider` output spec):
 *
 *   - One entry per raw model AND one entry per non-hidden combo.
 *   - `name` = model id (no separate display name on `/v1/models`).
 *   - `attachment` = `caps.attachment ?? caps.vision ?? false` — same
 *     convention as `mapRawModelToModelV2` (T-03).
 *   - `reasoning` = `caps.reasoning || caps.thinking`. Booleans only — we
 *     do NOT emit the field when both source flags are absent (keeps the
 *     stripped shape minimal).
 *   - `temperature` = `caps.temperature ?? true` — OpenAI-compat surface
 *     supports temperature by default; only an explicit `false` suppresses.
 *   - `tool_call` = `caps.tool_calling ?? false`.
 *   - `limit.context` = raw `context_length` when > 0; omitted otherwise.
 *   - `limit.input` = raw `max_input_tokens` when present.
 *   - `limit.output` = raw `max_output_tokens` when present.
 *
 * For combos: LCD across member raw models (matches `mapComboToModelV2`):
 *
 *   - `attachment`, `reasoning`, `tool_call`, `temperature`: `every` member.
 *   - `limit.context` = min(member context_lengths).
 *   - `limit.input` = min(member max_input_tokens) ONLY when every member
 *     declares one.
 *   - `limit.output` = min(member max_output_tokens).
 *   - Empty members → all-false / limits omitted.
 *
 * Collision: combos win (matches the dynamic provider hook).
 *
 * @param rawModels Raw `/v1/models` entries (may be empty).
 * @param rawCombos Raw `/api/combos` entries (may be empty).
 * @param opts      Resolved plugin options (we read `displayName` + `providerId`).
 * @param baseURL   Fully-qualified `/v1` base URL — written verbatim to
 *                  `options.baseURL`. Caller is responsible for `/v1`
 *                  normalisation; we do NOT touch it here.
 * @param apiKey    Bearer token — written verbatim to `options.apiKey`.
 */
export function buildStaticProviderEntry(
  rawModels: OmniRouteRawModelEntry[],
  rawCombos: OmniRouteRawCombo[],
  opts: ReturnType<typeof resolveOmniRoutePluginOptions>,
  baseURL: string,
  apiKey: string,
  enrichment?: OmniRouteEnrichmentMap,
  compressionCombos?: OmniRouteCompressionCombo[],
  connections?: OmniRouteProviderConnection[],
  logger?: OmniRouteLoggerSink
): OmniRouteStaticProviderEntry {
  const log = logger ?? _logger;
  const models: Record<string, OmniRouteStaticModelEntry> = {};

  // usableOnly filter — compute once when feature enabled AND we have
  // connection data to filter against. Soft-fail (empty connections list)
  // disables the filter rather than hiding the catalog.
  const wantUsableOnly = opts.features?.usableOnly === true;
  const usable =
    wantUsableOnly && connections && connections.length > 0
      ? usableProviderAliasSet(connections, enrichment)
      : undefined;
  // #9473: model allowlist/blocklist — compile once per static-block build.
  const visibleFilter = compileModelListFilter(opts.features?.visibleModels);
  const hiddenFilter = compileModelListFilter(opts.features?.hiddenModels);
  // Provider-tag suffix — default-on, opt-out via `features.providerTag: false`.
  // Prepends e.g. `Claude - ` to enriched raw-model names so the picker
  // can tell `cc/claude-opus-4-7` (Anthropic) apart from `kr/claude-opus-4-7`
  // (Kiro). Combos skip this by design.
  const wantProviderTag = opts.features?.providerTag !== false;

  // Build a name-set of every non-hidden combo from `/api/combos`. OmniRoute
  // pre-mirrors combos into `/v1/models` with the friendly name as the raw
  // id (e.g. `claude-primary`, `gemini-pro`), so without dedup the static
  // catalog ends up with both `claude-primary` (raw, opaque) AND the same
  // combo under `combo/claude-primary` (rich LCD). We suppress the raw twin
  // so each combo surfaces exactly once, under the `combo/` namespace.
  const comboNames = new Set<string>();
  for (const combo of rawCombos) {
    if (!combo || combo.isHidden === true) continue;
    const name = combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
    if (typeof name === "string" && name.length > 0) comboNames.add(name);
  }

  // Build the canonical→alias reverse map AND the canonical-dedup set
  // once per static-block construction. Same shape as the dynamic hook
  // so both catalogs publish identical keys (no `claude/X` raw twin
  // shadowing the enriched `cc/X` row).
  const canonicalToAlias = buildCanonicalToAliasMap(enrichment);
  const canonicalDedup = canonicalDedupSet(rawModels, canonicalToAlias);
  const aliasIndex = buildAliasIndex(enrichment);

  // Raw model entries → stripped per-model shape.
  for (const raw of rawModels) {
    if (!raw.id) continue;
    // Skip the 20 named no-slash entries that shadow combos under the
    // `combo/<name>` namespace. We keep `codex-auto-review` and any other
    // future no-slash raw entry that doesn't have a matching combo.
    if (comboNames.has(raw.id)) continue;
    // Skip canonical-named twins when the alias-keyed enriched row exists.
    if (canonicalDedup.has(raw.id)) continue;
    if (usable && !isUsableRawModelId(raw.id, usable, enrichment)) continue;
    // #9473: allowlist/blocklist filter (AND with usableOnly).
    if (!passesModelAllowlist(raw.id, visibleFilter, hiddenFilter)) continue;
    const caps = raw.capabilities ?? {};
    // Enrichment overlay: `/api/pricing/models` carries human display names
    // (e.g. "Claude Opus 4.7" for raw id "cc/claude-opus-4-7"). The OC TUI
    // model picker reads this `name` straight from the static block on
    // OC ≤1.15.5 where the dynamic provider hook never fires. Falls back
    // to the raw id when no enrichment entry is found. The alias-fallback
    // lookup rescues `<canonical>/<id>` rows whose enrichment indexed only
    // under `<alias>/<id>`.
    const enrichmentEntry = lookupEnrichment(raw.id, enrichment, canonicalToAlias, raw.owned_by);
    const enrichmentName = enrichmentEntry?.name;
    let displayName = enrichmentName && enrichmentName.length > 0 ? enrichmentName : raw.id;
    // Provider-tag PREFIX — `<label> - <name>` so the picker groups by
    // upstream provider when scanning a column of model names. Mirrors
    // `applyProviderTag` used in the dynamic hook. Idempotent: skip
    // when the name already starts with the prefix. The alias-index
    // fallback rescues raw rows like `cohere/rerank-multilingual-v3.0`
    // whose specific model id isn't in `/api/pricing/models` but whose
    // slot is.
    if (wantProviderTag) {
      const tagEntry = resolveProviderTagEntry(
        raw.id,
        enrichmentEntry,
        aliasIndex,
        canonicalToAlias
      );
      const label = shortProviderLabel(tagEntry);
      if (label) {
        const prefix = `${label}${PROVIDER_TAG_SEPARATOR}`;
        if (!displayName.startsWith(prefix)) displayName = `${prefix}${displayName}`;
      }
    }
    // OC's static-catalog schema doesn't expect a `providerID` field on
    // individual entries — the parent block ID is the provider. Adding
    // unknown fields here can cause OC's schema validator to reject the
    // entire provider block, hiding ALL models. The provider prefix on the
    // model KEY (e.g. `omniroute/claude-opus-4`) is what OC uses to recover
    // (providerID, modelID) when the user selects a model.
    const entry: OmniRouteStaticModelEntry = { name: displayName };

    const attachment = caps.attachment ?? caps.vision;
    if (typeof attachment === "boolean") entry.attachment = attachment;

    if (typeof caps.reasoning === "boolean" || typeof caps.thinking === "boolean") {
      entry.reasoning = Boolean(caps.reasoning || caps.thinking);
    }

    if (typeof caps.temperature === "boolean") {
      entry.temperature = caps.temperature;
    }

    if (typeof caps.tool_calling === "boolean") {
      entry.tool_call = caps.tool_calling;
    }

    // OC's SDK schema requires BOTH `context` and `output` when `limit` is
    // present. We previously emitted `limit.input` too, but the SDK reader
    // doesn't accept it — drop it. Only emit `limit` when both required
    // values are known.
    if (
      typeof raw.context_length === "number" &&
      raw.context_length > 0 &&
      typeof raw.max_output_tokens === "number" &&
      raw.max_output_tokens > 0
    ) {
      entry.limit = {
        context: raw.context_length,
        output: raw.max_output_tokens,
      };
    }

    // Modalities — emit when OmniRoute surfaced any. Without this field
    // OC's runtime model defaults `input.image: false` even for vision-
    // capable models, blocking clipboard image paste in the TUI.
    const inModalities = normaliseModalities(raw.input_modalities);
    const outModalities = normaliseModalities(raw.output_modalities);
    if (inModalities.length > 0 || outModalities.length > 0) {
      entry.modalities = {
        input: inModalities.length > 0 ? inModalities : ["text"],
        output: outModalities.length > 0 ? outModalities : ["text"],
      };
    }

    // Cost from enrichment pricing (sourced from `/api/pricing`). Map
    // OmniRoute field names to OC's static-schema field names.
    const pricing = enrichmentEntry?.pricing;
    if (pricing && (typeof pricing.input === "number" || typeof pricing.output === "number")) {
      const cost: NonNullable<OmniRouteStaticModelEntry["cost"]> = {
        input: typeof pricing.input === "number" ? pricing.input : 0,
        output: typeof pricing.output === "number" ? pricing.output : 0,
      };
      if (typeof pricing.cacheRead === "number") cost.cache_read = pricing.cacheRead;
      if (typeof pricing.cacheWrite === "number") cost.cache_write = pricing.cacheWrite;
      entry.cost = cost;
    }

    // release_date from /v1/models — surfaces in OC's model card when present.
    if (typeof raw.release_date === "string" && raw.release_date.length > 0) {
      entry.release_date = raw.release_date;
    }

    // #9175: OC's `getModel` looks the model up by BARE id — the part after
    // the first `/` in the user's request — so a dict key with an embedded
    // provider prefix (`<providerId>/<raw-id>`) is unreachable. Keys are the
    // raw id verbatim; ids that already contain `/` (e.g. `cc/claude-opus-4-7`)
    // keep it because the slash is part of the upstream model id itself.
    const key = raw.id;
    models[key] = entry;
  }

  // Combo entries → stripped LCD shape. Each combo is keyed as
  // `combo/<friendly-name>` so the OC TUI model picker shows them under a
  // distinct namespace (e.g. `combo/claude-primary`) instead of the opaque
  // upstream UUID id (e.g. `b4a0211e-e3e1-472d-b252-fb9bf6d1c935`).
  const rawModelById = new Map<string, OmniRouteRawModelEntry>();
  for (const m of rawModels) {
    if (m.id) rawModelById.set(m.id, m);
  }

  // Resolve the default compression pipeline once — its short signature
  // (e.g. `[rtk:standard → caveman:full]`) is appended to every routable
  // combo `name` so operators can see what compression a combo applies
  // at a glance. Provider hook does the same decoration when feature is
  // on. Suffix is suppressed for combos with no resolvable members —
  // claiming compression on an unroutable combo would mislead the
  // picker.
  let compressionSuffix = "";
  if (compressionCombos && compressionCombos.length > 0) {
    const def = compressionCombos.find((c) => c.isDefault === true);
    if (def) {
      const sig = formatCompressionPipeline(def.pipeline);
      if (sig.length > 0) compressionSuffix = ` ${sig}`;
    }
  }

  // Track combo keys to detect slug collisions across the catalog.
  const usedComboKeys = new Set<string>();

  // ── Combo LCD across nested combo-refs (T-NN mirror) ─────────────────
  // Mirror of the dynamic-catalog fixpoint iteration: combos can nest
  // other combos via `kind: "combo-ref"` members (e.g. MASTER-LIGHT
  // contains LEGACY, KIRO, Opecode Zen FREE). The nested combo's own
  // capabilities and limits are computed in this same loop, so we need
  // a fixpoint pass: if a combo-ref points at a combo not yet processed,
  // defer this combo and try again after the sibling combos catch up.
  // We bound the retries so a circular combo graph can't deadlock the
  // picker, and we break early when a pass makes no progress.
  const MAX_STATIC_COMBO_PASSES = 8;
  const resolvedStaticCombosByName = new Map<string, OmniRouteStaticModelEntry>();
  let pendingStatic = rawCombos.filter((combo) => {
    if (!combo.id) return false;
    if (combo.isHidden === true) return false;
    if (usable && !isUsableCombo(combo, usable)) return false;
    // #9473: combo allowlist — drop when no member matches visible filter.
    if (visibleFilter && !passesComboAllowlist(combo, visibleFilter)) return false;
    return true;
  });

  for (let pass = 0; pass < MAX_STATIC_COMBO_PASSES && pendingStatic.length > 0; pass++) {
    const stillPendingStatic: typeof pendingStatic = [];
    for (const combo of pendingStatic) {
      const memberSteps = Array.isArray(combo.models) ? combo.models : [];
      const memberEntries: OmniRouteRawModelEntry[] = [];
      let deferredThisPass = false;

      for (const step of memberSteps) {
        const stepKind = (step as unknown as { kind?: unknown }).kind;

        if (stepKind === "combo-ref") {
          const comboName = (step as unknown as { comboName?: unknown }).comboName;
          if (typeof comboName !== "string" || comboName.length === 0) {
            continue;
          }
          const nestedEntry = resolvedStaticCombosByName.get(comboName);
          if (!nestedEntry) {
            deferredThisPass = true;
            break;
          }
          // Synthesize a raw-model-shaped member entry carrying the
          // nested combo's pre-computed context + capabilities +
          // modalities. Mirrors the dynamic path so the static catalog
          // stays in lockstep with the dynamic one.
          const inputModalities = (nestedEntry.modalities?.input ?? ["text"]) as string[];
          const outputModalities = (nestedEntry.modalities?.output ?? ["text"]) as string[];
          memberEntries.push({
            id: `combo-ref:${comboName}`,
            context_length: nestedEntry.limit?.context ?? 0,
            max_output_tokens: nestedEntry.limit?.output ?? 0,
            max_input_tokens: 0,
            owned_by: "combo",
            input_modalities: inputModalities,
            output_modalities: outputModalities,
            capabilities: {
              temperature: nestedEntry.temperature,
              reasoning: nestedEntry.reasoning,
              thinking: nestedEntry.reasoning,
              attachment: nestedEntry.attachment,
              tool_calling: nestedEntry.tool_call,
            },
          } as unknown as OmniRouteRawModelEntry);
          continue;
        }

        const modelId = (step as unknown as { model?: unknown }).model;
        if (typeof modelId !== "string" || modelId.length === 0) continue;
        const member = rawModelById.get(modelId);
        if (member) memberEntries.push(member);
      }

      if (deferredThisPass) {
        stillPendingStatic.push(combo);
        continue;
      }

      const hasMembers = memberEntries.length > 0;
      const friendlyName =
        combo.name && combo.name.trim().length > 0 ? combo.name.trim() : combo.id;
      const displayName =
        hasMembers && compressionSuffix ? `${friendlyName} ${compressionSuffix}` : friendlyName;
      // See the raw-model entry comment above — `providerID` on entries is
      // not part of OC's static-catalog schema; the parent block ID is the
      // provider and the KEY prefix (`omniroute/<slug>`) is what OC parses.
      const entry: OmniRouteStaticModelEntry = { name: displayName };

      if (hasMembers) {
        // LCD across capabilities — every member must support for the combo
        // to support. Mirrors mapComboToModelV2.
        entry.attachment = memberEntries.every((m) =>
          Boolean(m.capabilities?.attachment ?? m.capabilities?.vision ?? false)
        );
        entry.reasoning = memberEntries.every((m) =>
          Boolean(m.capabilities?.reasoning || m.capabilities?.thinking)
        );
        entry.temperature = memberEntries.every(
          (m) => (m.capabilities?.temperature ?? true) !== false
        );
        entry.tool_call = memberEntries.every((m) =>
          Boolean(m.capabilities?.tool_calling ?? false)
        );

        // LCD across limits — min over declared values. OC's SDK static schema
        // accepts only `context` + `output` on `limit`, so we drop the legacy
        // `input` emission. Emit only when BOTH context AND output are known
        // across at least one member (mirrors the required-field constraint).
        const contextValues = memberEntries
          .map((m) => m.context_length)
          .filter((v): v is number => typeof v === "number" && v > 0);
        const outputValues = memberEntries
          .map((m) => m.max_output_tokens)
          .filter((v): v is number => typeof v === "number" && v > 0);

        // Prefer the server-computed aggregate (accounts for explicit
        // context_length overrides and members outside memberEntries, e.g.
        // not yet resolved in /v1/models) over the raw Math.min(member)
        // lower bound. Mirrors mapComboToModelV2's limit.context logic
        // (#13000) so the static catalog and the dynamic hook agree.
        const preferredContext =
          typeof combo.computed_context_length === "number" && combo.computed_context_length > 0
            ? combo.computed_context_length
            : contextValues.length > 0
              ? Math.min(...contextValues)
              : undefined;

        if (preferredContext !== undefined && outputValues.length > 0) {
          entry.limit = {
            context: preferredContext,
            output: Math.min(...outputValues),
          };
        }

        // LCD across modalities — combo accepts modality M iff every member
        // accepts M. Same intersection rule as runtime capabilities.
        const inSets = memberEntries.map((m) => new Set(normaliseModalities(m.input_modalities)));
        const outSets = memberEntries.map((m) => new Set(normaliseModalities(m.output_modalities)));
        const intersect = (sets: Set<OmniRouteModalityKind>[]): OmniRouteModalityKind[] => {
          if (sets.length === 0) return [];
          const [first, ...rest] = sets;
          const out: OmniRouteModalityKind[] = [];
          for (const v of first) {
            if (rest.every((s) => s.has(v))) out.push(v);
          }
          return out;
        };
        const inModalities = intersect(inSets);
        const outModalities = intersect(outSets);
        if (inModalities.length > 0 || outModalities.length > 0) {
          entry.modalities = {
            input: inModalities.length > 0 ? inModalities : ["text"],
            output: outModalities.length > 0 ? outModalities : ["text"],
          };
        }
      } else {
        // Empty members → safety posture: all caps false. Caller's OC picker
        // will grey out an unroutable combo rather than promise capabilities
        // we can't honour.
        entry.attachment = false;
        entry.reasoning = false;
        entry.temperature = false;
        entry.tool_call = false;
      }

      // Key under bare slug (e.g. `claude-primary`) — no `combo/` prefix
      // because OpenCode parses model IDs on `/` and would treat
      // `combo/MASTER` as provider=`combo`. Slug collisions across
      // combos are disambiguated with a short UUID-prefix suffix; see
      // `buildComboKey` for the policy.
      // #6859: server-facing key — NOT the OC-gate-prefixed `opts.providerId`.
      // OC dispatches the static-catalog `models` map key VERBATIM as the
      // `model` field of the outbound `@ai-sdk/openai-compatible` request
      // (only the top-level `provider["<id>"]` segment is stripped for
      // routing) — so a bare-slug combo key prefixed with the OC-gated
      // `opts.providerId` reaches OmniRoute's server doubled
      // (`opencode-omniroute/opencode-omniroute/<slug>`), and `parseModel()`
      // resolves credentials for the nonexistent provider `opencode-omniroute`
      // instead of `omniroute`. See #7976.
      const key = buildComboKey(combo, usedComboKeys, opts.omnirouteProviderId).split("/").pop()!;
      models[key] = entry;

      // Make this combo's resolved entry available to parent combos
      // that reference it via combo-ref. Use the friendly name since
      // that's the lookup key on the parent side.
      resolvedStaticCombosByName.set(friendlyName, entry);
    }

    if (stillPendingStatic.length === pendingStatic.length) {
      // No progress in this pass — remaining combos have unresolvable
      // refs (missing nested combo, circular graph, or nested combo
      // with no members). Break early to avoid wasting the pass budget.
      break;
    }
    pendingStatic = stillPendingStatic;
  }

  if (pendingStatic.length > 0) {
    log.warn(
      `${pendingStatic.length} combo(s) in the static catalog could not resolve all nested combo-refs after ${MAX_STATIC_COMBO_PASSES} passes; they will be omitted.`
    );
  }

  return {
    npm: "@ai-sdk/openai-compatible",
    name: opts.displayName,
    options: { baseURL, apiKey },
    models,
  };
}

/**
 * Shape we expect inside `auth.json`. The file is keyed by providerId, with
 * each entry being a flavor-tagged credential. Today only the `api` flavor
 * is consumed by this plugin (OAuth + WellKnown flavors are passed through
 * but never decoded into a static block).
 */
interface AuthJsonApiEntry {
  type: "api";
  key: string;
  baseURL?: string;
}

type AuthJsonShape = Record<string, AuthJsonApiEntry | { type?: string; [k: string]: unknown }>;

/**
 * Read & parse `auth.json` from OC's data dir. The path resolution mirrors
 * OC core's:
 *
 *   `${OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode")}/auth.json`
 *
 * Returns `undefined` when the file is missing (most-common case on a fresh
 * install — silent no-op). Returns `null` when the file exists but doesn't
 * parse as JSON (logs ONE warn so the operator sees the corruption).
 *
 * Exported as a dependency-injectable function on `createOmniRouteConfigHook`
 * so tests can stub it without monkey-patching `node:fs/promises`.
 */
// ─────────────────────────────────────────────────────────────────────────
// Disk-cache fallback. Persists the last successful raw-fetch snapshot to
// `${OPENCODE_DATA_DIR ?? ~/.local/share/opencode}/plugins/omniroute-<providerId>.json`.
// When `/v1/models` is unreachable (e.g. IP whitelist drop, offline laptop)
// AND the in-memory cache is cold, the config hook reads from disk so the
// last-known catalog still surfaces in OC's model picker. Feature-flagged:
// `features.diskCache !== false` (default-on).
// ─────────────────────────────────────────────────────────────────────────

/** Disk snapshot envelope. Versioned for forward-compat. */
interface OmniRouteDiskSnapshot {
  v: 2;
  /** Opaque identity for normalized baseURL + both effective credentials. */
  identityFingerprint: string;
  rawModels: OmniRouteRawModelEntry[];
  rawCombos: OmniRouteRawCombo[];
  /** Serialised as array-of-pairs (Map is not JSON-friendly). */
  rawEnrichment: Array<[string, OmniRouteEnrichmentEntry]>;
  rawCompressionCombos: OmniRouteCompressionCombo[];
  rawConnections: OmniRouteProviderConnection[];
  /** When the snapshot was written (epoch ms). */
  writtenAt: number;
}

/** Resolve the disk-snapshot path for a given providerId. */
export function diskSnapshotPath(providerId: string): string {
  const dir = process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
  return path.join(dir, "plugins", `omniroute-${providerId}.json`);
}

/** Best-effort delete of the disk snapshot for a provider (force-sync). */
export async function clearDiskSnapshot(providerId: string): Promise<boolean> {
  const file = diskSnapshotPath(providerId);
  try {
    await unlink(file);
    return true;
  } catch (err) {
    const code = (err as NodeJS.ErrnoException | undefined)?.code;
    if (code === "ENOENT") return false;
    return false;
  }
}

export type OmniRouteDiskSnapshotWriter = (
  providerId: string,
  entry: Omit<OmniRouteFetchCacheEntry, "expiresAt">,
  identityFingerprint: string
) => Promise<void>;

export type OmniRouteDiskSnapshotReader = (
  providerId: string,
  identityFingerprint: string
) => Promise<(Omit<OmniRouteFetchCacheEntry, "expiresAt"> & { writtenAt?: number }) | undefined>;

/**
 * Bind a snapshot to the endpoint and effective credential tuple without
 * persisting any raw token. This opaque value is only stored and compared;
 * it is never logged or included in generated provider configuration.
 */
function diskSnapshotIdentityFingerprint(
  baseURL: string,
  apiKey: string,
  managementReadToken: string
): string {
  let normalizedBaseURL: string;
  try {
    const parsed = new URL(baseURL);
    parsed.hash = "";
    parsed.pathname = trimTrailingSlashes(parsed.pathname) || "/";
    normalizedBaseURL = parsed.toString();
  } catch {
    normalizedBaseURL = trimTrailingSlashes(baseURL);
  }
  return createHash("sha256")
    .update(JSON.stringify([normalizedBaseURL, apiKey, managementReadToken]))
    .digest("hex");
}

/** Best-effort disk write. Soft-fails on any I/O error (no exception thrown). */
export const defaultDiskSnapshotWriter: OmniRouteDiskSnapshotWriter = async (
  providerId,
  entry,
  identityFingerprint
) => {
  try {
    const file = diskSnapshotPath(providerId);
    // Restrict perms to the owner: the snapshot lives alongside auth.json
    // (0o600) and embeds provider topology + masked connection records.
    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
    const snapshot: OmniRouteDiskSnapshot = {
      v: 2,
      identityFingerprint,
      rawModels: entry.rawModels,
      rawCombos: entry.rawCombos,
      rawEnrichment: Array.from(entry.rawEnrichment.entries()),
      rawCompressionCombos: entry.rawCompressionCombos,
      rawConnections: entry.rawConnections,
      writtenAt: Date.now(),
    };
    await writeFile(file, JSON.stringify(snapshot), {
      encoding: "utf8",
      mode: 0o600,
    });
  } catch {
    // Soft-fail; caller already has the in-memory cache.
  }
};

/** Best-effort disk read. Returns `undefined` when missing/corrupt/unreadable. */
export const defaultDiskSnapshotReader: OmniRouteDiskSnapshotReader = async (
  providerId,
  identityFingerprint
) => {
  try {
    const file = diskSnapshotPath(providerId);
    const body = await readFile(file, "utf8");
    const parsed = JSON.parse(body) as Partial<OmniRouteDiskSnapshot>;
    if (
      !parsed ||
      parsed.v !== 2 ||
      typeof parsed.identityFingerprint !== "string" ||
      parsed.identityFingerprint !== identityFingerprint
    ) {
      return undefined;
    }
    return {
      rawModels: Array.isArray(parsed.rawModels) ? parsed.rawModels : [],
      rawCombos: Array.isArray(parsed.rawCombos) ? parsed.rawCombos : [],
      rawEnrichment: new Map(Array.isArray(parsed.rawEnrichment) ? parsed.rawEnrichment : []),
      rawCompressionCombos: Array.isArray(parsed.rawCompressionCombos)
        ? parsed.rawCompressionCombos
        : [],
      rawConnections: Array.isArray(parsed.rawConnections) ? parsed.rawConnections : [],
      writtenAt: typeof parsed.writtenAt === "number" ? parsed.writtenAt : undefined,
    };
  } catch {
    return undefined;
  }
};

/** No-op disk-cache pair — used by tests to avoid filesystem side effects.
 * Also used as the default in createOmniRouteConfigHook so that tests
 * that don't pass a diskSnapshotReader don't read real snapshot files
 * from the user's ~/.local/share/opencode/plugins/ directory.
 * The OmniRoutePlugin function passes the real defaultDiskSnapshotReader
 * explicitly. */
export const noopDiskSnapshotReader: OmniRouteDiskSnapshotReader = async () => undefined;
export const noopDiskSnapshotWriter: OmniRouteDiskSnapshotWriter = async () => {};

/**
 * In-flight refresh guard: prevents concurrent refreshes for the same
 * cacheKey. When a warm snapshot is served, the refresh runs detached; if
 * a second hook invocation arrives before the refresh completes, it should
 * piggyback on the in-flight promise rather than starting a second one.
 * Cleared on settle so it doesn't leak.
 */
const _inflightRefresh: Map<string, Promise<void>> = new Map();

/** Reset the in-flight refresh guard (for test isolation). */
export function _resetInflightRefresh(): void {
  _inflightRefresh.clear();
}

// ────────────────────────────────────────────────────────────────────────────
// Debug logging (features.debugLog)
// ────────────────────────────────────────────────────────────────────────────

/**
 * One captured request/response pair written to the debug JSONL log.
 * Schema documented in the schema-aware `DebugLogEntry` interface below.
 */
export interface DebugLogEntry {
  reqId: string;
  providerId: string;
  ts: number;
  url: string;
  method: string;
  reqHeaders: Record<string, string>;
  reqBody: unknown;
  resStatus: number | null;
  resHeaders: Record<string, string>;
  resBody: unknown;
  durationMs: number | null;
  error?: string;
}

function debugLogDir(): string {
  return join(
    process.env.OPENCODE_DATA_DIR ?? join(homedir(), ".local", "share", "opencode"),
    "plugins"
  );
}

function debugLogPath(providerId: string): string {
  return join(debugLogDir(), `omniroute-debug-${providerId}.jsonl`);
}

function debugStatePath(providerId: string): string {
  return join(debugLogDir(), `omniroute-debug-${providerId}.state.json`);
}

export function debugLogEnabled(providerId: string): boolean {
  try {
    const p = debugStatePath(providerId);
    if (!existsSync(p)) return false;
    const s = JSON.parse(readFileSync(p, "utf8")) as { enabled?: boolean };
    return s.enabled === true;
  } catch {
    return false;
  }
}

export function debugLogSetEnabled(providerId: string, enabled: boolean): void {
  try {
    const dir = debugLogDir();
    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
    writeFileSync(debugStatePath(providerId), JSON.stringify({ enabled, ts: Date.now() }, null, 2));
  } catch (err) {
    // best-effort; never break the auth flow
    console.warn(`[omniroute-plugin] debugLogSetEnabled failed: ${(err as Error).message}`);
  }
}

/**
 * Header names whose values must never be written to the debug JSONL on disk.
 *
 * Audit #15159 O-05: `createDebugLoggingFetch` copies every request and response
 * header into the captured entry, and the entry was serialized to disk verbatim —
 * so enabling `features.debugLog` persisted live bearer tokens (and session
 * cookies) in plaintext, contradicting the AES-256-GCM-at-rest guarantee. The
 * feature defaults to off, which limits exposure but does not remove it.
 *
 * Matched list: the explicit credential headers plus anything whose name looks
 * like a credential (`token` / `secret` / `key`). The broad tail is deliberate —
 * a debug log is the wrong place to be clever about which credential slipped
 * through, and a false positive only costs one redacted header in a log whose
 * purpose is troubleshooting. Non-credential headers (`content-type`, `accept`,
 * …) are preserved so the log stays useful.
 *
 * Case-insensitive: `fetch` lowercases header names, but `debugLogAppend` is
 * exported and entries can also be appended directly with original casing.
 */
const DEBUG_LOG_REDACTED = "[REDACTED]";
const DEBUG_LOG_SENSITIVE_HEADER =
  /^(?:authorization|proxy-authorization|cookie|set-cookie|x-api-key)$|token|secret|key/i;

/**
 * Credential shapes scrubbed out of free-form text before it is persisted —
 * the `error` field, which carries an untrusted upstream message that routinely
 * echoes the rejected credential back ("invalid Authorization: Bearer sk-…").
 *
 * Covers the three shapes that actually occur: an auth-scheme value, a labeled
 * assignment, and credentials embedded in a URL's userinfo. Deliberately NOT a
 * blanket "any long random string" rule: the debug log's purpose is reading
 * error text, and an over-broad matcher would redact the message away while
 * still missing secret shapes it did not anticipate.
 */
const DEBUG_LOG_AUTH_SCHEME = /\b(bearer|basic)\s+[^\s"',;}]+/gi;
const DEBUG_LOG_LABELED_SECRET =
  /\b((?:x-)?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|auth[_-]?token|secret|password|passwd|token|key))(\s*[:=]\s*)("?)[^\s"',;}]+\3/gi;
const DEBUG_LOG_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/)[^/\s:@]+:[^/\s@]+@/gi;

/** Scrub credential-shaped substrings out of a free-form string (e.g. an error). */
function redactDebugText(value: string): string {
  return value
    .replace(DEBUG_LOG_URL_USERINFO, `$1${DEBUG_LOG_REDACTED}@`)
    .replace(DEBUG_LOG_AUTH_SCHEME, `$1 ${DEBUG_LOG_REDACTED}`)
    .replace(DEBUG_LOG_LABELED_SECRET, `$1$2${DEBUG_LOG_REDACTED}`);
}

/**
 * Copy a header map with every sensitive value replaced by `[REDACTED]`.
 * Defensive about a missing map: this runs on the logging path, where throwing
 * would silently drop the entry instead of writing it.
 */
function redactDebugHeaders(headers: Record<string, string> | undefined): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [name, value] of Object.entries(headers ?? {})) {
    out[name] = DEBUG_LOG_SENSITIVE_HEADER.test(name) ? DEBUG_LOG_REDACTED : value;
  }
  return out;
}

export function debugLogAppend(entry: DebugLogEntry): void {
  try {
    const dir = debugLogDir();
    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
    // Redact here rather than at the call sites: this is the only choke point
    // every captured entry passes through, so no future caller can reintroduce
    // the leak by forgetting to sanitize its own headers.
    const safe: DebugLogEntry = {
      ...entry,
      reqHeaders: redactDebugHeaders(entry.reqHeaders),
      resHeaders: redactDebugHeaders(entry.resHeaders),
      ...(typeof entry.error === "string" ? { error: redactDebugText(entry.error) } : {}),
    };
    appendFileSync(debugLogPath(entry.providerId), JSON.stringify(safe) + "\n", "utf8");
  } catch (err) {
    console.warn(`[omniroute-plugin] debugLogAppend failed: ${(err as Error).message}`);
  }
}

export function debugLogRead(providerId: string, limit = 20): DebugLogEntry[] {
  try {
    const p = debugLogPath(providerId);
    if (!existsSync(p)) return [];
    const lines = readFileSync(p, "utf8").trim().split("\n").filter(Boolean);
    return lines
      .slice(-limit)
      .map((line) => {
        try {
          return JSON.parse(line) as DebugLogEntry;
        } catch {
          return null;
        }
      })
      .filter((e): e is DebugLogEntry => e !== null);
  } catch {
    return [];
  }
}

export function debugLogGetById(providerId: string, reqId: string): DebugLogEntry | null {
  try {
    const p = debugLogPath(providerId);
    if (!existsSync(p)) return null;
    const lines = readFileSync(p, "utf8").trim().split("\n").filter(Boolean);
    for (let i = lines.length - 1; i >= 0; i--) {
      try {
        const e = JSON.parse(lines[i]) as DebugLogEntry;
        if (e.reqId === reqId) return e;
      } catch {
        // skip malformed
      }
    }
    return null;
  } catch {
    return null;
  }
}

export function debugLogClear(providerId: string): void {
  try {
    const p = debugLogPath(providerId);
    if (existsSync(p)) writeFileSync(p, "", "utf8");
  } catch (err) {
    console.warn(`[omniroute-plugin] debugLogClear failed: ${(err as Error).message}`);
  }
}

/**
 * Wrap a fetch function to capture request/response pairs into the debug
 * JSONL log. Honours the `featureDefault` opt-in flag and the on-disk
 * runtime toggle (`debugLogEnabled`).
 */
export function createDebugLoggingFetch(
  inner: typeof fetch,
  providerId: string,
  featureDefault: boolean
): typeof fetch {
  return async (input, init) => {
    const active = featureDefault || debugLogEnabled(providerId);
    if (!active) return inner(input, init);
    const reqId = randomUUID();
    const url =
      typeof input === "string"
        ? input
        : input instanceof URL
          ? input.toString()
          : input instanceof Request
            ? input.url
            : String(input);
    const method = (
      init?.method ?? (typeof input === "string" ? "GET" : ((input as Request).method ?? "GET"))
    ).toUpperCase();
    const reqHeaders: Record<string, string> = {};
    if (input instanceof Request) {
      input.headers.forEach((v, k) => (reqHeaders[k] = v));
    }
    if (init?.headers) {
      const h = init.headers;
      if (h instanceof Headers) h.forEach((v, k) => (reqHeaders[k] = v));
      else if (Array.isArray(h)) for (const [k, v] of h) reqHeaders[k] = v;
      else Object.assign(reqHeaders, h);
    }
    let reqBody: unknown = undefined;
    if (init?.body) {
      if (typeof init.body === "string") {
        try {
          reqBody = JSON.parse(init.body);
        } catch {
          reqBody = init.body.slice(0, 4096);
        }
      } else {
        reqBody = "[non-string body]";
      }
    } else if (input instanceof Request) {
      try {
        const clonedReq = input.clone();
        const text = await clonedReq.text();
        try {
          reqBody = JSON.parse(text);
        } catch {
          reqBody = text.slice(0, 4096);
        }
      } catch {
        reqBody = "[body unreadable]";
      }
    }
    const t0 = Date.now();
    try {
      const res = await inner(input, init);
      const durationMs = Date.now() - t0;
      const resHeaders: Record<string, string> = {};
      res.headers.forEach((v, k) => (resHeaders[k] = v));
      let resBody: unknown = undefined;
      try {
        const clone = res.clone();
        const ct = clone.headers.get("content-type") ?? "";
        if (ct.includes("application/json")) {
          resBody = await clone.json();
        } else if (ct.includes("text/event-stream")) {
          resBody = "[stream]";
        } else if (ct.includes("text/")) {
          const txt = await clone.text();
          resBody = txt.length > 4096 ? txt.slice(0, 4096) + "...[truncated]" : txt;
        } else {
          resBody = `[${ct || "unknown"} body, status ${res.status}]`;
        }
      } catch {
        resBody = "[body unparseable]";
      }
      debugLogAppend({
        reqId,
        providerId,
        ts: t0,
        url,
        method,
        reqHeaders,
        reqBody,
        resStatus: res.status,
        resHeaders,
        resBody,
        durationMs,
      });
      return res;
    } catch (err) {
      const durationMs = Date.now() - t0;
      debugLogAppend({
        reqId,
        providerId,
        ts: t0,
        url,
        method,
        reqHeaders,
        reqBody,
        resStatus: null,
        resHeaders: {},
        resBody: undefined,
        durationMs,
        error: (err as Error).message,
      });
      throw err;
    }
  };
}

export type OmniRouteReadAuthJson = () => Promise<AuthJsonShape | undefined | null>;

export const defaultReadAuthJson: OmniRouteReadAuthJson = async () => {
  const dir = process.env.OPENCODE_DATA_DIR ?? path.join(os.homedir(), ".local/share/opencode");
  const file = path.join(dir, "auth.json");
  let body: string;
  try {
    body = await readFile(file, "utf8");
  } catch {
    // File missing or unreadable — silent no-op. This is the expected path
    // on a fresh install BEFORE `/connect` has been run.
    return undefined;
  }
  try {
    const parsed = JSON.parse(body) as unknown;
    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
      return parsed as AuthJsonShape;
    }
    return null;
  } catch {
    return null;
  }
};

/**
 * Build the config-hook portion of the plugin for a given options bag.
 * Exported standalone so the contract is unit-testable without faking the
 * full PluginInput / Hooks surface, and so multi-instance setups can each
 * own their own (auth.json reader, fetch cache, fetcher) trio.
 *
 * Behavioural contract:
 *   - Runs BEFORE `auth.loader` in the OC startup sequence (per the
 *     @opencode-ai/plugin contract). `getAuth()` is NOT available here,
 *     so we read `auth.json` directly via the injected reader.
 *   - No-op when:
 *       (a) `auth.json` is missing / unreadable (fresh install before
 *           `/connect`),
 *       (b) `auth.json[providerId]` is missing or not type-api,
 *       (c) `apiKey` is empty after extraction,
 *       (d) `baseURL` is unresolvable (neither opts.baseURL nor
 *           `auth.json[providerId].baseURL`),
 *       (e) `input.provider[providerId]` is ALREADY set (operator override
 *           wins — we never clobber manually-curated catalogs).
 *     Each no-op path emits ONE debug-level breadcrumb through the leveled logger
 *     so the operator can diagnose without log spam. Malformed `auth.json`
 *     warns once and continues as if the file were missing.
 *   - Fail-open on fetcher errors: a `/v1/models` failure → still publish
 *     a stub `{models: {}}` provider block (so OC has a complete-shape
 *     entry to render). A `/api/combos` failure → publish models-only.
 *     Both paths emit ONE error-level logger message.
 *   - When the provider hook (T-03/T-05) has ALREADY populated the shared
 *     cache for this (baseURL, apiKey) tuple, we reuse the raw payloads
 *     directly — no second fetch. (And vice-versa: the config hook fires
 *     first on OC ≥1.14.49 cold start, populating the cache for the
 *     provider hook moments later.)
 *   - DUAL-PUBLISH SAFE: on OC ≥1.14.49 BOTH this static block and the
 *     dynamic `provider.models()` result will land in OC's catalog
 *     reducer. The dynamic block wins by OC's own merge rule — see
 *     OpenCode core's provider resolution order — so emitting both is a
 *     correctness-positive: ≤1.14.48 reads static, ≥1.14.49 prefers
 *     dynamic but the static one keeps things responsive during the
 *     ~50ms window before the dynamic fetch resolves.
 *
 * @param opts Plugin options (validated, resolved with defaults).
 * @param deps Dependency injection.
 *   - `readAuthJson`     — replaces `defaultReadAuthJson` (test stub).
 *   - `fetcher`          — replaces `defaultOmniRouteModelsFetcher`.
 *   - `combosFetcher`    — replaces `defaultOmniRouteCombosFetcher`.
 *   - `now`              — clock for cache TTL (default `Date.now`).
 *   - `cache`            — shared fetch-result cache (see
 *                          `OmniRouteFetchCache`). Pass the same Map the
 *                          provider hook owns to dedupe round-trips.
 *   - `logger`           — injected sink for breadcrumb capture in tests.
 *                          Defaults to the plugin's leveled logger.
 */
export function createOmniRouteConfigHook(
  opts?: OmniRoutePluginOptions,
  deps: {
    readAuthJson?: OmniRouteReadAuthJson;
    fetcher?: OmniRouteModelsFetcher;
    combosFetcher?: OmniRouteCombosFetcher;
    enrichmentFetcher?: OmniRouteEnrichmentFetcher;
    compressionMetaFetcher?: OmniRouteCompressionMetaFetcher;
    providersFetcher?: OmniRouteProvidersFetcher;
    diskSnapshotReader?: OmniRouteDiskSnapshotReader;
    diskSnapshotWriter?: OmniRouteDiskSnapshotWriter;
    now?: () => number;
    cache?: OmniRouteFetchCache;
    logger?: {
      error?: (message: string, ...args: unknown[]) => void;
      warn: (message: string, ...args: unknown[]) => void;
      debug?: (message: string, ...args: unknown[]) => void;
    };
  } = {}
): (input: Config) => Promise<void> {
  const resolved = resolveOmniRoutePluginOptions(opts);
  const readAuthJson = deps.readAuthJson ?? defaultReadAuthJson;
  const fetcher = deps.fetcher ?? defaultOmniRouteModelsFetcher;
  const combosFetcher = deps.combosFetcher ?? defaultOmniRouteCombosFetcher;
  const enrichmentFetcher = deps.enrichmentFetcher ?? defaultOmniRouteEnrichmentFetcher;
  const compressionMetaFetcher =
    deps.compressionMetaFetcher ?? defaultOmniRouteCompressionMetaFetcher;
  const providersFetcher = deps.providersFetcher ?? defaultOmniRouteProvidersFetcher;
  const diskSnapshotReader = deps.diskSnapshotReader ?? noopDiskSnapshotReader;
  const diskSnapshotWriter = deps.diskSnapshotWriter ?? noopDiskSnapshotWriter;
  const now = deps.now ?? Date.now;
  const cache: OmniRouteFetchCache = deps.cache ?? new Map();
  const logger = deps.logger ?? _logger;
  const logAt = (level: "error" | "warn" | "debug", message: string): void => {
    const sink = logger[level] ?? logger.warn;
    sink.call(logger, message);
  };
  const features = resolved.features ?? {};
  const wantCombos = features.combos !== false;
  const wantEnrichment = features.enrichment !== false;
  const wantCompressionMeta = features.compressionMetadata === true;
  const wantUsableOnly = features.usableOnly === true;
  const wantDiskCache = features.diskCache !== false;
  const wantProviderTag = features.providerTag !== false;

  return async (input: Config) => {
    // (e) operator override — `input.provider[providerId]` already set →
    // leave it alone. Manually curated catalogs ALWAYS win over the plugin's
    // generated block. Detect-and-respect before any I/O.
    const existingProviders = (input as { provider?: Record<string, unknown> }).provider;
    if (existingProviders && existingProviders[resolved.providerId] !== undefined) {
      logAt("debug", `config shim skipped: provider.${resolved.providerId} already set by user`);
      return;
    }

    // Read auth.json. `undefined` = missing file (silent path), `null` =
    // malformed JSON (warn once and treat as missing).
    let authJson: AuthJsonShape | undefined | null;
    try {
      authJson = await readAuthJson();
    } catch {
      // Reader threw — be conservative and treat like a missing file.
      authJson = undefined;
    }

    if (authJson === null) {
      logAt("warn", "config shim: auth.json failed to parse; treating as missing");
      authJson = undefined;
    }

    // Try both prefixed (e.g. opencode-omniroute) and unprefixed (e.g. omniroute)
    // keys so a user who ran `/connect omniroute` before the auto-prefix fix
    // does not need to re-auth. Also handles dual-key for auth.json entries
    // written by a newer OC dispatcher with the prefixed key.
    const bareKey = resolved.providerId.startsWith("opencode-")
      ? resolved.providerId.slice("opencode-".length)
      : resolved.providerId;
    const lookupKeys = [resolved.providerId];
    if (bareKey !== resolved.providerId) lookupKeys.push(bareKey);
    let entry;
    for (const k of lookupKeys) {
      const e = authJson?.[k];
      if (e?.type === "api" && typeof e.key === "string" && e.key.length > 0) {
        entry = e;
        break;
      }
    }
    const apiKey = entry?.type === "api" && typeof entry.key === "string" ? entry.key : "";

    if (!apiKey) {
      // (c) no apiKey — silent no-op (with debug breadcrumb). The operator
      // hasn't run `/connect <providerId>` yet, OR the stored credential
      // isn't api-flavored. OC will handle the `/connect` flow at runtime.
      logAt("debug", `config shim skipped: no apiKey for providerId=${resolved.providerId}`);
      return;
    }
    // Management-plane catalog reads may use a narrower read-only token.
    // Backward compatibility: when unset, retain the historical apiKey use.
    const managementReadToken = resolved.managementReadToken ?? apiKey;

    // baseURL resolution: opts.baseURL wins, then auth.json's stored baseURL.
    // No silent localhost default — a misconfigured plugin should surface a
    // breadcrumb and skip, not phantom requests.
    const storedBaseURL = entry && typeof entry.baseURL === "string" ? entry.baseURL : undefined;
    const baseURL = resolved.baseURL ?? storedBaseURL ?? "";
    if (!baseURL) {
      logAt("debug", `config shim skipped: no baseURL for providerId=${resolved.providerId}`);
      return;
    }

    // Try the shared cache first. On OC ≥1.14.49 the provider hook may have
    // populated it moments earlier; on OC ≤1.14.48 only this hook runs but
    // the cache still works (single producer + consumer through one Map).
    const cacheKey = modelsCacheKey(baseURL, `${apiKey}\0${managementReadToken}`);
    const snapshotFingerprint = diskSnapshotIdentityFingerprint(
      baseURL,
      apiKey,
      managementReadToken
    );
    const t = now();
    const cached = cache.get(cacheKey);

    let rawModels: OmniRouteRawModelEntry[] = [];
    let rawCombos: OmniRouteRawCombo[] = [];
    let rawEnrichment: OmniRouteEnrichmentMap = new Map();
    let rawCompressionCombos: OmniRouteCompressionCombo[] = [];
    let rawConnections: OmniRouteProviderConnection[] = [];

    if (cached && cached.expiresAt > t) {
      rawModels = cached.rawModels;
      rawCombos = cached.rawCombos;
      rawEnrichment = cached.rawEnrichment;
      rawCompressionCombos = cached.rawCompressionCombos;
      rawConnections = cached.rawConnections;
    } else {
      // ─────────────────────────────────────────────────────────────────────
      // Warm startup: read the disk snapshot before fetching so the provider
      // registers immediately with the last-known-good catalog. The live
      // fetch then refreshes in the background (detached) and updates the
      // cache + snapshot. Gated by features.diskCache (default-on).
      // ─────────────────────────────────────────────────────────────────────
      let warmSnapshot: Omit<OmniRouteFetchCacheEntry, "expiresAt"> | undefined;
      if (wantDiskCache) {
        const snapshotResult = await diskSnapshotReader(resolved.providerId, snapshotFingerprint);
        if (snapshotResult && snapshotResult.rawModels.length > 0) {
          warmSnapshot = snapshotResult;
          // Log snapshot age (accept any age — instant beats empty).
          const age = (snapshotResult as { writtenAt?: number }).writtenAt;
          const ageLabel =
            typeof age === "number" ? `${Math.round((Date.now() - age) / 3_600_000)}h` : "unknown";
          logAt(
            "warn",
            `config shim: warm startup from disk snapshot (${snapshotResult.rawModels.length} models, age ${ageLabel})`
          );
        }
      }

      // ─────────────────────────────────────────────────────────────────────
      // Parallel refresh: all five fetchers run concurrently via
      // Promise.allSettled. Each wrapper never rejects (catches internally)
      // so partial failure is tolerated — same soft-fail semantics as the
      // old sequential chain, but ~5x faster.
      // ─────────────────────────────────────────────────────────────────────
      const doRefresh = async (): Promise<void> => {
        let modelsFetchThrew = false;
        let localRawModels: OmniRouteRawModelEntry[] = [];
        let localRawCombos: OmniRouteRawCombo[] = [];
        let localRawEnrichment: OmniRouteEnrichmentMap = new Map();
        let localRawCompressionCombos: OmniRouteCompressionCombo[] = [];
        let localRawConnections: OmniRouteProviderConnection[] = [];

        // Each wrapper keeps the existing try/catch, default value, and
        // exact warn message so per-endpoint fallbacks are preserved.
        const doModels = async (): Promise<void> => {
          try {
            localRawModels = await fetcher(baseURL, apiKey, 30_000);
          } catch (err) {
            logAt(
              "error",
              `config shim: /v1/models fetch failed; publishing stub provider entry: ${err instanceof Error ? err.message : String(err)}`
            );
            localRawModels = [];
            modelsFetchThrew = true;
          }
        };

        const doCombos = async (): Promise<void> => {
          if (!wantCombos) return;
          try {
            localRawCombos = await combosFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logAt(
              "error",
              `config shim: /api/combos fetch failed; publishing models-only static catalog: ${err instanceof Error ? err.message : String(err)}`
            );
          }
        };

        const doEnrichment = async (): Promise<void> => {
          if (!wantEnrichment) return;
          try {
            localRawEnrichment = await enrichmentFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logAt(
              "error",
              `config shim: /api/pricing/models fetch failed; publishing raw-id static catalog: ${err instanceof Error ? err.message : String(err)}`
            );
          }
        };

        const doCompression = async (): Promise<void> => {
          if (!wantCompressionMeta) return;
          try {
            localRawCompressionCombos = await compressionMetaFetcher(
              baseURL,
              managementReadToken,
              10_000
            );
          } catch (err) {
            logAt(
              "error",
              `config shim: /api/context/combos fetch failed; publishing combos without compression suffix: ${err instanceof Error ? err.message : String(err)}`
            );
          }
        };

        const doConnections = async (): Promise<void> => {
          if (!wantUsableOnly) return;
          try {
            localRawConnections = await providersFetcher(baseURL, managementReadToken, 10_000);
          } catch (err) {
            logAt(
              "error",
              `config shim: /api/providers fetch failed; usableOnly filter disabled for this refresh: ${err instanceof Error ? err.message : String(err)}`
            );
          }
        };

        await Promise.allSettled([
          doModels(),
          doCombos(),
          doEnrichment(),
          doCompression(),
          doConnections(),
        ]);

        const modelsFetchOk = !modelsFetchThrew && localRawModels.length > 0;

        // Snapshot backfill for computed_context_length: a live /api/combos
        // response can come back without this field (server hasn't finished
        // recomputing it yet, e.g. just after a restart) even though the
        // combo's members and identity are otherwise unchanged. When that
        // happens, prefer the last-known-good value from the warm disk
        // snapshot over the Math.min(member) fallback in
        // mapComboToModelV2() — never overwrite any other combo field
        // (models/name/etc.) with stale data, only this one derived number.
        if (warmSnapshot) {
          const snapshotComboById = new Map(warmSnapshot.rawCombos.map((c) => [c.id, c]));
          for (const combo of localRawCombos) {
            const hasLive =
              typeof combo.computed_context_length === "number" &&
              combo.computed_context_length > 0;
            if (hasLive) continue;
            const stale = snapshotComboById.get(combo.id);
            if (
              stale &&
              typeof stale.computed_context_length === "number" &&
              stale.computed_context_length > 0
            ) {
              combo.computed_context_length = stale.computed_context_length;
            }
          }
        }

        // Disk-cache fallback (cold first run, no warm snapshot): when the
        // live fetch returned no models AND features.diskCache !== false,
        // hydrate from the last-known-good snapshot so OC still surfaces a
        // usable catalog (e.g. IP whitelist drop, offline laptop).
        if (modelsFetchThrew && wantDiskCache && !warmSnapshot) {
          const snapshot = await diskSnapshotReader(resolved.providerId, snapshotFingerprint);
          if (snapshot && snapshot.rawModels.length > 0) {
            // Report snapshot age like the warm-startup path already does:
            // "stale" alone reads as a transient blip, so a week-old catalog
            // is indistinguishable from a five-minute-old one.
            const snapshotAge = snapshot.writtenAt;
            const ageMs = typeof snapshotAge === "number" ? now() - snapshotAge : undefined;
            const snapshotAgeLabel =
              typeof ageMs === "number" ? `${Math.round(ageMs / 3_600_000)}h` : "unknown";
            const maxAgeMs = features.diskCacheMaxAgeMs;
            const pastMaxAge =
              typeof maxAgeMs === "number" &&
              maxAgeMs > 0 &&
              typeof ageMs === "number" &&
              ageMs > maxAgeMs;
            logAt(
              pastMaxAge ? "error" : "warn",
              `config shim: /v1/models unreachable; using stale disk cache (${snapshot.rawModels.length} models, age ${snapshotAgeLabel}${
                pastMaxAge ? `, past diskCacheMaxAgeMs=${maxAgeMs}` : ""
              })`
            );
            localRawModels = snapshot.rawModels;
            localRawCombos = snapshot.rawCombos;
            localRawEnrichment = snapshot.rawEnrichment;
            localRawCompressionCombos = snapshot.rawCompressionCombos;
            localRawConnections = snapshot.rawConnections;
          }
        }

        // Cache even partial results — a subsequent provider-hook call should
        // not re-burn the timeout window on the same broken endpoint.
        cache.set(cacheKey, {
          rawModels: localRawModels,
          rawCombos: localRawCombos,
          rawEnrichment: localRawEnrichment,
          rawCompressionCombos: localRawCompressionCombos,
          rawConnections: localRawConnections,
          expiresAt: now() + resolved.modelCacheTtl,
        });

        // Startup diagnostics (file-based) — fires at startup via config hook
        if (resolved.features?.startupDebug === true) {
          await writeStartupDiagnostics({
            providerId: resolved.providerId,
            baseURL,
            modelCount: localRawModels.length,
            comboCount: localRawCombos.length,
            enrichmentSize: localRawEnrichment.size,
            enrichment: localRawEnrichment,
            features: resolved.features,
          });
        }

        // Disk-cache write: persist the last successful (or any non-empty)
        // catalog so a subsequent cold start with a failed fetch can recover.
        // Best-effort; soft-fail keeps us moving when the data dir isn't
        // writable (e.g. read-only container). A failed refresh never
        // overwrites the snapshot (modelsFetchOk gate).
        if (modelsFetchOk && wantDiskCache) {
          await diskSnapshotWriter(
            resolved.providerId,
            {
              rawModels: localRawModels,
              rawCombos: localRawCombos,
              rawEnrichment: localRawEnrichment,
              rawCompressionCombos: localRawCompressionCombos,
              rawConnections: localRawConnections,
            },
            snapshotFingerprint
          );
        }

        // Re-publish a fresh block via the shared cache so OC >=1.14.49's
        // dynamic provider hook picks it up from the cache. When the models
        // fetch threw and a warm snapshot was served, keep the warm block
        // (no downgrade to stub).
        if (modelsFetchOk || !warmSnapshot) {
          const freshBlock = buildStaticProviderEntry(
            localRawModels,
            localRawCombos,
            resolved,
            baseURL,
            apiKey,
            localRawEnrichment,
            localRawCompressionCombos,
            localRawConnections,
            logger
          );
          const inputWithProvider2 = input as { provider?: Record<string, unknown> };
          if (inputWithProvider2.provider) {
            inputWithProvider2.provider[resolved.providerId] = freshBlock;
          }
        }
      };

      if (warmSnapshot) {
        // Warm startup: publish the snapshot block immediately, then run
        // the refresh detached (never a floating unhandled rejection).
        rawModels = warmSnapshot.rawModels;
        rawCombos = warmSnapshot.rawCombos;
        rawEnrichment = warmSnapshot.rawEnrichment;
        rawCompressionCombos = warmSnapshot.rawCompressionCombos;
        rawConnections = warmSnapshot.rawConnections;

        // In-flight guard: if a refresh is already running for this
        // cacheKey, piggyback on it instead of starting a second one.
        const existing = _inflightRefresh.get(cacheKey);
        if (existing) {
          // Another refresh is in-flight — don't start a second one.
          // The existing refresh will update the cache when it completes.
        } else {
          const refreshP = doRefresh()
            .catch((err: unknown) => {
              logAt(
                "error",
                `config shim: background refresh failed: ${err instanceof Error ? err.message : String(err)}`
              );
            })
            .finally(() => {
              _inflightRefresh.delete(cacheKey);
            });
          _inflightRefresh.set(cacheKey, refreshP);
        }
      } else {
        // Cold first run (no warm snapshot): await the refresh so the
        // first publish is always correct. In-flight guard still applies.
        const existing = _inflightRefresh.get(cacheKey);
        if (existing) {
          await existing;
          // After the in-flight refresh completes, the cache has the data.
          const fresh = cache.get(cacheKey);
          if (fresh) {
            rawModels = fresh.rawModels;
            rawCombos = fresh.rawCombos;
            rawEnrichment = fresh.rawEnrichment;
            rawCompressionCombos = fresh.rawCompressionCombos;
            rawConnections = fresh.rawConnections;
          }
        } else {
          const refreshP = doRefresh()
            .catch((err: unknown) => {
              logAt(
                "error",
                `config shim: refresh failed: ${err instanceof Error ? err.message : String(err)}`
              );
            })
            .finally(() => {
              _inflightRefresh.delete(cacheKey);
            });
          _inflightRefresh.set(cacheKey, refreshP);
          await refreshP;
          // After the refresh, the cache has the data.
          const fresh = cache.get(cacheKey);
          if (fresh) {
            rawModels = fresh.rawModels;
            rawCombos = fresh.rawCombos;
            rawEnrichment = fresh.rawEnrichment;
            rawCompressionCombos = fresh.rawCompressionCombos;
            rawConnections = fresh.rawConnections;
          }
        }
      }
    }

    const block = buildStaticProviderEntry(
      rawModels,
      rawCombos,
      resolved,
      baseURL,
      apiKey,
      rawEnrichment,
      rawCompressionCombos,
      rawConnections,
      logger
    );

    // Mutate the input.provider map. The Config type declares
    // `provider?: {[key: string]: ProviderConfig}` — we initialise the
    // bag when absent so users who never set `provider` in opencode.json
    // still get the static block.
    const inputWithProvider = input as { provider?: Record<string, unknown> };
    if (!inputWithProvider.provider) {
      inputWithProvider.provider = {};
    }
    inputWithProvider.provider[resolved.providerId] = block;

    // ─────────────────────────────────────────────────────────────────────
    // MCP auto-emit — opt-in via features.mcpAutoEmit. When enabled, writes
    // an `input.mcp[<providerId>]` remote entry pointing at
    // `<baseURL>/api/mcp/stream` with the resolved Bearer token. Token
    // resolution: features.mcpToken wins if set; otherwise falls back to
    // the same apiKey used for chat. Operator overrides win (same posture
    // as provider-block emit): if input.mcp[providerId] is already set,
    // we leave it alone.
    // ─────────────────────────────────────────────────────────────────────
    if (features.mcpAutoEmit === true) {
      const mcpKey = features.mcpToken ?? apiKey;
      if (!mcpKey) {
        logAt(
          "debug",
          `mcp auto-emit skipped: no Bearer token for providerId=${resolved.providerId}`
        );
      } else {
        const inputWithMcp = input as { mcp?: Record<string, unknown> };
        if (!inputWithMcp.mcp) {
          inputWithMcp.mcp = {};
        }
        if (inputWithMcp.mcp[resolved.providerId] !== undefined) {
          logAt("debug", `mcp auto-emit skipped: mcp.${resolved.providerId} already set by user`);
        } else {
          // Strip a trailing `/v1` from baseURL when present so we land on
          // the MCP transport at /api/mcp/stream, not /v1/api/mcp/stream.
          const mcpRoot = baseURL.replace(/\/v1\/?$/, "").replace(/\/$/, "");
          inputWithMcp.mcp[resolved.providerId] = {
            type: "remote",
            url: `${mcpRoot}/api/mcp/stream`,
            enabled: true,
            headers: {
              Authorization: `Bearer ${mcpKey}`,
            },
          };
        }
      }
    }
  };
}