@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/usage/telemetry-contract.ts

@@ -0,0 +1,237 @@
+/**
+ * The telemetry vocabulary both the proxy and the dashboard read.
+ *
+ * This module has NO imports, and that is its entire job. The dashboard is a separate TypeScript
+ * project with `erasableSyntaxOnly`, and a type-only import still pulls the imported file's whole
+ * import graph into that project. Importing these names from `./log` therefore dragged
+ * `node:fs`, `node:crypto` and the config barrel into the browser build, where a parameter
+ * property in `src/config/atomic-write.ts` fails to compile. The names below are the ones a
+ * browser legitimately needs, so they live where a browser can reach them.
+ *
+ * Anything added here must stay free of imports. A contract that acquires a dependency stops
+ * being a contract.
+ */
+
+/**
+ * Recovery kinds recorded per attempt in the usage log; the dashboard renders localized labels
+ * for these wire values.
+ *
+ * The roster is the single statement of this vocabulary and the type is derived from it. It was
+ * written twice once -- as a union and as the read-back whitelist -- and the two are not
+ * interchangeable: a member added only to the union compiles, is written to disk, and is dropped
+ * on the next read, so the row loses the field that says why it recovered. One declaration cannot
+ * drift from itself, and the dashboard now reads this one rather than keeping a third copy.
+ */
+export const ATTEMPT_RECOVERY_KIND_ROSTER = Object.freeze([
+  "transient-5xx",
+  "connection-reset",
+  "oauth-401",
+  "key-401",
+  "key-429",
+  "rate-limit-429",
+  "anthropic-oauth-429",
+  "oauth-account-429",
+  "image-413",
+  "console-go-upload-retry",
+  "opaque-blob-rejection",
+  "empty-completion",
+  "reasoning-effort-downgrade",
+] as const);
+
+export type AttemptRecoveryKind = typeof ATTEMPT_RECOVERY_KIND_ROSTER[number];
+
+/**
+ * Why a recovery this request was otherwise willing to make did not happen.
+ *
+ * Recorded separately from `recoveryKinds` and from `sendCount` because the question it answers
+ * is different from either. A log showing one physical send and no recovery kind used to be
+ * ambiguous: nothing was eligible, or something was and the send budget withheld it. Those need
+ * opposite follow-ups and the second was invisible (#5044).
+ *
+ * `sendCount` deliberately does not move for these. A refused attempt is not a physical send, and
+ * inflating the count to signal the refusal would corrupt the one number that means "requests this
+ * proxy actually made".
+ */
+export const ATTEMPT_RECOVERY_WITHHELD_ROSTER = Object.freeze([
+  "retry-send-budget",
+  "rotation-send-budget",
+] as const);
+
+export type AttemptRecoveryWithheld = typeof ATTEMPT_RECOVERY_WITHHELD_ROSTER[number];
+
+/**
+ * How far a failed exchange got, ordered by how much the DOWNSTREAM CLIENT observed.
+ *
+ * The order is by client observation rather than by upstream progress, because the question it
+ * answers is whether resending can duplicate something the caller already saw. An upstream that
+ * completed a turn we never relayed has committed nothing downstream; an upstream that emitted
+ * one token has.
+ *
+ * The roster lives here rather than beside the resend tables for the reason stated at the top of
+ * this file: the dashboard renders a label per member, and reaching the table module for the
+ * names would drag its import graph into the browser project. `src/lib/request-failure-model.ts`
+ * re-exports it, so every existing importer keeps its path and there is still exactly one
+ * declaration.
+ */
+export const REQUEST_FAILURE_STAGES = Object.freeze([
+  /** No response head exists. Whether the origin began the turn is not known from the stage alone. */
+  "pre-header",
+  /** A status line and headers exist, and no protocol body event has been parsed yet. */
+  "headers-only",
+  /** The protocol body began with control events only -- `response.created`, quota frames. */
+  "protocol-prelude",
+  /** At least one output-bearing event reached the caller. */
+  "semantic-output",
+  /** A tool call or other externally visible effect was emitted. */
+  "side-effect",
+  /** A terminal event settled the turn after its answer reached the caller. */
+  "terminal",
+] as const);
+
+export type RequestFailureStage = typeof REQUEST_FAILURE_STAGES[number];
+
+/**
+ * Why the request failed, as one closed dictionary for every layer.
+ *
+ * Bounded on purpose: these are wire values a maintainer reads and a metric labels by, never a
+ * credential, an account identifier, an upstream body or prompt content. That bound is what lets
+ * the value be a Prometheus label and a grouping key without a masking pass -- a closed roster
+ * has nothing to mask.
+ */
+export const REQUEST_FAILURE_CAUSES = Object.freeze([
+  /** The bytes provably never reached the origin: connect refused, DNS failure, TLS handshake. */
+  "transport-unsent",
+  /** The bytes left and the connection died before a head. The origin may be running the turn. */
+  "transport-ambiguous",
+  /** The origin answered that it would not start the turn now: 503, overloaded, backpressure. */
+  "upstream-declined",
+  /** A 429 rate limit. Capacity is momentarily gone; waiting is the remedy. */
+  "rate-limit",
+  /** Plan or credit quota is gone. Waiting out a retry window does not help; the account must change. */
+  "quota-exhausted",
+  /** Credentials were rejected: 401, 403 on identity. */
+  "credential-rejected",
+  /** The origin evaluated the content and refused it. Identical bytes get the identical refusal. */
+  "policy-refusal",
+  /**
+   * The origin rejected a request PARAMETER rather than the content: an unsupported reasoning
+   * effort, an unknown field. Distinct from `policy-refusal` because the remedy is opposite --
+   * the same content succeeds once the parameter is adjusted.
+   */
+  "parameter-rejected",
+  /** Opaque replay state was rejected as unverifiable. Only a request without it can succeed. */
+  "ciphertext-refusal",
+  /**
+   * The payload exceeded a size the origin accepts. A smaller rebuild of the same turn can
+   * succeed, which is why this is not the same answer as `payload-rejected`.
+   */
+  "payload-too-large",
+  /** The payload was rejected on its merits: unsupported media, malformed part. No repair helps. */
+  "payload-rejected",
+  /**
+   * The origin returned a server-side fault. Whether it had already begun the turn is not
+   * knowable from the status, so this is the honest classification for the mixed 5xx set the
+   * transient layer retries: 503 really did decline, 500 may not have.
+   */
+  "upstream-fault",
+  /** The turn settled carrying no usable output. */
+  "empty-output",
+  /** The caller went away. */
+  "client-cancelled",
+  /** This proxy refused before dispatch: send budget, route policy, replay refusal. */
+  "local-refusal",
+] as const);
+
+export type RequestFailureCause = typeof REQUEST_FAILURE_CAUSES[number];
+
+/**
+ * Whether this proxy may send the request again. Derived at READ time from the stage and the
+ * cause and never persisted, so a stored row cannot carry a verdict that the current table
+ * would no longer reach.
+ *
+ * Every refusal names WHY it refused, because the three reasons need different operator
+ * responses and used to arrive as one undifferentiated "no retry".
+ */
+export const RESEND_PERMISSIONS = Object.freeze([
+  /** The same request may be sent again. */
+  "permitted",
+  /** Only a modified request may be sent: rotated credential, stripped ciphertext. */
+  "permitted-after-repair",
+  /** Upstream execution state is unknown. No AUTOMATIC resend. */
+  "refused-ambiguous",
+  /** The caller already observed output or an externally visible effect. */
+  "refused-committed",
+  /** Identical bytes would get the identical answer. */
+  "refused-futile",
+] as const);
+
+export type ResendPermission = typeof RESEND_PERMISSIONS[number];
+
+/**
+ * Where a terminal or failure was observed on the wire.
+ *
+ * Declared here because three modules read it as a closed set -- the durable row's validator,
+ * the failure attribution and the failure fingerprint -- and a fourth restatement in a test is
+ * how a member added later leaves an "exhaustive" cross product green without exercising it.
+ */
+export const REQUEST_TRANSPORT_PHASES = Object.freeze([
+  "pre_headers",
+  "mid_stream",
+  "terminal_sse",
+] as const);
+
+export type RequestTransportPhase = typeof REQUEST_TRANSPORT_PHASES[number];
+
+/**
+ * What an attempt actually delivered, as five bounded counts (#3983).
+ *
+ * #3983 wanted these signals and emitted one debug line per event to get them. That is a second
+ * durable record: `emitDebugLine` writes the in-process ring AND stderr, and stderr is redirected
+ * to the service log under both launchd and systemd, so an installed service ends up with a
+ * per-event history beside the ledger, carrying its own retention, sequencing and identity. It
+ * also fingerprinted each payload under a process-global random key, which makes every repeated
+ * prompt fragment, tool name and error message correlatable for the process lifetime.
+ *
+ * Counts answer the same questions -- a missing terminal, adapter-to-client loss, empty output,
+ * partial output size -- and cannot carry content at all. They ride the attempt, so they inherit
+ * the ledger's normalization, masking and retention rather than acquiring their own.
+ *
+ * Counted where the event is DELIVERED, not where it is read. An adapter event the client never
+ * received is exactly the discrepancy worth seeing, and counting both ends at the reader would
+ * make the two numbers equal by construction.
+ */
+export interface AttemptDeliverySummary {
+  /** Events this attempt's adapter produced. */
+  adapterEvents: number;
+  /** Frames that reached the client transport, after a successful enqueue. */
+  relayedEvents: number;
+  /** UTF-8 bytes of output-bearing delta actually relayed. Never the content itself. */
+  semanticBytes: number;
+  /** Externally visible effects relayed: a tool call or a search call starting. */
+  sideEffectEvents: number;
+  /** Terminal frames relayed. Zero on a delivered stream is the missing-terminal signal. */
+  terminalEvents: number;
+}
+
+/**
+ * What one logical request spent upstream, decomposed by how much of it is explained.
+ *
+ * The counting half of the durable spend record, without the routing detail that sits beside it.
+ * Every surface that reports a send total reads these three numbers and none of them recomputes a
+ * total of its own -- a recomputed total is how the exporter and the dashboard ended up reporting
+ * different send counts for the same request.
+ */
+export interface RequestSpendTotals {
+  /** Physical upstream sends summed across every attempt, combo children included. */
+  sends: number;
+  /** Sends whose attempt reached a terminal status, so the spend has a known outcome. */
+  settled: number;
+  /**
+   * Sends charged with no terminal outcome behind them: an attempt abandoned mid-flight, or a
+   * budget charge no attempt row ever accounted for. Never folded into `settled` -- an unexplained
+   * send is the exact quantity this record exists to make visible.
+   */
+  unresolved: number;
+  /** Model sends the request execution budget charged. Absent when no budget was attached. */
+  reserved?: number;
+}

