@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/combo-stats.ts

@@ -0,0 +1,123 @@
+import { JEV_DECISION_GATES } from "../usage/jev-stats";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, printData, runtimeBaseUrl, runtimeRequest, takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = "Usage: ocx combo stats <stored-id> [--range <7d|30d|all>] [--json]";
+const SUMMARY_COUNTS = [
+  "decisions", "appliedDecisions", "failOpenDecisions", "successfulRequests", "requestsWithModelFallback",
+  "modelAttempts", "measuredModelAttempts", "modelInputTokens", "modelOutputTokens", "modelReasoningTokens",
+  "modelCacheReadTokens", "modelCacheWriteTokens", "modelTotalTokens", "decisionUsageReported",
+  "decisionInputTokens", "decisionOutputTokens", "decisionTotalTokens",
+] as const;
+const MODEL_COUNTS = [
+  "picks", "appliedPicks", "failOpenPicks", "attempts", "measuredAttempts", "inputTokens", "outputTokens",
+  "reasoningTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens",
+] as const;
+const EFFORTS = ["low", "medium", "high", "xhigh", "max", "ultra"];
+
+function invalid(): never { throw new Error("Invalid combo statistics response"); }
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
+  return value as Record<string, unknown>;
+}
+function number(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) return invalid();
+  return value;
+}
+function nullable(value: unknown, max = Number.MAX_SAFE_INTEGER): number | null {
+  if (value === null) return null;
+  const result = number(value);
+  return result <= max ? result : invalid();
+}
+function boolean(value: unknown): boolean {
+  return typeof value === "boolean" ? value : invalid();
+}
+function identity(value: unknown, empty = false): string {
+  if (typeof value !== "string" || (!empty && !value.trim()) || value.length > 512
+    || /[\u0000-\u001f\u007f]/u.test(value)) return invalid();
+  return value;
+}
+function counts<K extends string>(value: Record<string, unknown>, keys: readonly K[]): Record<K, number> {
+  // Every requested key is assigned only after numeric validation. fromEntries
+  // loses the literal-key set in its library type, so retain that set here.
+  return Object.fromEntries(keys.map(key => [key, number(value[key])])) as Record<K, number>;
+}
+function rows(value: unknown): Array<Record<string, unknown>> {
+  return Array.isArray(value) ? value.map(record) : invalid();
+}
+
+/** Rebuild only the real JEV wire contract; never expose unknown server fields. */
+function projectStats(value: unknown, id: string, range: string) {
+  const dto = record(value);
+  if (dto.comboId !== id || dto.range !== range) return invalid();
+  const rawSummary = record(dto.summary);
+  const summary = {
+    ...counts(rawSummary, SUMMARY_COUNTS),
+    averageLatencyMs: nullable(rawSummary.averageLatencyMs),
+    averageConfidence: nullable(rawSummary.averageConfidence, 1),
+    averageChosenProbability: nullable(rawSummary.averageChosenProbability, 1),
+  };
+  const gates = rows(dto.gates).map(row => {
+    if (!(JEV_DECISION_GATES as readonly unknown[]).includes(row.gate)) return invalid();
+    return { gate: row.gate as string, decisions: number(row.decisions) };
+  });
+  const backends = rows(dto.backends).map(row => {
+    if (!["typesafe", "systemone", "model", "unknown"].includes(String(row.backend))) return invalid();
+    return { backend: row.backend as string, decisions: number(row.decisions), applied: number(row.applied), averageLatencyMs: nullable(row.averageLatencyMs) };
+  });
+  const models = rows(dto.models).map(row => {
+    const overflow = boolean(row.overflow);
+    const efforts = rows(row.efforts).map(item => {
+      if (item.effort !== null && (typeof item.effort !== "string" || !EFFORTS.includes(item.effort))) return invalid();
+      return { effort: item.effort as string | null, picks: number(item.picks) };
+    });
+    return { provider: identity(row.provider, overflow), model: identity(row.model, overflow), overflow, ...counts(row, MODEL_COUNTS), efforts };
+  });
+  const incomplete: { usageIncomplete?: boolean; usageIncompleteReason?: "oversized_rows" } = {};
+  if (Object.hasOwn(dto, "usageIncomplete")) incomplete.usageIncomplete = boolean(dto.usageIncomplete);
+  if (Object.hasOwn(dto, "usageIncompleteReason")) {
+    if (dto.usageIncompleteReason !== "oversized_rows" || dto.usageIncomplete !== true) return invalid();
+    incomplete.usageIncompleteReason = "oversized_rows";
+  }
+  if (dto.usageIncomplete === true && incomplete.usageIncompleteReason === undefined) return invalid();
+  return {
+    range, comboId: id, since: nullable(dto.since),
+    ...(Object.hasOwn(dto, "until") ? { until: number(dto.until) } : {}),
+    generatedAt: number(dto.generatedAt), summary, gates, backends, models,
+    snapshotWindowStart: nullable(dto.snapshotWindowStart), snapshotWindowEnd: nullable(dto.snapshotWindowEnd),
+    ...incomplete, historyTruncated: boolean(dto.historyTruncated), truncatedPrefixBytes: number(dto.truncatedPrefixBytes),
+    entriesTruncated: boolean(dto.entriesTruncated), entriesDropped: number(dto.entriesDropped),
+  };
+}
+
+export async function handleComboStatsCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const id = args.shift();
+    const wantsJson = takeFlag(args, "--json");
+    const range = takeOptionWithSyntax(args, "--range")?.value ?? "30d";
+    // Do not normalize, truncate or resolve a public alias to another stored ID.
+    if (!id || id.length > 128 || id.trim() !== id || id.startsWith("--") || /[\u0000-\u001f\u007f]/u.test(id)) {
+      throw new CliUsageError("A nonblank exact stored combo ID of at most 128 characters is required", USAGE);
+    }
+    if (!["7d", "30d", "all"].includes(range)) throw new CliUsageError("--range must be 7d, 30d or all", USAGE);
+    if (args.length) throw new CliUsageError("Unexpected combo stats argument(s)", USAGE);
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const query = new URLSearchParams({ jev: "1", comboId: id, range });
+    const data = projectStats(await runtimeRequest(`/api/usage?${query}`, { redirect: "error" }, pinned), id, range);
+    const summary = data.summary;
+    const incomplete = data.usageIncomplete || data.historyTruncated || data.entriesTruncated;
+    printData(data, wantsJson, [
+      `Combo ${id} — JEV observations (${range})`,
+      ...(summary.decisions === 0 ? ["No recorded JEV decisions in this window."] : []),
+      `Decisions: ${summary.decisions}; applied: ${summary.appliedDecisions}; fail-open: ${summary.failOpenDecisions}`,
+      `Successful requests: ${summary.successfulRequests}; requests with model fallback: ${summary.requestsWithModelFallback}`,
+      `Model tokens: ${summary.modelTotalTokens}; measured attempts: ${summary.measuredModelAttempts}/${summary.modelAttempts}`,
+      `Decision tokens: ${summary.decisionTotalTokens}; decisions reporting usage: ${summary.decisionUsageReported}/${summary.decisions}`,
+      `Average decision latency: ${summary.averageLatencyMs === null ? "unavailable" : `${summary.averageLatencyMs} ms`}`,
+      `Average confidence: ${summary.averageConfidence ?? "unavailable"}; chosen probability: ${summary.averageChosenProbability ?? "unavailable"}`,
+      ...(incomplete ? ["History is incomplete; totals cover only observed records."] : []),
+    ]);
+    return 0;
+  });
+}

