@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/combo-input.ts

@@ -0,0 +1,88 @@
+import { JEV_MAX_CANDIDATE_FIELD_CHARS } from "../combos/types";
+import { isCodexReasoningEffort } from "../reasoning-effort";
+import { readJsonInput } from "./json-input";
+import { CliUsageError, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+type ComboInput = {
+  targets?: Array<Record<string, unknown>>;
+  imageInput?: "auto" | "disabled";
+  reasoningEffortMode?: "strict" | "adaptive";
+  nativeAlias?: boolean;
+};
+const TARGET_KEYS = new Set(["provider", "model", "weight", "reasoningEfforts", "modelProfile", "lastResort"]);
+
+export function parseComboTargets(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value) || value.length === 0) throw new CliUsageError("Targets input must be a nonempty array");
+  return value.map(target => {
+    if (target === null || typeof target !== "object" || Array.isArray(target)
+      || Object.keys(target).some(key => !TARGET_KEYS.has(key))) {
+      throw new CliUsageError("Targets input contains an invalid object or unsupported field");
+    }
+    for (const key of ["provider", "model"]) {
+      if (typeof target[key] !== "string" || !target[key].trim() || /[\u0000-\u001f\u007f]/u.test(target[key])) {
+        throw new CliUsageError("Each target requires a nonblank provider and raw model ID without control characters");
+      }
+    }
+    if (Object.hasOwn(target, "weight") && (typeof target.weight !== "number"
+      || !Number.isInteger(target.weight) || target.weight < 1 || target.weight > 10_000)) {
+      throw new CliUsageError("Target weight must be an integer from 1 to 10000");
+    }
+    if (Object.hasOwn(target, "reasoningEfforts") && (!Array.isArray(target.reasoningEfforts)
+      || target.reasoningEfforts.length === 0
+      || target.reasoningEfforts.some((effort: unknown) => typeof effort !== "string" || !isCodexReasoningEffort(effort))
+      || new Set(target.reasoningEfforts).size !== target.reasoningEfforts.length)) {
+      throw new CliUsageError("Target reasoningEfforts must contain unique low, medium, high, xhigh, max or ultra values");
+    }
+    if (Object.hasOwn(target, "modelProfile") && (typeof target.modelProfile !== "string"
+      || !target.modelProfile.trim() || target.modelProfile.length > JEV_MAX_CANDIDATE_FIELD_CHARS
+      || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(target.modelProfile))) {
+      throw new CliUsageError("Target modelProfile must be nonblank, at most 512 characters, with no controls except tab or newline");
+    }
+    if (Object.hasOwn(target, "lastResort") && typeof target.lastResort !== "boolean") {
+      throw new CliUsageError("Target lastResort must be a boolean");
+    }
+    // Preserve raw slashes, target order, explicit false and omitted metadata.
+    return { ...target };
+  });
+}
+
+function takeNativeAlias(args: string[]): boolean | undefined {
+  const flag = "--native-alias";
+  const positions = args.flatMap((value, index) => value === flag || value.startsWith(`${flag}=`) ? [index] : []);
+  if (positions.length === 0) return undefined;
+  if (positions.length !== 1) throw new CliUsageError("--native-alias was given more than once");
+  const index = positions[0]!;
+  const token = args[index]!;
+  const inline = token !== flag;
+  const next = inline ? token.slice(flag.length + 1) : args[index + 1];
+  if (!inline && (next === undefined || next.startsWith("--"))) {
+    args.splice(index, 1);
+    return true;
+  }
+  if (next !== "on" && next !== "off") throw new CliUsageError("--native-alias accepts on, off, or the legacy bare flag");
+  args.splice(index, inline ? 1 : 2);
+  return next === "on";
+}
+
+/** Consume only extension options, before the parent set flow resolves a target or reads HTTP. */
+export async function prepareComboInput(args: string[], deps: RuntimeApiDeps = {}): Promise<ComboInput> {
+  const file = takeOptionWithSyntax(args, "--targets-file")?.value;
+  const image = takeOptionWithSyntax(args, "--image-input")?.value;
+  const reasoning = takeOptionWithSyntax(args, "--reasoning-effort-mode")?.value;
+  const nativeAlias = takeNativeAlias(args);
+  if (file !== undefined && args.some(arg => arg === "--targets" || arg.startsWith("--targets="))) {
+    throw new CliUsageError("--targets-file cannot be combined with --targets");
+  }
+  if (image !== undefined && image !== "auto" && image !== "disabled") {
+    throw new CliUsageError("--image-input must be auto or disabled");
+  }
+  if (reasoning !== undefined && reasoning !== "strict" && reasoning !== "adaptive") {
+    throw new CliUsageError("--reasoning-effort-mode must be strict or adaptive");
+  }
+  return {
+    ...(file === undefined ? {} : { targets: parseComboTargets(await readJsonInput(file, deps)) }),
+    ...(image === undefined ? {} : { imageInput: image }),
+    ...(reasoning === undefined ? {} : { reasoningEffortMode: reasoning }),
+    ...(nativeAlias === undefined ? {} : { nativeAlias }),
+  };
+}