package/src/usage/timeline.ts

@@ -0,0 +1,236 @@
+import { cacheTokensFromUsage, usageAttributions } from "./summary";
+import type { PersistedUsageEntry } from "./log";
+import { usageDisplayTotalTokens } from "./totals";
+
+export type TimelineMetric = "total" | "input" | "output" | "cached";
+export type TimelineAggregation = "sum" | "average" | "max";
+export type TimelineGrouping = "model" | "modelAccount";
+export const TIMELINE_HOURS = [6, 24, 72, 168] as const;
+
+export interface TimelineQuery {
+  hours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+  now: number;
+}
+
+export interface TimelineSeries {
+  id: string;
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  total: number;
+  points: number[];
+}
+
+export interface UsageTimeline {
+  appliedFilters: { models: string[] | null; hiddenProviders: string[] };
+  start: number;
+  end: number;
+  bucketSeconds: number;
+  buckets: number;
+  metric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  grouping: TimelineGrouping;
+  series: TimelineSeries[];
+  availableModels: string[];
+  missingMeasurements: number;
+  truncated: boolean;
+}
+
+const METRICS: readonly TimelineMetric[] = ["total", "input", "output", "cached"];
+const AGGREGATIONS: readonly TimelineAggregation[] = ["sum", "average", "max"];
+const GROUPINGS: readonly TimelineGrouping[] = ["model", "modelAccount"];
+
+function enumValue<T extends string>(value: string | null, values: readonly T[], fallback: T): T | { error: string } {
+  if (value === null || value === "") return fallback;
+  return values.includes(value as T) ? value as T : { error: `invalid value for parameter: ${value}` };
+}
+
+export function isTimelineModelId(value: unknown): value is string {
+  return typeof value === "string" && /^[^/\s]+\/\S+$/.test(value);
+}
+
+function parseModels(raw: string | null): string[] | null | { error: string } {
+  if (raw === null || raw.trim() === "") return null;
+  const models = raw.split(",").map(model => model.trim());
+  if (models.length > 100) return { error: "models must contain at most 100 identifiers" };
+  if (models.some(model => !isTimelineModelId(model))) {
+    return { error: "models must contain provider/model identifiers" };
+  }
+  return [...new Set(models)];
+}
+
+export function parseTimelineQuery(params: URLSearchParams, now: number): TimelineQuery | { error: string } {
+  const rawHours = params.get("hours") ?? "24";
+  const hoursNumber = Number(rawHours);
+  if (!TIMELINE_HOURS.includes(hoursNumber as typeof TIMELINE_HOURS[number])) {
+    return { error: "hours must be one of 6, 24, 72, 168" };
+  }
+  const bucketMinutes = Number(params.get("bucketMinutes") ?? "60");
+  if (!Number.isInteger(bucketMinutes) || bucketMinutes < 1 || bucketMinutes > 1440) {
+    return { error: "bucketMinutes must be an integer from 1 through 1440" };
+  }
+  const buckets = Math.ceil(hoursNumber * 60 / bucketMinutes);
+  if (buckets > 2000) return { error: "timeline bucket count must not exceed 2000" };
+  const metric = enumValue(params.get("metric"), METRICS, "total");
+  if (typeof metric !== "string") return metric;
+  const aggregation = enumValue(params.get("aggregation"), AGGREGATIONS, "sum");
+  if (typeof aggregation !== "string") return aggregation;
+  const grouping = enumValue(params.get("grouping"), GROUPINGS, "model");
+  if (typeof grouping !== "string") return grouping;
+  const models = parseModels(params.get("models"));
+  if (typeof models === "object" && models !== null && "error" in models) return models;
+  const hiddenProviders = params.getAll("hiddenProvider");
+  if (hiddenProviders.length > 100 || hiddenProviders.some(value => !value || /\s/.test(value))) {
+    return { error: "hiddenProvider must contain at most 100 nonblank provider names" };
+  }
+  if (!Number.isFinite(now)) return { error: "now must be finite" };
+  return {
+    hours: hoursNumber as TimelineQuery["hours"],
+    bucketMinutes,
+    metric,
+    aggregation,
+    grouping,
+    models: models as string[] | null,
+    hiddenProviders: [...new Set(hiddenProviders)].sort(),
+    now,
+  };
+}
+
+interface SeriesState {
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  points: number[];
+  requests: Map<number, Map<string, number>>;
+}
+
+function metricValue(metric: TimelineMetric, attribution: ReturnType<typeof usageAttributions>[number]): number | undefined {
+  if (metric === "total") return usageDisplayTotalTokens(attribution.usage, attribution.totalTokens);
+  if (metric === "input") return attribution.usage?.inputTokens;
+  if (metric === "output") return attribution.usage?.outputTokens;
+  return cacheTokensFromUsage(attribution.usage).read;
+}
+
+export function createTimelineAccumulator(query: TimelineQuery): { add(entry: PersistedUsageEntry): void; finish(): UsageTimeline } {
+  const bucketSeconds = query.bucketMinutes * 60;
+  const buckets = Math.ceil(query.hours * 60 / query.bucketMinutes);
+  const end = (Math.floor(query.now / 1000 / bucketSeconds) + 1) * bucketSeconds;
+  const start = end - buckets * bucketSeconds;
+  const startMs = start * 1000;
+  const endMs = end * 1000;
+  const series = new Map<string, SeriesState>();
+  const availableModels = new Set<string>();
+  const hiddenProviders = new Set(query.hiddenProviders);
+  let missingMeasurements = 0;
+
+  function add(entry: PersistedUsageEntry): void {
+    if (entry.timestamp < startMs || entry.timestamp >= endMs) return;
+    const bucket = Math.floor((entry.timestamp - startMs) / (bucketSeconds * 1000));
+    if (bucket < 0 || bucket >= buckets) return;
+    for (const attribution of usageAttributions(entry)) {
+      if (hiddenProviders.has(attribution.provider)) continue;
+      const modelId = `${attribution.provider}/${attribution.model}`;
+      availableModels.add(modelId);
+      if (query.models && !query.models.includes(modelId)) continue;
+      const id = query.grouping === "model"
+        ? modelId
+        : `${modelId} · ${attribution.accountLogLabel ?? "unknown"}`;
+      let state = series.get(id);
+      if (!state) {
+        state = {
+          provider: attribution.provider,
+          model: attribution.model,
+          ...(query.grouping === "modelAccount" ? { accountLogLabel: attribution.accountLogLabel ?? "unknown" } : {}),
+          points: Array<number>(buckets).fill(0),
+          requests: new Map(),
+        };
+        series.set(id, state);
+      }
+      const value = metricValue(query.metric, attribution);
+      if (value === undefined) {
+        missingMeasurements += 1;
+        continue;
+      }
+      if (query.aggregation === "sum") {
+        state.points[bucket] = (state.points[bucket] ?? 0) + value;
+      } else {
+        let requests = state.requests.get(bucket);
+        if (!requests) {
+          requests = new Map();
+          state.requests.set(bucket, requests);
+        }
+        requests.set(attribution.requestId, (requests.get(attribution.requestId) ?? 0) + value);
+      }
+    }
+  }
+
+  function finish(): UsageTimeline {
+    const rows = [...series].map(([id, state]): { row: TimelineSeries; state: SeriesState } => {
+      if (query.aggregation !== "sum") {
+        for (const [bucket, requests] of state.requests) {
+          const values = [...requests.values()];
+          state.points[bucket] = query.aggregation === "max"
+            ? Math.max(...values)
+            : values.reduce((sum, value) => sum + value, 0) / values.length;
+        }
+      }
+      const total = state.points.reduce((sum, value) => sum + value, 0);
+      return {
+        row: {
+          id,
+          provider: state.provider,
+          model: state.model,
+          ...(state.accountLogLabel !== undefined ? { accountLogLabel: state.accountLogLabel } : {}),
+          total,
+          points: state.points,
+        },
+        state,
+      };
+    }).sort((left, right) => right.row.total - left.row.total || left.row.id.localeCompare(right.row.id));
+    const kept = (rows.length > 24 ? rows.slice(0, 23) : rows).map(({ row }) => row);
+    if (rows.length > 24) {
+      const otherPoints = Array<number>(buckets).fill(0);
+      const folded = rows.slice(23);
+      if (query.aggregation === "sum") {
+        for (const { row } of folded) {
+          for (let index = 0; index < buckets; index += 1) otherPoints[index] = (otherPoints[index] ?? 0) + (row.points[index] ?? 0);
+        }
+      } else {
+        for (let index = 0; index < buckets; index += 1) {
+          const values = folded.flatMap(({ state }) => [...(state.requests.get(index)?.values() ?? [])]);
+          if (values.length > 0) {
+            otherPoints[index] = query.aggregation === "max"
+              ? Math.max(...values)
+              : values.reduce((sum, value) => sum + value, 0) / values.length;
+          }
+        }
+      }
+      kept.push({ id: "other", provider: "", model: "other", total: otherPoints.reduce((sum, value) => sum + value, 0), points: otherPoints });
+    }
+    return {
+      appliedFilters: {
+        models: query.models === null ? null : [...new Set(query.models)].sort(),
+        hiddenProviders: [...hiddenProviders].sort(),
+      },
+      start,
+      end,
+      bucketSeconds,
+      buckets,
+      metric: query.metric,
+      aggregation: query.aggregation,
+      grouping: query.grouping,
+      series: kept,
+      availableModels: [...availableModels].sort(),
+      missingMeasurements,
+      truncated: false,
+    };
+  }
+
+  return { add, finish };
+}

