@yansigit/opencodex 2.31.0

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

@@ -0,0 +1,94 @@
+import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../../lib/app-owned-memory";
+import type { UsageSummary } from "../../usage/summary";
+
+export type CachedUsageSummary = UsageSummary & {
+  historyTruncated: boolean;
+  truncatedPrefixBytes: number;
+  entriesTruncated: boolean;
+  entriesDropped: number;
+};
+
+export interface UsageSummaryCacheEntry {
+  revisionKey: string;
+  /** path/dev/ino/birthtime only; appends keep this stable. */
+  identityKey: string;
+  maxReadBytes: number;
+  /** userCostOverlayVersion() when the summary was computed; overlay edits invalidate the entry. */
+  overlayVersion: number;
+  expiresAt: number;
+  /** Generation freshness: ignore size/mtime until this instant. */
+  freshUntil: number;
+  lastSeenSize: number;
+  summary: CachedUsageSummary;
+  revisionReadAt: number;
+  sizeBytes: number;
+}
+
+const usageSummaryCache = new Map<string, UsageSummaryCacheEntry>();
+let usageSummaryCacheBytes = 0;
+let oldestUsageSummaryKey: string | undefined;
+let oldestUsageSummaryAt: number | null = null;
+
+function recomputeOldestUsageSummary(): void {
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+  for (const [key, entry] of usageSummaryCache) {
+    const readAt = entry.revisionReadAt;
+    if (oldestUsageSummaryAt !== null && readAt >= oldestUsageSummaryAt) continue;
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = readAt;
+  }
+}
+
+function deleteUsageSummaryCacheEntry(key: string): number {
+  const entry = usageSummaryCache.get(key);
+  if (!entry) return 0;
+  usageSummaryCache.delete(key);
+  usageSummaryCacheBytes = Math.max(0, usageSummaryCacheBytes - entry.sizeBytes);
+  if (oldestUsageSummaryKey === key) recomputeOldestUsageSummary();
+  return entry.sizeBytes;
+}
+
+export function getUsageSummaryCacheEntry(key: string): UsageSummaryCacheEntry | undefined {
+  return usageSummaryCache.get(key);
+}
+
+export function discardUsageSummaryCacheEntry(key: string): number {
+  return deleteUsageSummaryCacheEntry(key);
+}
+
+export function setUsageSummaryCacheEntry(
+  key: string,
+  entry: Omit<UsageSummaryCacheEntry, "sizeBytes">,
+): void {
+  deleteUsageSummaryCacheEntry(key);
+  const sizeBytes = Buffer.byteLength(JSON.stringify({ key, ...entry }), "utf8");
+  usageSummaryCache.set(key, { ...entry, sizeBytes });
+  usageSummaryCacheBytes += sizeBytes;
+  if (oldestUsageSummaryAt === null || entry.revisionReadAt < oldestUsageSummaryAt) {
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = entry.revisionReadAt;
+  }
+  enforceAppOwnedMemoryBudget();
+}
+
+export function usageSummaryRetainedStoreSnapshot(): RetainedStoreSnapshot {
+  return {
+    count: usageSummaryCache.size,
+    bytes: usageSummaryCacheBytes,
+    evictableBytes: usageSummaryCacheBytes,
+    pinnedBytes: 0,
+    oldestAt: oldestUsageSummaryAt,
+  };
+}
+
+export function evictOldestUsageSummaryForBudget(): number {
+  return oldestUsageSummaryKey === undefined ? 0 : deleteUsageSummaryCacheEntry(oldestUsageSummaryKey);
+}
+
+export function resetUsageSummaryCacheForTests(): void {
+  usageSummaryCache.clear();
+  usageSummaryCacheBytes = 0;
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+}

package/src/server/management/vision-sidecar-options.ts