package/src/cli/combo-result.ts

@@ -0,0 +1,52 @@
+import { parseComboTargets } from "./combo-input";
+import { printCatalogResult } from "./catalog-command-result";
+
+const ENUMS: Readonly<Record<string, readonly (string | null)[]>> = {
+  strategy: ["failover", "round-robin", "random", "least-used", "reset-window", "jev"],
+  defaultEffort: [null, "low", "medium", "high", "xhigh", "max", "ultra"],
+  defaultEffortMode: ["fallback", "force"], reasoningEffortMode: ["strict", "adaptive"],
+  imageInput: ["auto", "disabled"], cooldownWaitPolicy: ["before-last-resort"],
+};
+const STRINGS = new Set(["alias", "displayName", "decisionProvider", "decisionModel"]);
+const RANGES: Readonly<Record<string, readonly [number, number]>> = {
+  stickyLimit: [1, 100], cooldownMs: [1, 600_000], waitForCooldownMs: [0, 600_000],
+  decisionTimeoutMs: [1_000, 120_000],
+};
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+function invalid(): never { throw new Error("Invalid combo receipt"); }
+
+/** Shape/field ownership only; target graph/alias semantics remain on the server. */
+function publicCombo(value: unknown): Record<string, unknown> {
+  if (!record(value)) invalid();
+  let targets: Array<Record<string, unknown>>;
+  try { targets = parseComboTargets(value.targets); } catch { return invalid(); }
+  const result: Record<string, unknown> = { targets };
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "targets") continue;
+    if (Object.hasOwn(ENUMS, key)) {
+      if (!ENUMS[key]!.includes(child as string | null)) invalid();
+    } else if (STRINGS.has(key)) {
+      if (typeof child !== "string" || child.length > 4096) invalid();
+    } else if (Object.hasOwn(RANGES, key)) {
+      const [min, max] = RANGES[key]!;
+      if (typeof child !== "number" || !Number.isSafeInteger(child) || child < min || child > max) invalid();
+    } else if (key === "nativeAlias") {
+      if (typeof child !== "boolean") invalid();
+    } else invalid();
+    result[key] = child;
+  }
+  return result;
+}
+
+export function printComboWriteResult(value: unknown, id: string, wantsJson: boolean): number {
+  if (!record(value) || value.success !== true || value.id !== id || typeof value.model !== "string"
+    || Object.keys(value).some(key => !["success", "id", "model", "combo", "catalogRefresh"].includes(key))) invalid();
+  const combo = publicCombo(value.combo);
+  const model = typeof combo.alias === "string" && combo.alias.trim() ? combo.alias.trim() : `combo/${id}`;
+  if (value.model !== model) invalid();
+  return printCatalogResult({ success: true, id, model: value.model, combo }, value.catalogRefresh,
+    wantsJson, [`Saved combo ${id}.`]);
+}

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"}`,
+    ]);
+  });
+}