package/src/cli/combo.ts

@@ -5,22 +5,30 @@ import {
   rejectArgs,
   runCliAction,
   runtimeRequest,
+  runtimeBaseUrl,
   takeFlag,
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
 
+import { prepareComboInput } from "./combo-input";
+import { printComboWriteResult } from "./combo-result";
+import { runCatalogAction } from "./catalog-command-result";
+import { serializeManagementJson } from "./json-input";
+
 const USAGE = `Usage:
   ocx combo [list] [--json]
   ocx combo show <id> [--json]
-  ocx combo set <id> [--targets <provider/model[:weight],...>]
+  ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->]
       [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->]
       [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->]
       (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
-      [--native-alias] [--display-name <label|->]
+      [--native-alias [on|off]] [--display-name <label|->]
+      [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>]
       [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->]
       (jev only; the provider must be a configured jev-decision row)
       [--rename-from <id>] [--json]
+  ocx combo stats <id> [--range <7d|30d|all>] [--json]
   ocx combo remove <id> --yes [--json]
   ocx combo test [--combo <id>] [--decision-provider <provider|jev> | --decision-model <route>]
       [--decision-timeout <ms>] [--json]
@@ -72,18 +80,22 @@ async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(combo, wantsJson);
 }
 
-async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const id = args.shift()?.trim();
   const wantsJson = takeFlag(args, "--json");
   if (!id) throw new CliUsageError("combo id is required", USAGE);
+  const additional = await prepareComboInput(args, deps);
   const targetsRaw = takeOption(args, "--targets");
   const renameFrom = takeOption(args, "--rename-from");
+  const replacingTargets = targetsRaw !== undefined || additional.targets !== undefined;
+  deps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+  // A structured target file replaces the target list, not unrelated combo settings.
   const partialCurrent = targetsRaw === undefined
-    ? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps)
+    ? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps)
     : undefined;
   const partialExisting = partialCurrent?.combos?.find(row => row.id === (renameFrom ?? id));
-  if (targetsRaw === undefined && !partialExisting) {
+  if (!replacingTargets && !partialExisting) {
     throw new CliUsageError("--targets is required when creating a combo", USAGE);
   }
   const strategyRaw = takeOption(args, "--strategy");
@@ -104,7 +116,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     throw new CliUsageError("--effort-mode must be fallback, force, or -", USAGE);
   }
   const alias = takeOption(args, "--alias");
-  const nativeAlias = takeFlag(args, "--native-alias");
+
   const displayName = takeOption(args, "--display-name");
   const decisionProvider = takeOption(args, "--decision-provider");
   const decisionModel = takeOption(args, "--decision-model");
@@ -138,15 +150,18 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   // Listing-only nulls must not be resent as explicit clears (alias rejects null).
   const combo: Record<string, unknown> = partialExisting
     ? Object.fromEntries(Object.entries(partialExisting).filter(([, value]) => value !== null))
-    : { strategy, stickyLimit: stickyLimit ?? 1, targets: parseTargets(targetsRaw!) };
+    : { strategy, stickyLimit: stickyLimit ?? 1, targets: additional.targets ?? parseTargets(targetsRaw!) };
   delete combo.id;
   delete combo.model;
+  if (additional.targets !== undefined) combo.targets = additional.targets;
   if (strategyRaw !== undefined) combo.strategy = strategy;
   if (stickyLimit !== undefined) combo.stickyLimit = stickyLimit;
   if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
   if (effortMode !== undefined) combo.defaultEffortMode = effortMode === "-" ? "fallback" : effortMode;
   if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
-  if (nativeAlias) combo.nativeAlias = true;
+  if (additional.nativeAlias !== undefined) combo.nativeAlias = additional.nativeAlias;
+  if (additional.imageInput !== undefined) combo.imageInput = additional.imageInput;
+  if (additional.reasoningEffortMode !== undefined) combo.reasoningEffortMode = additional.reasoningEffortMode;
   if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
   if (decisionProvider !== undefined) combo.decisionProvider = decisionProvider === "-" ? null : decisionProvider;
   if (decisionModel !== undefined) combo.decisionModel = decisionModel === "-" ? null : decisionModel;
@@ -158,17 +173,20 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     delete combo.decisionModel;
     delete combo.decisionTimeoutMs;
   }
-  const current = partialCurrent ?? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const current = partialCurrent ?? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps);
   const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));
-  if (existing?.imageInput === "disabled") combo.imageInput = "disabled";
+  if (additional.imageInput === undefined && existing?.imageInput === "disabled") combo.imageInput = "disabled";
+  if (effort === undefined && existing?.defaultEffort != null && combo.defaultEffort === undefined) {
+    combo.defaultEffort = existing.defaultEffort;
+  }
   if (effortMode === undefined && existing?.defaultEffortMode === "force") {
     combo.defaultEffortMode = effort === "-" ? "fallback" : "force";
   }
   const result = await runtimeRequest("/api/combos", {
-    method: "PUT",
-    body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
+    method: "PUT", redirect: "error",
+    body: serializeManagementJson({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
   }, deps);
-  printData(result, wantsJson, [`Saved combo ${id}.`]);
+  return printComboWriteResult(result, id, wantsJson);
 }
 
 async function remove(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -249,11 +267,16 @@ async function discover(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleComboCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const [subcommand, ...writeArgs] = argv;
+  if (subcommand === "set" || subcommand === "create" || subcommand === "update") return runCatalogAction(() => set(writeArgs, deps));
+  if (subcommand === "stats") {
+    const { handleComboStatsCommand } = await import("./combo-stats");
+    return handleComboStatsCommand(writeArgs, deps);
+  }
   return runCliAction(async () => {
     const [sub = "list", ...rest] = argv;
     if (sub === "list") await list(rest, deps);
     else if (sub === "show") await show(rest, deps);
-    else if (sub === "set" || sub === "create" || sub === "update") await set(rest, deps);
     else if (sub === "remove" || sub === "delete") await remove(rest, deps);
     else if (sub === "test") await testDecision(rest, deps);
     else if (sub === "discover") await discover(rest, deps);

package/src/cli/companion-timeline.ts

@@ -0,0 +1,142 @@
+/** Read the existing usage timeline without changing companion settings. */
+import { isTimelineModelId, normalizeTimelineModelId, parseTimelineQuery, type TimelineQuery, type TimelineSeries, type UsageTimeline } from "../usage/timeline";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, printData, runtimeRequest, takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage: ocx companion timeline [--hours <6|24|72|168>] [--bucket-minutes <1..1440>]
+  [--metric <total|input|output|cached>] [--aggregation <sum|average|max>]
+  [--grouping <model|modelAccount>] [--model <provider/model>]... [--hide-provider <name>]... [--json]
+Providers are excluded with --hide-provider; --provider is not supported.`;
+
+function repeatedOption(args: string[], flag: string): string[] {
+  const values: string[] = [];
+  for (let index = 0; index < args.length;) {
+    const token = args[index]!;
+    if (token === flag) {
+      const next = args[index + 1];
+      if (!next || next.startsWith("--")) throw new CliUsageError(`${flag} requires a value`, USAGE);
+      values.push(next); args.splice(index, 2);
+    } else if (token.startsWith(`${flag}=`)) {
+      const value = token.slice(flag.length + 1);
+      if (!value) throw new CliUsageError(`${flag} requires a value`, USAGE);
+      values.push(value); args.splice(index, 1);
+    } else index++;
+  }
+  return values;
+}
+
+function timelineInput(argv: string[]): { query: TimelineQuery; params: URLSearchParams; wantsJson: boolean } {
+  const args = [...argv], wantsJson = takeFlag(args, "--json"), params = new URLSearchParams();
+  for (const [flag, name] of [
+    ["--hours", "hours"], ["--bucket-minutes", "bucketMinutes"], ["--metric", "metric"],
+    ["--aggregation", "aggregation"], ["--grouping", "grouping"],
+  ] as const) {
+    const option = takeOptionWithSyntax(args, flag);
+    if (option) params.set(name, option.value);
+  }
+  const models = repeatedOption(args, "--model");
+  // Each occurrence is one identifier, not an implicit CSV escape hatch.
+  if (models.some(model => !isTimelineModelId(model) || model.includes(","))) {
+    throw new CliUsageError("Each --model must be one provider/model identifier", USAGE);
+  }
+  if (models.length) params.set("models", models.join(","));
+  for (const provider of repeatedOption(args, "--hide-provider")) params.append("hiddenProvider", provider);
+  if (args.length) throw new CliUsageError("Unsupported timeline arguments; use --hide-provider to exclude providers", USAGE);
+  const query = parseTimelineQuery(params, Date.now());
+  if ("error" in query) throw new CliUsageError("Invalid timeline options; check window, bucket count, enums and the 100-item filter limits", USAGE);
+  return { query, params, wantsJson };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid timeline object");
+  return value as Record<string, unknown>;
+}
+function number(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error("Invalid timeline measurement");
+  return value;
+}
+function integer(value: unknown): number {
+  const result = number(value);
+  if (!Number.isSafeInteger(result)) throw new Error("Invalid timeline integer");
+  return result;
+}
+function text(value: unknown): string {
+  if (typeof value !== "string") throw new Error("Invalid timeline text");
+  return value;
+}
+function strings(value: unknown): string[] {
+  if (!Array.isArray(value)) throw new Error("Invalid timeline list");
+  return value.map(text);
+}
+function sameStrings(left: string[], right: string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function timelineDto(raw: unknown, query: TimelineQuery): UsageTimeline {
+  const value = record(raw), filters = record(value.appliedFilters);
+  const models = filters.models === null ? null : strings(filters.models);
+  const hiddenProviders = strings(filters.hiddenProviders), expectedModels = query.models === null ? null : [...query.models].sort();
+  if ((models === null) !== (expectedModels === null)
+    || (models !== null && expectedModels !== null && !sameStrings(models, expectedModels))
+    || !sameStrings(hiddenProviders, query.hiddenProviders)) throw new Error("Timeline filters were not acknowledged");
+  const start = integer(value.start), end = integer(value.end), buckets = integer(value.buckets), bucketSeconds = integer(value.bucketSeconds);
+  const expectedBucketSeconds = query.bucketMinutes * 60;
+  const requestedEnd = (Math.floor(query.now / 1000 / expectedBucketSeconds) + 1) * expectedBucketSeconds;
+  const observedNow = Math.floor(Date.now() / 1000);
+  const currentWindow = end === requestedEnd
+    || (observedNow >= requestedEnd && end === requestedEnd + expectedBucketSeconds);
+  if (bucketSeconds !== query.bucketMinutes * 60 || buckets !== Math.ceil(query.hours * 60 / query.bucketMinutes)
+    || end <= start || end - start !== buckets * bucketSeconds || start % bucketSeconds !== 0 || end % bucketSeconds !== 0
+    // Match the requested current bucket, or its immediate successor after an observed rollover.
+    || !currentWindow || end > observedNow + bucketSeconds
+    || value.metric !== query.metric || value.aggregation !== query.aggregation || value.grouping !== query.grouping
+    || typeof value.truncated !== "boolean" || !Array.isArray(value.series) || value.series.length > 24) {
+    throw new Error("Invalid timeline bounds or metadata");
+  }
+  const availableModels = strings(value.availableModels);
+  if (availableModels.some(model => !isTimelineModelId(model)) || new Set(availableModels).size !== availableModels.length) {
+    throw new Error("Invalid available timeline models");
+  }
+  const selectedModels = models === null ? null : new Set(models.map(normalizeTimelineModelId));
+  const available = new Set(availableModels);
+  const series: TimelineSeries[] = value.series.map(rawSeries => {
+    const row = record(rawSeries), id = text(row.id), provider = text(row.provider), model = text(row.model);
+    const accountLogLabel = row.accountLogLabel === undefined ? undefined : text(row.accountLogLabel);
+    const total = number(row.total);
+    if (!Array.isArray(row.points) || row.points.length !== buckets) throw new Error("Invalid timeline points");
+    const points = row.points.map(number), pointTotal = points.reduce((sum, point) => sum + point, 0);
+    if (!Number.isFinite(pointTotal) || Math.abs(total - pointTotal) > 1e-9 * Math.max(1, total, pointTotal)) throw new Error("Invalid timeline total");
+    const other = id === "other" && provider === "" && model === "other" && accountLogLabel === undefined;
+    if (!other && (!isTimelineModelId(`${provider}/${model}`) || hiddenProviders.includes(provider)
+      || !available.has(`${provider}/${model}`) || (selectedModels !== null && !selectedModels.has(`${provider}/${model}`))
+      || id !== (query.grouping === "model" ? `${provider}/${model}` : `${provider}/${model} · ${accountLogLabel}`)
+      || (query.grouping === "modelAccount" ? accountLogLabel === undefined : accountLogLabel !== undefined))) {
+      throw new Error("Invalid timeline series identity");
+    }
+    return { id, provider, model, ...(accountLogLabel !== undefined ? { accountLogLabel } : {}), total, points };
+  });
+  if (new Set(series.map(row => row.id)).size !== series.length) throw new Error("Duplicate timeline series");
+  return { appliedFilters: { models, hiddenProviders }, start, end, bucketSeconds, buckets,
+    metric: query.metric, aggregation: query.aggregation, grouping: query.grouping, series, availableModels,
+    missingMeasurements: integer(value.missingMeasurements), truncated: value.truncated };
+}
+
+/** argv starts after `companion timeline`; numeric errors propagate through the public companion dispatcher. */
+export async function handleCompanionTimelineCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const { params, query, wantsJson } = timelineInput(argv);
+    const result = timelineDto(await runtimeRequest(`/api/usage/timeline${params.size ? `?${params}` : ""}`,
+      { method: "GET", redirect: "error" }, deps), query);
+    printData(result, wantsJson, [
+      `Usage timeline: ${result.metric}, ${result.aggregation}, grouped by ${result.grouping}`,
+      `Window: ${new Date(result.start * 1000).toISOString()} to ${new Date(result.end * 1000).toISOString()} (end exclusive)`,
+      `Buckets: ${result.buckets} × ${result.bucketSeconds} seconds`,
+      `Models: ${result.appliedFilters.models?.join(", ") ?? "all"}; excluded providers: ${result.appliedFilters.hiddenProviders.join(", ") || "none"}`,
+      `Missing measurements: ${result.missingMeasurements}; truncated: ${result.truncated}`,
+      ...(result.missingMeasurements || result.truncated ? ["Incomplete evidence: plotted zeros do not establish zero usage."] : []),
+      ...(result.series.length ? result.series.map(row => `${row.id}: ${row.total} (${row.points.join(", ")})`)
+        : ["No matching series in the available timeline. Try a wider --hours window or fewer filters."]),
+      `Available models: ${result.availableModels.join(", ") || "none"}`,
+    ]);
+  });
+}

