@yansigit/opencodex 2.31.0

package/src/server/management/routing-profile-routes.ts

@@ -0,0 +1,385 @@
+/**
+ * Routing-profile management API (RI-04).
+ *
+ * - `GET    /api/routing-profiles` - normalized profiles with revisions
+ * - `PUT    /api/routing-profiles` - create or replace one validated profile
+ * - `DELETE /api/routing-profiles?id=<id>` - remove one profile
+ * - `POST   /api/routing-profiles/dry-run` - deterministic dry-run evaluation
+ *   (never dispatches an upstream request)
+ */
+
+import {
+  getRoutingProfile,
+  listRoutingProfileIds,
+  normalizeRoutingProfile,
+  policyPublicModelId,
+  routingProfileIssues,
+} from "../../routing/profile";
+import { evaluatePolicyProfile, type PolicyCandidateEvidence, type PolicyRequestEvidence } from "../../routing/evaluator";
+import { assemblePolicyCandidateEvidence } from "../../routing/compatibility/assemble";
+import { activateLab, labActivationRequired } from "../../lib/lab-activation";
+import { quotaEvidenceForCandidate } from "../../routing/quota";
+import { routedProviderConfig } from "../../router";
+import { saveConfigPreservingClaudeCode, getConfigDir } from "../../config";
+import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
+import { isPlainRecord } from "./shared";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import type { OcxConfig, OcxRoutingProfileConfig } from "../../types";
+
+function profileDto(config: Parameters<typeof getRoutingProfile>[0], id: string): Record<string, unknown> | null {
+  const profile = getRoutingProfile(config, id);
+  if (!profile) return null;
+  return {
+    id,
+    alias: profile.alias,
+    model: policyPublicModelId(id, profile),
+    revision: profile.revision,
+    candidates: profile.candidates,
+    require: profile.require,
+    optimize: profile.optimize,
+    limits: profile.limits,
+    unknownEvidence: profile.unknownEvidence,
+    ...(profile.compatibility ? { compatibility: profile.compatibility } : {}),
+  };
+}
+
+function parseEvidence(raw: unknown): { evidence: PolicyRequestEvidence; ok: boolean } {
+  // Absent evidence is empty evidence, mirroring the absent-candidates case.
+  if (raw === undefined) return { evidence: {}, ok: true };
+  if (!isPlainRecord(raw)) return { evidence: {}, ok: false };
+  const record = raw as Record<string, unknown>;
+  const evidence: PolicyRequestEvidence = {};
+  if (typeof record.contextWindow === "number" && Number.isFinite(record.contextWindow) && record.contextWindow >= 0) {
+    evidence.contextWindow = record.contextWindow;
+  }
+  for (const key of ["toolsRequired", "imageInputRequired", "structuredOutputRequired", "encryptedCodexTask"] as const) {
+    if (typeof record[key] === "boolean") evidence[key] = record[key];
+  }
+  if (typeof record.reasoningEffort === "string") evidence.reasoningEffort = record.reasoningEffort;
+  if (typeof record.serviceTier === "string") evidence.serviceTier = record.serviceTier;
+  return { evidence, ok: true };
+}
+
+function parseCandidateEvidence(raw: unknown): PolicyCandidateEvidence[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: PolicyCandidateEvidence[] = [];
+  for (const item of raw) {
+    if (!isPlainRecord(item)) return null;
+    const provider = item.provider;
+    const model = item.model;
+    if (typeof provider !== "string" || typeof model !== "string") return null;
+    out.push({
+      provider,
+      model,
+      ...(typeof item.accountRef === "string" ? { accountRef: item.accountRef } : {}),
+      ...(typeof item.codexAccountId === "string" ? { codexAccountId: item.codexAccountId } : {}),
+      // Dry-run evidence is caller-supplied and echoed back in the result as
+      // given; the trace's candidate rows carry only score/exclusions, which
+      // the trace builder bounds. Structural casts keep the API permissive.
+      ...(isPlainRecord(item.capability) ? { capability: item.capability as unknown as PolicyCandidateEvidence["capability"] } : {}),
+      ...(isPlainRecord(item.health) ? { health: item.health as unknown as PolicyCandidateEvidence["health"] } : {}),
+      ...(isPlainRecord(item.quota) ? { quota: item.quota as unknown as PolicyCandidateEvidence["quota"] } : {}),
+      ...(isPlainRecord(item.cost) ? { cost: item.cost as unknown as PolicyCandidateEvidence["cost"] } : {}),
+      // Derive account-scoped quota evidence from the documented refs when the
+      // caller does not supply an explicit quota object, so a dry-run following
+      // the documented shape reports the same cached account quota as routing.
+      ...(item.quota === undefined && typeof item.codexAccountId === "string"
+        ? { quota: quotaEvidenceForCandidate({ provider, model, codexAccountId: item.codexAccountId }) }
+        : {}),
+      ...(item.quota === undefined && typeof item.accountRef === "string" && typeof item.codexAccountId !== "string"
+        ? { quota: quotaEvidenceForCandidate({ provider, model, accountRef: item.accountRef }) }
+        : {}),
+    });
+  }
+  return out;
+}
+
+function assembleCandidateEvidence(
+  config: OcxConfig,
+  profile: NonNullable<ReturnType<typeof getRoutingProfile>>,
+  now: number,
+): PolicyCandidateEvidence[] {
+  return assemblePolicyCandidateEvidence(config, profile, now, {
+    routedProviderConfig,
+  });
+}
+
+function storedProfile(
+  id: string,
+  raw: OcxRoutingProfileConfig,
+): OcxRoutingProfileConfig {
+  const normalized = normalizeRoutingProfile(id, raw);
+  const {
+    id: _id,
+    revision: _revision,
+    alias,
+    ...profile
+  } = normalized;
+  return alias === null ? profile : { ...profile, alias };
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+/**
+ * Detect a modelMap key collision that the alias migration would silently
+ * resolve by dropping one mapping: the map already contains the new public
+ * model as a key with a different target than the old-alias key's target.
+ */
+function modelMapMigrationCollision(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): string | null {
+  const map = config.claudeCode?.modelMap;
+  if (!map) return null;
+  if (oldPublicModel === newPublicModel) return null;
+  const oldTarget = map[oldPublicModel];
+  if (oldTarget === undefined) return null;
+  const newTarget = map[newPublicModel];
+  if (newTarget === undefined) return null;
+  if (oldTarget === newTarget) return null;
+  return `modelMap already maps \"${newPublicModel}\" to \"${newTarget}\"; renaming \"${oldPublicModel}\" (→ \"${newTarget}\") would drop one mapping. Resolve the conflict and retry.`;
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+function migrateProfileModelReferences(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): boolean {
+  if (oldPublicModel === newPublicModel) return false;
+  const migrateReference = (model: string): string => (
+    model === oldPublicModel ? newPublicModel : model
+  );
+  let shouldSyncClaudeAgentDefs = false;
+  const migrateAgentReference = (model: string): string => {
+    const migrated = migrateReference(model);
+    if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+    return migrated;
+  };
+  const migrateReferences = (models: string[]): string[] => [
+    ...new Set(models.map(migrateReference)),
+  ];
+  if (config.disabledModels) {
+    config.disabledModels = migrateReferences(config.disabledModels);
+  }
+  if (config.subagentModels) {
+    config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+  }
+  if (config.subagentRoles) {
+    for (const role of config.subagentRoles) {
+      role.model = migrateAgentReference(role.model);
+    }
+  }
+  if (config.subagentModelFallback) {
+    config.subagentModelFallback = [...new Set(config.subagentModelFallback.map(migrateAgentReference))];
+  }
+  if (config.injectionModel && config.injectionModel === oldPublicModel) {
+    config.injectionModel = newPublicModel;
+  }
+  if (config.shadowCallIntercept?.model && config.shadowCallIntercept.model === oldPublicModel) {
+    config.shadowCallIntercept = { ...config.shadowCallIntercept, model: newPublicModel };
+  }
+  if (config.claudeCode) {
+    const claudeCode = { ...config.claudeCode };
+    for (const field of ["model", "smallFastModel"] as const) {
+      if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+    }
+    if (claudeCode.tierModels) {
+      claudeCode.tierModels = Object.fromEntries(
+        Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+      );
+    }
+    if (claudeCode.modelMap) {
+      // Keys are the inbound ids matched for reroute (src/claude/inbound.ts);
+      // an old-alias key must follow the rename or that request stops intercepting.
+      claudeCode.modelMap = Object.fromEntries(
+        Object.entries(claudeCode.modelMap).map(([source, model]) => [
+          migrateAgentReference(source),
+          migrateAgentReference(model),
+        ]),
+      );
+    }
+    config.claudeCode = claudeCode;
+  }
+  return shouldSyncClaudeAgentDefs;
+}
+export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "GET") {
+    const profiles = listRoutingProfileIds(config).map(id => profileDto(config, id)).filter(
+      (profile): profile is Record<string, unknown> => profile !== null,
+    );
+    return jsonResponse({ profiles }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "PUT") {
+    let rawBody: unknown;
+    try {
+      rawBody = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400, req, config);
+    }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400, req, config);
+    }
+    const body = rawBody as Record<string, unknown>;
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!id) {
+      return jsonResponse({ error: { code: "missing_profile_id", message: "id is required" } }, 400, req, config);
+    }
+    const mode = body.mode === "create" || body.mode === "update" ? body.mode : null;
+    if (!mode) {
+      return jsonResponse({ error: { code: "invalid_profile_mode", message: "mode must be create or update" } }, 400, req, config);
+    }
+    const exists = Object.hasOwn(config.routingProfiles ?? {}, id);
+    if (mode === "create" && exists) {
+      return jsonResponse({ error: { code: "profile_exists", message: `routing profile already exists: ${id}` } }, 409, req, config);
+    }
+    if (mode === "update" && !exists) {
+      return jsonResponse({ error: { code: "unknown_profile", message: `unknown routing profile: ${id}` } }, 404, req, config);
+    }
+    if (mode === "update") {
+      const expectedRevision = typeof body.expectedRevision === "string" && body.expectedRevision.trim()
+        ? body.expectedRevision.trim()
+        : undefined;
+      if (expectedRevision) {
+        const current = getRoutingProfile(config, id);
+        if (current && current.revision !== expectedRevision) {
+          return jsonResponse({
+            error: {
+              code: "profile_revision_conflict",
+              message: `routing profile ${id} changed since it was loaded; reload and retry`,
+              currentRevision: current.revision,
+            },
+          }, 409, req, config);
+        }
+      }
+    }
+    const issues = routingProfileIssues(id, body.profile, config, { excludeProfileId: id });
+    if (issues.length > 0) {
+      return jsonResponse({
+        error: {
+          code: "invalid_profile",
+          message: issues[0]!.message,
+          issues,
+        },
+      }, 400, req, config);
+    }
+
+    const previousProfile = mode === "update" ? getRoutingProfile(config, id) : undefined;
+    if (mode === "update" && previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newProfile = normalizeRoutingProfile(id, body.profile as OcxRoutingProfileConfig);
+      const newPublicModel = policyPublicModelId(id, newProfile);
+      const collision = modelMapMigrationCollision(config, oldPublicModel, newPublicModel);
+      if (collision) {
+        return jsonResponse({
+          error: { code: "alias_reference_conflict", message: collision },
+        }, 409, req, config);
+      }
+    }
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    nextProfiles[id] = storedProfile(id, body.profile as OcxRoutingProfileConfig);
+    config.routingProfiles = nextProfiles;
+    // Creating the first profile on a process started profile-less must install the
+    // compatibility provider now; activation is synchronous and idempotent per configDir.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
+    // An alias change on update renames the public model id; rewrite config
+    // references (disabledModels, subagentModels, injectionModel,
+    // shadowCallIntercept, claudeCode) so they follow the new alias.
+    let shouldSyncClaudeAgentDefs = false;
+    if (previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newPublicModel = policyPublicModelId(id, getRoutingProfile(config, id)!);
+      shouldSyncClaudeAgentDefs = migrateProfileModelReferences(config, oldPublicModel, newPublicModel);
+    }
+    const save = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    save(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    if (shouldSyncClaudeAgentDefs) await syncClaudeAgentDefsBestEffort();
+    const profile = profileDto(config, id)!;
+    return jsonResponse({
+      success: true,
+      id,
+      model: profile.model,
+      profile,
+      catalogRefresh,
+    }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "DELETE") {
+    const id = url.searchParams.get("id")?.trim();
+    if (!id) {
+      return jsonResponse({ error: "id query param is required" }, 400, req, config);
+    }
+    if (!Object.hasOwn(config.routingProfiles ?? {}, id)) {
+      return jsonResponse({ error: "unknown routing profile" }, 404, req, config);
+    }
+
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    delete nextProfiles[id];
+    if (Object.keys(nextProfiles).length > 0) config.routingProfiles = nextProfiles;
+    else delete config.routingProfiles;
+    const saveConfigPreservingClaudeCodeSafe = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    saveConfigPreservingClaudeCodeSafe(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ success: true, id, catalogRefresh }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles/dry-run" && req.method === "POST") {
+    let rawBody: unknown;
+    try { rawBody = await readManagementJsonBody(req); } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400, req, config);
+    }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400, req, config);
+    }
+    const body = rawBody as Record<string, unknown>;
+    const profile = typeof body.profile === "string" ? body.profile.trim() : "";
+    if (!profile) {
+      return jsonResponse({ error: { code: "missing_profile", message: "profile is required" } }, 400, req, config);
+    }
+    const resolvedProfile = getRoutingProfile(config, profile);
+    if (!resolvedProfile) {
+      return jsonResponse({ error: { code: "unknown_profile", message: `unknown routing profile: ${profile}` } }, 404, req, config);
+    }
+    const { evidence, ok } = parseEvidence(body.evidence);
+    if (!ok) {
+      return jsonResponse({ error: { code: "invalid_evidence", message: "evidence must be an object" } }, 400, req, config);
+    }
+    // One clock read for both assembly and evaluation keeps freshness, health,
+    // and trace timestamps mutually consistent with the production router.
+    const now = Date.now();
+    // R3-1: dry-run assembles candidate evidence independently of the startup gate, so an
+    // operator preview on a process started without profiles would silently omit
+    // compatibility evidence and disagree with production. Activate first.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
+    const candidateEvidence = body.candidates === undefined
+      ? assembleCandidateEvidence(config, resolvedProfile, now)
+      : parseCandidateEvidence(body.candidates);
+    if (candidateEvidence === null) {
+      return jsonResponse({ error: { code: "invalid_candidates", message: "candidates must be an array of evidence objects" } }, 400, req, config);
+    }
+    const result = evaluatePolicyProfile(config, profile, evidence, candidateEvidence, now);
+    return jsonResponse(result, 200, req, config);
+  }
+
+  return null;
+}