package/src/vision/eligibility.ts

@@ -35,6 +35,54 @@ import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-dest
  */
 export type VisionSidecarBackend = "openai" | "anthropic" | "routed";
 
+/**
+ * Input modalities an explicit custom row declares for one routed model.
+ *
+ * A custom row is the operator's own definition of that model, so its declaration outranks the
+ * provider-level hints the predicates below read. Without this the two halves of one config
+ * disagreed in production: the catalog overlay in `src/codex/catalog/routed-gather.ts` copies
+ * `customModels[].inputModalities` onto the row and the dashboard showed "text, image", while
+ * the request path consulted only `providers[].noVisionModels` / `modelInputModalities` and
+ * stripped the image before dispatch. A model the operator had declared image-capable therefore
+ * received an omission marker instead of its attachment.
+ *
+ * Precedence, highest first: `modelCapabilities` (the documented per-model capability
+ * declaration), then this custom-row declaration, then `noVisionModels`, then
+ * `modelInputModalities`, then registry/vendor metadata. `modelCapabilities` stays on top
+ * because it is the dedicated capability axis and the CLI `--text-only` flag writes it; when the
+ * two explicit forms contradict each other the more specific axis wins.
+ *
+ * Matching is exact on the routed identity — provider name and native model id, the pair the
+ * custom-model API keys rows by. A row that declares no modalities returns `undefined` rather
+ * than `["text"]`, so it stays silent instead of turning into a text-only claim.
+ */
+export function customRowInputModalities(
+  config: Pick<OcxConfig, "customModels">,
+  providerName: string,
+  modelId: string,
+): string[] | undefined {
+  for (const row of config.customModels ?? []) {
+    if (row.provider !== providerName || row.modelId !== modelId) continue;
+    if (Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
+      return [...row.inputModalities];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The custom row's verdict for one model, in the shape the predicates need:
+ * `true`/`false` when the row declares modalities, `undefined` when it declares none.
+ */
+function customRowAcceptsImageInput(
+  config: Pick<OcxConfig, "customModels">,
+  providerName: string,
+  modelId: string,
+): boolean | undefined {
+  const declared = customRowInputModalities(config, providerName, modelId);
+  return declared === undefined ? undefined : declared.includes("image");
+}
+
 /** The two sides every deployment has; also the empty-auth fallback set. */
 export type UniversalVisionBackend = "openai" | "anthropic";
 
@@ -60,6 +108,14 @@ export interface VisionCandidateModel {
   native?: boolean;
 }
 
+/**
+ * The config slice the capability predicates need. `customModels` is optional so provider-only
+ * callers and unit tests keep compiling; a caller that omits it is simply silent about custom
+ * rows rather than wrong about them.
+ */
+export type VisionCapabilityConfig =
+  Pick<OcxConfig, "providers"> & { customModels?: OcxConfig["customModels"] };
+
 export interface VisionModelOption {
   value: string;
   label: string;
@@ -142,20 +198,31 @@ function enrichedProviderForVision(
 }
 
 function isVisionSidecarConsumerWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   providerName: string,
   modelId: string,
   cache: EnrichedProviderCache,
 ): boolean {
   const provider = enrichedProviderForVision(config, providerName, cache);
-  return provider !== undefined && isModelVisionSidecarConsumer(provider, modelId);
+  if (provider === undefined) return false;
+  // Documented precedence, highest first: the dedicated per-model capability axis, then the
+  // operator's own custom row, then the provider-level hints. Reading the custom row ahead of
+  // `modelCapabilities` would let it override the more specific axis.
+  const capabilityDeclared = Object.hasOwn(provider.modelCapabilities ?? {}, modelId)
+    ? provider.modelCapabilities?.[modelId]?.inputModalities : undefined;
+  if (capabilityDeclared !== undefined) {
+    return capabilityDeclared.includes("text") && !capabilityDeclared.includes("image");
+  }
+  const customDeclared = customRowInputModalities(config, providerName, modelId);
+  if (customDeclared !== undefined) return customDeclared.includes("text") && !customDeclared.includes("image");
+  return isModelVisionSidecarConsumer(provider, modelId);
 }
 
 /**
  * Is this model listed as one the sidecar describes FOR? Such a model cannot be
  * the describer, and its advertised modalities are untrustworthy.
  */
-export function isVisionSidecarConsumer(config: Pick<OcxConfig, "providers">, providerName: string, modelId: string): boolean {
+export function isVisionSidecarConsumer(config: VisionCapabilityConfig, providerName: string, modelId: string): boolean {
   return isVisionSidecarConsumerWithCache(config, providerName, modelId, new Map());
 }
 
@@ -165,23 +232,30 @@ export function isVisionSidecarConsumer(config: Pick<OcxConfig, "providers">, pr
  * which callers treat as eligible.
  */
 export function modelAcceptsImageInput(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
 ): boolean | undefined {
   return modelAcceptsImageInputWithCache(config, candidate, new Map());
 }
 
 function modelAcceptsImageInputWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
   cache: EnrichedProviderCache,
 ): boolean | undefined {
   if (candidate.native === true || (candidate.provider === "openai" && SUPPORTED_NATIVE_OPENAI_SLUGS.has(candidate.id))) {
     const nativeProvider = enrichedProviderForVision(config, candidate.provider, cache);
-    if (nativeProvider && isModelVisionSidecarConsumer(nativeProvider, candidate.id)) return false;
     const declared = Object.hasOwn(nativeProvider?.modelCapabilities ?? {}, candidate.id)
       ? nativeProvider?.modelCapabilities?.[candidate.id]?.inputModalities : undefined;
     if (declared !== undefined) return declared.includes("image");
+    // The catalog already lets an explicit custom row replace the native modality list for the
+    // same slug; consult it here too or the row would advertise what the request path ignores.
+    const fromCustomRow = customRowAcceptsImageInput(config, candidate.provider, candidate.id);
+    if (fromCustomRow !== undefined) return fromCustomRow;
+    // The sidecar hints come after both explicit declarations, matching the documented order.
+    // Ahead of them a `noVisionModels` membership would short-circuit to text-only before the
+    // operator's own row was read.
+    if (nativeProvider && isModelVisionSidecarConsumer(nativeProvider, candidate.id)) return false;
     return advertisesImageInput(nativeInputModalities(candidate.id)) ?? true;
   }
   if (isVisionSidecarConsumerWithCache(config, candidate.provider, candidate.id, cache)) return false;
@@ -189,6 +263,11 @@ function modelAcceptsImageInputWithCache(
   const declared = Object.hasOwn(provider?.modelCapabilities ?? {}, candidate.id)
     ? provider?.modelCapabilities?.[candidate.id]?.inputModalities : undefined;
   if (declared !== undefined) return declared.includes("image");
+  // Ahead of the provider's own hints: this row is the operator's definition of this exact model,
+  // and the catalog overlay reads the same field. Behind modelCapabilities, which is the dedicated
+  // capability axis the CLI `--text-only` writes.
+  const fromCustomRow = customRowAcceptsImageInput(config, candidate.provider, candidate.id);
+  if (fromCustomRow !== undefined) return fromCustomRow;
   const configuredModalities = provider ? modelRecordValue(provider.modelInputModalities, candidate.id) : undefined;
   const fromConfiguredModalities = advertisesImageInput(configuredModalities);
   if (fromConfiguredModalities !== undefined) return fromConfiguredModalities;
@@ -206,14 +285,14 @@ function modelAcceptsImageInputWithCache(
 
 /** Eligible = not a sidecar consumer, and not positively known to be text-only. */
 export function isVisionEligibleModel(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
 ): boolean {
   return isVisionEligibleModelWithCache(config, candidate, new Map());
 }
 
 function isVisionEligibleModelWithCache(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidate: VisionCandidateModel,
   cache: EnrichedProviderCache,
 ): boolean {
@@ -274,7 +353,7 @@ function baselineCandidate(
  * backend, and only `value` reaches the client, so first-wins costs nothing.
  */
 export function visionEligibleModelOptions(
-  config: Pick<OcxConfig, "providers">,
+  config: VisionCapabilityConfig,
   candidates: readonly VisionCandidateModel[],
   enabledBackends: readonly VisionSidecarBackend[],
   anthropicProviderName?: string,