@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/server/management/lab-routes.ts

@@ -0,0 +1,388 @@
+/**
+ * CL-04 read-only Compatibility Lab management API.
+ *
+ * - GET /api/lab/status
+ * - GET /api/lab/verdicts
+ * - GET /api/lab/subjects
+ * - GET /api/lab/subjects/:subjectId
+ * - GET /api/lab/observations
+ * - GET /api/lab/events
+ * - GET /api/lab/events/:eventId
+ * - GET /api/lab/artifacts
+ * - GET /api/lab/artifacts/:digest
+ * - GET /api/lab/catalog
+ */
+
+import {
+  EVIDENCE_LAYERS,
+  EXECUTION_MODES,
+  EVENT_KINDS,
+  OUTCOMES,
+  VERDICTS,
+  type EvidenceLayer,
+  type ExecutionMode,
+  type LabEventKind,
+  type ObservationOutcome,
+  type CompatibilityVerdict,
+} from "../../lab/constants";
+import {
+  InvalidCursorError,
+  LabProjectionIncompatibleError,
+  LabProjectionUnavailableError,
+  LAB_QUERY_MAX_PAGE_SIZE,
+  queryLabArtifactByDigest,
+  queryLabArtifacts,
+  queryLabCatalogEntries,
+  queryLabEventById,
+  queryLabEvents,
+  queryLabObservations,
+  queryLabStatus,
+  queryLabSubjectById,
+  queryLabSubjects,
+  queryLabVerdicts,
+} from "../../lab/query";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+function parseQueryInt(raw: string | null): number | undefined | "invalid" {
+  if (raw === null) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return "invalid";
+  const value = Number(trimmed);
+  return Number.isInteger(value) ? value : "invalid";
+}
+
+function errorResponse(
+  code: string,
+  message: string,
+  status: number,
+  ctx: ManagementContext,
+): Response {
+  return jsonResponse({ error: { code, message } }, status, ctx.req, ctx.config);
+}
+
+function projectionErrorResponse(err: unknown, ctx: ManagementContext): Response | null {
+  if (err instanceof LabProjectionUnavailableError) {
+    return errorResponse("lab_projection_unavailable", "lab projection is not available", 503, ctx);
+  }
+  if (err instanceof LabProjectionIncompatibleError) {
+    return errorResponse("lab_projection_incompatible", "lab projection schema or spec version is incompatible", 503, ctx);
+  }
+  if (err instanceof InvalidCursorError) {
+    return errorResponse("invalid_cursor", "invalid cursor", 400, ctx);
+  }
+  return null;
+}
+
+function parseLimit(raw: string | null, ctx: ManagementContext): number | undefined | Response {
+  const parsed = raw === null ? undefined : parseQueryInt(raw);
+  if (parsed === "invalid") {
+    return errorResponse(
+      "invalid_limit",
+      `limit must be an integer from 1 to ${LAB_QUERY_MAX_PAGE_SIZE}`,
+      400,
+      ctx,
+    );
+  }
+  if (parsed !== undefined && (parsed < 1 || parsed > LAB_QUERY_MAX_PAGE_SIZE)) {
+    return errorResponse(
+      "invalid_limit",
+      `limit must be an integer from 1 to ${LAB_QUERY_MAX_PAGE_SIZE}`,
+      400,
+      ctx,
+    );
+  }
+  return parsed;
+}
+
+function parseRange(
+  fromRaw: string | null,
+  toRaw: string | null,
+  ctx: ManagementContext,
+): { from?: number; to?: number } | Response {
+  const fromParsed = parseQueryInt(fromRaw);
+  if (fromParsed === "invalid") {
+    return errorResponse("invalid_range", "from must be an integer timestamp", 400, ctx);
+  }
+  const toParsed = parseQueryInt(toRaw);
+  if (toParsed === "invalid") {
+    return errorResponse("invalid_range", "to must be an integer timestamp", 400, ctx);
+  }
+  if (fromParsed !== undefined && toParsed !== undefined && fromParsed > toParsed) {
+    return errorResponse("invalid_range", "from must not be after to", 400, ctx);
+  }
+  return { from: fromParsed, to: toParsed };
+}
+
+function parseLayer(raw: string | null, ctx: ManagementContext): EvidenceLayer | undefined | Response {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!EVIDENCE_LAYERS.includes(trimmed as EvidenceLayer)) {
+    return errorResponse("invalid_layer", "layer must be a supported evidence layer", 400, ctx);
+  }
+  return trimmed as EvidenceLayer;
+}
+
+function parseVerdict(raw: string | null, ctx: ManagementContext): CompatibilityVerdict | undefined | Response {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!VERDICTS.includes(trimmed as CompatibilityVerdict)) {
+    return errorResponse("invalid_verdict", "verdict must be a supported compatibility verdict", 400, ctx);
+  }
+  return trimmed as CompatibilityVerdict;
+}
+
+function parseEventKind(raw: string | null, ctx: ManagementContext): LabEventKind | undefined | Response {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!EVENT_KINDS.includes(trimmed as LabEventKind)) {
+    return errorResponse("invalid_event_kind", "eventKind must be a supported lab event kind", 400, ctx);
+  }
+  return trimmed as LabEventKind;
+}
+
+function parseOutcome(raw: string | null, ctx: ManagementContext): ObservationOutcome | undefined | Response {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!OUTCOMES.includes(trimmed as ObservationOutcome)) {
+    return errorResponse("invalid_outcome", "outcome must be a supported observation outcome", 400, ctx);
+  }
+  return trimmed as ObservationOutcome;
+}
+
+function parseExecutionMode(raw: string | null, ctx: ManagementContext): ExecutionMode | undefined | Response {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!EXECUTION_MODES.includes(trimmed as ExecutionMode)) {
+    return errorResponse("invalid_execution_mode", "executionMode must be a supported execution mode", 400, ctx);
+  }
+  return trimmed as ExecutionMode;
+}
+
+function rejectUnsafeId(id: string, ctx: ManagementContext): Response | null {
+  if (id.includes("/") || id.includes("\\") || id.includes("%2f") || id.includes("%5c")) {
+    return errorResponse("not_found", "unknown resource", 404, ctx);
+  }
+  if (id.length === 0 || id.length > 256) {
+    return errorResponse("not_found", "unknown resource", 404, ctx);
+  }
+  return null;
+}
+
+function decodePathSegment(raw: string): string | null {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return null;
+  }
+}
+
+function paginatedEnvelope<T>(page: { items: T[]; nextCursor?: string; hasMore: boolean }, key: string) {
+  return {
+    [key]: page.items,
+    hasMore: page.hasMore,
+    ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+  };
+}
+
+export async function handleLabRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (!url.pathname.startsWith("/api/lab")) return null;
+  if (req.method !== "GET") return null;
+
+  if (url.pathname === "/api/lab/status") {
+    return jsonResponse(queryLabStatus(), 200, req, config);
+  }
+
+  if (url.pathname === "/api/lab/catalog") {
+    const layerRaw = url.searchParams.get("layer");
+    const layerParsed = layerRaw ? parseLayer(layerRaw, ctx) : undefined;
+    if (layerParsed instanceof Response) return layerParsed;
+    const suiteId = url.searchParams.get("suiteId")?.trim() || url.searchParams.get("suite")?.trim() || undefined;
+    try {
+      const scenarios = queryLabCatalogEntries({
+        layer: layerParsed,
+        suiteId,
+      });
+      return jsonResponse({ scenarios }, 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/lab/verdicts") {
+    const limit = parseLimit(url.searchParams.get("limit"), ctx);
+    if (limit instanceof Response) return limit;
+    const range = parseRange(url.searchParams.get("from"), url.searchParams.get("to"), ctx);
+    if (range instanceof Response) return range;
+    const layer = parseLayer(url.searchParams.get("layer"), ctx);
+    if (layer instanceof Response) return layer;
+    const verdict = parseVerdict(url.searchParams.get("verdict"), ctx);
+    if (verdict instanceof Response) return verdict;
+    try {
+      const page = queryLabVerdicts({
+        subjectId: url.searchParams.get("subjectId")?.trim() || undefined,
+        layer,
+        suiteId: url.searchParams.get("suiteId")?.trim() || undefined,
+        verdict,
+        from: range.from,
+        to: range.to,
+      }, url.searchParams.get("cursor"), limit);
+      return jsonResponse(paginatedEnvelope(page, "verdicts"), 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/lab/subjects") {
+    const limit = parseLimit(url.searchParams.get("limit"), ctx);
+    if (limit instanceof Response) return limit;
+    try {
+      const page = queryLabSubjects(
+        url.searchParams.get("kind")?.trim() || undefined,
+        url.searchParams.get("cursor"),
+        limit,
+      );
+      return jsonResponse(paginatedEnvelope(page, "subjects"), 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  const subjectMatch = url.pathname.match(/^\/api\/lab\/subjects\/([^/]+)$/);
+  if (subjectMatch) {
+    const subjectId = decodePathSegment(subjectMatch[1]!);
+    if (subjectId === null) return errorResponse("not_found", "unknown resource", 404, ctx);
+    const unsafe = rejectUnsafeId(subjectId, ctx);
+    if (unsafe) return unsafe;
+    try {
+      const subject = queryLabSubjectById(subjectId);
+      if (!subject) return errorResponse("not_found", "unknown subject", 404, ctx);
+      return jsonResponse({ subjectId, subject }, 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/lab/observations") {
+    const limit = parseLimit(url.searchParams.get("limit"), ctx);
+    if (limit instanceof Response) return limit;
+    const range = parseRange(url.searchParams.get("from"), url.searchParams.get("to"), ctx);
+    if (range instanceof Response) return range;
+    const layer = parseLayer(url.searchParams.get("layer"), ctx);
+    if (layer instanceof Response) return layer;
+    const outcome = parseOutcome(url.searchParams.get("outcome"), ctx);
+    if (outcome instanceof Response) return outcome;
+    const executionMode = parseExecutionMode(url.searchParams.get("executionMode"), ctx);
+    if (executionMode instanceof Response) return executionMode;
+    try {
+      const page = queryLabObservations({
+        subjectId: url.searchParams.get("subjectId")?.trim() || undefined,
+        layer,
+        suiteId: url.searchParams.get("suiteId")?.trim() || undefined,
+        scenarioId: url.searchParams.get("scenarioId")?.trim() || undefined,
+        outcome,
+        executionMode,
+        from: range.from,
+        to: range.to,
+      }, url.searchParams.get("cursor"), limit);
+      return jsonResponse(paginatedEnvelope(page, "observations"), 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/lab/events") {
+    const limit = parseLimit(url.searchParams.get("limit"), ctx);
+    if (limit instanceof Response) return limit;
+    const range = parseRange(url.searchParams.get("from"), url.searchParams.get("to"), ctx);
+    if (range instanceof Response) return range;
+    const eventKind = parseEventKind(url.searchParams.get("eventKind"), ctx);
+    if (eventKind instanceof Response) return eventKind;
+    const excludedRaw = url.searchParams.get("excluded");
+    let excluded: boolean | undefined;
+    if (excludedRaw === "true") excluded = true;
+    else if (excludedRaw === "false") excluded = false;
+    try {
+      const page = queryLabEvents({
+        eventKind,
+        subjectId: url.searchParams.get("subjectId")?.trim() || undefined,
+        from: range.from,
+        to: range.to,
+        excluded,
+      }, url.searchParams.get("cursor"), limit);
+      return jsonResponse(paginatedEnvelope(page, "events"), 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  const eventMatch = url.pathname.match(/^\/api\/lab\/events\/([^/]+)$/);
+  if (eventMatch) {
+    const eventId = decodePathSegment(eventMatch[1]!);
+    if (eventId === null) return errorResponse("not_found", "unknown resource", 404, ctx);
+    const unsafe = rejectUnsafeId(eventId, ctx);
+    if (unsafe) return unsafe;
+    try {
+      const event = queryLabEventById(eventId);
+      if (!event) return errorResponse("not_found", "unknown event", 404, ctx);
+      return jsonResponse({ event }, 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  if (url.pathname === "/api/lab/artifacts") {
+    const limit = parseLimit(url.searchParams.get("limit"), ctx);
+    if (limit instanceof Response) return limit;
+    const statusRaw = url.searchParams.get("status")?.trim();
+    const artifactClass = url.searchParams.get("artifactClass")?.trim() || undefined;
+    if (statusRaw && !["present", "corrupt", "purged_unavailable"].includes(statusRaw)) {
+      return errorResponse("invalid_status", "status must be present, corrupt, or purged_unavailable", 400, ctx);
+    }
+    try {
+      const page = queryLabArtifacts({
+        status: statusRaw as "present" | "corrupt" | "purged_unavailable" | undefined,
+        artifactClass: artifactClass as import("../../lab/constants").ArtifactClass | undefined,
+      }, url.searchParams.get("cursor"), limit);
+      return jsonResponse(paginatedEnvelope(page, "artifacts"), 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  const artifactMatch = url.pathname.match(/^\/api\/lab\/artifacts\/([^/]+)$/);
+  if (artifactMatch) {
+    const digest = decodePathSegment(artifactMatch[1]!);
+    if (digest === null) return errorResponse("not_found", "unknown resource", 404, ctx);
+    const unsafe = rejectUnsafeId(digest, ctx);
+    if (unsafe) return unsafe;
+    try {
+      const artifact = queryLabArtifactByDigest(digest);
+      if (!artifact) return errorResponse("not_found", "unknown artifact", 404, ctx);
+      return jsonResponse({ artifact }, 200, req, config);
+    } catch (err) {
+      const mapped = projectionErrorResponse(err, ctx);
+      if (mapped) return mapped;
+      return errorResponse("server_error", "internal lab read failure", 500, ctx);
+    }
+  }
+
+  return null;
+}

package/src/server/management/logs-usage-routes.ts

@@ -70,6 +70,7 @@ import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, filteredRequestLogCount, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
+import { userCostOverlayVersion } from "../../usage/user-cost-overlays";
 import type { PersistedUsageAttempt } from "../../usage/log";
 import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
 import { applySystemEnvToggle } from "../system-env";
@@ -193,10 +194,19 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
       const effectiveReadLimit = config.managementUsageMaxReadBytes ?? 64 * 1024 * 1024;
       const observedRevisionKey = `${usageLogRevisionKey(currentUsageLogRevision())}\0${effectiveReadLimit}`;
       const cached = getUsageSummaryCacheEntry(cacheKey);
-      if (cached && cached.revisionKey === observedRevisionKey && now < cached.expiresAt) {
+      if (cached
+        && cached.revisionKey === observedRevisionKey
+        && cached.overlayVersion === userCostOverlayVersion()
+        && now < cached.expiresAt) {
         return jsonResponse(refreshedUsageSummary(cached.summary, range, now));
       }
       if (cached) discardUsageSummaryCacheEntry(cacheKey);
+      // Capture the overlay version BEFORE reading/computing: the cache entry
+      // must be stamped with the version the summary was priced under. Reading
+      // it again at stamp time could cache an old-price summary as current,
+      // and the next request would then accept stale pricing for the whole
+      // cache lifetime.
+      const overlayVersion = userCostOverlayVersion();
       const snapshot = await readUsageSnapshotForManagement(effectiveReadLimit);
       const revisionReadAt = Date.now();
       const summary = {
@@ -206,8 +216,16 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
         entriesTruncated: snapshot.entriesTruncated,
         entriesDropped: snapshot.entriesDropped,
       };
+      if (userCostOverlayVersion() !== overlayVersion) {
+        // The overlay changed while the summary was being computed, so this
+        // summary may mix old and new prices. Serve it uncached: the next
+        // request recomputes against the settled overlay instead of caching a
+        // mixed-price entry under either version.
+        return jsonResponse(summary);
+      }
       setUsageSummaryCacheEntry(cacheKey, {
         revisionKey: `${usageLogRevisionKey(snapshot.revision)}\0${effectiveReadLimit}`,
+        overlayVersion,
         expiresAt: usageSummaryExpiresAt(snapshot.entries, range, surface, now),
         revisionReadAt,
         summary,

package/src/server/management/model-rows.ts

@@ -9,7 +9,14 @@
  * Bodies are unchanged from their previous home; only `export` was added.
  */
 import type { CatalogModel } from "../../codex/catalog";
-import { catalogModelSlug, nativeModelRows, nativeReasoningEfforts, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  catalogModelSlug,
+  nativeDefaultReasoningEffort,
+  nativeInputModalities,
+  nativeModelRows,
+  nativeReasoningEfforts,
+  uniqueCatalogModelsForPublicList,
+} from "../../codex/catalog";
 import type { ExportModel } from "../../clients/config-export";
 import { providerContextCap } from "../../providers/context-cap";
 import { isVisionReasoningEffort } from "../../reasoning-effort";
@@ -42,16 +49,21 @@ export async function listManagementModelRows(config: OcxConfig): Promise<Manage
   const disabled = new Set(config.disabledModels ?? []);
   // Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
   // from the static supported set so a disabled model stays listed and re-enableable.
-  const native: ManagementModelRow[] = nativeModelRows(config).map(row => ({
-    provider: "openai",
-    id: row.slug,
-    namespaced: row.slug,
-    disabled: row.disabled,
-    native: true,
-    // The Codex catalog may advertise `ultra`, but the image describer accepts only low..max.
-    reasoningEfforts: nativeReasoningEfforts(row.slug).filter(isVisionReasoningEffort),
-    ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
-  }));
+  const native: ManagementModelRow[] = nativeModelRows(config).map(row => {
+    const reasoningEfforts = nativeReasoningEfforts(row.slug).filter(isVisionReasoningEffort);
+    const defaultReasoningEffort = nativeDefaultReasoningEffort(row.slug);
+    return {
+      provider: "openai",
+      id: row.slug,
+      namespaced: row.slug,
+      disabled: row.disabled,
+      native: true,
+      reasoningEfforts,
+      ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
+      inputModalities: nativeInputModalities(row.slug),
+      ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
+    };
+  });
   const customModels: ManagementModelRow[] = (config.customModels ?? []).map(cm => {
     const namespaced = routedSlug(cm.provider, cm.modelId);
     return {
@@ -102,6 +114,8 @@ export function toExportModel(row: ManagementModelRow): ExportModel {
     ...(row.displayName ? { displayName: row.displayName } : {}),
     ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
     ...(row.inputModalities ? { inputModalities: row.inputModalities } : {}),
+    ...(row.reasoningEfforts ? { reasoningEfforts: row.reasoningEfforts } : {}),
+    ...(row.defaultReasoningEffort ? { defaultReasoningEffort: row.defaultReasoningEffort } : {}),
   };
 }
 

package/src/server/management/native-integration-routes.ts

@@ -18,7 +18,7 @@
  * 011 (Claude Code), 012 (Grok).
  */
 import { loadConfig, readRuntimePort, saveConfigPreservingClaudeCode } from "../../config";
-import { filterCatalogVisibleModels, nativeOpenAiContextWindow, visibleNativeSlugs } from "../../codex/catalog";
+import { desktopVisibleNativeSlugs, filterCatalogVisibleModels, nativeOpenAiContextWindow, visibleNativeSlugs } from "../../codex/catalog";
 import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
 import { injectGrokConfig, stripGrokConfig, type GrokInjectModel } from "../../grok/inject";
 import { inspectGrokConfig } from "../../grok/inspect";
@@ -656,7 +656,7 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
       const runtime = (ctx.deps.readRuntimePort ?? readRuntimePort)(process.pid);
       const result = (ctx.deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
         runtime?.port ?? latest.port,
-        [...visibleNativeSlugs(latest)],
+        [...desktopVisibleNativeSlugs(latest)],
         routed,
         latest.apiKeys?.[0]?.key,
         "static",
@@ -696,7 +696,7 @@ export async function handleNativeIntegrationRoutes(ctx: ManagementContext): Pro
       rethrowManagementBodyTooLarge(error);
       return jsonResponse({ error: "invalid JSON body" }, 400);
     }
-    if (typeof body.enabled !== "boolean") {
+    if (!body || typeof body !== "object" || Array.isArray(body) || typeof body.enabled !== "boolean") {
       return jsonResponse({ error: "enabled must be a boolean" }, 400);
     }
 

package/src/server/management/provider-routes.ts

@@ -340,6 +340,11 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     // let the (possibly new) apiKey join the pool as the active entry.
     const existingPool = config.providers[name]?.apiKeyPool;
     if (existingPool && !prov.apiKeyPool) prov.apiKeyPool = existingPool;
+    // The same rule applies to user-configured price overlays: the dashboard's
+    // add/edit form does not send modelCosts, so an overwrite must not silently
+    // erase hand-edited per-model prices from Logs/Usage estimates.
+    const existingCosts = config.providers[name]?.modelCosts;
+    if (existingCosts && !prov.modelCosts) prov.modelCosts = existingCosts;
     config.providers[name] = stripRegistryOnlyStaticHeaders(name, prov);
     if (body.setDefault === true) config.defaultProvider = name;
     save(config);

package/src/server/management/shared.ts

@@ -82,7 +82,11 @@ export type TokPerSecondResult =
   | { kind: "value"; value: number; estimated: boolean }
   | { kind: "unavailable"; reason: MetricUnavailableReason };
 
-export type CostEstimateReason = "usage_estimated" | "cache_detail_missing" | "expected_price_overlay";
+export type CostEstimateReason =
+  | "usage_estimated"
+  | "cache_detail_missing"
+  | "expected_price_overlay"
+  | "provider_cost_overlay";
 
 export type CostResult =
   | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
@@ -123,6 +127,7 @@ export function unavailableCostReason(entry: MetricSource): MetricUnavailableRea
   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
@@ -136,6 +141,8 @@ export function costResult(entry: MetricSource): CostResult {
       && 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,
   ].filter((reason): reason is CostEstimateReason => reason !== undefined);
   return { kind: "value", estimate, estimateReasons };
 }

package/src/server/management/usage-summary-cache.ts

@@ -10,6 +10,8 @@ export type CachedUsageSummary = UsageSummary & {
 
 interface UsageSummaryCacheEntry {
   revisionKey: string;
+  /** userCostOverlayVersion() when the summary was computed; overlay edits invalidate the entry. */
+  overlayVersion: number;
   expiresAt: number;
   summary: CachedUsageSummary;
   revisionReadAt: number;