@yansigit/opencodex 2.31.3 → 2.32.0

package/src/cli/usage-report.ts

@@ -0,0 +1,134 @@
+/**
+ * Human rendering for `ocx usage`.
+ *
+ * Kept out of `observe.ts` and away from the shared `summaryLines()` helper on
+ * purpose. `summaryLines()` is a generic depth-1 flattener shared with
+ * storage/memory/debug/claude-inbound/injection; it renders any array as
+ * "N item(s)", which is why every per-model and per-provider cost the server
+ * computes used to vanish before reaching the terminal. Deepening it would
+ * change five unrelated commands.
+ *
+ * Formatting follows the existing CLI house style: dynamic `padEnd` columns
+ * (as in `formatAccountTable`), plain text, no ANSI colour.
+ */
+
+interface CostRow {
+  provider: string;
+  model?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+}
+
+interface UsageReportInput {
+  range?: string;
+  surface?: string;
+  since?: number | null;
+  summary?: {
+    requests?: number;
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCostUsd?: number;
+    unpricedRequests?: number;
+    unmeteredRequests?: number;
+  };
+  models?: CostRow[];
+  providers?: CostRow[];
+  days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
+  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+}
+
+const MAX_MODEL_ROWS = 10;
+
+function count(value: number | undefined): string {
+  return (value ?? 0).toLocaleString("en-US");
+}
+
+/**
+ * Matches the dashboard's `~$` with four fraction digits. Estimates below a
+ * hundredth of a cent still read as a number rather than collapsing to $0.00,
+ * which matters when a single request is being inspected.
+ */
+function usd(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+  return `~$${value.toFixed(4)}`;
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+  const line = (cols: string[]): string => cols.map((c, i) => (c ?? "").padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)];
+}
+
+function describeScope(data: UsageReportInput): string {
+  const parts = [`Usage — ${data.range ?? "?"}`];
+  if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
+  if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.model) parts.push(`model=${data.filter.model}`);
+  return parts.join(", ");
+}
+
+export function formatUsageReport(data: UsageReportInput): string[] {
+  const summary = data.summary ?? {};
+  const lines: string[] = [describeScope(data), ""];
+
+  if (data.filter && !data.filter.matched) {
+    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+      .filter(Boolean).join(" and ");
+    lines.push(`No usage recorded for ${what} in this range.`);
+    lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
+    return lines;
+  }
+
+  const tokenSplit = [
+    summary.inputTokens !== undefined ? `in ${count(summary.inputTokens)}` : null,
+    summary.outputTokens !== undefined ? `out ${count(summary.outputTokens)}` : null,
+    summary.cachedInputTokens ? `cached ${count(summary.cachedInputTokens)}` : null,
+  ].filter(Boolean).join(" / ");
+
+  lines.push(`Requests   ${count(summary.requests)}`);
+  lines.push(`Tokens     ${count(summary.totalTokens)}${tokenSplit ? `  (${tokenSplit})` : ""}`);
+  lines.push(`Est. cost  ${usd(summary.estimatedCostUsd)}    API list-price equivalent (this range)`);
+
+  const unpriced = summary.unpricedRequests ?? 0;
+  const unmetered = summary.unmeteredRequests ?? 0;
+  if (unpriced > 0 || unmetered > 0) {
+    // Spelled out because a $0 total is ambiguous otherwise: it can mean "no
+    // spend" or "no price row matched", and those are very different answers.
+    lines.push(`           ${count(unpriced)} unpriced, ${count(unmetered)} unmetered excluded from ~$`);
+  }
+
+  const providers = (data.providers ?? []).filter(row => row.requests > 0);
+  if (providers.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      providers.map(row => [row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+  }
+
+  const models = (data.models ?? []).filter(row => row.requests > 0);
+  if (models.length > 0) {
+    lines.push("");
+    const shown = models.slice(0, MAX_MODEL_ROWS);
+    lines.push(...table(
+      ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+    if (models.length > shown.length) {
+      lines.push(`... ${models.length - shown.length} more (use --json)`);
+    }
+  }
+
+  if (data.filter?.comboOverlap) {
+    lines.push("");
+    lines.push("Some requests ran as combos, so per-model request counts can overlap. Cost does not.");
+  }
+
+  lines.push("");
+  lines.push("Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}

package/src/codex/app-server-processes.ts

@@ -17,7 +17,8 @@ import {
 import { readCodexCatalogPath } from "./catalog/parsing";
 
 export const STALE_CODEX_APP_SERVER_HINT =
-  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex).";
+  "If Codex still shows an older model list, restart its long-lived app-server process after sync (ocx sync --restart-codex). "
+  + "On Windows the desktop app itself may also need a full restart (ocx sync --restart-desktop-app).";
 
 /** Attach the shared dashboard hint only after a catalog or models_cache write. */
 export function attachStaleAppServerHint<T extends {
@@ -505,6 +506,7 @@ export function formatStaleCodexAppServerWarning(
     `WARNING: ${processes.length} Codex app-server process(es) still running (PID${processes.length === 1 ? "" : "s"}: ${pids}). `
     + "Disk catalog/cache were updated, but Codex may keep showing the old model list until those processes restart. "
     + "Re-run with `ocx sync --restart-codex` (or `ocx sync-cache --restart-codex`) to send SIGTERM only to matching app-server processes. "
+    + "On Windows the desktop app itself may also need a full restart (`ocx sync --restart-desktop-app`). "
     + "Active turns may be interrupted."
   );
 }

package/src/codex/catalog/aggregation.ts

@@ -152,10 +152,20 @@ export function deriveComboCatalogModel(
   // A combo is cap-limited only when every member defining its effective minimum was
   // itself reduced by a provider cap. An uncapped member at the same minimum means the
   // combo would have the same window even without the cap.
-  const contextCapped = limitingMembers.every(member => member.contextCapped === true);
+  const contextCapped = limitingMembers.every(member => (
+    member.contextCapped === true
+    || (
+      typeof member.detectedContextWindow === "number"
+      && typeof member.contextWindow === "number"
+      && member.detectedContextWindow > member.contextWindow
+    )
+  ));
   const maxInputTokens = Math.min(
     ...members.map(member => member.maxInputTokens ?? member.contextWindow!),
   );
+  const detectedContextWindow = Math.min(
+    ...limitingMembers.map(member => member.detectedContextWindow ?? member.contextWindow!),
+  );
   const defaultReasoningEffort = effectiveComboDefault(
     combo.defaultEffort,
     reasoningEfforts,
@@ -167,6 +177,8 @@ export function deriveComboCatalogModel(
     owned_by: COMBO_NAMESPACE,
     contextWindow,
     maxInputTokens,
+    metadataSource: "derived",
+    detectedContextWindow,
     ...(hasLimitingContextCapMetadata ? { contextCapped } : {}),
     inputModalities,
     reasoningEfforts,

package/src/codex/catalog/effort.ts

@@ -33,6 +33,7 @@ import upstreamModelsSnapshot from "../data/upstream-models.json";
 
 import { generatedModelMetadata, readCatalog, readCodexCatalogPath } from "./parsing";
 import type { CatalogModel, RawEntry } from "./parsing";
+import { shouldStampContextProvenance } from "./model-metadata";
 import { UPSTREAM_NATIVE_ENTRIES } from "./metadata";
 import { nativeOpenAiCapabilitySourceSlug } from "./native-models";
 import { loadBundledCodexCatalog } from "./bundled";
@@ -171,33 +172,47 @@ export function applyCatalogModelMetadata(entry: RawEntry, model?: CatalogModel)
  * live in that table.
  */
 function stampCapabilityProvenance(entry: RawEntry, model: CatalogModel): void {
-  // Virtual combo rows are synthesized from last-resort defaults (a generic 128k
-  // context and a `["text"]` modality), so their values are placeholders rather
-  // than assertions. Stamping them would reintroduce the exact false-evidence
-  // defect this block exists to prevent.
-  if (model.provider === COMBO_NAMESPACE) return;
+  // Virtual combo rows without derived member evidence are placeholders
+  // (generic 128k / `["text"]`). Stamping those would reintroduce the
+  // false-evidence defect this block exists to prevent. Combos that actually
+  // min() real member windows carry `metadataSource: "derived"`.
+  if (model.provider === COMBO_NAMESPACE && model.metadataSource !== "derived") return;
 
   const meta = generatedModelMetadata(model.provider, model.id);
   const metaContext = typeof meta?.contextWindow === "number" && meta.contextWindow > 0
-    // The generated context is capped before it reaches the entry, so provenance
-    // must apply the same cap or routing would advertise a window the cap refused.
     ? applyProviderContextCap(meta.contextWindow, model.contextCap) ?? meta.contextWindow
     : undefined;
-  const contextWindow = typeof model.contextWindow === "number" && model.contextWindow > 0
+  const stampModelContext = shouldStampContextProvenance(model);
+  const contextWindow = stampModelContext
     ? model.contextWindow
-    : metaContext;
+    : (model.metadataSource === undefined ? metaContext : undefined);
   const inputModalities = Array.isArray(model.inputModalities) && model.inputModalities.length > 0
     ? model.inputModalities
     : (Array.isArray(meta?.input) && meta.input.length > 0 ? meta.input : undefined);
+  const maxInputTokens = typeof model.maxInputTokens === "number" && model.maxInputTokens > 0
+    ? model.maxInputTokens
+    : undefined;
+  const source = model.metadataSource;
+  const stampSource = source === "live" || source === "registry" || source === "snapshot" || source === "derived";
+
+  if (contextWindow === undefined && inputModalities === undefined
+    && !(Array.isArray(model.capabilities) && model.capabilities.length > 0)) {
+    return;
+  }
 
   entry.opencodex_capability_provenance = {
     provider: model.provider,
     model_id: model.id,
     ...(contextWindow !== undefined ? { context_window: contextWindow } : {}),
+    ...(maxInputTokens !== undefined && stampModelContext ? { max_input_tokens: maxInputTokens } : {}),
     ...(inputModalities !== undefined ? { input_modalities: [...inputModalities] } : {}),
     ...(Array.isArray(model.capabilities) && model.capabilities.length > 0
       ? { capabilities: [...model.capabilities] }
       : {}),
+    ...(stampSource ? { source } : {}),
+    ...(typeof model.metadataObservedAt === "string" && stampSource
+      ? { observed_at: model.metadataObservedAt }
+      : {}),
   };
 }