@@ -0,0 +1,167 @@
+/**
+ * The one place that decides which models the management API offers as vision
+ * describers, and which it refuses to persist.
+ *
+ * Two routes write a vision sidecar model — `PUT /api/sidecar-settings` and the
+ * `visionSidecar` override in `PUT /api/claude-code`. They share this module so
+ * the policy cannot drift: a gate on one route and a stale copy on the other is
+ * the same as no gate at all.
+ */
+import type { OcxConfig } from "../../types";
+import { findAnthropicVisionProvider, type AnthropicVisionProvider } from "../../vision";
+import { VISION_BACKENDS } from "../../vision/backends";
+import {
+  modelAcceptsImageInput,
+  visionEligibleModelOptions,
+  type VisionCandidateModel,
+  type VisionModelOption,
+  type VisionSidecarBackend,
+} from "../../vision/eligibility";
+import { pickerVisibleSidecarCandidates } from "../../sidecar/candidates";
+import { resolveSidecarAuth } from "../../sidecar/auth";
+
+/**
+ * Backends whose executor could actually run (#2188 roadmap 170): openai
+ * forward, anthropic OAuth, xai OAuth, Antigravity OAuth — resolved by the
+ * VISION_BACKENDS descriptor table so this module and the options path cannot
+ * drift on what "active" means.
+ *
+ * `anthropicSidecar` is REQUIRED rather than defaulted. `findAnthropicVisionProvider`
+ * reads the OAuth account store from disk, and a default argument made every helper
+ * in this chain re-resolve it whenever a caller passed an explicit `undefined` —
+ * which is exactly the no-executor case. Passing it in keeps one read per request.
+ * The descriptor table re-derives the anthropic flag from the shared auth
+ * module; asserting the caller's resolution stays consistent with it is the
+ * job of the shared module, not this file.
+ */
+export function enabledVisionBackends(
+  config: OcxConfig,
+  anthropicSidecar: AnthropicVisionProvider | undefined,
+): VisionSidecarBackend[] {
+  const auth = resolveSidecarAuth(config);
+  // Preserve the caller's resolution for the anthropic side: the descriptor
+  // reads the shared auth module, but a caller that already resolved "no
+  // executor" must not see anthropic options it cannot dispatch. The filter
+  // applies to the ACTIVE set only — the fresh-install fallback below stays
+  // both universal sides, exactly the pre-widening behavior (test 6 pins it).
+  const active = VISION_BACKENDS
+    .filter(descriptor => descriptor.isActive(auth, config))
+    .map(descriptor => descriptor.backend)
+    .filter(backend => backend !== "anthropic" || anthropicSidecar !== undefined);
+  // "routed" is active by construction, so the fresh-install fallback keys on
+  // the UNIVERSAL sides: when neither resolves, both are offered so the picker
+  // stays populated (permissive-unknown rule; test 6 pins it).
+  if (!active.includes("openai") && !active.includes("anthropic")) {
+    return ["openai", "anthropic", ...active];
+  }
+  return active;
+}
+
+/**
+ * Visible catalog rows in the shape the eligibility predicate consumes.
+ * Sourced from the unified picker set (#2188): picker-visible rows ∪ auth
+ * slots, UNFILTERED. Rule 2 (− provably text-only) belongs to the OPTIONS
+ * path only (visionEligibleModelOptions already applies it). The PUT gate
+ * consumes this list as EVIDENCE: a picker row proving an id text-only is
+ * exactly what visionDescriberIsProvablyBlind needs to reject that id, so
+ * pre-filtering here would deaden the gate (review F1: reject → allow flip).
+ */
+export async function visionCandidateRows(config: OcxConfig): Promise<VisionCandidateModel[]> {
+  const auth = resolveSidecarAuth(config);
+  const all = await pickerVisibleSidecarCandidates(config, auth);
+  return all.map(candidate => ({
+    provider: candidate.provider,
+    id: candidate.id,
+    ...(candidate.inputModalities ? { inputModalities: candidate.inputModalities } : {}),
+    ...(candidate.native ? { native: true } : {}),
+  }));
+}
+
+export function visionModelOptionsFrom(
+  config: OcxConfig,
+  candidates: readonly VisionCandidateModel[],
+  anthropicSidecar: AnthropicVisionProvider | undefined,
+): VisionModelOption[] {
+  return visionEligibleModelOptions(
+    config,
+    candidates,
+    enabledVisionBackends(config, anthropicSidecar),
+    anthropicSidecar?.providerName,
+  );
+}
+
+/** Convenience for read paths that have no candidate list in hand yet. */
+export async function visionModelOptionsFor(
+  config: OcxConfig,
+  anthropicSidecar: AnthropicVisionProvider | undefined,
+): Promise<VisionModelOption[]> {
+  return visionModelOptionsFrom(config, await visionCandidateRows(config), anthropicSidecar);
+}
+
+/**
+ * Can we PROVE the requested describer is blind?
+ *
+ * Only a positive `false` rejects. An id no source knows stays allowed, because
+ * the runtime never required catalog membership and an operator may be ahead of
+ * our tables.
+ *
+ * When no catalog row matches, the caller's `backend` is only a HINT, never the
+ * authority. Trusting it let a client launder a known-blind OpenAI model past the
+ * gate by claiming `backend: "anthropic"`, since the id is absent from the
+ * Anthropic table and absence reads as "unknown".
+ *
+ * A NAMESPACED id ("provider/model", the routed-backend option shape) names
+ * its provider outright, so that provider's config row and metadata family
+ * are probed directly. A BARE id probes ALL configured provider families and
+ * any positive text-only verdict wins (roadmap 170: a bare `grok-4` is
+ * provably text-only in the xai vendor table and must not slip through a
+ * two-family probe). That is safe precisely because the vendor tables share
+ * no bare model id (collision scan in roadmap 160: openai 48, anthropic 26,
+ * xai 32, google 43, zero overlaps), so they can never disagree about one.
+ */
+export function visionDescriberIsProvablyBlind(
+  config: OcxConfig,
+  requested: string,
+  candidates: readonly VisionCandidateModel[],
+  backendHint: VisionSidecarBackend | undefined,
+): boolean {
+  // Catalog rows can carry operator-authored modalities. A positive claim from one
+  // must not hide another row or canonical metadata that proves this id is blind.
+  if (candidates.some(candidate => candidate.id === requested
+    && modelAcceptsImageInput(config, candidate) === false)) return true;
+
+  // Namespaced routed id: the provider is named, probe it directly (config
+  // row enrichment + its metadata family both flow through the predicate).
+  const sep = requested.indexOf("/");
+  if (sep > 0) {
+    const provider = requested.slice(0, sep);
+    const id = requested.slice(sep + 1);
+    if (modelAcceptsImageInput(config, { provider, id }) === false) return true;
+    // A namespaced candidate row (value shape) may also carry the proof.
+    return candidates.some(candidate => candidate.provider === provider && candidate.id === id
+      && modelAcceptsImageInput(config, candidate) === false);
+  }
+
+  // Bare id: probe the base vendor families plus every configured provider —
+  // a positive text-only verdict from any source wins.
+  const families = new Set(["openai", "anthropic", "xai", "google-antigravity", ...Object.keys(config.providers ?? {})]);
+  const ordered = backendHint === "anthropic"
+    ? ["anthropic", ...[...families].filter(family => family !== "anthropic")]
+    : ["openai", ...[...families].filter(family => family !== "openai")];
+  return ordered.some(provider => modelAcceptsImageInput(config, { provider, id: requested }) === false);
+}
+
+/** The 400 body both routes return, so the two errors cannot diverge either. */
+export function visionDescriberRejection(
+  field: "vision.model" | "visionSidecar.model",
+  requested: string,
+  config: OcxConfig,
+  candidates: readonly VisionCandidateModel[],
+): { error: string; allowed: string[] } {
+  return {
+    error: `${field} "${requested}" cannot describe images: it has no image input support, or it is a model the vision sidecar describes FOR.`,
+    // The rejection path is not hot, so it resolves the executor itself rather than
+    // making every 400 caller thread one through.
+    allowed: visionModelOptionsFrom(config, candidates, findAnthropicVisionProvider(config)).map(option => option.value),
+  };
+}

