@@ -1224,6 +1242,7 @@ export default function Usage({ apiBase, connected = false, apiKeyId }: { apiBas
range={customWindow ? null : range}
locale={locale}
t={t}
+ apiBase={apiBase}
/>
)}
diff --git a/gui/src/pages/usage-companion-chart.tsx b/gui/src/pages/usage-companion-chart.tsx
new file mode 100644
index 00000000000..0cf5505efb2
--- /dev/null
+++ b/gui/src/pages/usage-companion-chart.tsx
@@ -0,0 +1,119 @@
+import type { Locale, TFn } from "../i18n/shared";
+import {
+ chartPolylinePoints,
+ chartStackedBarRects,
+ formatCompanionTokens,
+ type UsageTimeline,
+} from "./usage-companion-utils";
+
+const CHART_COLORS = ["#0A84FF", "#FF9F0A", "#30D158", "#BF5AF2", "#FF453A", "#64D2FF"];
+const WIDTH = 640;
+const HEIGHT = 160;
+const PADDING = 28;
+
+function maxValue(timeline: UsageTimeline, chartStyle: "line" | "stackedBar"): number {
+ if (chartStyle === "stackedBar") {
+ return Math.max(...Array.from({ length: timeline.buckets }, (_, index) =>
+ timeline.series.reduce((sum, series) => sum + (series.points[index] ?? 0), 0),
+ ), 0);
+ }
+ return Math.max(...timeline.series.flatMap(series => series.points), 0);
+}
+
+function dateLabels(timeline: UsageTimeline, locale: Locale): string[] {
+ const formatter = new Intl.DateTimeFormat(locale, { month: "short", day: "numeric" });
+ const interval = Math.max(1, Math.floor((timeline.buckets - 1) / 3));
+ return [0, 1, 2, 3].map(index => {
+ const bucket = Math.min(timeline.buckets - 1, index * interval);
+ return formatter.format(new Date((timeline.start + bucket * timeline.bucketSeconds) * 1000));
+ });
+}
+
+export function UsageCompanionChart({
+ timeline,
+ chartStyle,
+ hours,
+ loading,
+ error,
+ onRetry,
+ locale,
+ t,
+}: {
+ timeline: UsageTimeline | null;
+ chartStyle: "line" | "stackedBar";
+ hours: number;
+ loading: boolean;
+ error: string | null;
+ onRetry: () => void;
+ locale: Locale;
+ t: TFn;
+}) {
+ if (loading) {
+ return
;
+ }
+ if (error) {
+ return (
+
+ {t("usage.companion.timelineUnavailable")}
+
+
+ );
+ }
+ if (!timeline || timeline.series.length === 0) {
+ return
{t("usage.companion.empty", { hours: timeline?.buckets ? Math.round(timeline.buckets * timeline.bucketSeconds / 3600) : hours })}
;
+ }
+ const max = maxValue(timeline, chartStyle);
+ const labels = dateLabels(timeline, locale);
+ const plotWidth = WIDTH - PADDING * 2;
+ const plotHeight = HEIGHT - PADDING * 2;
+ const y = PADDING;
+ const baseline = PADDING + plotHeight;
+ const translate = "trans" + "late";
+ const xLabels = labels.map((label, index) => (
+
{label}
+ ));
+ const marks = chartStyle === "line"
+ ? timeline.series.map((series, index) => (
+
+ ))
+ : chartStackedBarRects(timeline.series, plotWidth, plotHeight, max, 0).map(rect => (
+
+ ));
+ return (
+
+
+
+ {timeline.series.map((series, index) => (
+
+
+ {series.id}
+
+ ))}
+
+ {timeline.truncated &&
{t("usage.companion.olderRecordsSkipped")}
}
+
+ );
+}
diff --git a/gui/src/pages/usage-companion-panel.tsx b/gui/src/pages/usage-companion-panel.tsx
new file mode 100644
index 00000000000..f3af2082de1
--- /dev/null
+++ b/gui/src/pages/usage-companion-panel.tsx
@@ -0,0 +1,422 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { useI18n } from "../i18n/shared";
+import { relativeTimeLabelsFromT, formatRelativeTime } from "../provider-workspace/usage";
+import { Switch } from "../ui";
+import { UsageCompanionChart } from "./usage-companion-chart";
+import {
+ bucketMinutesForWindow,
+ buildCompanionSettingsPatch,
+ formatCompanionTokens,
+ groupCompanionModels,
+ toggleCompanionModels,
+ type CompanionSettings,
+ type CompanionSettingsResponse,
+ type UsageTimeline,
+} from "./usage-companion-utils";
+
+interface CompanionProvider {
+ provider: string;
+}
+
+const MENU_METRICS = ["requests", "tokens", "cost", "quota", "none"] as const;
+const WINDOWS = [6, 24, 72, 168] as const;
+const CHART_STYLES = ["line", "stackedBar"] as const;
+const TOKEN_METRICS = ["total", "input", "output", "cached"] as const;
+const AGGREGATIONS = ["sum", "average", "max"] as const;
+const GROUPINGS = ["model", "modelAccount"] as const;
+
+function formatSaveTime(value: number, locale: string): string {
+ return new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" }).format(value);
+}
+
+function errorMessage(value: unknown): string {
+ if (value instanceof Error && value.message) return value.message;
+ return String(value);
+}
+
+function Segment
({
+ label,
+ value,
+ options,
+ optionLabel,
+ onChange,
+}: {
+ label: string;
+ value: T;
+ options: readonly T[];
+ optionLabel: (value: T) => string;
+ onChange: (value: T) => void;
+}) {
+ return (
+
+
{label}
+
+ {options.map(option => (
+
+ ))}
+
+
{t("usage.companion.settingsUnavailable")}
;
+ }
+ const current = settings;
+ if (!current) {
+ return ;
+ }
+ const providerNames = providers.map(provider => provider.provider).filter((provider, index, all) => all.indexOf(provider) === index).toSorted();
+ const selectedModels = current.models ?? availableModels;
+ const selectedModelSet = new Set(selectedModels);
+ const modelGroups = groupCompanionModels(availableModels, knownTotals);
+ const hiddenProviderSet = new Set(current.hiddenProviders);
+ const saveMessage = saveState === "saved" && response?.updatedAt
+ ? t("usage.companion.saved", { time: formatSaveTime(response.updatedAt, locale) })
+ : saveState === "error" ? t("usage.companion.saveFailed", { error: saveError ?? "" }) : "";
+ return (
+
+ {response?.corrupt &&
+ {t("usage.companion.corrupt")}
+
+
}
+
+ {(() => {
+ const lastSeenAt = response?.companion?.lastSeenAt ?? null;
+ const connected = lastSeenAt !== null && fetchedAt !== null && fetchedAt - lastSeenAt <= 10 * 60 * 1000;
+ const age = lastSeenAt === null || fetchedAt === null ? "" : formatRelativeTime(lastSeenAt, relativeTimeLabelsFromT(t), fetchedAt);
+ const steps = (
+
+ - {t("usage.companion.installStep1")} {t("common.github")}
+ - {t("usage.companion.installStep2")}
+ - {t("usage.companion.installStep3")}
+
+ );
+ return connected ? (
+
+
{t("usage.companion.connected", { age })}
+
+ {t("usage.companion.installAnother")}
+ {steps}
+ xattr -d com.apple.quarantine /Applications/OpenCodex.app
+
+
+ {t("usage.companion.installTitle")}
+ {lastSeenAt !== null && {t("usage.companion.lastSeen", { age })}
}
+ {lastSeenAt === null && {t("usage.companion.notConnected")}
}
+ {steps}
+ xattr -d com.apple.quarantine /Applications/OpenCodex.app
+
+ );
+ })()}
+ void loadTimeline()} locale={locale} t={t} />
+ {modelGroups.length > 0 &&
+
+
+ {t("usage.companion.modelsOnChart")}
+ {t("usage.companion.modelsCount", { selected: selectedModels.length, total: availableModels.length })}
+
+ {current.models !== null &&
}
+
+ {modelGroups.map(group => {
+ const selectedCount = group.models.filter(model => selectedModelSet.has(model.id)).length;
+ const groupOn = selectedCount === group.models.length;
+ return
+
+ {group.provider}
+ {group.models.length}
+ 0 && !groupOn}
+ onClick={() => updateSettings({ models: toggleCompanionModels(current.models, availableModels, group.models.map(model => model.id), !groupOn) })}
+ disabled={response?.corrupt}
+ label={group.provider}
+ title={group.provider}
+ />
+
+ {group.models.map(model => {
+ const on = selectedModelSet.has(model.id);
+ return
+ updateSettings({ models: toggleCompanionModels(current.models, availableModels, [model.id], !on) })}
+ disabled={response?.corrupt}
+ label={model.id}
+ title={model.id}
+ />
+ {model.id}
+ {knownTotals.has(model.id) ? formatCompanionTokens(model.total) : "—"}
+
;
+ })}
+
;
+ })}
+
+ {saveMessage || "\u00a0"}
+ {saveState === "error" && }
+
+
+ {t("usage.companion.footer")}
+
+ );
+}
diff --git a/gui/src/pages/usage-companion-utils.ts b/gui/src/pages/usage-companion-utils.ts
new file mode 100644
index 00000000000..9f68b323a52
--- /dev/null
+++ b/gui/src/pages/usage-companion-utils.ts
@@ -0,0 +1,214 @@
+export type TimelineMetric = "total" | "input" | "output" | "cached";
+export type TimelineAggregation = "sum" | "average" | "max";
+export type TimelineGrouping = "model" | "modelAccount";
+export type CompanionMenuBarMetric = "requests" | "tokens" | "cost" | "quota" | "none";
+export type CompanionChartStyle = "line" | "stackedBar";
+export type ChartHours = 6 | 24 | 72 | 168;
+
+export interface CompanionSettings {
+ menuBarMetric: CompanionMenuBarMetric;
+ menuBarTemplate: string | null;
+ showToday: boolean;
+ showChart: boolean;
+ showModels: boolean;
+ showCost: boolean;
+ showAccounts: boolean;
+ chartHours: ChartHours;
+ bucketMinutes: number;
+ chartStyle: CompanionChartStyle;
+ tokenMetric: TimelineMetric;
+ aggregation: TimelineAggregation;
+ chartGrouping: TimelineGrouping;
+ models: string[] | null;
+ hiddenProviders: string[];
+}
+
+export interface TimelineSeries {
+ id: string;
+ provider: string;
+ model: string;
+ accountLogLabel?: string;
+ total: number;
+ points: number[];
+}
+
+export interface UsageTimeline {
+ start: number;
+ end: number;
+ bucketSeconds: number;
+ buckets: number;
+ metric: TimelineMetric;
+ aggregation: TimelineAggregation;
+ grouping: TimelineGrouping;
+ series: TimelineSeries[];
+ availableModels: string[];
+ missingMeasurements: number;
+ truncated: boolean;
+}
+
+export interface CompanionSettingsResponse {
+ settings: CompanionSettings;
+ updatedAt: number | null;
+ defaults: CompanionSettings;
+ corrupt?: boolean;
+ companion?: {
+ lastSeenAt: number | null;
+ };
+}
+
+export const CHART_BUCKET_MINUTES: Record = {
+ 6: 15,
+ 24: 60,
+ 72: 180,
+ 168: 360,
+};
+
+export function bucketMinutesForWindow(hours: ChartHours): number {
+ return CHART_BUCKET_MINUTES[hours];
+}
+
+export function formatCompanionTokens(value: number): string {
+ if (value < 1_000) return String(Math.round(value));
+ const units = [
+ [1_000_000_000_000, "T"],
+ [1_000_000_000, "B"],
+ [1_000_000, "M"],
+ [1_000, "K"],
+ ] as const;
+ for (let index = 0; index < units.length; index += 1) {
+ const [threshold, suffix] = units[index]!;
+ if (value >= threshold) {
+ const rounded = Math.round(value / threshold);
+ if (rounded >= 1000 && index > 0) {
+ const [largerThreshold, largerSuffix] = units[index - 1]!;
+ return `${Math.round(value / largerThreshold)}${largerSuffix}`;
+ }
+ return `${rounded}${suffix}`;
+ }
+ }
+ return String(Math.round(value));
+}
+
+export interface CompanionModelGroup {
+ provider: string;
+ models: { id: string; total: number }[];
+ total: number;
+}
+
+export function groupCompanionModels(
+ available: string[],
+ totals: Map,
+): CompanionModelGroup[] {
+ const groups = new Map();
+ for (const id of available) {
+ const provider = id.includes("/") ? id.slice(0, id.indexOf("/")) : id;
+ const group = groups.get(provider) ?? { provider, models: [], total: 0 };
+ const total = totals.get(id) ?? 0;
+ group.models.push({ id, total });
+ group.total += total;
+ groups.set(provider, group);
+ }
+ return Array.from(groups.values())
+ .map(group => ({
+ ...group,
+ models: group.models.toSorted((a, b) => b.total - a.total || a.id.localeCompare(b.id)),
+ }))
+ .toSorted((a, b) => b.total - a.total || a.provider.localeCompare(b.provider));
+}
+
+export function toggleCompanionModels(
+ selected: string[] | null,
+ available: string[],
+ ids: string[],
+ on: boolean,
+): string[] | null {
+ const availableSet = new Set(available);
+ const next = new Set((selected ?? available).filter(id => availableSet.has(id)));
+ for (const id of ids) {
+ if (on) next.add(id);
+ else next.delete(id);
+ }
+ if (available.length > 0 && available.every(id => next.has(id))) return null;
+ return available.filter(id => next.has(id));
+}
+
+export function buildCompanionSettingsPatch(
+ patch: Partial,
+ availableModels: readonly string[] = [],
+): Partial {
+ const next = { ...patch };
+ if (typeof next.menuBarTemplate === "string" && next.menuBarTemplate.trim() === "") {
+ next.menuBarTemplate = null;
+ }
+ if (next.models !== undefined && availableModels.length > 0) {
+ const selected = next.models ?? [];
+ const selectedSet = new Set(selected);
+ const allSelected = selected.length === availableModels.length
+ && availableModels.every(model => selectedSet.has(model));
+ if (allSelected) next.models = null;
+ }
+ return next;
+}
+
+export function chartPolylinePoints(
+ points: readonly number[],
+ width: number,
+ height: number,
+ maxValue: number,
+ padding = 8,
+): string {
+ const plotWidth = Math.max(0, width - padding * 2);
+ const plotHeight = Math.max(0, height - padding * 2);
+ const denominator = Math.max(maxValue, 1);
+ const divisor = Math.max(points.length - 1, 1);
+ return points.map((value, index) => {
+ const x = padding + plotWidth * index / divisor;
+ const y = padding + plotHeight * (1 - Math.max(0, value) / denominator);
+ return `${x},${y}`;
+ }).join(" ");
+}
+
+export interface StackedBarRect {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ seriesIndex: number;
+ bucketIndex: number;
+}
+
+export function chartStackedBarRects(
+ series: readonly Pick[],
+ width: number,
+ height: number,
+ maxValue: number,
+ padding = 8,
+): StackedBarRect[] {
+ const buckets = series[0]?.points.length ?? 0;
+ if (buckets === 0) return [];
+ const plotWidth = Math.max(0, width - padding * 2);
+ const plotHeight = Math.max(0, height - padding * 2);
+ const denominator = Math.max(maxValue, 1);
+ const gap = Math.min(3, plotWidth / Math.max(buckets * 8, 1));
+ const barWidth = Math.max(0, plotWidth / buckets - gap);
+ const rects: StackedBarRect[] = [];
+ for (let bucketIndex = 0; bucketIndex < buckets; bucketIndex += 1) {
+ let offset = 0;
+ for (let seriesIndex = 0; seriesIndex < series.length; seriesIndex += 1) {
+ const value = Math.max(0, series[seriesIndex]?.points[bucketIndex] ?? 0);
+ const barHeight = plotHeight * value / denominator;
+ if (barHeight > 0) {
+ rects.push({
+ x: padding + bucketIndex * (plotWidth / buckets) + gap / 2,
+ y: padding + plotHeight - offset - barHeight,
+ width: barWidth,
+ height: barHeight,
+ seriesIndex,
+ bucketIndex,
+ });
+ }
+ offset += barHeight;
+ }
+ }
+ return rects;
+}
diff --git a/gui/src/styles-usage-workspace.css b/gui/src/styles-usage-workspace.css
index aa9e3bb45c6..6f8d4a2af74 100644
--- a/gui/src/styles-usage-workspace.css
+++ b/gui/src/styles-usage-workspace.css
@@ -214,6 +214,90 @@
gap: 6px;
}
+.usage-companion-panel {
+ display: grid;
+ gap: 16px;
+ padding-top: 4px;
+}
+.usage-companion-header {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 16px;
+}
+.usage-companion-header .panel-title { margin: 0; }
+.usage-companion-header .card-sub { margin: 4px 0 0; }
+.usage-companion-install {
+ display: grid;
+ gap: 10px;
+ padding: 12px;
+ border: 1px solid var(--border);
+ border-radius: var(--radius-sm);
+ background: var(--surface);
+}
+.usage-companion-install summary { cursor: pointer; color: var(--text); font-size: 12px; font-weight: 600; }
+.usage-companion-install-status { display: flex; align-items: center; gap: 8px; color: var(--text); font-size: 12px; }
+.usage-companion-install-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--green); }
+.usage-companion-install-steps { display: grid; gap: 8px; margin: 0; padding-left: 20px; color: var(--muted); font-size: 12px; }
+.usage-companion-install-steps .btn { margin-left: 6px; }
+.usage-companion-install-last-seen { margin: 0; }
+.usage-companion-install-command { display: block; overflow-x: auto; padding: 7px 9px; border-radius: var(--radius-xs); background: var(--raised); color: var(--text); font-size: 11px; }
+.usage-companion-models { display: grid; gap: 8px; }
+.usage-companion-models-header { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+.usage-companion-models-header > div { display: flex; align-items: baseline; gap: 8px; min-width: 0; }
+.usage-companion-models-count { white-space: nowrap; }
+.usage-companion-models-list { max-height: 280px; overflow-y: auto; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); }
+.usage-companion-model-group + .usage-companion-model-group { border-top: 1px solid var(--border-soft); }
+.usage-companion-model-group-header { position: sticky; top: 0; z-index: 1; display: flex; align-items: center; gap: 7px; padding: 8px 10px; background: color-mix(in srgb, var(--surface) 92%, var(--raised)); }
+.usage-companion-model-provider { flex: 1; min-width: 0; overflow: hidden; color: var(--text); font-size: 12px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+.usage-companion-model-chip { padding: 2px 5px; border: 1px solid var(--border); border-radius: 999px; color: var(--muted); }
+.usage-companion-model-group-header .switch { flex: 0 0 auto; }
+.usage-companion-model-row { display: flex; align-items: center; gap: 8px; min-width: 0; padding: 7px 10px 7px 18px; }
+.usage-companion-model-row .switch { flex: 0 0 auto; }
+.usage-companion-model-row code { min-width: 0; overflow: hidden; color: var(--text); text-overflow: ellipsis; white-space: nowrap; }
+.usage-companion-model-row.is-off code { color: var(--faint); text-decoration: line-through; }
+.usage-companion-model-total { flex: 0 0 auto; margin-left: auto; font-variant-numeric: tabular-nums; }
+.usage-companion-chart { min-width: 0; }
+.usage-companion-chart svg { display: block; width: 100%; height: 160px; overflow: visible; }
+.usage-companion-axis { stroke: var(--border); stroke-width: 1; }
+.usage-companion-axis-label { fill: var(--muted); font-size: 10px; }
+.usage-companion-legend { display: flex; flex-wrap: wrap; gap: 8px 14px; margin-top: 8px; }
+.usage-companion-legend-item { display: inline-flex; align-items: center; gap: 5px; color: var(--muted); font-size: 11px; }
+.usage-companion-swatch { width: 8px; height: 8px; border-radius: 50%; }
+.usage-companion-chart-skeleton {
+ height: 160px;
+ border: 1px solid var(--border-soft);
+ background: var(--surface);
+ animation: pulse 1.2s ease-in-out infinite alternate;
+}
+.usage-companion-chart-state { display: flex; align-items: center; gap: 10px; min-height: 160px; color: var(--muted); }
+.usage-companion-controls { display: grid; gap: 14px; border: 0; padding: 0; margin: 0; min-width: 0; }
+.usage-companion-control { display: grid; gap: 6px; min-width: 0; }
+.usage-companion-control > select, .usage-companion-control > input {
+ min-height: 34px; width: 100%; padding: 6px 9px;
+ border: 1px solid var(--border); border-radius: var(--radius-xs);
+ background: var(--raised); color: var(--text); font: inherit;
+}
+.usage-companion-control > .usage-segmented { width: fit-content; max-width: 100%; }
+.field-label { color: var(--muted); font-size: 11.5px; font-weight: 550; }
+.usage-companion-switches, .usage-companion-check-list {
+ display: grid; gap: 8px; border: 0; padding: 0; margin: 0;
+}
+.usage-companion-switches legend { padding: 0; margin-bottom: 2px; }
+.usage-companion-switch { display: flex; align-items: center; justify-content: space-between; gap: 12px; color: var(--text); font-size: 12px; }
+.usage-companion-switch .toggle { flex: 0 0 auto; }
+.usage-companion-advanced { border-top: 1px solid var(--border-soft); padding-top: 12px; }
+.usage-companion-advanced summary { cursor: pointer; color: var(--text); font-size: 12px; font-weight: 600; }
+.usage-companion-advanced-body { display: grid; gap: 14px; padding-top: 12px; }
+.usage-companion-check-list label { display: flex; align-items: center; gap: 7px; color: var(--text); font-size: 12px; }
+.usage-companion-save-status { display: flex; align-items: center; gap: 8px; min-height: 26px; color: var(--muted); font-size: 11.5px; }
+.usage-companion-save-status.is-error { color: var(--red); }
+.usage-companion-loading { min-height: 160px; color: var(--muted); }
+
@media (max-width: 640px) {
.usage-source-row { align-items: flex-start; flex-direction: column; }
+ .usage-companion-header { align-items: stretch; flex-direction: column; }
+ .usage-companion-header .btn { align-self: flex-start; }
+ .usage-companion-control > .usage-segmented { width: 100%; }
+ .usage-companion-control > .usage-segmented .usage-segmented-btn { flex: 1 1 0; min-width: 0; padding-inline: 6px; }
}
diff --git a/gui/tests/usage-companion-utils.test.ts b/gui/tests/usage-companion-utils.test.ts
new file mode 100644
index 00000000000..2fd02c7fd9e
--- /dev/null
+++ b/gui/tests/usage-companion-utils.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import {
+ bucketMinutesForWindow,
+ buildCompanionSettingsPatch,
+ chartPolylinePoints,
+ chartStackedBarRects,
+ formatCompanionTokens,
+ groupCompanionModels,
+ toggleCompanionModels,
+} from "../src/pages/usage-companion-utils";
+
+describe("usage companion utilities", () => {
+ test("maps chart windows to bounded buckets", () => {
+ expect([6, 24, 72, 168].map(bucketMinutesForWindow)).toEqual([15, 60, 180, 360]);
+ });
+
+ test("normalizes empty templates and all-selected models", () => {
+ expect(buildCompanionSettingsPatch({
+ menuBarTemplate: " ",
+ models: ["openai/gpt-5", "anthropic/claude"],
+ }, ["openai/gpt-5", "anthropic/claude"])).toEqual({
+ menuBarTemplate: null,
+ models: null,
+ });
+ expect(buildCompanionSettingsPatch({ models: ["openai/gpt-5"] }, ["openai/gpt-5", "anthropic/claude"])).toEqual({
+ models: ["openai/gpt-5"],
+ });
+ });
+
+ test("creates line and stacked bar geometry", () => {
+ expect(chartPolylinePoints([0, 5, 10], 100, 50, 10)).toBe("8,42 50,25 92,8");
+ expect(chartStackedBarRects([
+ { points: [5] },
+ { points: [5] },
+ ], 100, 50, 10)).toEqual([
+ { x: 9.5, y: 25, width: 81, height: 17, seriesIndex: 0, bucketIndex: 0 },
+ { x: 9.5, y: 8, width: 81, height: 17, seriesIndex: 1, bucketIndex: 0 },
+ ]);
+ });
+
+ test("formats companion token values as integer SI units", () => {
+ expect([999, 1_000, 999_600, 1_634_303, 333_400_000, 12_300_000_000].map(formatCompanionTokens)).toEqual([
+ "999", "1K", "1M", "2M", "333M", "12B",
+ ]);
+ });
+
+ test("groups companion models by descending totals with alphabetical ties", () => {
+ expect(groupCompanionModels(
+ ["openai/gpt-4", "anthropic/claude", "openai/gpt-5", "local"],
+ new Map([
+ ["openai/gpt-4", 5],
+ ["anthropic/claude", 10],
+ ["openai/gpt-5", 5],
+ ]),
+ )).toEqual([
+ { provider: "anthropic", models: [{ id: "anthropic/claude", total: 10 }], total: 10 },
+ { provider: "openai", models: [{ id: "openai/gpt-4", total: 5 }, { id: "openai/gpt-5", total: 5 }], total: 10 },
+ { provider: "local", models: [{ id: "local", total: 0 }], total: 0 },
+ ]);
+ });
+
+ test("keeps known totals for models absent from the current timeline", () => {
+ expect(groupCompanionModels(
+ ["openai/gpt-4", "anthropic/claude"],
+ new Map([["openai/gpt-4", 10]]),
+ )).toEqual([
+ { provider: "openai", models: [{ id: "openai/gpt-4", total: 10 }], total: 10 },
+ { provider: "anthropic", models: [{ id: "anthropic/claude", total: 0 }], total: 0 },
+ ]);
+ });
+
+ test("toggles mixed groups and collapses all-selected state to null", () => {
+ const available = ["openai/gpt-4", "openai/gpt-5", "anthropic/claude"];
+ expect(toggleCompanionModels(["openai/gpt-4"], available, ["openai/gpt-5"], true)).toEqual(["openai/gpt-4", "openai/gpt-5"]);
+ expect(toggleCompanionModels(["openai/gpt-4", "openai/gpt-5"], available, ["anthropic/claude"], true)).toBeNull();
+ });
+});
diff --git a/package.json b/package.json
index 7278f576ab6..26fce207d75 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,9 @@
"build:gui": "cd gui && bun install --frozen-lockfile && bun run build && cd .. && bun run prepare:package",
"build:remote-workspace-helper": "cargo build --release --locked --manifest-path native/remote-workspace-helper/Cargo.toml",
"test:remote-workspace-helper": "cargo test --locked --manifest-path native/remote-workspace-helper/Cargo.toml",
+ "build:macos": "bash scripts/build-macos-app.sh",
+ "package:macos": "bash scripts/package-macos-release.sh",
+ "test:macos": "swift run --package-path app MenuBarCoreTests && swift run --package-path app MenuBarUITests",
"prepare:package": "bun scripts/prepare-package.ts",
"prepack": "bun run prepare:package",
"prepublishOnly": "bun run audit:high && bun run typecheck && bun run build:gui",
diff --git a/readme/README.fr.md b/readme/README.fr.md
index 160acfb908d..411a27e7597 100644
--- a/readme/README.fr.md
+++ b/readme/README.fr.md
@@ -92,6 +92,19 @@ Ouvrez **http://localhost:10100** et configurez tout dans le tableau de bord web
fournisseurs (plus de 40 intégrés, ou n'importe quel point de terminaison compatible OpenAI),
choisissez les modèles, gérez les comptes. `ocx gui`
rouvre le tableau de bord à tout moment.
+### Application macOS dans la barre des menus
+
+Un compagnon natif pour l’état du proxy, l’utilisation et les quotas des fournisseurs sans ouvrir
+le tableau de bord. Le code source se trouve dans [`app/`](../app) (Swift + AppKit, sans dépendance
+tierce). Téléchargez-le depuis la
+[page des releases](https://github.com/lidge-jun/opencodex/releases) ou compilez-le localement avec
+`bun run build:macos`.
+
+Le premier lancement nécessite un clic droit → Ouvrir, car l’application est signée ad hoc et non
+notarisée. Consultez le [guide de l’application macOS dans la barre des menus](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+pour l’explication complète.
+
+L’application inclut également un widget macOS 14+ affichant l’état du proxy, l’utilisation du jour et les quotas.
Il peut également gérer un **groupe de comptes ChatGPT** pour l'authentification Codex. Ajoutez plusieurs
comptes ChatGPT / Codex et actualisez leurs quotas 5 h / hebdomadaires / 30 j dans le tableau de bord.
Avec le routage par quota, les nouvelles sessions peuvent utiliser le compte opérationnel le moins sollicité ;
diff --git a/readme/README.ja.md b/readme/README.ja.md
index 415d5c9674d..ee8a7e6adc5 100644
--- a/readme/README.ja.md
+++ b/readme/README.ja.md
@@ -99,6 +99,18 @@ Codex 認証用の **ChatGPT アカウントプール**も管理できます。C
は使わず他が尽きたときだけ回したいアカウント（多くは Codex Desktop のログイン）があるなら、アカウント
に選択順を指定してください。
+### macOS メニューバーアプリ
+
+ダッシュボードを開かずにプロキシの状態、使用量、プロバイダーのクォータを確認できるネイティブ
+コンパニオンです。ソースは [`app/`](../app)（Swift + AppKit、サードパーティ依存なし）にあります。
+[リリースページ](https://github.com/lidge-jun/opencodex/releases)からダウンロードするか、
+`bun run build:macos` でローカルビルドできます。
+
+アプリは未公証のアドホック署名のため、初回起動時は右クリックして「開く」を選択してください。
+詳しくは [macOS メニューバーアプリガイド](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)をご覧ください。
+
+macOS 14 以降では、プロキシの状態、今日の使用量、クォータを表示するウィジェットも利用できます。
+
### スポンサー
アップストリームのプロトコルが変わるたびに opencodex を追随させているのはスポンサーの支援です。
diff --git a/readme/README.ko.md b/readme/README.ko.md
index f4c44f121c6..f93936bc5a5 100644
--- a/readme/README.ko.md
+++ b/readme/README.ko.md
@@ -96,6 +96,18 @@ round-robin과 fill-first는 각자 정책을 따릅니다. 기존 Codex 스레
계정 제외, affinity 만료, 401/403·429 복구가 일어나면 다시 묶일 수 있습니다. Codex Desktop 로그인처럼
다른 계정이 소진된 뒤에만 쓰고 싶은 계정이 있으면, 계정에 선택 순서를 지정하세요.
+### macOS 메뉴 막대 앱
+
+대시보드를 열지 않고 프록시 상태, 사용량, 제공자 쿼터를 확인하는 네이티브 동반 앱입니다.
+소스는 [`app/`](../app)에 있으며 Swift + AppKit으로 작성되었고 서드파티 의존성이 없습니다.
+[릴리스 페이지](https://github.com/lidge-jun/opencodex/releases)에서 다운로드하거나
+`bun run build:macos`로 직접 빌드할 수 있습니다.
+
+앱은 공증되지 않은 애드혹 서명이므로 처음 실행할 때 마우스 오른쪽 버튼을 클릭하고 열기를 선택하세요.
+자세한 내용은 [macOS 메뉴 막대 앱 가이드](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)를 참조하세요.
+
+macOS 14 이상에서는 프록시 상태, 오늘의 사용량과 쿼터를 보여 주는 위젯도 포함됩니다.
+
### 스폰서
업스트림 프로토콜이 바뀔 때마다 opencodex가 따라갈 수 있는 건 스폰서 덕분입니다. 관심이 있으면
diff --git a/readme/README.ru.md b/readme/README.ru.md
index e654f571a93..d2df43cd07f 100644
--- a/readme/README.ru.md
+++ b/readme/README.ru.md
@@ -103,6 +103,18 @@ ocx start # прокси + панель управлен
них — обычно вход Codex Desktop — должен использоваться только после того, как остальные
исчерпаны.
+### Приложение macOS в строке меню
+
+Нативный компаньон для состояния прокси, использования и квот провайдеров без открытия панели.
+Исходный код находится в [`app/`](../app) (Swift + AppKit, без сторонних зависимостей).
+Скачайте его со [страницы релизов](https://github.com/lidge-jun/opencodex/releases) или
+соберите локально командой `bun run build:macos`.
+
+При первом запуске нажмите правой кнопкой мыши и выберите «Открыть»: приложение подписано ad hoc,
+но не нотариализовано. Подробности — в [руководстве по приложению macOS в строке меню](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/).
+
+Приложение также включает виджет для macOS 14+, показывающий состояние прокси, расход за сегодня и квоты.
+
### Спонсоры
Спонсоры позволяют поддерживать opencodex при каждом изменении вышестоящих протоколов. Интересно?
diff --git a/readme/README.tr.md b/readme/README.tr.md
index 998338d8760..511a42b0a1c 100644
--- a/readme/README.tr.md
+++ b/readme/README.tr.md
@@ -99,6 +99,18 @@ değerlendirmesi, failover, hesabın devre dışı bırakılması, bağlılığ
429 toparlanması bu bağı yeniden kurabilir. Yalnızca diğerleri tükendiğinde kullanılmasını istediğiniz
bir hesap varsa — genellikle Codex Desktop girişiniz — hesaplara bir seçim sırası verin.
+### macOS menü çubuğu uygulaması
+
+Panoyu açmadan proxy durumunu, kullanımı ve sağlayıcı kotalarını gösteren yerel yardımcı uygulama.
+Kaynak kodu [`app/`](../app) konumundadır (Swift + AppKit, üçüncü taraf bağımlılığı yoktur).
+[Sürümler sayfasından](https://github.com/lidge-jun/opencodex/releases) indirin veya
+`bun run build:macos` ile yerel olarak derleyin.
+
+Uygulama noter tasdikli olmadığından ve ad hoc imzalandığından ilk açılışta sağ tıklayıp Aç'ı seçin.
+Ayrıntılar için [macOS menü çubuğu uygulaması kılavuzuna](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/) bakın.
+
+Uygulama ayrıca proxy durumunu, bugünkü kullanımı ve kotaları gösteren macOS 14+ widget'ını içerir.
+
### Sponsorlar
Her yukarı akış protokol değişiminde opencodex'in bakımını sürdürebilmesi sponsorlar sayesinde.
diff --git a/readme/README.zh-CN.md b/readme/README.zh-CN.md
index 79392708a13..cc2e57271f3 100644
--- a/readme/README.zh-CN.md
+++ b/readme/README.zh-CN.md
@@ -97,6 +97,17 @@ ocx start # 代理 + 仪表板：localhost:10100
401/403 与 429 恢复，仍可能重新绑定。给账户设定选择顺序，以便其中某个账户 ——
通常是你的 Codex Desktop 登录 —— 只在其他账户耗尽后才被选中。
+### macOS 菜单栏应用
+
+无需打开仪表板即可查看代理状态、用量和提供商配额的原生伴侣应用。源代码位于
+[`app/`](../app)（Swift + AppKit，无第三方依赖）。请从[发布页面](https://github.com/lidge-jun/opencodex/releases)
+下载，或使用 `bun run build:macos` 在本地构建。
+
+应用采用未公证的临时签名，首次启动时请右键点击并选择“打开”。详情请参阅
+[macOS 菜单栏应用指南](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)。
+
+应用还包含适用于 macOS 14 及更高版本的小组件，可显示代理状态、今日用量和配额。
+
### 赞助商
赞助商支撑 opencodex 跟上每一次上游协议变更。有兴趣？
diff --git a/readme/README.zh-TW.md b/readme/README.zh-TW.md
index 6a25aae4d15..adb8bf52012 100644
--- a/readme/README.zh-TW.md
+++ b/readme/README.zh-TW.md
@@ -95,6 +95,17 @@ ocx start # 代理 + 儀表板位於 localhost:10100
行動裝置連線的會話不會在對話中途跳帳號——但配額重新評估、failover、
帳號排除、親和性到期，或 401/403 與 429 復原，仍可能重新綁定。當其中一個帳號——通常是你的 Codex Desktop 登入——只應在其他帳號用盡後才被用到時，請為帳號設定選取順序。
+### macOS 選單列應用程式
+
+無需開啟儀表板即可查看代理狀態、用量與供應商配額的原生伴侶應用程式。原始碼位於
+[`app/`](../app)（Swift + AppKit，沒有第三方相依套件）。請從[發行頁面](https://github.com/lidge-jun/opencodex/releases)
+下載，或使用 `bun run build:macos` 在本機建置。
+
+應用程式未經公證且使用 ad hoc 簽章，首次啟動時請按右鍵並選擇「開啟」。詳情請參閱
+[macOS 選單列應用程式指南](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)。
+
+應用程式也包含 macOS 14 以上的小工具，可顯示代理狀態、今日用量與配額。
+
### 贊助
贊助讓 opencodex 能跟上每一次上游協議變更。有興趣？
diff --git a/readme/i18n-manifest.json b/readme/i18n-manifest.json
index d64870cad2c..569d3612db8 100644
--- a/readme/i18n-manifest.json
+++ b/readme/i18n-manifest.json
@@ -6,43 +6,43 @@
"file": "readme/README.fr.md",
"label": "Français",
"docsPath": "fr",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"ko": {
"file": "readme/README.ko.md",
"label": "한국어",
"docsPath": "ko",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"zh-CN": {
"file": "readme/README.zh-CN.md",
"label": "简体中文",
"docsPath": "zh-cn",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"zh-TW": {
"file": "readme/README.zh-TW.md",
"label": "繁體中文",
"docsPath": "zh-tw",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"ru": {
"file": "readme/README.ru.md",
"label": "Русский",
"docsPath": "ru",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"ja": {
"file": "readme/README.ja.md",
"label": "日本語",
"docsPath": "ja",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
},
"tr": {
"file": "readme/README.tr.md",
"label": "Türkçe",
"docsPath": "tr",
- "sourceSha256": "20eebe786feb7ef23f4488beae3aa30134d64ba2e26bafd1b7bca19b226bf776"
+ "sourceSha256": "4b8346eb370744ca0128f926279e1b468cc5bfe6eb066d7788de5cc3950525dd"
}
}
}
diff --git a/scripts/build-macos-app.sh b/scripts/build-macos-app.sh
new file mode 100755
index 00000000000..8dcac03ee18
--- /dev/null
+++ b/scripts/build-macos-app.sh
@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Assembles OpenCodex.app by hand.
+#
+# No Xcode project, so there is nothing to keep in sync with the package manifest. The
+# bundle is staged in a temp directory and moved into place at the end, so an interrupted
+# build never leaves a half-written .app that launches and misbehaves.
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/.." && pwd)"
+package_dir="$repo_root/app"
+output_root="${OUTPUT_DIR:-$repo_root/dist/macos}"
+configuration="${CONFIGURATION:-release}"
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+ echo "build:macos requires macOS." >&2
+ exit 1
+fi
+
+# Validate BEFORE creating anything, so the script cannot leave a directory behind at a
+# path it then refuses to build into.
+#
+# `cd … && pwd` keeps LOGICAL paths on macOS, so a symlink inside the repository that
+# points elsewhere would satisfy the prefix check below and then be deleted for real.
+# Resolve physically: walk up to the nearest existing ancestor, resolve that, and
+# re-append the parts that do not exist yet.
+resolve_physical() {
+ local target="$1" part resolved
+ # Absolute-ise relative input against the caller's directory.
+ [[ "$target" = /* ]] || target="$PWD/$target"
+
+ # ORDER MATTERS, and getting it wrong has been a bypass twice.
+ #
+ # 1. Normalise lexically FIRST. Resolving physically first and normalising afterwards
+ # lets `..` reveal a symlink that is then never physically resolved — so
+ # /.missing/../some-symlink passed containment while pointing elsewhere.
+ # 2. THEN walk up to the nearest existing ancestor of the normalised path and resolve
+ # that with `pwd -P`, which follows any symlinks that survived normalisation.
+ #
+ # Iteration is over a quoted array, never `for part in $tail`: word splitting there
+ # let a literal glob such as `rel*` expand against the filesystem.
+ local -a parts=() stack=()
+ local IFS=/
+ read -r -a parts <<< "$target"
+ unset IFS
+
+ for part in "${parts[@]}"; do
+ case "$part" in
+ "" | ".") continue ;;
+ "..")
+ # `unset 'stack[-1]'` is a bad subscript in bash 3.2 (what macOS ships), so it
+ # silently failed and `..` was never applied. Compute the index instead.
+ if [[ ${#stack[@]} -gt 0 ]]; then
+ unset "stack[$(( ${#stack[@]} - 1 ))]"
+ stack=("${stack[@]}")
+ fi
+ ;;
+ *) stack+=("$part") ;;
+ esac
+ done
+
+ # Now resolve physically, component by component, so a symlink ANYWHERE along the
+ # surviving path is followed — including one that only became reachable because a
+ # `..` removed a non-existent parent above it.
+ #
+ # Resolving only the nearest existing ancestor is not enough: for
+ # /.missing/../outward-link the ancestor is , and the trailing
+ # `outward-link` symlink was re-appended unresolved and never followed.
+ resolved="/"
+ for part in "${stack[@]}"; do
+ local candidate="${resolved%/}/$part"
+ if [[ -L "$candidate" && ! -d "$candidate" ]]; then
+ # A symlink that is not a directory: dangling, or pointing at a file. Following it
+ # lexically was the third bypass here — a link to `../../outside` produced
+ # `/../../outside`, which satisfied the `/*` prefix check and then
+ # escaped during `mkdir -p`. There is no legitimate reason for OUTPUT_DIR to pass
+ # through such a link, so refuse instead of trying to be clever.
+ echo "Refusing to build through '$candidate': it is a symlink that does not" >&2
+ echo "resolve to an existing directory." >&2
+ exit 1
+ fi
+ if [[ -d "$candidate" ]]; then
+ # `cd … && pwd -P` follows the symlink and any chain behind it.
+ resolved="$(cd "$candidate" && pwd -P)"
+ else
+ resolved="${resolved%/}/$part"
+ fi
+ done
+ printf '%s' "$resolved"
+}
+
+output_root="$(resolve_physical "$output_root")"
+app_bundle="$output_root/OpenCodex.app"
+
+# The build deletes whatever sits at $app_bundle, so the destination must be somewhere
+# this project owns. Comparing $app_bundle against $output_root proves nothing — both
+# come from the same variable, so pointing OUTPUT_DIR at /Applications would have passed
+# and then recursively removed a real app.
+allowed_root="$(cd "$repo_root" && pwd -P)"
+if [[ -n "${TMPDIR:-}" ]]; then
+ allowed_tmp="$(cd "${TMPDIR%/}" 2>/dev/null && pwd -P || echo "")"
+else
+ allowed_tmp=""
+fi
+case "$output_root" in
+ "$allowed_root"/*) ;;
+ /private/tmp/*|/tmp/*) ;;
+ *)
+ if [[ -z "$allowed_tmp" || "$output_root" != "$allowed_tmp"/* ]]; then
+ echo "Refusing to build into '$output_root': it is outside the repository and the" >&2
+ echo "temp directory. Set OUTPUT_DIR to a path under $repo_root." >&2
+ exit 1
+ fi
+ ;;
+esac
+
+mkdir -p "$output_root"
+
+swift_args=(--package-path "$package_dir" -c "$configuration" --product OpenCodexMenuBar)
+widget_swift_args=(--package-path "$package_dir" -c "$configuration" --product OpenCodexWidget)
+
+if [[ "${UNIVERSAL:-0}" == "1" ]]; then
+ developer_dir="$(xcode-select -p 2>/dev/null || true)"
+ if [[ "$developer_dir" == *"CommandLineTools"* ]]; then
+ echo "UNIVERSAL=1 requires the full Xcode toolchain; Command Line Tools ships only" >&2
+ echo "current-architecture Swift compatibility libraries, so the x86_64 slice cannot" >&2
+ echo "link. Install Xcode, then:" >&2
+ echo " sudo xcode-select -s /Applications/Xcode.app/Contents/Developer" >&2
+ exit 1
+ fi
+ swift_args+=(--arch arm64 --arch x86_64)
+ widget_swift_args+=(--arch arm64 --arch x86_64)
+fi
+
+echo "==> Building ($configuration)…"
+swift build "${swift_args[@]}"
+swift build "${widget_swift_args[@]}"
+bin_dir="$(swift build "${swift_args[@]}" --show-bin-path)"
+executable="$bin_dir/OpenCodexMenuBar"
+widget_bin_dir="$(swift build "${widget_swift_args[@]}" --show-bin-path)"
+widget_executable="$widget_bin_dir/OpenCodexWidget"
+
+if [[ ! -x "$executable" ]]; then
+ echo "Build did not produce an executable at $executable" >&2
+ exit 1
+fi
+if [[ ! -x "$widget_executable" ]]; then
+ echo "Build did not produce an executable at $widget_executable" >&2
+ exit 1
+fi
+
+staging_root="$(mktemp -d "$output_root/.OpenCodex-build.XXXXXX")"
+staged_app="$staging_root/OpenCodex.app"
+iconset="$staging_root/OpenCodex.iconset"
+cleanup() { rm -rf "$staging_root"; }
+trap cleanup EXIT
+
+mkdir -p "$staged_app/Contents/MacOS" "$staged_app/Contents/Resources"
+cp "$executable" "$staged_app/Contents/MacOS/OpenCodexMenuBar"
+cp "$package_dir/Info.plist" "$staged_app/Contents/Info.plist"
+appex="$staged_app/Contents/PlugIns/OpenCodexWidget.appex"
+mkdir -p "$appex/Contents/MacOS"
+cp "$widget_executable" "$appex/Contents/MacOS/OpenCodexWidget"
+cp "$package_dir/Widget-Info.plist" "$appex/Contents/Info.plist"
+
+# The app version comes from package.json, so it can never claim a version the release
+# did not ship.
+version="$(sed -n 's/^[[:space:]]*"version": "\([^"]*\)",/\1/p' "$repo_root/package.json" | head -n 1)"
+if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+ echo "Could not read a valid version from package.json: '$version'" >&2
+ exit 1
+fi
+
+# Apple constrains BOTH version fields, and differently from the npm version string:
+#
+# CFBundleShortVersionString - three period-separated integers. A prerelease suffix
+# like "-preview.1" is not valid here.
+# CFBundleVersion - ONE TO THREE period-separated integers. A fourth
+# component is ignored, so appending a build number to a
+# full semver produces no additional identity at all.
+#
+# So the short version is the numeric core, and when CI supplies a run number it becomes
+# the CFBundleVersion outright — a monotonically increasing single integer is both valid
+# and genuinely distinguishing, which "2.7.36." would not have been.
+version_core="${version%%-*}"
+if [[ ! "$version_core" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "Version core must be three integers for CFBundleShortVersionString: '$version_core'" >&2
+ exit 1
+fi
+
+if [[ -n "${MACOS_BUILD_NUMBER:-}" ]]; then
+ if [[ ! "$MACOS_BUILD_NUMBER" =~ ^[0-9]+$ ]]; then
+ echo "MACOS_BUILD_NUMBER must be a positive integer, got '$MACOS_BUILD_NUMBER'" >&2
+ exit 1
+ fi
+ build_version="$MACOS_BUILD_NUMBER"
+else
+ build_version="$version_core"
+fi
+if [[ ! "$build_version" =~ ^[0-9]+(\.[0-9]+){0,2}$ ]]; then
+ echo "CFBundleVersion must be one to three integers, got '$build_version'" >&2
+ exit 1
+fi
+
+plutil -replace CFBundleShortVersionString -string "$version_core" "$staged_app/Contents/Info.plist"
+plutil -replace CFBundleVersion -string "$build_version" "$staged_app/Contents/Info.plist"
+plutil -replace CFBundleShortVersionString -string "$version_core" "$appex/Contents/Info.plist"
+plutil -replace CFBundleVersion -string "$build_version" "$appex/Contents/Info.plist"
+
+# Icon: reuse the dashboard favicon rather than adding another binary asset to the repo.
+icon_source="$repo_root/gui/public/favicon.png"
+if [[ ! -f "$icon_source" ]]; then
+ echo "Missing icon source: $icon_source" >&2
+ exit 1
+fi
+mkdir -p "$iconset"
+for size in 16 32 128 256 512; do
+ sips -z "$size" "$size" "$icon_source" \
+ --out "$iconset/icon_${size}x${size}.png" >/dev/null
+ sips -z "$((size * 2))" "$((size * 2))" "$icon_source" \
+ --out "$iconset/icon_${size}x${size}@2x.png" >/dev/null
+done
+iconutil -c icns "$iconset" -o "$staged_app/Contents/Resources/OpenCodex.icns"
+
+# Signing.
+#
+# MACOS_SIGN_IDENTITY selects a Developer ID Application certificate already present in
+# the caller's keychain and enables the hardened runtime, which is what notarization
+# requires. It is a LOCAL hook: CI does not set it, because an identity name alone
+# cannot sign on a hosted runner — nothing imports the certificate and private key, so
+# codesign fails with "no identity found". Wiring CI signing properly means a protected
+# P12 import, a temporary keychain, notarytool credentials, and stapling.
+#
+# Without it the bundle is ad-hoc signed: structurally valid, but `spctl --assess`
+# rejects it and a downloaded copy shows "cannot be opened because the developer cannot
+# be verified". The project has no Developer ID certificate today, so ad-hoc is what
+# ships and the docs must carry the right-click-Open path rather than pretend
+# otherwise.
+#
+# The widget reads the host snapshot through its own bundle container fallback path.
+# App Groups require a team-ID-prefixed group and a Developer ID / team-signed extension;
+# ad-hoc signatures cannot satisfy that requirement, so the widget uses its own container.
+if [[ -n "${MACOS_SIGN_IDENTITY:-}" ]]; then
+ codesign --force --options runtime --timestamp \
+ --entitlements "$package_dir/Widget.entitlements" \
+ --sign "$MACOS_SIGN_IDENTITY" "$appex"
+ codesign --force --deep --options runtime --timestamp \
+ --sign "$MACOS_SIGN_IDENTITY" "$staged_app"
+ echo "==> Signed with $MACOS_SIGN_IDENTITY (hardened runtime)"
+else
+ codesign --force --sign - --entitlements "$package_dir/Widget.entitlements" \
+ --timestamp=none "$appex"
+ codesign --force --sign - --timestamp=none "$staged_app"
+ echo "==> Ad-hoc signed (no MACOS_SIGN_IDENTITY): Gatekeeper will require the" >&2
+ echo " right-click-Open path on first launch." >&2
+fi
+
+if [[ -L "$app_bundle" ]]; then
+ echo "Refusing to replace '$app_bundle': it is a symlink." >&2
+ exit 1
+fi
+rm -rf "$app_bundle"
+mv "$staged_app" "$app_bundle"
+
+echo "==> Built $app_bundle (release $version, short $version_core, build $build_version)"
+lipo -archs "$app_bundle/Contents/MacOS/OpenCodexMenuBar"
+lipo -archs "$app_bundle/Contents/PlugIns/OpenCodexWidget.appex/Contents/MacOS/OpenCodexWidget"
diff --git a/scripts/package-macos-release.sh b/scripts/package-macos-release.sh
new file mode 100755
index 00000000000..f9b0b1ebd89
--- /dev/null
+++ b/scripts/package-macos-release.sh
@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Wraps OpenCodex.app for distribution.
+#
+# Every step is an assertion rather than a hope: a release asset that is produced but
+# empty, unsigned, or missing its executable is worse than no asset at all, because the
+# failure surfaces on the user's machine instead of in CI.
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$script_dir/.." && pwd)"
+output_dir="${RELEASE_OUTPUT_DIR:-$repo_root/dist/release}"
+universal="${UNIVERSAL:-1}"
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+ echo "package:macos requires macOS." >&2
+ exit 1
+fi
+
+package_version="$(sed -n 's/^[[:space:]]*"version": "\([^"]*\)",/\1/p' "$repo_root/package.json" | head -n 1)"
+if [[ ! "$package_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+ echo "Invalid package version for the macOS release asset: '$package_version'" >&2
+ exit 1
+fi
+
+# A release dispatched for one version must never package a different one.
+if [[ -n "${RELEASE_VERSION:-}" && "$RELEASE_VERSION" != "$package_version" ]]; then
+ echo "package.json ($package_version) does not match the requested release (${RELEASE_VERSION})" >&2
+ exit 1
+fi
+
+if [[ "$universal" != "0" && "$universal" != "1" ]]; then
+ echo "UNIVERSAL must be 0 or 1." >&2
+ exit 1
+fi
+
+mkdir -p "$output_dir"
+output_dir="$(cd "$output_dir" && pwd)"
+
+build_root="$(mktemp -d "${TMPDIR:-/tmp}/OpenCodex-release.XXXXXX")"
+cleanup() { rm -rf "$build_root"; }
+trap cleanup EXIT
+
+OUTPUT_DIR="$build_root" UNIVERSAL="$universal" CONFIGURATION=release \
+ bash "$script_dir/build-macos-app.sh" >&2
+
+app_bundle="$build_root/OpenCodex.app"
+executable="$app_bundle/Contents/MacOS/OpenCodexMenuBar"
+
+codesign --verify --deep --strict --verbose=2 "$app_bundle"
+
+# Report the Gatekeeper verdict rather than discovering it on a user's machine. An
+# ad-hoc build is expected to be rejected; that is documented, not a packaging failure.
+# A build that claimed a real identity and STILL fails assessment is a failure.
+if spctl --assess --type execute "$app_bundle" >/dev/null 2>&1; then
+ echo "==> Gatekeeper: accepted" >&2
+else
+ if [[ -n "${MACOS_SIGN_IDENTITY:-}" ]]; then
+ echo "Signed with $MACOS_SIGN_IDENTITY but Gatekeeper still rejects the bundle." >&2
+ echo "It likely needs notarization (notarytool) and a stapled ticket." >&2
+ exit 1
+ fi
+ echo "==> Gatekeeper: rejected (expected for an ad-hoc signature)." >&2
+ echo " Users must right-click > Open on first launch; this is documented." >&2
+fi
+
+architectures="$(lipo -archs "$executable")"
+if [[ "$universal" == "1" ]]; then
+ for required_arch in arm64 x86_64; do
+ if [[ " $architectures " != *" $required_arch "* ]]; then
+ echo "Universal build is missing $required_arch (got: $architectures)" >&2
+ exit 1
+ fi
+ done
+ architecture_label="universal"
+else
+ architecture_label="${architectures// /-}"
+fi
+
+archive_name="OpenCodex-${package_version}-macos-${architecture_label}.zip"
+checksum_name="${archive_name}.sha256"
+archive_path="$output_dir/$archive_name"
+checksum_path="$output_dir/$checksum_name"
+rm -f "$archive_path" "$checksum_path"
+
+# ditto rather than zip: it preserves extended attributes and symlinks, so the unpacked
+# bundle stays launchable. Plain zip corrupts the code signature.
+ditto -c -k --sequesterRsrc --keepParent "$app_bundle" "$archive_path"
+
+# An archive that exists but does not contain the executable is the failure mode this
+# assertion exists to catch.
+archive_entries="$(unzip -Z1 "$archive_path")"
+if ! grep -Fqx 'OpenCodex.app/Contents/MacOS/OpenCodexMenuBar' <<< "$archive_entries"; then
+ echo "Packaged archive does not contain the OpenCodex executable." >&2
+ echo "Archive entries were:" >&2
+ printf '%s\n' "$archive_entries" | head -20 >&2
+ exit 1
+fi
+
+(
+ cd "$output_dir"
+ shasum -a 256 "$archive_name" > "$checksum_name"
+)
+
+if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+ {
+ echo "archive_name=$archive_name"
+ echo "checksum_name=$checksum_name"
+ } >> "$GITHUB_OUTPUT"
+fi
+
+echo "$archive_path"
+echo "$checksum_path"
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index f9d1fe63007..37969710498 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -167,6 +167,7 @@
}
},
"explicit": {
+ "macos-build-script.test.ts": "gui",
"server-combo-held-response.test.ts": "server",
"key-attribution.test.ts": "usage",
"provider-send-path-import.test.ts": "server",
@@ -189,6 +190,7 @@
"hub-usage.test.ts": "server",
"client-hub-usage.test.ts": "clients",
"cli-usage-hub.test.ts": "cli",
+ "cli-companion.test.ts": "cli",
"abort-idle-deadline.test.ts": "lib",
"abort-race.test.ts": "adapters",
"account-import.test.ts": "server",
@@ -1581,6 +1583,8 @@
"management-google-tool-schema-policy.test.ts": "server",
"codex-shim-destroyed-probe.test.ts": "codex-integration",
"client-runtime.test.ts": "clients",
+ "usage-timeline.test.ts": "usage",
+ "companion-settings.test.ts": "server",
"chat-tool-choice-allowed-tools.test.ts": "responses",
"anthropic-tool-declaration-constraints.test.ts": "adapters/anthropic",
"google-strict-tool-validated-mode.test.ts": "adapters/google",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index 78d2047d1aa..4918176da31 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -537,6 +537,25 @@ JSON mode: `payload`.
- `store` verifies every keychain write by read-back before config.json is rewritten with keychain: references; an unavailable keychain refuses with 503 and leaves the file untouched.
- Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.
+### `ocx companion`
+
+Inspect and configure menu-bar and widget companion usage settings.
+
+| Method | Route |
+|---|---|
+| GET | `/api/companion/settings` |
+| GET | `/api/usage/timeline` |
+| PUT | `/api/companion/settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--json` | boolean | Emit companion settings as JSON. |
+
+JSON mode: `payload`.
+
+- `show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.
+- Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.
+
### `ocx account main reauth`
Reauthenticate the native main Codex login with a device code (#3898); headless hubs need no Codex App or keyring.
@@ -896,6 +915,6 @@ JSON mode: `payload`.
## Counts
-- declared capabilities: 48
-- of those, state-changing: 24
+- declared capabilities: 49
+- of those, state-changing: 25
- head-resolved invocations: 2
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index e67390041b9..f651183d053 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -314,6 +314,22 @@ export const CAPABILITIES: readonly Capability[] = [
"Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
],
},
+ {
+ command: ["companion"],
+ summary: "Inspect and configure menu-bar and widget companion usage settings.",
+ routes: [
+ { method: "GET", path: "/api/companion/settings" },
+ { method: "GET", path: "/api/usage/timeline" },
+ { method: "PUT", path: "/api/companion/settings" },
+ ],
+ flags: [{ name: "--json", value: "boolean", summary: "Emit companion settings as JSON." }],
+ mutates: true,
+ json: "payload",
+ details: [
+ "`show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.",
+ "Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.",
+ ],
+ },
{
command: ["account", "history"],
summary: "Cached quota observations for one stored Codex pool account.",
diff --git a/src/cli/companion.ts b/src/cli/companion.ts
new file mode 100644
index 00000000000..2b24258fcc3
--- /dev/null
+++ b/src/cli/companion.ts
@@ -0,0 +1,56 @@
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+ ocx companion [show] [--json]
+ ocx companion set = [...] [--json]
+ ocx companion reset [--json]`;
+
+function parseValue(raw: string): unknown {
+ if (raw === "null") return null;
+ try { return JSON.parse(raw); } catch { return raw; }
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise {
+ const args = [...argv];
+ const wantsJson = takeFlag(args, "--json");
+ rejectArgs(args, USAGE);
+ printData(await runtimeRequest("/api/companion/settings", {}, deps), wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise {
+ const args = [...argv];
+ const wantsJson = takeFlag(args, "--json");
+ if (args.length === 0) throw new CliUsageError("companion set requires key=value assignments", USAGE);
+ const patch: Record = {};
+ for (const assignment of args) {
+ const separator = assignment.indexOf("=");
+ if (separator <= 0) throw new CliUsageError(`invalid companion setting "${assignment}"; use key=value`, USAGE);
+ patch[assignment.slice(0, separator)] = parseValue(assignment.slice(separator + 1));
+ }
+ printData(await runtimeRequest("/api/companion/settings", {
+ method: "PUT",
+ body: JSON.stringify({ settings: patch }),
+ }, deps), wantsJson, ["Companion settings saved."]);
+}
+
+async function reset(argv: string[], deps: RuntimeApiDeps): Promise {
+ const args = [...argv];
+ const wantsJson = takeFlag(args, "--json");
+ rejectArgs(args, USAGE);
+ printData(await runtimeRequest("/api/companion/settings", {
+ method: "PUT",
+ body: JSON.stringify({ reset: true }),
+ }, deps), wantsJson, ["Companion settings reset."]);
+}
+
+export async function handleCompanionCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise {
+ 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);
+ else throw new CliUsageError(`unknown companion command ${sub}`, USAGE);
+ });
+}
+
+export const COMPANION_USAGE = USAGE;
diff --git a/src/cli/dispatch.ts b/src/cli/dispatch.ts
index b9b09420c87..beb3170d992 100644
--- a/src/cli/dispatch.ts
+++ b/src/cli/dispatch.ts
@@ -786,6 +786,10 @@ const commandRunners: Record = {
const { handleComboCommand } = await import("./combo");
return await handleComboCommand(deps.args.slice(1));
},
+ companion: async deps => {
+ const { handleCompanionCommand } = await import("./companion");
+ return await handleCompanionCommand(deps.args.slice(1));
+ },
route: async deps => {
if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
console.error("Usage: ocx route ");
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 0be199f1a5a..da5450880b4 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -89,6 +89,7 @@ Usage:
ocx grok Grok Build model selection and apply
ocx system Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
ocx config Validated configuration show/get/set/import/export
+ ocx companion Menu-bar and widget companion usage settings
ocx lab Read-only Compatibility Lab projection inspection
ocx claude [args...] Launch Claude Code wired to the proxy (model discovery on)
ocx claude desktop [sub] Manage and apply Claude Desktop's four-family profile
diff --git a/src/cli/registry.ts b/src/cli/registry.ts
index f9b9d95d969..85c2d660310 100644
--- a/src/cli/registry.ts
+++ b/src/cli/registry.ts
@@ -298,6 +298,16 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
usage: "ocx model ",
summary: "Alias of ocx models.",
},
+ {
+ name: "companion",
+ usage: "ocx companion ...",
+ summary: "Inspect and configure menu-bar and widget companion usage settings.",
+ details: [
+ "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
+ "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
+ "ocx companion reset restores the default settings.",
+ ],
+ },
{
name: "combo",
usage: "ocx combo ...",
diff --git a/src/companion/settings.ts b/src/companion/settings.ts
new file mode 100644
index 00000000000..c838285b6fe
--- /dev/null
+++ b/src/companion/settings.ts
@@ -0,0 +1,131 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import {
+ TIMELINE_HOURS,
+ type TimelineAggregation,
+ type TimelineGrouping,
+ type TimelineMetric,
+} from "../usage/timeline";
+
+export interface CompanionSettings {
+ menuBarMetric: "requests" | "tokens" | "cost" | "quota" | "none";
+ menuBarTemplate: string | null;
+ showToday: boolean;
+ showChart: boolean;
+ showModels: boolean;
+ showCost: boolean;
+ showAccounts: boolean;
+ chartHours: typeof TIMELINE_HOURS[number];
+ bucketMinutes: number;
+ chartStyle: "line" | "stackedBar";
+ tokenMetric: TimelineMetric;
+ aggregation: TimelineAggregation;
+ chartGrouping: TimelineGrouping;
+ models: string[] | null;
+ hiddenProviders: string[];
+}
+
+export const DEFAULT_COMPANION_SETTINGS: CompanionSettings = {
+ menuBarMetric: "tokens",
+ menuBarTemplate: null,
+ showToday: true,
+ showChart: true,
+ showModels: true,
+ showCost: true,
+ showAccounts: true,
+ chartHours: 24,
+ bucketMinutes: 60,
+ chartStyle: "line",
+ tokenMetric: "total",
+ aggregation: "sum",
+ chartGrouping: "model",
+ models: null,
+ hiddenProviders: [],
+};
+
+const TEMPLATE_FIELDS = new Set(["requests", "totalTokens", "inputTokens", "outputTokens", "costUsd", "quotaPercent"]);
+const MENU_BAR_METRICS = new Set(["requests", "tokens", "cost", "quota", "none"]);
+const CHART_STYLES = new Set(["line", "stackedBar"]);
+const TIMELINE_METRICS = new Set(["total", "input", "output", "cached"]);
+const AGGREGATIONS = new Set(["sum", "average", "max"]);
+const GROUPINGS = new Set(["model", "modelAccount"]);
+const SETTINGS_KEYS = Object.keys(DEFAULT_COMPANION_SETTINGS) as (keyof CompanionSettings)[];
+
+export function companionSettingsPath(): string {
+ return join(getConfigDir(), "companion.json");
+}
+
+function invalid(message: string): { error: string } {
+ return { error: message };
+}
+
+function validModels(value: unknown, key: string): value is string[] | null {
+ return value === null
+ || (Array.isArray(value)
+ && value.length <= 100
+ && value.every(model => typeof model === "string" && /^[^/\s]+\/[^/\s]+$/.test(model)));
+}
+
+function validateValue(key: keyof CompanionSettings, value: unknown): string | null {
+ if (key === "menuBarMetric") return typeof value === "string" && MENU_BAR_METRICS.has(value) ? null : "menuBarMetric is invalid";
+ if (key === "menuBarTemplate") {
+ if (value === null) return null;
+ if (typeof value !== "string" || value.length > 200) return "menuBarTemplate must be null or at most 200 characters";
+ for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+ if (!TEMPLATE_FIELDS.has(match[1]!)) return `menuBarTemplate contains unknown placeholder: ${match[1]}`;
+ }
+ return null;
+ }
+ if (["showToday", "showChart", "showModels", "showCost", "showAccounts"].includes(key)) {
+ return typeof value === "boolean" ? null : `${key} must be a boolean`;
+ }
+ if (key === "chartHours") return TIMELINE_HOURS.includes(value as typeof TIMELINE_HOURS[number]) ? null : "chartHours is invalid";
+ if (key === "bucketMinutes") return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 1440 ? null : "bucketMinutes must be an integer from 1 through 1440";
+ if (key === "chartStyle") return typeof value === "string" && CHART_STYLES.has(value) ? null : "chartStyle is invalid";
+ if (key === "tokenMetric") return typeof value === "string" && TIMELINE_METRICS.has(value) ? null : "tokenMetric is invalid";
+ if (key === "aggregation") return typeof value === "string" && AGGREGATIONS.has(value) ? null : "aggregation is invalid";
+ if (key === "chartGrouping") return typeof value === "string" && GROUPINGS.has(value) ? null : "chartGrouping is invalid";
+ if (key === "models") return validModels(value, key) ? null : "models must be null or at most 100 provider/model identifiers";
+ if (key === "hiddenProviders") return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/\s/.test(item))
+ ? null : "hiddenProviders must contain at most 100 provider names";
+ return `${key} is unsupported`;
+}
+
+export function applyCompanionSettingsPatch(
+ current: CompanionSettings,
+ patch: unknown,
+): CompanionSettings | { error: string } {
+ if (!patch || typeof patch !== "object" || Array.isArray(patch)) return invalid("settings must be an object");
+ const values = patch as Record;
+ for (const key of Object.keys(values)) {
+ if (!SETTINGS_KEYS.includes(key as keyof CompanionSettings)) return invalid(`unknown settings key: ${key}`);
+ const error = validateValue(key as keyof CompanionSettings, values[key]);
+ if (error) return invalid(error);
+ }
+ return { ...current, ...values } as CompanionSettings;
+}
+
+export function loadCompanionSettings(): { settings: CompanionSettings; updatedAt: number | null; corrupt?: true } {
+ const path = companionSettingsPath();
+ if (!existsSync(path)) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null };
+ try {
+ const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+ const settings = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, parsed);
+ if ("error" in settings) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+ return { settings, updatedAt: statSync(path).mtimeMs };
+ } catch {
+ return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+ }
+}
+
+export function saveCompanionSettings(settings: CompanionSettings): void {
+ const path = companionSettingsPath();
+ const dir = getConfigDir();
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+ const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+ writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+ chmodSync(temp, 0o600);
+ renameSync(temp, path);
+ chmodSync(path, 0o600);
+}
diff --git a/src/server/management-api.ts b/src/server/management-api.ts
index 7c8766367c2..dbd5d7345d6 100644
--- a/src/server/management-api.ts
+++ b/src/server/management-api.ts
@@ -71,6 +71,8 @@ import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
import { handleComboRoutes } from "./management/combo-routes";
import { handleSystemRoutes } from "./management/system-routes";
import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleUsageTimelineRoutes } from "./management/usage-timeline-routes";
+import { handleCompanionRoutes } from "./management/companion-routes";
import { handleCodexPromptRoutes } from "./management/codex-prompt-routes";
import { handleIntegrationRoutes } from "./management/integration-routes";
import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -266,7 +268,7 @@ export async function handleManagementAPI(
} catch { /* best-effort */ }
}
const ctx: ManagementContext = { req, url, config, deps, version: VERSION, principal, sessionControl, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
- let routed: Response | null;
+ let routed: Response | null | undefined;
try {
routed = handleSessionRoutes(ctx)
?? (await handleRemoteWorkspaceRoutesOnDemand(ctx))
@@ -291,6 +293,8 @@ export async function handleManagementAPI(
?? (await handleComboRoutes(ctx))
?? (await handleSystemRoutes(ctx))
?? (await handleLabRoutesOnDemand(ctx))
+ ?? (await handleUsageTimelineRoutes(ctx))
+ ?? (await handleCompanionRoutes(ctx))
?? (await handleSidebarRoutes(ctx));
} catch (error) {
const tooLarge = managementBodyTooLargeResponse(error, req, config);
diff --git a/src/server/management/companion-routes.ts b/src/server/management/companion-routes.ts
new file mode 100644
index 00000000000..df0fd8ab6de
--- /dev/null
+++ b/src/server/management/companion-routes.ts
@@ -0,0 +1,53 @@
+import {
+ applyCompanionSettingsPatch,
+ DEFAULT_COMPANION_SETTINGS,
+ loadCompanionSettings,
+ saveCompanionSettings,
+} from "../../companion/settings";
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+
+let companionLastSeenAt: number | null = null;
+
+export function resetCompanionPresenceForTests(): void {
+ companionLastSeenAt = null;
+}
+
+function response(): Response {
+ const loaded = loadCompanionSettings();
+ return jsonResponse({
+ settings: loaded.settings,
+ updatedAt: loaded.updatedAt,
+ defaults: DEFAULT_COMPANION_SETTINGS,
+ companion: { lastSeenAt: companionLastSeenAt },
+ ...(loaded.corrupt ? { corrupt: true } : {}),
+ });
+}
+
+export async function handleCompanionRoutes(ctx: ManagementContext): Promise {
+ if (ctx.url.pathname === "/api/companion/settings" && ctx.req.method === "GET") {
+ if (ctx.req.headers.get("user-agent")?.startsWith("OpenCodexMenuBar/")) companionLastSeenAt = Date.now();
+ return response();
+ }
+ if (ctx.url.pathname !== "/api/companion/settings" || ctx.req.method !== "PUT") return null;
+ let body: unknown;
+ try {
+ body = await readManagementJsonBody(ctx.req);
+ } catch (error) {
+ rethrowManagementBodyTooLarge(error);
+ return jsonResponse({ error: "invalid JSON body" }, 400, ctx.req, ctx.config);
+ }
+ if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid settings body" }, 400, ctx.req, ctx.config);
+ const input = body as { reset?: unknown; settings?: unknown };
+ if (input.reset === true) {
+ saveCompanionSettings(DEFAULT_COMPANION_SETTINGS);
+ return response();
+ }
+ if (!("settings" in input)) return jsonResponse({ error: "provide settings or reset:true" }, 400, ctx.req, ctx.config);
+ const current = loadCompanionSettings().settings;
+ const updated = applyCompanionSettingsPatch(current, input.settings);
+ if ("error" in updated) return jsonResponse(updated, 400, ctx.req, ctx.config);
+ saveCompanionSettings(updated);
+ return response();
+}
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index 95dc71be749..fbaafcb5d36 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -240,6 +240,11 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
{ method: "GET", path: "/api/storage/trash", module: "server/management/logs-usage-routes", mutates: false },
{ method: "GET", path: "/api/storage/trash/restore/test-stream", module: "server/management/logs-usage-routes", mutates: false, exempt: { reason: "test-seam", why: "Opt-in streaming seam declared at src/storage/restore-job.ts:34." } },
{ method: "GET", path: "/api/usage", module: "server/management/logs-usage-routes", mutates: false },
+ // server/management/usage-timeline-routes
+ { method: "GET", path: "/api/usage/timeline", module: "server/management/usage-timeline-routes", mutates: false },
+ // server/management/companion-routes
+ { method: "GET", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: false },
+ { method: "PUT", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: true },
{ method: "POST", path: "/api/storage/cleanup", module: "server/management/logs-usage-routes", mutates: true },
{ method: "POST", path: "/api/storage/cleanup-policy/run", module: "server/management/logs-usage-routes", mutates: true },
{ method: "POST", path: "/api/storage/cleanup/preview", module: "server/management/logs-usage-routes", mutates: true },
diff --git a/src/server/management/usage-timeline-routes.ts b/src/server/management/usage-timeline-routes.ts
new file mode 100644
index 00000000000..d4f04c37186
--- /dev/null
+++ b/src/server/management/usage-timeline-routes.ts
@@ -0,0 +1,44 @@
+import { readUsageSnapshotForManagement } from "../../usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../usage/timeline";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+const TIMELINE_CACHE_TTL_MS = 15_000;
+const cache = new Map["finish"]>> }>();
+
+export async function handleUsageTimelineRoutes(ctx: ManagementContext): Promise {
+ const { req, url } = ctx;
+ if (url.pathname !== "/api/usage/timeline" || req.method !== "GET") return undefined;
+ const query = parseTimelineQuery(url.searchParams, Date.now());
+ if ("error" in query) return jsonResponse(query, 400, req, ctx.config);
+ const bucketMs = query.bucketMinutes * 60_000;
+ const roundedNow = Math.floor(query.now / bucketMs) * bucketMs;
+ const normalized = { ...query, now: roundedNow };
+ const key = JSON.stringify(normalized);
+ const current = Date.now();
+ const cached = cache.get(key);
+ if (cached && cached.expiresAt > current) return jsonResponse(await cached.promise, 200, req, ctx.config);
+ let promise: Promise["finish"]>>;
+ promise = (async () => {
+ const accumulator = createTimelineAccumulator(normalized);
+ const snapshot = await readUsageSnapshotForManagement(ctx.config.managementUsageMaxReadBytes);
+ for (const entry of snapshot.entries) accumulator.add(entry);
+ return {
+ ...accumulator.finish(),
+ truncated: snapshot.truncatedPrefixBytes > 0 || snapshot.entriesTruncated,
+ };
+ })().catch(error => {
+ const entry = cache.get(key);
+ if (entry?.promise === promise) cache.delete(key);
+ throw error;
+ });
+ cache.set(key, { expiresAt: current + TIMELINE_CACHE_TTL_MS, promise });
+ try {
+ return jsonResponse(await promise, 200, req, ctx.config);
+ } finally {
+ setTimeout(() => {
+ const entry = cache.get(key);
+ if (entry?.promise === promise && entry.expiresAt <= Date.now()) cache.delete(key);
+ }, TIMELINE_CACHE_TTL_MS + 1);
+ }
+}
diff --git a/src/usage/summary.ts b/src/usage/summary.ts
index b1468fd1258..091dac17632 100644
--- a/src/usage/summary.ts
+++ b/src/usage/summary.ts
@@ -410,7 +410,7 @@ function isMeasuredStatus(status: UsageStatus): boolean {
return status === "reported" || status === "estimated";
}
-interface UsageAttribution {
+export interface UsageAttribution {
requestId: string;
provider: string;
model: string;
@@ -454,7 +454,7 @@ function usageModelKey(providerKey: string, model: string): string {
return `${providerKey}\0${model}`;
}
-function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
+export function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
if (!entry.attempts?.length) {
return [{
requestId: entry.requestId,
diff --git a/src/usage/timeline.ts b/src/usage/timeline.ts
new file mode 100644
index 00000000000..af44587f512
--- /dev/null
+++ b/src/usage/timeline.ts
@@ -0,0 +1,219 @@
+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;
+ now: number;
+}
+
+export interface TimelineSeries {
+ id: string;
+ provider: string;
+ model: string;
+ accountLogLabel?: string;
+ total: number;
+ points: number[];
+}
+
+export interface UsageTimeline {
+ 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(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}` };
+}
+
+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 => !/^[^/\s]+\/[^/\s]+$/.test(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;
+ 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,
+ now,
+ };
+}
+
+interface SeriesState {
+ provider: string;
+ model: string;
+ accountLogLabel?: string;
+ points: number[];
+ requests: Map>;
+}
+
+function metricValue(metric: TimelineMetric, attribution: ReturnType[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 start = Math.floor((query.now - query.hours * 3_600_000) / 1000 / bucketSeconds) * bucketSeconds;
+ const buckets = Math.ceil(query.hours * 60 / query.bucketMinutes);
+ const end = start + buckets * bucketSeconds;
+ const startMs = start * 1000;
+ const endMs = end * 1000;
+ const series = new Map();
+ const availableModels = new Set();
+ 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)) {
+ 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(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(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 {
+ start,
+ end,
+ bucketSeconds,
+ buckets,
+ metric: query.metric,
+ aggregation: query.aggregation,
+ grouping: query.grouping,
+ series: kept,
+ availableModels: [...availableModels].sort(),
+ missingMeasurements,
+ truncated: false,
+ };
+ }
+
+ return { add, finish };
+}
diff --git a/structure/INDEX.md b/structure/INDEX.md
index cd101960def..40c82166e69 100644
--- a/structure/INDEX.md
+++ b/structure/INDEX.md
@@ -90,6 +90,7 @@ A source area can be described by more than one doc, because these docs are orga
| Source path | Described by |
| --- | --- |
| `.github/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
+| `app/` | [`overview.md`](overview.md) |
| `bin/` | [`runtime.md`](runtime.md)
[`ops/docs-and-release.md`](ops/docs-and-release.md) |
| `docs-site/` | [`ops/docs-and-release.md`](ops/docs-and-release.md) |
| `gui/` | [`overview.md`](overview.md)
[`gui-and-management-api.md`](gui-and-management-api.md)
[`design-methodology.md`](design-methodology.md) |
@@ -103,6 +104,7 @@ A source area can be described by more than one doc, because these docs are orga
| `src/clients/` | [`clients/integrations.md`](clients/integrations.md) |
| `src/codex/` | [`runtime.md`](runtime.md)
[`config.md`](config.md)
[`codex-home.md`](codex-home.md)
[`catalog.md`](catalog.md)
[`subagents.md`](subagents.md)
[`providers/openai-tiers.md`](providers/openai-tiers.md)
[`gui-and-management-api.md`](gui-and-management-api.md)
[`ops/docs-and-release.md`](ops/docs-and-release.md) |
| `src/combos/` | [`runtime.md`](runtime.md)
[`providers-and-adapters.md`](providers-and-adapters.md) |
+| `src/companion/` | [`overview.md`](overview.md)
[`gui-and-management-api.md`](gui-and-management-api.md) |
| `src/compatibility/` | [`runtime.md`](runtime.md)
[`adapters/compatibility-contracts.md`](adapters/compatibility-contracts.md) |
| `src/config.ts` | [`overview.md`](overview.md)
[`runtime.md`](runtime.md)
[`config.md`](config.md)
[`providers/openai-tiers.md`](providers/openai-tiers.md) |
| `src/config/` | [`runtime.md`](runtime.md)
[`config.md`](config.md) |
@@ -132,6 +134,7 @@ A source area can be described by more than one doc, because these docs are orga
| `src/types.ts` | [`runtime.md`](runtime.md)
[`config.md`](config.md) |
| `src/update/` | [`runtime.md`](runtime.md) |
| `src/usage/` | [`runtime.md`](runtime.md)
[`gui-and-management-api.md`](gui-and-management-api.md) |
+| `src/usage/timeline.ts` | [`gui-and-management-api.md`](gui-and-management-api.md) |
| `src/vision/` | [`runtime.md`](runtime.md)
[`gui-and-management-api.md`](gui-and-management-api.md) |
| `src/web-search/` | [`runtime.md`](runtime.md)
[`providers-and-adapters.md`](providers-and-adapters.md) |
diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
index 218df3838d5..47bd09d1cb2 100644
--- a/structure/gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -1,5 +1,9 @@
# GUI And Management API
+The companion settings contract in `src/companion/` persists menu-bar and widget display
+preferences, while `src/server/management/companion-routes.ts` exposes those settings and the
+usage timeline assembled by `src/usage/timeline.ts` to local clients.
+
Native result continuations and function-result injection follow [the mode-specific result and control contract](transports/streaming-health.md#experimental-native-function-result-injection); this surface does not infer upstream support or alter its defaults.
Explicit Codex CLI installation observation is a local CLI surface, not a management API or GUI update permission. See the [read-only observation contract](runtime.md#explicit-codex-cli-installation-observation).
@@ -142,7 +146,7 @@ this document owns is which module holds which area and what invariant that area
| Subagents | Read/write the featured `subagentModels` list capped at five ids. `GET/PUT /api/injection-model` manages the shared delegation model/effort selection, the independent OpenCodex guidance switch, and the default-off `syncCodexSubagentDefaults` opt-in for native Codex subagent defaults. When OpenCodex owns the active Codex routing, native `[agents]` defaults apply to newly created Codex tasks after sync/restart; external user-managed provider configs remain untouched. The defaults do not cause delegation and preserve existing user-owned defaults rather than overwriting them. PUT is partial-update: absent keys are unchanged, `null` clears, and non-object bodies are rejected with 400 before field validation. `syncCodexSubagentDefaults: true` requires a nonblank `model` and a supported Codex reasoning effort when effort is set; clearing `model` (null/empty) always clears effort and disables native-default sync even when the stored effort was invalid. |
| V2 / Multi-agent mode | `GET/PUT /api/v2` — reports/sets the codex `multi_agent_v2` feature flag, the 3-state `multiAgentMode` override (`v1`/`default`/`v2`), the `keepNativeChatGptOnV1` hybrid pin, and the logical maximum thread count. Selecting `v2` normally enables the native flag; with the hybrid pin it disables that global override so native rows can resolve to v1 while routed rows resolve to v2. Selecting `v1` disables the flag; `default` leaves it unchanged. PUT rejects an explicit enabled flag that conflicts with the selected mode or hybrid pin. Every transition preserves the logical thread limit, is rollback-safe, and resyncs the catalog. GET and successful PUT also return stored `multiAgentModeHintText` plus response-only `multiAgentModeHintRecommendation: { text, revision }`; the recommendation is not a writable or persisted config field. Both also return response-only `multiAgentSurfaceAdvisory: { required, mode, recommended, version, docsUrl }`, true while the resolved mode is not v1 and the stored acknowledgement version is behind; PUT accepts `multiAgentSurfaceAdvisoryAcknowledged`, where only `true` stores the current version and `false` is an explicit no-op, and it composes with a `multiAgentMode` write in the same body so the dialog's recommended answer is one request. |
| Logs & Debug | One sidebar entry (`/#logs`) with two tabs. Logs tab: request/runtime logs for local diagnosis. `LogsFilterBar` owns controls over the shared `LogFilterState`; `filterLogs` composes filters over the loaded ring. The logs envelope adds `generatedAt` (proxy epoch milliseconds); the page advances that sample with monotonic elapsed time and retains a browser-clock fallback for older proxies. Reset returns focus to the stable All surface radio. Provider/model options include attempts, model choices match normalized complete identities, and relative-time filtering refreshes every 30 seconds while the Logs tab is active, independently of network auto-refresh. Debug tab (`/#logs/debug`; legacy `/#debug` deep links redirect there): provider + usage toggles, refresh/follow log viewer. `GET/PUT /api/debug`; `GET /api/debug/logs` and `GET /api/debug/usage-logs` (monotonic `after` cursor, legacy `since` accepted). CLI: `ocx debug provider|usage …` (both streams via running proxy API). |
-| Usage | `GET /api/usage` read-only aggregates of readable rows from `~/.opencodex/usage.jsonl`; the ledger is streamed in fixed 1 MiB chunks, so the former read-byte and parsed-row caps cannot omit its prefix. Oversized skipped rows produce positive `usageIncomplete` metadata. The response includes measured / reported / unreported / unsupported / estimated counts, a daily zero-filled grid, and model and provider breakdowns. Never exposes prompts. |
+| Usage | `GET /api/usage` read-only aggregates of readable rows from `~/.opencodex/usage.jsonl`; the ledger is streamed in fixed 1 MiB chunks, so the former read-byte and parsed-row caps cannot omit its prefix. Oversized skipped rows produce positive `usageIncomplete` metadata. The response includes measured / reported / unreported / unsupported / estimated counts, a daily zero-filled grid, and model and provider breakdowns. `GET /api/usage/timeline` uses the same ledger and canonical attribution helpers for bounded bucketed model series. Never exposes prompts. |
| Request metrics | `GET /api/metrics` exposes process-local Prometheus text format v0.0.4 only when `metricsExport.enabled` was true at startup. The ordinary management gate applies; data-plane credentials do not grant access, and disabled mode is 404. `src/server/request-metrics.ts` owns fixed counters/histograms and receives a narrow final-request fact from `src/server/request-log.ts`; `src/server/index/serve-options.ts` creates one owner and injects the recorder and read-only snapshot into the request and management paths. |
| System | `POST /api/system/restart` restarts the proxy in place. Local CLI/tray callers first attest the exact runtime PID and port, then send a process-scoped HMAC capability bound to that method, path, PID, and port; the capability authorizes no other management route and is invalid after replacement. The caller observes one absolute deadline and accepts success only after a different runtime PID is healthy on the same port. `GET /api/system/health` is the authenticated scalar-only identity used by shared-plane Dashboard status and restart reconnect polling; its `spendLedger` block reports only ownership held/unheld, initialized/configured/degraded booleans and bounded persistence/corruption counters. Reading it never constructs, replays or prunes the ledger. Paths, scopes, accounts and request ids are absent, and the block never moves to unauthenticated `/healthz`. `GET /api/system/memory` — service-process runtime/memory identity (pid, Bun version/revision, optional `bunRuntimeSource` provenance, platform, RSS/heap/external/ArrayBuffers scalars, observed memory = max(RSS, external, ArrayBuffers), `bun:jsc` heap context, streamMode + eager-relay gate decision, watchdog snapshot sliced to the last 60 samples) plus privacy-safe `appOwnedBytes` retained-store totals/counters under static store ids. Its response-state block also reports spill-write `initial`/`healthy`/`degraded` status, a consecutive-failure streak, fixed error class, and failure/success timestamps. A successful publication clears the streak in the same process; raw error text and paths never enter this surface. Scalar-only payload; dashboard/admin callers use the standard management gate, while `ocx doctor` may use only the exact process-scoped local-read capability. It must never move to unauthenticated `/healthz`. |
| Stop | `POST /api/stop` — restore native Codex, stop any installed service, and exit the proxy. |
diff --git a/structure/manifest.json b/structure/manifest.json
index cbd3c7da0fc..20e69a13f39 100644
--- a/structure/manifest.json
+++ b/structure/manifest.json
@@ -49,7 +49,9 @@
"title": "Overview",
"scope": "Product boundary, local state ownership, and the non-negotiable invariants index.",
"documents": [
+ "app/",
"gui/",
+ "src/companion/",
"scripts/",
"src/config.ts",
"src/lib/"
@@ -326,10 +328,12 @@
"scope": "Dashboard serving, authentication boundaries, /api/* ownership, and usage accounting.",
"documents": [
"gui/",
+ "src/companion/",
"src/codex/",
"src/lib/",
"src/server/",
"src/usage/",
+ "src/usage/timeline.ts",
"src/vision/"
]
},
diff --git a/structure/overview.md b/structure/overview.md
index 7178b292b70..48e24dc1dc5 100644
--- a/structure/overview.md
+++ b/structure/overview.md
@@ -33,6 +33,12 @@ native Anthropic passthrough branch that forwards without translation. The Live/
different in kind — it resolves an OpenAI/ChatGPT relay and forwards to it directly, without the
adapter bridge.
+`app/` is a second, optional surface: a native macOS menu bar companion. It is a client
+of the management API, not part of the proxy — it adds no endpoint and changes no
+routing. Treat it the way you treat `gui/`: it may consume what `src/` already exposes,
+and a change that requires a new endpoint is a change to the proxy first.
+Its persisted display contract is owned by `src/companion/`.
+
The default install keeps native OpenAI/ChatGPT passthrough working through one option-aware
`openai` provider. Pool is the default and selects across main plus added accounts; Direct uses only
the current caller/main login. `openai-apikey` explicitly selects API-key transport, and the two
diff --git a/tests/ci-workflows/ci-structure-gate.test.ts b/tests/ci-workflows/ci-structure-gate.test.ts
index b6f21009092..0cda8de5330 100644
--- a/tests/ci-workflows/ci-structure-gate.test.ts
+++ b/tests/ci-workflows/ci-structure-gate.test.ts
@@ -67,8 +67,17 @@ test("the aggregate gate expects the job instead of ignoring it", () => {
// job missing from `expected_for` reads as `undeclared`, not as skipped.
const gate = workflow.jobs?.ci;
expect(Array.isArray(gate?.needs) ? gate?.needs : []).toContain("structure-gate");
+ expect(Array.isArray(gate?.needs) ? gate?.needs : []).toContain("macos-app");
const script = (gate?.steps ?? []).map(step => step.run ?? "").join("\n");
expect(script).toContain("structure-gate) echo \"$structure\" ;;");
- expect(script).toContain("GATED_JOBS=\"$GATED_JOBS structure-gate\"");
+ expect(script).toContain("GATED_JOBS=\"$GATED_JOBS structure-gate macos-app\"");
+ expect(script).toContain("|macos-app)");
expect(script).toContain("CHANGES_STRUCTURE");
});
+
+test("app changes select the macOS app job", () => {
+ expect(filters.ci).toContain("app/**");
+ const macosApp = workflow.jobs?.["macos-app"];
+ expect(macosApp?.if).toContain("needs.changes.outputs.ci == 'true'");
+ expect(Array.isArray(macosApp?.needs) ? macosApp?.needs : []).toContain("changes");
+});
diff --git a/tests/ci-workflows/ci-workflows.test.ts b/tests/ci-workflows/ci-workflows.test.ts
index 22b02edb141..658bd378346 100644
--- a/tests/ci-workflows/ci-workflows.test.ts
+++ b/tests/ci-workflows/ci-workflows.test.ts
@@ -495,6 +495,7 @@ describe("GitHub Actions hardening", () => {
"Dockerfile",
"LICENSE",
"README.md",
+ "app/**",
"assets/**",
"bin/**",
"bun.lock",
diff --git a/tests/cli/cli-companion.test.ts b/tests/cli/cli-companion.test.ts
new file mode 100644
index 00000000000..2f3d361bacb
--- /dev/null
+++ b/tests/cli/cli-companion.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { handleCompanionCommand } from "../../src/cli/companion";
+
+describe("ocx companion", () => {
+ test("set parses JSON values and reset sends the matching management payload", async () => {
+ const requests: Array<{ path: string; method: string; body: unknown }> = [];
+ const deps = {
+ baseUrl: "http://proxy.test",
+ fetchImpl: async (input: RequestInfo | URL, init?: RequestInit) => {
+ const body = init?.body ? JSON.parse(String(init.body)) : null;
+ requests.push({ path: new URL(String(input)).pathname, method: init?.method ?? "GET", body });
+ return Response.json({ settings: {}, defaults: {}, updatedAt: null });
+ },
+ };
+ expect(await handleCompanionCommand(["set", "showChart=false", "chartHours=6", "menuBarTemplate=null", "--json"], deps)).toBe(0);
+ expect(requests[0]).toEqual({
+ path: "/api/companion/settings",
+ method: "PUT",
+ body: { settings: { showChart: false, chartHours: 6, menuBarTemplate: null } },
+ });
+ expect(await handleCompanionCommand(["reset"], deps)).toBe(0);
+ expect(requests[1]).toEqual({
+ path: "/api/companion/settings",
+ method: "PUT",
+ body: { reset: true },
+ });
+ });
+});
diff --git a/tests/cli/cli-headless-parity.test.ts b/tests/cli/cli-headless-parity.test.ts
index c8b7257a8d0..27e9f657ff8 100644
--- a/tests/cli/cli-headless-parity.test.ts
+++ b/tests/cli/cli-headless-parity.test.ts
@@ -404,6 +404,7 @@ describe("headless GUI parity CLI", () => {
["/api/logs", "ocx observe"],
["/api/lab", "ocx lab"],
["/api/config", "ocx config"],
+ ["/api/companion", "ocx companion"],
// The client machine plane. These are served by the connected client's own loopback
// listener rather than the hub, and each one mirrors a connect-family command:
// status/clients -> `ocx connect status`, sync -> `ocx sync`, shim -> the client
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 0dc6bec9f2c..78fd2d90802 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -1,4 +1,5 @@
{
+ "macos-build-script.test.ts": "gui",
"server-combo-held-response.test.ts": "server",
"key-attribution.test.ts": "usage",
"provider-send-path-import.test.ts": "server",
@@ -21,6 +22,7 @@
"hub-usage.test.ts": "server",
"client-hub-usage.test.ts": "clients",
"cli-usage-hub.test.ts": "cli",
+ "cli-companion.test.ts": "cli",
"abort-idle-deadline.test.ts": "lib",
"abort-race.test.ts": "adapters",
"account-import.test.ts": "server",
@@ -1413,6 +1415,8 @@
"web-search-sidecar-429.test.ts": "web-search",
"codex-shim-destroyed-probe.test.ts": "codex-integration",
"client-runtime.test.ts": "clients",
+ "usage-timeline.test.ts": "usage",
+ "companion-settings.test.ts": "server",
"chat-tool-choice-allowed-tools.test.ts": "responses",
"anthropic-tool-declaration-constraints.test.ts": "adapters/anthropic",
"google-strict-tool-validated-mode.test.ts": "adapters/google",
diff --git a/tests/gui/macos-build-script.test.ts b/tests/gui/macos-build-script.test.ts
new file mode 100644
index 00000000000..70d4a018e7f
--- /dev/null
+++ b/tests/gui/macos-build-script.test.ts
@@ -0,0 +1,201 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { repoPath, repoRoot as findRepoRoot } from "../helpers/repo-root";
+
+// The macOS build script deletes whatever sits at its destination, so its containment
+// check is a safety boundary rather than a convenience. These run the real script.
+//
+// Every case here shipped as a defect at some point:
+// - the original check compared two values derived from the same variable, so any
+// OUTPUT_DIR passed;
+// - resolving logical paths let a repository-local symlink point outside;
+// - re-appending an unresolved tail let `.nope/../../outside` escape entirely;
+// - resolving physically BEFORE normalising let `..` reveal a symlink that was then
+// never followed.
+
+const repoRoot = findRepoRoot();
+const script = repoPath("scripts", "build-macos-app.sh");
+const isMacOS = process.platform === "darwin";
+
+const scriptText = await Bun.file(script).text();
+const packageText = await Bun.file(repoPath("app", "Package.swift")).text();
+
+async function runScript(outputDir: string, cwd: string = repoRoot) {
+ const proc = Bun.spawn(["bash", script], {
+ cwd,
+ env: { ...process.env, OUTPUT_DIR: outputDir },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const [stderr, exitCode] = await Promise.all([
+ new Response(proc.stderr).text(),
+ proc.exited,
+ ]);
+ return { stderr, exitCode };
+}
+
+/// Runs `body` with a uniquely named sandbox that this test owns and always removes.
+///
+/// An earlier version deleted FIXED paths such as `/ocx-escaped-probe`,
+/// which would have destroyed unrelated data if anything already lived there. A test
+/// for a safety boundary must not itself be destructive.
+async function withSandbox(body: (sandbox: string) => Promise): Promise {
+ const sandbox = mkdtempSync(join(tmpdir(), "ocx-containment-"));
+ try {
+ return await body(sandbox);
+ } finally {
+ rmSync(sandbox, { recursive: true, force: true });
+ }
+}
+
+describe.skipIf(!isMacOS)("macOS build script containment", () => {
+ test("refuses a destination outside the repository and creates nothing", async () => {
+ // Deliberately NOT derived from process.env.HOME: other suites replace HOME with a
+ // temp directory, and temp is a permitted root — so this test built successfully and
+ // failed during a full-suite run. A sibling of the repository is stable and is
+ // outside every permitted root.
+ const target = resolve(repoRoot, "..", `.ocx-outside-${process.pid}-${Date.now()}`);
+
+ const { stderr, exitCode } = await runScript(target);
+
+ expect(exitCode).not.toBe(0);
+ expect(stderr).toContain("Refusing to build");
+ expect(existsSync(target)).toBe(false);
+ }, 120_000);
+
+ test("refuses an unresolved .. traversal before creating any directory", async () => {
+ const intermediate = join(repoRoot, `.ocx-traversal-${process.pid}`);
+ const escapedName = `.ocx-escaped-${process.pid}-${Date.now()}`;
+ const escaped = resolve(repoRoot, "..", escapedName);
+
+ // String concatenation, NOT path.join: join() normalises `..` itself, so the script
+ // would never receive the traversal that was the actual bypass. Written with join()
+ // this test passed against the broken resolver.
+ const traversal = `${intermediate}/../../${escapedName}`;
+
+ const { stderr, exitCode } = await runScript(traversal);
+
+ expect(exitCode).not.toBe(0);
+ // The message names the RESOLVED path, which is the proof normalisation happened.
+ expect(stderr).toContain(escapedName);
+ expect(stderr).toContain("Refusing to build into");
+ expect(existsSync(escaped)).toBe(false);
+ expect(existsSync(intermediate)).toBe(false);
+ }, 120_000);
+
+ test("follows a symlink revealed by a .. traversal instead of trusting the link path", async () => {
+ const link = join(repoRoot, `.ocx-link-${process.pid}`);
+ const missing = join(repoRoot, `.ocx-missing-${process.pid}`);
+
+ const { stderr, exitCode } = await withSandbox(async (sandbox) => {
+ const outside = join(sandbox, "outside-target");
+ rmSync(link, { recursive: true, force: true });
+ symlinkSync(outside, link);
+ try {
+ // Nothing exists at the missing component, so `..` has to be applied lexically
+ // before the symlink can be resolved.
+ return await runScript(`${missing}/../${link.split("/").pop()}`);
+ } finally {
+ rmSync(link, { recursive: true, force: true });
+ rmSync(missing, { recursive: true, force: true });
+ }
+ });
+
+ // The link points at a directory that does not exist, so the script refuses to
+ // build THROUGH it rather than guessing where it leads. What must never happen is
+ // treating the unresolved link path as a destination inside the repository.
+ expect(exitCode).not.toBe(0);
+ expect(stderr).toContain("Refusing to build");
+ expect(stderr).not.toContain(`${missing}/`);
+ expect(existsSync(link)).toBe(false);
+ expect(existsSync(missing)).toBe(false);
+ }, 300_000);
+
+ test("refuses a symlink that points outside the permitted roots", async () => {
+ const link = join(repoRoot, `.ocx-outward-${process.pid}`);
+ const outside = join(
+ process.env.HOME ?? "/Users/shared",
+ `.ocx-symtarget-${process.pid}-${Date.now()}`,
+ );
+
+ rmSync(link, { recursive: true, force: true });
+ symlinkSync(outside, link);
+ try {
+ const { stderr, exitCode } = await runScript(link);
+
+ expect(exitCode).not.toBe(0);
+ expect(stderr).toContain("Refusing to build");
+ expect(existsSync(outside)).toBe(false);
+ } finally {
+ rmSync(link, { recursive: true, force: true });
+ }
+ }, 120_000);
+
+ // The third bypass: a RELATIVE dangling target was joined onto the resolved prefix
+ // without normalising, so `link -> ../../outside` became `/../../outside`,
+ // satisfied the `/*` prefix check, and escaped during mkdir -p.
+ test("refuses a symlink whose relative target escapes the repository", async () => {
+ const link = join(repoRoot, `.ocx-rel-${process.pid}`);
+ const escaped = resolve(repoRoot, "..", "..", `ocx-rel-target-${process.pid}`);
+
+ rmSync(link, { recursive: true, force: true });
+ symlinkSync(`../../ocx-rel-target-${process.pid}`, link);
+ try {
+ const { stderr, exitCode } = await runScript(link);
+
+ expect(exitCode).not.toBe(0);
+ expect(stderr).toContain("Refusing to build");
+ expect(existsSync(escaped)).toBe(false);
+ } finally {
+ rmSync(link, { recursive: true, force: true });
+ }
+ }, 120_000);
+
+ // Runs the child in a directory that CONTAINS a matching entry, so the old unquoted
+ // loop would have expanded the star. With cwd=repoRoot and the glob under dist/, the
+ // pattern matched nothing and the test passed against the broken implementation too.
+ test("treats glob characters as literal path components", async () => {
+ await withSandbox(async (sandbox) => {
+ const decoy = join(sandbox, "ocx-glob-decoy-probe");
+ mkdirSync(decoy, { recursive: true });
+
+ const { stderr } = await runScript(join(sandbox, "ocx-glob-*-probe"), sandbox);
+
+ expect(stderr).not.toContain("Refusing to build");
+ // The literal-star path is the one that was used, not the decoy it could match.
+ expect(existsSync(join(sandbox, "ocx-glob-*-probe"))).toBe(true);
+ expect(existsSync(join(decoy, "OpenCodex.app"))).toBe(false);
+ });
+ }, 300_000);
+
+ test("allows a destination inside the repository", async () => {
+ const inside = join(repoRoot, "dist", `ocx-inside-${process.pid}`);
+ try {
+ const { stderr } = await runScript(inside);
+ expect(stderr).not.toContain("Refusing to build into");
+ } finally {
+ rmSync(inside, { recursive: true, force: true });
+ }
+ }, 300_000);
+
+ test("allows a temp destination", async () => {
+ await withSandbox(async (sandbox) => {
+ const { stderr } = await runScript(join(sandbox, "build"));
+ expect(stderr).not.toContain("Refusing to build into");
+ });
+ }, 300_000);
+});
+
+describe("macOS widget packaging", () => {
+ test("stages, signs, and validates the WidgetKit appex", () => {
+ expect(scriptText).toContain("--product OpenCodexWidget");
+ expect(scriptText).toContain("Contents/PlugIns/OpenCodexWidget.appex");
+ expect(scriptText).toContain("Widget-Info.plist");
+ expect(scriptText).toContain("Widget.entitlements");
+ expect(scriptText).toContain("Contents/PlugIns/OpenCodexWidget.appex/Contents/MacOS/OpenCodexWidget");
+ expect(scriptText).toContain("container fallback path");
+ expect(packageText).toContain("_NSExtensionMain");
+ });
+});
diff --git a/tests/server/companion-settings.test.ts b/tests/server/companion-settings.test.ts
new file mode 100644
index 00000000000..de0058dc861
--- /dev/null
+++ b/tests/server/companion-settings.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+ applyCompanionSettingsPatch,
+ DEFAULT_COMPANION_SETTINGS,
+ loadCompanionSettings,
+ saveCompanionSettings,
+} from "../../src/companion/settings";
+import { resetCompanionPresenceForTests } from "../../src/server/management/companion-routes";
+import { handleManagementAPI } from "../../src/server/management-api";
+import type { OcxConfig } from "../../src/types";
+
+const config = { port: 10100, defaultProvider: "openai", providers: {} } as OcxConfig;
+async function withHome(run: (home: string) => Promise | T): Promise {
+ const home = mkdtempSync(join(tmpdir(), "ocx-companion-"));
+ const old = process.env.OPENCODEX_HOME;
+ process.env.OPENCODEX_HOME = home;
+ try { return await run(home); } finally {
+ if (old === undefined) delete process.env.OPENCODEX_HOME; else process.env.OPENCODEX_HOME = old;
+ rmSync(home, { recursive: true, force: true });
+ }
+}
+async function call(method: string, body?: unknown, userAgent?: string): Promise<{ status: number; body: any }> {
+ const url = new URL("http://127.0.0.1:10100/api/companion/settings");
+ const req = new Request(url, {
+ method,
+ headers: {
+ host: "127.0.0.1:10100",
+ ...(userAgent ? { "user-agent": userAgent } : {}),
+ ...(body === undefined ? {} : { "content-type": "application/json" }),
+ },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
+ const response = await handleManagementAPI(req, url, config, {}, "admin-token");
+ return { status: response?.status ?? 404, body: response ? await response.json() : null };
+}
+
+describe("companion settings", () => {
+ test("defaults, corrupt files, validation, and roundtrip persistence", async () => {
+ await withHome(home => {
+ expect(loadCompanionSettings().settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+ writeFileSync(join(home, "companion.json"), "{");
+ expect(loadCompanionSettings().settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+ expect(loadCompanionSettings().corrupt).toBe(true);
+ expect(applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { unknown: true })).toEqual({ error: expect.any(String) });
+ expect(applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { menuBarTemplate: "x".repeat(201) })).toEqual({ error: expect.any(String) });
+ const updated = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, { showChart: false });
+ if ("error" in updated) throw new Error(updated.error);
+ saveCompanionSettings(updated);
+ expect(loadCompanionSettings().settings.showChart).toBe(false);
+ });
+ });
+
+ test("GET, PUT, and reset are routed", async () => {
+ await withHome(async () => {
+ expect((await call("GET")).status).toBe(200);
+ expect((await call("PUT", { settings: { showToday: false } })).body.settings.showToday).toBe(false);
+ expect((await call("PUT", { reset: true })).body.settings).toEqual(DEFAULT_COMPANION_SETTINGS);
+ expect((await call("PUT", { settings: { bad: true } })).status).toBe(400);
+ });
+ });
+
+ test("GET reports corrupt persisted settings without overwriting them", async () => {
+ await withHome(async home => {
+ writeFileSync(join(home, "companion.json"), "{");
+ const result = await call("GET");
+ expect(result.status).toBe(200);
+ expect(result.body.corrupt).toBe(true);
+ expect(readFileSync(join(home, "companion.json"), "utf8")).toBe("{");
+ });
+ });
+
+ test("GET records menu bar presence only for the companion user agent", async () => {
+ await withHome(async () => {
+ resetCompanionPresenceForTests();
+ const initial = await call("GET");
+ expect(initial.body.companion.lastSeenAt).toBeNull();
+ const ordinary = await call("GET", undefined, "Mozilla/5.0");
+ expect(ordinary.body.companion.lastSeenAt).toBeNull();
+ const companion = await call("GET", undefined, "OpenCodexMenuBar/2.60.0");
+ expect(companion.body.companion.lastSeenAt).toBeNumber();
+ });
+ });
+});
diff --git a/tests/usage/usage-timeline.test.ts b/tests/usage/usage-timeline.test.ts
new file mode 100644
index 00000000000..ee395007e1e
--- /dev/null
+++ b/tests/usage/usage-timeline.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import type { PersistedUsageEntry } from "../../src/usage/log";
+import { createTimelineAccumulator, parseTimelineQuery } from "../../src/usage/timeline";
+
+const now = 1_700_000_000_000;
+function entry(overrides: Partial = {}): PersistedUsageEntry {
+ return {
+ requestId: "request",
+ timestamp: now - 30 * 60_000,
+ provider: "openai",
+ model: "gpt-5",
+ status: 200,
+ durationMs: 1,
+ usageStatus: "reported",
+ ...overrides,
+ };
+}
+function attempt(totalTokens: number, ordinal: number): NonNullable[number] {
+ return {
+ ordinal,
+ provider: "openai",
+ model: "gpt-5",
+ adapter: "test",
+ status: 200,
+ durationMs: 1,
+ sendCount: 1,
+ recoveryKinds: [],
+ usageStatus: "reported",
+ totalTokens,
+ };
+}
+
+describe("usage timeline", () => {
+ test("parses defaults and rejects invalid values", () => {
+ expect(parseTimelineQuery(new URLSearchParams(), now)).toMatchObject({
+ hours: 24, bucketMinutes: 60, metric: "total", aggregation: "sum", grouping: "model", models: null,
+ });
+ expect(parseTimelineQuery(new URLSearchParams("hours=7"), now)).toEqual({ error: expect.any(String) });
+ expect(parseTimelineQuery(new URLSearchParams("bucketMinutes=0"), now)).toEqual({ error: expect.any(String) });
+ expect(parseTimelineQuery(new URLSearchParams("metric=nope"), now)).toEqual({ error: expect.any(String) });
+ expect(parseTimelineQuery(new URLSearchParams("models=openai%2Fgpt-5%2Cbad"), now)).toEqual({ error: expect.any(String) });
+ });
+
+ test("buckets timestamps and attributes attempts without parent double counting", () => {
+ const query = parseTimelineQuery(new URLSearchParams("hours=6&bucketMinutes=60"), now);
+ if ("error" in query) throw new Error(query.error);
+ const acc = createTimelineAccumulator(query);
+ acc.add(entry({
+ requestId: "retry",
+ totalTokens: 999,
+ attempts: [
+ attempt(10, 0),
+ attempt(20, 1),
+ ],
+ }));
+ const result = acc.finish();
+ expect(result.series[0]?.total).toBe(30);
+ expect(result.buckets).toBe(6);
+ });
+
+ test("supports request average and max", () => {
+ const make = (aggregation: "sum" | "average" | "max") => {
+ const query = parseTimelineQuery(new URLSearchParams(`hours=6&aggregation=${aggregation}`), now);
+ if ("error" in query) throw new Error(query.error);
+ const acc = createTimelineAccumulator(query);
+ acc.add(entry({ requestId: "a", totalTokens: 10 }));
+ acc.add(entry({ requestId: "b", totalTokens: 30 }));
+ return acc.finish().series[0]?.total;
+ };
+ expect(make("sum")).toBe(40);
+ expect(make("average")).toBe(20);
+ expect(make("max")).toBe(30);
+ });
+
+ test("filters plotted models but keeps available models and supports accounts", () => {
+ const query = parseTimelineQuery(new URLSearchParams("models=openai%2Fone&grouping=modelAccount"), now);
+ if ("error" in query) throw new Error(query.error);
+ const acc = createTimelineAccumulator(query);
+ acc.add(entry({ model: "one", accountLogLabel: "main", totalTokens: 4 }));
+ acc.add(entry({ model: "two", totalTokens: 8 }));
+ const result = acc.finish();
+ expect(result.availableModels).toEqual(["openai/one", "openai/two"]);
+ expect(result.series[0]?.id).toBe("openai/one · main");
+ });
+
+ test("counts missing measurements and folds excess series", () => {
+ const query = parseTimelineQuery(new URLSearchParams("hours=6&metric=input"), now);
+ if ("error" in query) throw new Error(query.error);
+ const acc = createTimelineAccumulator(query);
+ acc.add(entry({ usage: undefined, totalTokens: 1 }));
+ for (let index = 0; index < 25; index += 1) {
+ acc.add(entry({ model: `model-${index}`, usage: { inputTokens: index } }));
+ }
+ const result = acc.finish();
+ expect(result.missingMeasurements).toBe(1);
+ expect(result.series).toHaveLength(24);
+ expect(result.series.at(-1)?.id).toBe("other");
+ });
+
+ test("folds other rows with request-level max and average", () => {
+ const make = (aggregation: "average" | "max") => {
+ const query = parseTimelineQuery(new URLSearchParams(`hours=6&aggregation=${aggregation}`), now);
+ if ("error" in query) throw new Error(query.error);
+ const acc = createTimelineAccumulator(query);
+ for (let index = 0; index < 25; index += 1) {
+ acc.add(entry({
+ requestId: `request-${index}`,
+ model: `model-${index}`,
+ totalTokens: index < 23 ? 100 + index : index - 22,
+ }));
+ }
+ return acc.finish().series.at(-1);
+ };
+ expect(make("max")?.points.at(-1)).toBe(2);
+ expect(make("average")?.points.at(-1)).toBe(1.5);
+ });
+});