package/src/server/management/shared.ts

@@ -0,0 +1,286 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { CatalogModel } from "../../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  DEFAULT_SUBAGENT_MODELS,
+  codexAutoStartEnabled,
+  hasOwnProvider,
+  isValidProviderName,
+  multiAgentGuidanceEnabled,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  saveConfigPreservingClaudeCode,
+} from "../../config";
+import {
+  clearLoginState,
+  getLoginStatus,
+  isPublicOAuthProvider,
+  listOAuthProviders,
+  startLoginFlow,
+  submitManualLoginCode,
+  upsertOAuthProvider,
+} from "../../oauth";
+import { removeCredential } from "../../oauth/store";
+import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
+import { deriveProviderPresets } from "../../providers/derive";
+import { providerCodexAccountMode } from "../../providers/registry";
+import { routedSlug, slugEquals } from "../../providers/slug-codec";
+import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { clearThreadAccountMap } from "../../codex/routing";
+import { primeCodexPoolQuotas } from "../../codex/auth-api";
+import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
+import { resolveCodexHomeDir } from "../../codex/home";
+import { readUsageEntries } from "../../usage/log";
+import { getUsageDebugLogEntries } from "../../usage/debug";
+import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
+import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
+import { getDebugLogEntries } from "../../lib/debug-log-buffer";
+import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
+import {
+  clearDebugSettings,
+  clearDebugSetting,
+  getDebugSettings,
+  setDebugSettings,
+  type DebugFlag,
+} from "../../lib/debug-settings";
+import type { OcxClaudeCodeConfig, OcxClaudeDesktopProfile, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import type { DesktopProfileModel } from "../../claude/desktop-profile";
+import { drainAndShutdown } from "../lifecycle";
+import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
+import { estimateComboCost, estimateRequestCost, serviceTierContext, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
+import type { PersistedUsageAttempt } from "../../usage/log";
+import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
+import { applySystemEnvToggle } from "../system-env";
+
+
+export function isPlainRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export function parseDebugLogQuery(url: URL): { after: number; limit: number } {
+  const after = Number(url.searchParams.get("after") ?? url.searchParams.get("since") ?? "0");
+  const limit = Number(url.searchParams.get("limit") ?? "500");
+  return {
+    after: Number.isFinite(after) && after > 0 ? after : 0,
+    limit: Number.isFinite(limit) && limit > 0 ? Math.min(limit, 2000) : 500,
+  };
+}
+
+// ---- /api/logs display metrics (devlog/_plan/260720_toks_speed_price_columns/020) ----
+// Derived at response time only; NEVER persisted to the request log or usage.jsonl.
+
+export type MetricUnavailableReason =
+  | "usage_missing" | "usage_unsupported" | "output_missing" | "invalid_duration"
+  | "price_unmatched" | "invalid_cache_breakdown"
+  | "invalid_usage" | "combo_attempt_unavailable";
+
+export type TokPerSecondResult =
+  | { kind: "value"; value: number; estimated: boolean }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+export type CostEstimateReason =
+  | "usage_estimated"
+  | "cache_detail_missing"
+  | "expected_price_overlay"
+  | "provider_cost_overlay"
+  | "priority_lower_bound";
+
+export type CostResult =
+  | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier" | "tierOutcome"> & {
+  attempts?: readonly PersistedUsageAttempt[];
+};
+
+export function tokPerSecondResult(entry: Pick<MetricSource, "durationMs" | "usageStatus" | "usage">): TokPerSecondResult {
+  if (!entry.usage) return { kind: "unavailable", reason: "usage_missing" };
+  if (entry.usageStatus === "unsupported") return { kind: "unavailable", reason: "usage_unsupported" };
+  const value = tokensPerSecond(entry.usage.outputTokens, entry.durationMs);
+  if (value === null) {
+    return {
+      kind: "unavailable",
+      reason: entry.usage.outputTokens <= 0 ? "output_missing" : "invalid_duration",
+    };
+  }
+  return { kind: "value", value, estimated: entry.usageStatus === "estimated" || entry.usage.estimated === true };
+}
+
+export function unavailableCostReason(entry: MetricSource): MetricUnavailableReason {
+  // Normalizer-first classification: the landed normalizer recovers legacy
+  // cachedInputTokens=read+write rows via retry, so a raw read+write>input
+  // pre-check would misclassify recoverable rows (020 audit blocker #2).
+  if (!entry.usage && !entry.attempts?.length) return "usage_missing";
+  if (entry.usageStatus === "unsupported") return "usage_unsupported";
+  if (entry.attempts?.length) return "combo_attempt_unavailable";
+  if (!entry.usage) return "usage_missing";
+  if (!normalizeCostTokens(entry.usage)) {
+    const effectiveRead = entry.usage.cacheReadInputTokens ?? entry.usage.cachedInputTokens ?? 0;
+    const effectiveWrite = entry.usage.cacheCreationInputTokens ?? 0;
+    const finite = [entry.usage.inputTokens, entry.usage.outputTokens, effectiveRead, effectiveWrite]
+      .every(v => Number.isFinite(v) && v >= 0);
+    return finite ? "invalid_cache_breakdown" : "invalid_usage";
+  }
+  return "price_unmatched";
+}
+
+/** Display-time cost estimate for one log entry (or its attempt list), including the reasons that qualify the estimate. */
+export function costResult(entry: MetricSource): CostResult {
+  const tier = serviceTierContext(entry);
+  const estimate = entry.attempts?.length
+    ? estimateComboCost(entry.attempts, undefined, tier)
+    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus, serviceTier: tier });
+  if (!estimate) return { kind: "unavailable", reason: unavailableCostReason(entry) };
+  const estimateReasons = [
+    entry.usageStatus === "estimated" || entry.usage?.estimated ? "usage_estimated" as const : undefined,
+    entry.usage && entry.usage.cachedInputTokens === undefined
+      && entry.usage.cacheReadInputTokens === undefined
+      && entry.usage.cacheCreationInputTokens === undefined ? "cache_detail_missing" as const : undefined,
+    estimate.price?.source === "expected" || estimate.attempts?.some(a => a.price.source === "expected")
+      ? "expected_price_overlay" as const : undefined,
+    estimate.price?.source === "user" || estimate.attempts?.some(a => a.price.source === "user")
+      ? "provider_cost_overlay" as const : undefined,
+    estimate.priorityLowerBound ? "priority_lower_bound" as const : undefined,
+  ].filter((reason): reason is CostEstimateReason => reason !== undefined);
+  return { kind: "value", estimate, estimateReasons };
+}
+
+export function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
+  return {
+    ...entry,
+    displayMetrics: {
+      tokPerSecond: tokPerSecondResult(entry),
+      cost: costResult(entry),
+    },
+    ...(entry.attempts?.length
+      ? {
+        attempts: entry.attempts.map(attempt => ({
+          ...attempt,
+          displayMetrics: {
+            tokPerSecond: tokPerSecondResult(attempt),
+            cost: costResult({ ...attempt, attempts: undefined, requestedServiceTier: entry.requestedServiceTier, configuredServiceTier: entry.configuredServiceTier, responseServiceTier: entry.responseServiceTier }),
+          },
+        })),
+      }
+      : {}),
+  };
+}
+
+/**
+ * Live routed-provider models for the proxy's /api/* and /v1/models endpoints. Delegates to the
+ * canonical, TTL-cached `gatherRoutedModels` (single source of truth) — so the GUI/codex endpoints
+ * share the same fetch, the same per-provider cache (dedups Codex's frequent /v1/models polling),
+ * and the same stale fallback when a provider blips, instead of a parallel uncached copy.
+ */
+export async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+  const { gatherRoutedModels } = await import("../../codex/catalog");
+  return gatherRoutedModels(config);
+}
+
+export interface GrokCandidateModel {
+  id: string;
+  contextWindow?: number;
+  native: boolean;
+}
+
+/**
+ * The model list `syncGrokConfig` would inject, BEFORE the user's exclusions. The Grok
+ * page needs this to show a switch for a model the user has already excluded — such a
+ * model is absent from the fence, so readGrokStatus alone could never list it. Built
+ * from the same two sources as the sync so the two can never disagree.
+ */
+export async function fetchGrokCandidateModels(config: OcxConfig): Promise<GrokCandidateModel[]> {
+  const { filterCatalogVisibleModels, nativeContextLimits, nativeOpenAiContextWindow, visibleNativeSlugs } = await import("../../codex/catalog");
+  const routed = filterCatalogVisibleModels(await fetchAllModels(config), config);
+  return [
+    ...visibleNativeSlugs(config).map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id, nativeContextLimits(config));
+      return { id, native: true, ...(contextWindow !== undefined ? { contextWindow } : {}) };
+    }),
+    ...routed.map(m => ({
+      id: m.alias ?? `${m.provider}/${m.id}`,
+      native: false,
+      ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
+    })),
+  ];
+}
+
+export function stripRegistryOnlyStaticHeaders(name: string, provider: OcxProviderConfig): OcxProviderConfig {
+  const entry = providerMatchesRegistryTransport(name, provider) ? getProviderRegistryEntry(name) : undefined;
+  if (!entry?.staticHeaders || !provider.headers) return provider;
+  const headerEntries = Object.entries(provider.headers);
+  const staticEntries = Object.entries(entry.staticHeaders);
+  if (headerEntries.length !== staticEntries.length) return provider;
+  const matchesRegistryStaticHeaders = staticEntries.every(([key, value]) => provider.headers?.[key] === value);
+  if (!matchesRegistryStaticHeaders) return provider;
+  const { headers: _headers, ...rest } = provider;
+  return rest;
+}
+
+/** Shared Desktop profile DTO builder for the management API and CLI. */
+export async function buildClaudeDesktopState(config: OcxConfig, stored?: OcxClaudeDesktopProfile) {
+  const { filterCatalogVisibleModels, nativeContextLimits, nativeOpenAiContextWindow, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
+  const { DESKTOP_SUPPORTS_1M_THRESHOLD } = await import("../../claude/desktop-3p");
+  const { reconcileDesktopProfile, renderDesktopProfile } = await import("../../claude/desktop-profile");
+  const routed = filterCatalogVisibleModels(await fetchAllModels(config), config);
+  const profileModels: DesktopProfileModel[] = [
+    // Native rows carry their real context window from the same accessor the Grok sync
+    // uses — otherwise Sol's 372k and gpt-5.5's 272k render as blank on Desktop.
+    ...desktopVisibleNativeSlugs(config).map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id, nativeContextLimits(config));
+      return { route: `native/${id}`, label: `${id} (native)`,
+        ...(contextWindow !== undefined ? { contextWindow } : {}) };
+    }),
+    ...routed.map(model => ({
+      route: `${model.provider}/${model.id}`,
+      label: `${model.id} (${model.provider})`,
+      ...(typeof model.contextWindow === "number" ? { contextWindow: model.contextWindow } : {}),
+    })),
+  ];
+  const profile = reconcileDesktopProfile(stored ?? config.claudeCode?.desktopProfile, profileModels);
+  if (config.claudeCode?.desktopNativeModels === false) {
+    for (const route of Object.keys(profile.assignments)) {
+      if (route.startsWith("native/")) delete profile.assignments[route];
+    }
+    for (const family of ["opus", "fable", "sonnet", "haiku"] as const) {
+      const current = profile.defaults[family];
+      if (current?.startsWith("native/")) {
+        profile.defaults[family] = Object.keys(profile.assignments)
+          .filter(route => profile.assignments[route]?.family === family)
+          .sort()[0] ?? null;
+      }
+    }
+  }
+  const available = new Set(profileModels.map(model => model.route));
+  const modelByRoute = new Map(profileModels.map(model => [model.route, model]));
+  // Effort support: routed models with a non-empty reasoningEfforts ladder support effort;
+  // native models always support it (Anthropic native effort).
+  const effortByRoute = new Map<string, boolean>();
+  for (const m of routed) {
+    effortByRoute.set(`${m.provider}/${m.id}`, Array.isArray(m.reasoningEfforts) && m.reasoningEfforts.length > 0);
+  }
+  for (const id of desktopVisibleNativeSlugs(config)) {
+    effortByRoute.set(`native/${id}`, true);
+  }
+  const models = Object.keys(profile.assignments).sort().map(route => ({
+    route,
+    label: modelByRoute.get(route)?.label ?? route,
+    available: available.has(route),
+    ...(modelByRoute.get(route)?.contextWindow ? { contextWindow: modelByRoute.get(route)!.contextWindow } : {}),
+    effortSupported: effortByRoute.get(route) ?? false,
+    // Read-only view of the 1M capability the written Desktop config already emits,
+    // derived from the SAME threshold so the dashboard chip can never disagree.
+    supports1m: (modelByRoute.get(route)?.contextWindow ?? 0) >= DESKTOP_SUPPORTS_1M_THRESHOLD,
+    assignment: profile.assignments[route]!,
+  }));
+  return {
+    profile,
+    models,
+    rendered: renderDesktopProfile(profile, profileModels),
+    port: config.port,
+  };
+}