package/src/server/management/web-search-sidecar-options.ts

@@ -0,0 +1,120 @@
+/**
+ * The one place that decides which models the management API offers as the
+ * web-search sidecar, and which it refuses to persist (#2188).
+ *
+ * Two routes write `webSearchSidecar.model` — `PUT /api/sidecar-settings`
+ * and the `webSearchSidecar` override in `PUT /api/claude-code`. They share
+ * this module for the same reason the vision routes share
+ * vision-sidecar-options.ts: a gate on one route and a stale copy on the
+ * other is the same as no gate at all. `ocx config set` raw JSON writes
+ * bypass management gates by design (operator escape hatch, same as vision).
+ *
+ * Unlike vision's provably-blind gate (reject only on positive proof), the
+ * web-search gate is MEMBERSHIP: the executor set is closed and known, so an
+ * id outside (candidates ∪ auth slots) can never run and is refused.
+ */
+import type { OcxConfig } from "../../types";
+import { AUTH_SLOT_MODELS, resolveSidecarAuth } from "../../sidecar/auth";
+import { pickerVisibleSidecarCandidates, type SidecarCandidate } from "../../sidecar/candidates";
+import { WEB_SEARCH_BACKENDS, webSearchSidecarCandidates } from "../../web-search/backends";
+import type { WebSearchBackendId } from "../../web-search/index";
+
+// The full configured union. Rows only ever materialize for backends whose
+// executor admits the candidate, so inert arms (gemini/exa without config)
+// simply never produce rows.
+export type WebSearchBackend = WebSearchBackendId;
+
+export interface WebSearchCandidateRow extends SidecarCandidate {
+  /** Executor backend that admitted this exact candidate row. */
+  backend: WebSearchBackend;
+}
+
+export interface WebSearchModelOption {
+  value: string;
+  label: string;
+  /** Exact runnable pair represented by this picker row. */
+  backend: WebSearchBackend;
+  model: string;
+  /** True when the row is an auth-slot entitlement rather than a picker row. */
+  authSlot?: boolean;
+}
+
+/** The candidate rows the web-search executors can actually run right now. */
+export async function webSearchCandidateRows(config: OcxConfig): Promise<WebSearchCandidateRow[]> {
+  const auth = resolveSidecarAuth(config);
+  const all = await pickerVisibleSidecarCandidates(config, auth);
+  return webSearchSidecarCandidates(config, auth, all).flatMap(candidate => {
+   const descriptor = WEB_SEARCH_BACKENDS.find(entry =>
+      entry.isActive(auth, config) && entry.eligibleModel(candidate, auth));
+    return descriptor ? [{ ...candidate, backend: descriptor.backend }] : [];
+  });
+}
+
+/**
+ * The GUI/CLI option list. The persisted model is display-grandfathered so an
+ * operator can SEE a now-illegal setting in the picker (parity with the vision
+ * GET); new writes of such an id are still rejected by the gate below.
+ */
+export function webSearchModelOptionsFrom(
+  config: Pick<OcxConfig, "webSearchSidecar">,
+  candidates: readonly WebSearchCandidateRow[],
+): WebSearchModelOption[] {
+  const byValue = new Map<string, WebSearchModelOption>();
+  for (const candidate of candidates) {
+    if (byValue.has(candidate.id)) continue;
+    byValue.set(candidate.id, {
+      value: candidate.id,
+      label: candidate.id,
+      backend: candidate.backend,
+      model: candidate.id,
+      ...(candidate.authSlot ? { authSlot: true } : {}),
+    });
+  }
+  const persisted = config.webSearchSidecar?.model;
+  if (persisted && !byValue.has(persisted)) {
+    byValue.set(persisted, {
+      value: persisted,
+      label: persisted,
+      backend: config.webSearchSidecar?.backend ?? "openai",
+      model: persisted,
+    });
+  }
+  return [...byValue.values()].sort((a, b) => a.value.localeCompare(b.value));
+}
+
+/**
+ * Membership gate: reject when the id is neither a runnable candidate nor an
+ * auth-slot model. Auth slots pass even when the matching login is currently
+ * absent — the slot is a legal setting whose executor simply is not live yet,
+ * and refusing it would make settings order-dependent on login state.
+ */
+export function webSearchModelIsRejected(
+  backend: WebSearchBackend,
+  requested: string,
+  candidates: readonly WebSearchCandidateRow[],
+): boolean {
+  if (requested === AUTH_SLOT_MODELS.codex) return backend !== "openai";
+  if (requested === AUTH_SLOT_MODELS.anthropic) return backend !== "anthropic";
+  return !candidates.some(candidate => candidate.backend === backend && candidate.id === requested);
+}
+
+/** Uniform 400 payload naming the filter, mirroring visionDescriberRejection's shape. */
+export function webSearchModelRejection(
+  field: string,
+  backend: WebSearchBackend,
+  requested: string,
+  candidates: readonly WebSearchCandidateRow[],
+): { error: string; allowedModels: string[] } {
+  const allowed = new Set(candidates
+    .filter(candidate => candidate.backend === backend)
+    .map(candidate => candidate.id));
+  // Preserve the response contract: allowedModels lists both always-configurable
+  // auth-slot ids even though the pair gate below binds each to its own backend.
+  allowed.add(AUTH_SLOT_MODELS.codex);
+  allowed.add(AUTH_SLOT_MODELS.anthropic);
+  return {
+    error: `${field}: backend/model pair "${backend}/${requested}" is not a web-search sidecar candidate — ` +
+      "the model must be picker-visible and runnable by that executor-backed backend (or its auth-slot model)",
+    allowedModels: [...allowed].sort(),
+  };
+}