Skip to content

Commit 8efe4f1

Browse files
committed
Merge remote-tracking branch 'origin/dev' into agent/fix-issue-497-orca-home-diagnostic
2 parents 2228fe9 + 5078ffc commit 8efe4f1

10 files changed

Lines changed: 342 additions & 20 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,9 @@ jobs:
4646
test:
4747
name: ${{ matrix.os }}
4848
runs-on: ${{ matrix.os }}
49-
timeout-minutes: 8
49+
# The Windows full suite now completes near the old 8-minute ceiling; leave
50+
# enough room for the privacy/build smokes instead of cancelling a green run.
51+
timeout-minutes: 12
5052
strategy:
5153
fail-fast: false
5254
matrix:

‎gui/src/pages/dashboard-core-poll.ts‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@ export type DashboardCorePoll = {
3838
startupHealthSeed: SettingsData["startupHealth"] | null | undefined;
3939
sidecar: SidecarData | null;
4040
shadowCall: ShadowCallData | null | undefined;
41-
usage30d: UsageSummary30d | null;
4241
maMode: "v1" | "default" | "v2";
4342
maModeResolved: boolean;
4443
/** Absent when the optional endpoint failed — callers must keep prior UI state. */
@@ -89,6 +88,14 @@ export async function fetchDashboardModels(apiBase: string, signal: AbortSignal)
8988
return requireJson<ModelInfo[]>(response);
9089
}
9190