package/src/cli/companion-usage.ts

@@ -0,0 +1,146 @@
+/** Saved companion display filters applied to two bounded management reads. */
+import { ObservationError, withObserveStream, type ObserveStreamDeps } from "./observe-stream";
+import { printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = "Usage: ocx companion usage [--json]";
+const TOTAL_FIELDS = ["requests", "totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "cacheReadInputTokens", "estimatedCostUsd", "measuredRequests", "pricedRequests", "coverageRatio"] as const;
+type Totals = Partial<Record<typeof TOTAL_FIELDS[number], number>>;
+type Model = Totals & { model: string; provider: string };
+interface Usage {
+  summary: Totals;
+  models: Model[];
+  customWindow?: boolean;
+  since?: number | null;
+  until?: number;
+  usageIncomplete?: boolean;
+  historyTruncated?: boolean;
+  entriesTruncated?: boolean;
+}
+interface Filters { models: string[] | null; hiddenProviders: string[] }
+interface Settings { filters: Filters; updatedAt: number | null; corrupt: boolean }
+type RangeResult = { status: "available"; data: Usage } | { status: "unavailable" };
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ObservationError("Invalid companion response. Check the runtime and retry the command.");
+  return value as Record<string, unknown>;
+}
+
+function stringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/[\x00-\x1f\x7f-\x9f]/.test(item));
+}
+
+function parseSettings(value: unknown): Settings {
+  const body = object(value), settings = object(body.settings);
+  if ((settings.models !== null && !stringList(settings.models)) || !stringList(settings.hiddenProviders)
+    || (body.updatedAt !== null && (typeof body.updatedAt !== "number" || !Number.isFinite(body.updatedAt)))
+    || (body.corrupt !== undefined && typeof body.corrupt !== "boolean")) {
+    throw new ObservationError("Invalid companion settings. Check the runtime and retry the command.");
+  }
+  return { filters: { models: settings.models, hiddenProviders: settings.hiddenProviders }, updatedAt: body.updatedAt, corrupt: body.corrupt === true };
+}
+
+function parseTotals(value: unknown): Totals {
+  const row = object(value), totals: Totals = {};
+  for (const key of TOTAL_FIELDS) {
+    const metric = row[key];
+    if (metric === undefined) continue;
+    if (typeof metric !== "number" || !Number.isFinite(metric) || metric < 0) throw new ObservationError("Invalid companion usage metrics. Check the runtime and retry the command.");
+    totals[key] = metric;
+  }
+  return totals;
+}
+
+function parseUsage(value: unknown): Usage {
+  const body = object(value);
+  if (body.error || !Array.isArray(body.models)) throw new ObservationError("Invalid companion usage report. Check the runtime and retry the command.");
+  const usage: Usage = {
+    summary: parseTotals(body.summary),
+    models: body.models.map(raw => {
+      const row = object(raw);
+      if (typeof row.model !== "string" || typeof row.provider !== "string") throw new ObservationError("Invalid companion model row. Check the runtime and retry the command.");
+      return { ...parseTotals(row), model: row.model, provider: row.provider };
+    }),
+  };
+  for (const key of ["customWindow", "usageIncomplete", "historyTruncated", "entriesTruncated"] as const) {
+    if (body[key] === undefined) continue;
+    if (typeof body[key] !== "boolean") throw new ObservationError("Invalid companion usage metadata. Check the runtime and retry the command.");
+    usage[key] = body[key];
+  }
+  for (const key of ["since", "until"] as const) {
+    const timestamp = body[key];
+    if (timestamp === undefined) continue;
+    if (key === "since" && timestamp === null) { usage.since = null; continue; }
+    if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) throw new ObservationError("Invalid companion usage window. Check the runtime and retry the command.");
+    usage[key] = timestamp;
+  }
+  return usage;
+}
+
+/** Keep in conformance with tray-data's display rules without a GUI runtime import. */
+function filterUsage(usage: Usage, filters: Filters): Usage {
+  const hidden = new Set(filters.hiddenProviders), selected = filters.models === null ? null : new Set(filters.models);
+  const models = usage.models.filter(row => !hidden.has(row.provider)
+    && (selected === null || selected.has(`${row.provider}/${row.model}`) || selected.has(row.model)));
+  if (filters.models === null && filters.hiddenProviders.length === 0) return { ...usage, models };
+  if (filters.models?.length !== 0 && usage.models.some(row => !row.provider || !row.model || (row.provider === "other" && row.model === "other"))) {
+    return { ...usage, models: models.filter(row => row.provider !== "other" || row.model !== "other"), summary: {}, usageIncomplete: true };
+  }
+  const summary: Totals = {};
+  for (const key of TOTAL_FIELDS) {
+    if (key === "coverageRatio") continue;
+    if (models.length && models.every(row => row[key] !== undefined)) summary[key] = models.reduce((sum, row) => sum + row[key]!, 0);
+  }
+  return { ...usage, models, summary };
+}
+
+function measuredTotals<T extends Totals>(data: T): T {
+  const next = { ...data };
+  if ((data.requests ?? 0) > 0 && (data.measuredRequests === 0 || data.coverageRatio === 0)) {
+    for (const key of ["totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "cacheReadInputTokens"] as const) delete next[key];
+  }
+  if ((data.requests ?? 0) > 0 && data.pricedRequests === 0) delete next.estimatedCostUsd;
+  return next;
+}
+
+function formatRange(label: string, result: RangeResult): string[] {
+  if (result.status === "unavailable") return [`${label}: unavailable`];
+  const count = (value: number | undefined) => value === undefined ? "unknown" : value.toLocaleString("en-US");
+  const cost = (value: number | undefined) => value === undefined ? "unknown" : `~$${value.toFixed(4)}`;
+  const data = result.data;
+  return [`${label}: ${count(data.summary.requests)} requests; ${count(data.summary.totalTokens)} tokens; cost ${cost(data.summary.estimatedCostUsd)}`,
+    ...(data.usageIncomplete || data.historyTruncated || data.entriesTruncated ? ["  Incomplete observation; totals include only attributable measured data."] : []),
+    ...data.models.map(row => `  ${row.provider}/${row.model}: ${count(row.requests)} requests; ${count(row.totalTokens)} tokens; cost ${cost(row.estimatedCostUsd)}`)];
+}
+
+export async function handleCompanionUsageCommand(argv: string[], deps: ObserveStreamDeps = {}): Promise<number> {
+  let outcome = 0;
+  const parseExit = await runCliAction(async () => {
+    const args = [...argv], wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE, { redactValues: true });
+    outcome = await withObserveStream(deps, async stream => {
+      const settings = parseSettings(await stream.get("/api/companion/settings", new URLSearchParams()));
+      const ranges: Record<"today" | "30d", RangeResult> = { today: { status: "unavailable" }, "30d": { status: "unavailable" } };
+      for (const range of ["today", "30d"] as const) {
+        try {
+          const data = filterUsage(parseUsage(await stream.get("/api/usage", new URLSearchParams({ range }))), settings.filters);
+          ranges[range] = { status: "available", data: { ...data, summary: measuredTotals(data.summary), models: data.models.map(measuredTotals) } };
+        } catch {
+          stream.signal.throwIfAborted();
+        }
+      }
+      stream.signal.throwIfAborted();
+      const partial = ranges.today.status === "unavailable" || ranges["30d"].status === "unavailable";
+      const result = { schemaVersion: 1, filters: settings.filters, settingsUpdatedAt: settings.updatedAt, settingsCorrupt: settings.corrupt,
+        settingsFallback: settings.corrupt || settings.updatedAt === null, ranges, partial };
+      const lines = ["Companion usage — saved display filters (sequential observations)",
+        `Models: ${settings.filters.models === null ? "all" : settings.filters.models.length === 0 ? "none" : settings.filters.models.join(", ")}`,
+        `Hidden providers: ${settings.filters.hiddenProviders.join(", ") || "none"}`,
+        ...(settings.corrupt ? ["WARNING: Saved settings are corrupt; the runtime supplied fallback settings."] : []),
+        ...formatRange("Today", ranges.today), ...formatRange("30 days", ranges["30d"])];
+      printData(result, wantsJson, wantsJson ? undefined : lines);
+      if (partial) console.error("Error: Some companion usage ranges are unavailable. Check the runtime and retry the command.");
+      return partial ? 1 : 0;
+    }, { kind: "snapshot" });
+  });
+  return parseExit || outcome;
+}

package/src/cli/companion.ts

@@ -1,9 +1,16 @@
+import { handleCompanionTimelineCommand } from "./companion-timeline";
+import { handleCompanionUsageCommand } from "./companion-usage";
+import type { ObserveStreamDeps } from "./observe-stream";
 import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
 
 const USAGE = `Usage:
   ocx companion [show] [--json]
   ocx companion set <key>=<value> [...] [--json]
-  ocx companion reset [--json]`;
+  ocx companion reset [--json]
+  ocx companion usage [--json]
+  ocx companion timeline [--hours <6|24|72|168>] [--bucket-minutes <1..1440>]
+      [--metric <total|input|output|cached>] [--aggregation <sum|average|max>]
+      [--grouping <model|modelAccount>] [--model <provider/model>]... [--hide-provider <name>]... [--json]`;
 
 function parseValue(raw: string): unknown {
   if (raw === "null") return null;
@@ -43,9 +50,11 @@ async function reset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }, deps), wantsJson, ["Companion settings reset."]);
 }
 
-export async function handleCompanionCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleCompanionCommand(argv: string[], deps: ObserveStreamDeps = {}): Promise<number> {
+  const [sub = "show", ...rest] = argv;
+  if (sub === "timeline") return handleCompanionTimelineCommand(rest, deps);
+  if (sub === "usage") return handleCompanionUsageCommand(rest, deps);
   return runCliAction(async () => {
-    const [sub = "show", ...rest] = argv;
     if (sub === "show") await show(rest, deps);
     else if (sub === "set") await set(rest, deps);
     else if (sub === "reset") await reset(rest, deps);