91+
export async function fetchDashboardUsage(apiBase: string, signal: AbortSignal): Promise<UsageSummary30d> {
92+
const response = await fetch(`${apiBase}/api/usage?range=30d`, { signal });
93+
// Usage can be expensive on an older server. Keeping it in its own resource means
94+
// it cannot delay health/provider/settings commits, and a failed refresh retains
95+
// the last good usage snapshot.
96+
return requireJson<UsageSummary30d>(response);
97+
}
98+
9299
export async function fetchDashboardCore(
93100
apiBase: string,
94101
signal: AbortSignal,
@@ -112,7 +119,6 @@ export async function fetchDashboardCore(
112119
startupHealthSeed: undefined,
113120
sidecar: null,
114121
shadowCall: undefined,
115-
usage30d: null,
116122
maMode: "default",
117123
maModeResolved: true,
118124
injection: undefined,
@@ -121,13 +127,12 @@ export async function fetchDashboardCore(
121127
};
122128

123129
try {
124-
const [hRes, pRes, sRes, scRes, shRes, uRes] = await Promise.all([
130+
const [hRes, pRes, sRes, scRes, shRes] = await Promise.all([
125131
fetch(`${apiBase}/healthz`, { signal }),
126132
fetch(`${apiBase}/api/providers`, { signal }),
127133
fetch(`${apiBase}/api/settings`, { signal }),
128134
fetch(`${apiBase}/api/sidecar-settings`, { signal }),
129135
fetch(`${apiBase}/api/shadow-call-settings`, { signal }),
130-
fetch(`${apiBase}/api/usage?range=30d`, { signal }),
131136
]);
132137

133138
const health = await requireJson<HealthData>(hRes);
@@ -176,14 +181,6 @@ export async function fetchDashboardCore(
176181
}
177182
}
178183

179-
// Usage is best-effort: a malformed/empty body must not mark the whole dashboard offline.
180-
let usage30d: UsageSummary30d | null = null;
181-
try {
182-
usage30d = (await readJsonIfOk<UsageSummary30d>(uRes)) ?? null;
183-
} catch {
184-
usage30d = null;
185-
}
186-
187184
let maMode: "v1" | "default" | "v2" = "default";
188185
let maModeResolved = false;
189186
try {
@@ -236,7 +233,6 @@ export async function fetchDashboardCore(
236233
startupHealthSeed,
237234
sidecar,
238235
shadowCall,
239-
usage30d,
240236
maMode,
241237
maModeResolved,
242238
injection,

‎gui/src/pages/use-dashboard-data.ts‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
} from "../startup-health-ui";
99
import {
1010
fetchDashboardCore,
11+
fetchDashboardUsage,
1112
fetchDashboardModels,
1213
fetchProjectConfigDiagnostics,
1314
fetchStartupHealth,
@@ -147,6 +148,13 @@ export function useDashboardData(apiBase: string) {
147148
{ pollMs: 5000 },
148149
);
149150

151+
const usagePoll = useKeyedClientResource(
152+
`dashboard-usage:${apiBase}`,
153+
[apiBase],
154+
(signal) => fetchDashboardUsage(apiBase, signal),
155+
{ pollMs: 60_000 },
156+
);
157+
150158
const diagnosticsPoll = useKeyedClientResource(
151159
`dashboard-diagnostics:${apiBase}`,
152160
[apiBase],
@@ -188,7 +196,6 @@ export function useDashboardData(apiBase: string) {
188196
}
189197
if (data.sidecar) setSidecar(data.sidecar);
190198
if (data.shadowCall !== undefined) setShadowCall(data.shadowCall);
191-
setUsage30d(data.usage30d);
192199
setMaMode(data.maMode);
193200
setMaModeResolved(data.maModeResolved);
194201
if (data.injection) {
@@ -205,6 +212,10 @@ export function useDashboardData(apiBase: string) {
205212
setError(data.error);
206213
}, [corePoll.data]);
207214

215+
useEffect(() => {
216+
if (usagePoll.data !== undefined) setUsage30d(usagePoll.data);
217+
}, [usagePoll.data]);
218+
208219
useEffect(() => {
209220
if (diagnosticsPoll.data) setProjectConfigWarnings(diagnosticsPoll.data);
210221
}, [diagnosticsPoll.data]);

‎gui/tests/dashboard-contracts.test.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,19 @@ test("Dashboard wires a single project-config diagnostics owner outside the sett
1919
expect(coreBody).not.toContain("diagnostics/project-config");
2020
});
2121

22+
test("Dashboard usage polling cannot delay core health and settings", async () => {
23+
const core = await Bun.file(new URL("../src/pages/dashboard-core-poll.ts", import.meta.url)).text();
24+
const hook = await Bun.file(new URL("../src/pages/use-dashboard-data.ts", import.meta.url)).text();
25+
const coreFnStart = core.indexOf("export async function fetchDashboardCore");
26+
const usageFnStart = core.indexOf("export async function fetchDashboardUsage");
27+
expect(coreFnStart).toBeGreaterThan(-1);
28+
expect(usageFnStart).toBeGreaterThan(-1);
29+
expect(core.slice(coreFnStart)).not.toContain("/api/usage?range=30d");
30+
expect(hook).toContain("dashboard-usage:${apiBase}");
31+
expect(hook).toContain("fetchDashboardUsage(apiBase, signal)");
32+
expect(hook).toMatch(/dashboard-usage:\$\{apiBase\}[\s\S]*pollMs: 60_000/);
33+
});
34+
2235
test("Dashboard workspace pane is a labelled section, not a nested main landmark", async () => {
2336
const src = await Bun.file(new URL("../src/pages/Dashboard.tsx", import.meta.url)).text();
2437
expect(src).toContain("dashboard-workspace-main");

‎src/server/management/logs-usage-routes.ts‎

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,14 @@ import { primeCodexPoolQuotas } from "../../codex/auth-api";
3434
import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
3535
import { resolveCodexHomeDir } from "../../codex/home";
3636
import { scanStorage } from "../../storage/scanner";
37-
import { readUsageEntries } from "../../usage/log";
37+
import {
38+
currentUsageLogRevision,
39+
readUsageSnapshotForManagement,
40+
usageLogRevisionKey,
41+
type PersistedUsageEntry,
42+
} from "../../usage/log";
3843
import { getUsageDebugLogEntries } from "../../usage/debug";
39-
import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
44+
import { parseRange, parseUsageSurface, summarizeUsage, type UsageRange, type UsageSummary, type UsageSurface } from "../../usage/summary";
4045
import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
4146
import { getProviderRegistryEntry } from "../../providers/registry";
4247
import { getDebugLogEntries } from "../../lib/debug-log-buffer";
@@ -60,6 +65,48 @@ import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostR
6065
import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
6166
import type { ManagementContext } from "./context";
6267

68+
const USAGE_DAY_MS = 86_400_000;
69+
const usageSummaryCache = new Map<string, {
70+
revisionKey: string;
71+
expiresAt: number;
72+
summary: UsageSummary;
73+
}>();
74+
75+
function usageEntryMatchesSurface(entry: PersistedUsageEntry, surface: UsageSurface): boolean {
76+
if (surface === "claude") return entry.surface === "claude" || entry.surface === "claude-desktop";
77+
if (surface === "grok") return entry.surface === "grok";
78+
if (surface === "codex") return entry.surface === undefined;
79+
return true;
80+
}
81+
82+
function nextLocalMidnight(now: number): number {
83+
const next = new Date(now);
84+
next.setHours(24, 0, 0, 0);
85+
return next.getTime();
86+
}
87+
88+
function usageSummaryExpiresAt(
89+
entries: PersistedUsageEntry[],
90+
range: UsageRange,
91+
surface: UsageSurface,
92+
now: number,
93+
): number {
94+
let expiresAt = nextLocalMidnight(now);
95+
const windowMs = range === "7d" ? 7 * USAGE_DAY_MS : range === "30d" ? 30 * USAGE_DAY_MS : null;
96+
if (windowMs === null) return expiresAt;
97+
for (const entry of entries) {
98+
if (!usageEntryMatchesSurface(entry, surface)) continue;
99+
const expiry = entry.timestamp + windowMs;
100+
if (expiry > now && expiry < expiresAt) expiresAt = expiry;
101+
}
102+
return expiresAt;
103+
}
104+
105+
function refreshedUsageSummary(summary: UsageSummary, range: UsageRange, now: number): UsageSummary {
106+
const since = range === "7d" ? now - 7 * USAGE_DAY_MS : range === "30d" ? now - 30 * USAGE_DAY_MS : null;
107+
return { ...summary, since, generatedAt: now };
108+
}
109+
63110
export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Response | null> {
64111
const { req, url, config, deps, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort } = ctx;
65112

@@ -123,7 +170,20 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
123170
const surface = parseUsageSurface(url.searchParams.get("surface"));
124171
const now = Date.now();
125172
try {
126-
return jsonResponse(summarizeUsage(readUsageEntries(), range, now, surface));
173+
const cacheKey = `${range}:${surface}`;
174+
const observedRevisionKey = usageLogRevisionKey(currentUsageLogRevision());
175+
const cached = usageSummaryCache.get(cacheKey);
176+
if (cached && cached.revisionKey === observedRevisionKey && now < cached.expiresAt) {
177+
return jsonResponse(refreshedUsageSummary(cached.summary, range, now));
178+
}
179+
const snapshot = await readUsageSnapshotForManagement();
180+
const summary = summarizeUsage(snapshot.entries, range, now, surface);
181+
usageSummaryCache.set(cacheKey, {
182+
revisionKey: usageLogRevisionKey(snapshot.revision),
183+
expiresAt: usageSummaryExpiresAt(snapshot.entries, range, surface, now),
184+
summary,
185+
});
186+
return jsonResponse(summary);
127187
} catch {
128188
return jsonResponse({
129189
range,

‎src/usage/log.ts‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,145 @@ export function appendUsageEntry(entry: PersistedUsageEntry): void {
287287
try { chmodSync(path, 0o600); } catch { /* best-effort on platforms that ignore chmod */ }
288288
}
289289

290+
export type UsageLogRevision = {
291+
path: string;
292+
dev: number;
293+
ino: number;
294+
birthtimeMs: number;
295+
size: number;
296+
mtimeMs: number;
297+
ctimeMs: number;
298+
};
299+
300+
let usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
301+
let managementUsageReadInflight: {
302+
key: string;
303+
promise: Promise<{ entries: PersistedUsageEntry[]; revision: UsageLogRevision }>;
304+
} | null = null;
305+
306+
/** Test-only observability for proving that unchanged prefixes are not reparsed. */
307+
export function usageReadCacheStatsForTests(): Readonly<typeof usageReadCacheStats> {
308+
return { ...usageReadCacheStats };
309+
}
310+
311+
export function resetUsageReadCacheForTests(): void {
312+
usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
313+
managementUsageReadInflight = null;
314+
}
315+
316+
function readExactly(fd: number, length: number, position: number): Buffer | null {
317+
const output = Buffer.allocUnsafe(length);
318+
let offset = 0;
319+
while (offset < length) {
320+
const read = readSync(fd, output, offset, length - offset, position + offset);
321+
if (read === 0) return null;
322+
offset += read;
323+
}
324+
return output;
325+
}
326+
327+
function usageLogRevision(path: string, stat: ReturnType<typeof fstatSync>): UsageLogRevision {
328+
if (!stat.isFile()) throw new Error("usage log is not a regular file");
329+
return {
330+
path,
331+
dev: Number(stat.dev),
332+
ino: Number(stat.ino),
333+
birthtimeMs: Number(stat.birthtimeMs),
334+
size: Number(stat.size),
335+
mtimeMs: Number(stat.mtimeMs),
336+
ctimeMs: Number(stat.ctimeMs),
337+
};
338+
}
339+
340+
export function usageLogRevisionKey(revision: UsageLogRevision | null): string {
341+
if (!revision) return "missing";
342+
return [
343+
revision.path,
344+
revision.dev,
345+
revision.ino,
346+
revision.birthtimeMs,
347+
revision.size,
348+
revision.mtimeMs,
349+
revision.ctimeMs,
350+
].join("\0");
351+
}
352+
353+
export function currentUsageLogRevision(): UsageLogRevision | null {
354+
const path = usageLogPath();
355+
if (!existsSync(path)) return null;
356+
let fd: number | undefined;
357+
try {
358+
fd = openSync(path, "r");
359+
return usageLogRevision(path, fstatSync(fd));
360+
} finally {
361+
if (fd !== undefined) closeSync(fd);
362+
}
363+
}
364+
365+
async function parseUsageTextCooperatively(text: string): Promise<PersistedUsageEntry[]> {
366+
const lines = text.split(/\r?\n/);
367+
usageReadCacheStats.parsedLines += lines.filter(line => line.trim()).length;
368+
const entries: PersistedUsageEntry[] = [];
369+
const batchSize = 1_000;
370+
for (let offset = 0; offset < lines.length; offset += batchSize) {
371+
entries.push(...parseUsageLines(lines.slice(offset, offset + batchSize)));
372+
if (offset + batchSize < lines.length) {
373+
// JSON parsing dominates large-log startup. Yield between bounded batches so
374+
// Bun can continue serving health and settings requests on the same thread.
375+
await new Promise<void>(resolve => setTimeout(resolve, 0));
376+
}
377+
}
378+
return entries;
379+
}
380+
381+
async function readUsageEntriesFullCooperatively(
382+
path: string,
383+
): Promise<{ entries: PersistedUsageEntry[]; revision: UsageLogRevision }> {
384+
let fd: number | undefined;
385+
try {
386+
fd = openSync(path, "r");
387+
const stat = fstatSync(fd);
388+
const size = Number(stat.size);
389+
const bytes = readExactly(fd, size, 0);
390+
if (bytes === null) throw new Error("usage log changed while it was being read");
391+
const entries = await parseUsageTextCooperatively(bytes.toString("utf-8"));
392+
usageReadCacheStats.fullReads += 1;
393+
return { entries, revision: usageLogRevision(path, stat) };
394+
} finally {
395+
if (fd !== undefined) closeSync(fd);
396+
}
397+
}
398+
399+
/**
400+
* Management API reader: full parses yield between bounded batches and concurrent
401+
* callers share work only when they observed the same exact file revision. Parsed rows
402+
* are returned to the request and never retained in module state.
403+
*/
404+
export async function readUsageSnapshotForManagement(): Promise<{
405+
entries: PersistedUsageEntry[];
406+
revision: UsageLogRevision | null;
407+
}> {
408+
const path = usageLogPath();
409+
if (!existsSync(path)) return { entries: [], revision: null };
410+
const observed = currentUsageLogRevision();
411+
const key = usageLogRevisionKey(observed);
412+
if (managementUsageReadInflight?.key === key) {
413+
const shared = await managementUsageReadInflight.promise;
414+
return { entries: shared.entries.slice(), revision: shared.revision };
415+
}
416+
const promise = readUsageEntriesFullCooperatively(path);
417+
managementUsageReadInflight = { key, promise };
418+
try {
419+
return await promise;
420+
} finally {
421+
if (managementUsageReadInflight?.promise === promise) managementUsageReadInflight = null;
422+
}
423+
}
424+
425+
export async function readUsageEntriesForManagement(): Promise<PersistedUsageEntry[]> {
426+
return (await readUsageSnapshotForManagement()).entries;
427+
}
428+
290429
export function readUsageEntries(): PersistedUsageEntry[] {
291430
const path = usageLogPath();
292431
if (!existsSync(path)) return [];

‎structure/05_gui-and-management-api.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,21 @@ Missing usage is never treated as zero. The dashboard Usage tab renders the same
7878
main Dashboard surfaces a 30d token / coverage summary. The in-memory `requestLog` is capped at
7979
200 entries and is **not** the source of truth for aggregation — the JSONL on disk is.
8080

81+
The management API caches only the compact summary for an exact file revision and query; it never
82+
retains normalized per-request rows after a response. The cache invalidates on any identity, size, or
83+
timestamp change and at the next range expiry or local-day boundary. Rebuilds parse in bounded
84+
batches and yield between them, so unrelated management requests remain serviceable even for a large
85+
existing log. The Dashboard polls its 30-day usage summary independently once per minute, so usage
86+
work cannot delay health/provider/settings state or run every five seconds.
87+
88+
[Decision Log]
89+
- 목적과 의도: Keep dashboard and management requests responsive as `usage.jsonl` grows.
90+
- 기존 구현 및 제약 조건: The JSONL file remains the durable source of truth and may be truncated, replaced, or hand-edited.
91+
- 검토한 주요 대안: Retain normalized rows, maintain a second database, or cache only revision-keyed summaries and cooperatively rebuild them.
92+
- 선택한 방식: Keep only bounded summary results, share full reads by exact file identity, yield during parsing, and poll usage separately at a slower cadence.
93+
- 다른 대안 대신 이 방식을 선택한 이유: It bounds resident heap and avoids a second persistence format while keeping unrelated endpoints responsive.
94+
- 장점, 단점 및 영향: Unchanged queries are cheap and memory stays bounded; a changed large log still consumes rebuild CPU, but cooperatively and at most once per observed revision/query.
95+
8196
For diagnosing upstream-shape / usage-extraction issues run `ocx debug usage on` (or set
8297
`OPENCODEX_USAGE_DEBUG=1` before start). The proxy then writes a rolling debug record per finalized
8398
request to `~/.opencodex/usage-debug.jsonl` (mode `0o600`, auto-trimmed to the most-recent 100 lines

0 commit comments

Comments
 (0)