codex-copilot-dx 0.9.19 → 0.9.20

package/docs/README.md

@@ -16,6 +16,7 @@ test counts, timings, live-provider observations, and limitations remain
 historical facts rather than current guarantees.
 
 - [0.9.19: GitHub startup checks and stable-release updates](RELEASE_0.9.19.md)
+- [0.9.20: timing evidence, real-client checks and bounded analytics reuse](RELEASE_0.9.20.md)
 - [0.9.13: model-bound Auto-review reasoning selection](RELEASE_0.9.13.md)
 - [0.9.12: GPT-6.1 Sol / low Auto-review default](RELEASE_0.9.12.md)
 - [0.9.11: bounded usage-summary cache and diagnostic redaction](RELEASE_0.9.11.md)

package/docs/REFERENCE.md

@@ -201,7 +201,7 @@ ccdx image-status
 ccdx disable-image
 ```
 
-`image-status` never prints the API key and performs only a local, non-generating tool-readiness check. Disabling removes the stored provider credential, the CCDX-owned MCP block, and unmodified skill, reference, and helper files; user-modified files are preserved. Cached tool calls then fail closed. The Node helper creates a new file under the task's `output/imagegen` directory by default and reports its absolute path; it never overwrites an existing file or automatically repeats a failed generation. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` or `edit_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
+`image-status` never prints the API key and performs only a local, non-generating tool-readiness check. It lists generation and editing separately based on the local tools/list response; a configured model name alone does not prove editing is available. Disabling removes the stored provider credential, the CCDX-owned MCP block, and unmodified skill, reference, and helper files; user-modified files are preserved. Cached tool calls then fail closed. The Node helper creates a new file under the task's `output/imagegen` directory by default and reports its absolute path; it never overwrites an existing file or automatically repeats a failed generation. The image endpoint is contacted only by `enable-image` validation and by explicit `generate_image` or `edit_image` tool calls. Ordinary Responses, models, authentication, Fast, Auto-review, compaction, and image-input paths remain on their existing routes.
 
 Generated image downloads must use public HTTPS addresses, do not follow redirects, are DNS-checked against private and reserved addresses, and are capped at 32 MiB. Well-known NAT64 `64:ff9b::/96` addresses apply the same IPv4 public/private rules to the embedded address, without rejecting legitimate public translations. DNS resolution and downloading share one deadline and respond to cancellation; a late DNS result cannot start a cancelled download. The local MCP route accepts calls only from the same device and permits at most two concurrent image operations. Host must name loopback, the actual local socket address (including equivalent IPv6/IPv4-mapped forms), or the explicitly configured bind hostname. Missing Host remains compatible with HTTP/1.0 and in-process clients. It requires `application/json` and rejects browser `Origin` headers; native Codex and Node clients do not send an Origin. The tool supports new-image generation at `1024x1024`, `1536x1024`, or `1024x1536`.
 
@@ -240,6 +240,28 @@ If a configured npm mirror has not synchronized the current release yet, use the
 
 ## Diagnostics
 
+`ccdx status` and the dashboard show the sample count beside each timing. First
+output is observed at the gateway from generated deltas, hidden-reasoning/tool
+announcements or content snapshots; a runtime-only result is marked separately.
+Empty message/envelope frames, client tool results and compaction are excluded.
+`first_output_sources` and each recent request's `first_output_source` describe
+that evidence, not internal model decode or prefill timing. Per-token time is a
+gateway estimate and can include hosted-tool and downstream delays. The new
+timing classifier does not change stream forwarding or the existing output
+commitment that gates compatibility retries.
+
+The adapted Codex model catalog preserves valid multi-agent reasoning mappings.
+Only a mapping no longer supported by the final advertised effort options is
+repaired to the last available non-Ultra effort; no model switch or forced
+highest-effort policy is introduced. Client-provided defaults, option order,
+instructions and multi-agent version stay intact.
+
+CI additionally provisions the latest official Codex on its runner and uses an
+isolated app-server to verify configuration, its model list and synthetic direct
+and proxied Responses message delivery. It logs the tested runtime version,
+does not skip installed-version mismatches and does not install clients on user
+machines or use live credentials/models.
+
 `ccdx doctor` also inspects installed macOS App version metadata and running
 Codex/ChatGPT App executable identities, without reading command arguments,
 changing client files or killing processes. It shows the running adapter version,
@@ -432,7 +454,7 @@ The summary covers the current log and its single rotated backup, not an unbound
 
 Usage writes are asynchronous and batched under the existing cross-process rotation lock. Pending and in-flight records share a 4096-record / 4 MiB ceiling. If either ceiling is reached, new excess records are dropped with a warning and a status counter; inference does not wait or retry. Normal records and per-record rotation boundaries are unchanged. The bounded shutdown flush remains 1.5 seconds; disk failures and shutdown deadlines can prevent persistence, so usage is diagnostic rather than a billing ledger.
 
-Repeated plain usage summaries in the same process reuse one bounded cache entry when both retained log files are unchanged. File identity, size, modification/change timestamps and a two-second recent-write guard control reuse; concurrent settled-file queries share one scan. The serialized summary budget is 256 KiB and at most 128 model groups; larger results remain complete but uncached. Warnings, unstable reads, metadata errors and scans with changed files are not retained. Each caller receives an independent result. Analytics record callbacks and custom-warning reads keep the original streaming path. There is no persistent index, background polling, cross-process cache or change to usage writes; opening analytics still scans the retained records.
+Repeated plain usage summaries in the same process reuse one bounded cache entry when both retained log files are unchanged. File identity, size, modification/change timestamps and a two-second recent-write guard control reuse; concurrent settled-file queries share one scan. The serialized summary budget is 256 KiB and at most 128 model groups; larger results remain complete but uncached. Warnings, unstable reads, metadata errors and scans with changed files are not retained. Each caller receives an independent result. Analytics record callbacks and custom-warning reads keep the original streaming path. There is no persistent index, background polling, cross-process cache or change to usage writes; the first analytics read still scans the retained records. Dashboard analytics then reuses up to two settled aggregate snapshots within a combined 2 MiB serialized budget, keyed by file identity/version, time zone and local date. Concurrent identical reads share one scan; writes, rotation, truncation, replacement, warnings, future/undated records and oversized results prevent reuse. Returned data is cloned, and custom callbacks/warnings keep the uncached path.
 
 Diagnostic redaction removes Basic authorization payloads and URL userinfo, and consumes escaped quotes inside sensitive JSON fields. Ordinary Basic-related prose, safe host/path information and error codes are retained. These protections apply to existing failure/status/debug diagnostics, not forwarded requests or upstream response bodies. They do not make arbitrary upstream prose guaranteed safe to share.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/cli-image.mjs

@@ -159,7 +159,10 @@ export function syncEnabledImageSkill({ home = os.homedir(), codexPath = default
 }
 
 function printImageReadiness(readiness, output, commandName) {
-  if (readiness.ready) output.write("Local image service: ready (generation tool verified; no image generated).\n");
+  if (readiness.ready) {
+    output.write("Local image service: ready (generation tool verified; no image generated).\n");
+    output.write(`Generate: available\nEdit: ${readiness.editing ? "available" : "not advertised"}\n`);
+  }
   else output.write(`Local image service: unavailable (${readiness.reason}). Start or restart ${commandName} to use images.\n`);
 }
 

package/src/cli-options.mjs

@@ -354,7 +354,7 @@ function topicHelp(name, topic) {
     animation: `Usage:\n  ${name} animation\n\nPreviews all terminal activity animations together and selects the theme used the next time the adapter starts.`,
     "enable-image": `Usage:\n  ${name} enable-image\n\nInteractively configures an HTTPS image API endpoint (base URLs are also accepted) and API key, detects its supported image model and protocol, installs CCDX image guidance, and checks the local image tool for Codex App without generating an image. A blank key preserves the saved key only for the same origin; a new origin requires explicit key entry. Concurrent unrelated config edits are preserved.`,
     "disable-image": `Usage:\n  ${name} disable-image\n\nDisables the local CCDX image tool and removes its stored API credential and unmodified CCDX image guidance.`,
-    "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and probes local image-tool readiness without generating an image or exposing its API key.`,
+    "image-status": `Usage:\n  ${name} image-status\n\nShows provider configuration and locally advertised generation/editing tools without generating an image or exposing its API key.`,
     "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nSelect a Responses model, then an advertised reasoning effort. Enter keeps the default/current choice; q cancels both steps without saving. Effort 0 follows the client (low when omitted). Settings apply only to Auto-review on the next request; no client patch or restart is required for adapters running 0.9.13 or newer.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or the latest stable GitHub release. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,

package/src/cli-status.mjs

@@ -150,7 +150,7 @@ export function formatAdapterStatus({ baseUrl, data }, { commandName = "ccdx", c
     `${commandName} status`,
     adapterLine,
     status("info", `Requests: ${count(requests.completed)}/${count(requests.total)} completed, ${count(requests.active)} active, ${count(requests.status_4xx)} 4xx, ${count(requests.status_5xx)} 5xx, ${count(requests.aborted)} aborted`),
-    status("info", `Responses stream: TTFT avg ${latency(performance.ttft_ms?.avg)} (${count(performance.ttft_ms?.samples)} samples), TPOT avg ${tpot(performance.tpot_us)}`),
+    status("info", `Responses stream: TTFT avg ${latency(performance.ttft_ms?.avg)} (${count(performance.ttft_ms?.samples)} samples), TPOT avg ${tpot(performance.tpot_us)} (${count(performance.tpot_us?.samples)} samples; gateway estimate)`),
     ...(terminalOutcomes ? [status("info", `Model outcomes: ${count(terminalOutcomes.completed)} completed, ${count(terminalOutcomes.incomplete)} incomplete, ${count(terminalOutcomes.failed)} failed, ${count(terminalOutcomes.cancelled)} cancelled, ${count(terminalOutcomes.unknown)} without terminal`)] : []),
     status("info", `Admission: ${count(admission.activeRequests)} active, ${count(admission.queued)} queued, ${count(admission.rejected)} rejected, ${count(admission.timedOut)} timed out, wait avg ${latency(admission.waitMsAvg)}`),
     status("info", `Memory: RSS ${mebibytes(processStats.rss_bytes)}, heap ${mebibytes(processStats.heap_used_bytes)}`),

package/src/codex-model-catalog.mjs

@@ -110,6 +110,16 @@ function catalogModelForCopilot(model, copilotModels, { filterReasoning = false
       ? model.supported_reasoning_levels.filter(({ effort }) => reasoning.has(effort))
       : model.supported_reasoning_levels,
   };
+  // Only repair a supplied mapping that no longer names an advertised wire effort.
+  const levels = patched.supported_reasoning_levels;
+  if (Array.isArray(levels) && patched.multi_agent_reasoning_effort != null
+    && (!levels.some(level => level.effort === patched.multi_agent_reasoning_effort)
+      || (reasoning.size && !reasoning.has(patched.multi_agent_reasoning_effort)))) {
+    const supported = levels.filter(level => level.effort !== "ultra"
+      && (!reasoning.size || reasoning.has(level.effort)));
+    const effort = supported.at(-1)?.effort;
+    if (effort) patched.multi_agent_reasoning_effort = effort;
+  }
   // The Codex catalog describes ChatGPT service tiers. Copilot must advertise
   // an exact fast model before CCDX exposes the corresponding selector.
   if (!isEligibleCopilotGpt6(copilotModels, `${model.slug}-fast`)) {

package/src/dashboard/index.html

@@ -36,6 +36,8 @@
             <div class="panel-heading"><h2 data-i18n>MODEL OUTCOMES</h2><span>RESPONSES</span></div>
             <dl class="stats"><div><dt data-i18n>Completed</dt><dd id="completed">—</dd></div><div><dt data-i18n>Incomplete</dt><dd id="incomplete">—</dd></div><div><dt data-i18n>Failed</dt><dd id="failed">—</dd></div><div><dt data-i18n>Cancelled</dt><dd id="cancelled">—</dd></div></dl>
             <p class="hint" data-i18n>HTTP 2xx != model completed.</p>
+            <dl class="stats timing-stats"><div><dt data-i18n>First output</dt><dd id="ttft">—</dd></div><div><dt data-i18n>Token time</dt><dd id="tpot">—</dd></div></dl>
+            <p class="hint" data-i18n>Gateway timing. Token time is estimated.</p>
           </article>
           <article class="panel">
             <div class="panel-heading"><h2 data-i18n>LOCAL HISTORY</h2><span data-i18n>ACTIVE LIMIT</span></div>

package/src/dashboard/language.js

@@ -1,5 +1,9 @@
 (() => {
   const translations = {
+    "First output": ["First output", "首次输出"],
+    "Token time": ["Token time", "输出耗时"],
+    "Gateway timing. Token time is estimated.": ["Observed at the gateway. Token time is an estimate.", "网关观测时间。\n每Token耗时为估算值。"],
+    "{value} / {samples} samples": ["{value} / {samples} samples", "{value} / {samples}次样本"],
     "CCDX · Local dashboard": ["CCDX · Dashboard", "CCDX · 运行看板"],
     "/ LOCAL STATUS": ["/ DASHBOARD", "/ 运行看板"],
     "READING": ["READING", "读取中"],

package/src/dashboard/ui.css

@@ -134,3 +134,5 @@ footer { color: var(--footer); font-size: 10px; letter-spacing: .05em; padding:
 @media (max-width: 620px) { .snapshot-meta { justify-content: flex-start; margin-top: 9px; } }
 @media (max-width: 620px) { .shell { padding: 0 16px; } .topbar { min-height: 60px; } .brand-detail { display: none; } .topbar-actions { gap: 11px; } .intro { display: block; padding: 29px 0 21px; } .intro p { margin-top: 9px; } .overview, .details { grid-template-columns: 1fr; } .details .panel:last-child { grid-column: auto; } .card { min-height: 122px; } .card strong { margin-top: 14px; } .lower li { display: block; } .lower li span { display: block; margin-top: 5px; } }
 @media (max-width: 460px) { .topbar { flex-wrap: wrap; padding: 12px 0; gap: 10px; } .topbar-actions { gap: 9px; } .panel-heading { flex-wrap: wrap; } .heading-actions { gap: 10px; } .failure-detail { grid-template-columns: 1fr; gap: 3px; } .failure-detail dd { margin-bottom: 7px; } select { max-width: 210px; } }
+.timing-stats { grid-template-columns: 1fr; }
+.timing-stats dt { white-space: nowrap; }

package/src/dashboard/ui.js

@@ -147,6 +147,11 @@ function render(data) {
 
   const outcomes = data.stream_performance?.by_route?.responses?.terminal_outcomes?.totals || {};
   for (const key of ["completed", "incomplete", "failed", "cancelled"]) text(key, number(outcomes[key]));
+  const timing = data.stream_performance?.by_route?.responses || {};
+  for (const [id, metric, scale, unit] of [["ttft", timing.ttft_ms, 1, "ms"], ["tpot", timing.tpot_us, timing.tpot_us?.unit === "us" ? 1000 : 1, "ms/token"]]) {
+    const value = metric?.samples > 0 && finite(metric.avg) ? `${(Number(metric.avg) / scale).toFixed(1)} ${unit}` : "—";
+    text(id, "{value} / {samples} samples", { value, samples: number(metric?.samples) });
+  }
 
   const history = data.response_history || {};
   const limit = Number(history.maxBytes || data.limits?.response_history_max_bytes || 0);

package/src/dashboard-api.mjs

@@ -13,6 +13,7 @@ import {
 } from "./terminal-animation.mjs";
 import { cacheReadTokens, summarizeUsageLogs, usageCacheHitRate } from "./usage-store.mjs";
 import { createUsageAnalytics } from "./usage-analytics.mjs";
+import { analyzeUsageLogs } from "./usage-analysis.mjs";
 import { readUserSettings, terminalAnimationPreference, writeTerminalAnimationTheme } from "./user-settings.mjs";
 
 const ANIMATION_PATH = "/_ccdx/ui/animation";
@@ -111,7 +112,7 @@ export async function handleDashboardApi(req, res, pathname, {
   env = process.env,
   home = os.homedir(),
   liveModelsFn = () => fetchLiveCopilotModels({ home }),
-  usageSummaryFn = (options) => summarizeUsageLogs(undefined, options),
+  usageSummaryFn,
   authStatusFn = () => authStatus({ home }),
 } = {}) {
   if (!isLoopbackAddress(req.socket?.remoteAddress)
@@ -229,8 +230,10 @@ export async function handleDashboardApi(req, res, pathname, {
       }
     }
     try {
-      const summary = await usageSummaryFn(analytics ? { onRecord: analytics.record } : undefined);
-      sendJson(res, 200, { source: "local_usage_log", ...usageTable(summary), ...(analytics ? { analytics: analytics.snapshot() } : {}) });
+      const analysis = analytics && !usageSummaryFn
+        ? await analyzeUsageLogs(undefined, { timeZone: query.get("time_zone") || "UTC" }) : null;
+      const summary = analysis?.summary || await (usageSummaryFn || (options => summarizeUsageLogs(undefined, options)))(analytics ? { onRecord: analytics.record } : undefined);
+      sendJson(res, 200, { source: "local_usage_log", ...usageTable(summary), ...(analytics ? { analytics: analysis?.analytics || analytics.snapshot() } : {}) });
     } catch {
       sendJson(res, 500, { error: "Could not read local usage summary" });
     }

package/src/image-readiness.mjs

@@ -47,7 +47,7 @@ export async function probeImageTool(codexContent, { fetchImpl = fetch, timeoutM
     await rpc(undefined, "notifications/initialized", {});
     const result = await rpc(2, "tools/list", {});
     return result?.tools?.some((tool) => tool.name === "generate_image")
-      ? { ready: true }
+      ? { ready: true, generation: true, editing: result.tools.some(tool => tool.name === "edit_image") }
       : { ready: false, reason: "tool_unavailable" };
   } catch (error) {
     return { ready: false, reason: signal.aborted ? "timeout" : /^HTTP \d+$/.test(error.message) ? error.message : "unreachable" };

package/src/responses-proxy.mjs

@@ -40,6 +40,7 @@ import {
 import {
   isResponsesOutputEvent,
   markFirstOutput,
+  responsesTimingSource,
   markOutputTokens,
   markRequestObservation,
   markResponseErrorOrigin,
@@ -127,9 +128,15 @@ function inspectResponseSseEvent(state, eventName, data) {
   if (outputTokens !== undefined) markOutputTokens(outputTokens);
   const inputTokens = event.response?.usage?.input_tokens ?? event.usage?.input_tokens;
   if (inputTokens !== undefined) markRequestObservation({ input_tokens: inputTokens });
+  if (!state.sawTiming) {
+    const timingSource = responsesTimingSource(event, eventType);
+    if (timingSource) {
+      state.sawTiming = true;
+      markFirstOutput(timingSource);
+    }
+  }
   if (!state.sawOutput && isResponsesOutputEvent(event, eventType)) {
     state.sawOutput = true;
-    markFirstOutput();
   }
   if (["response.function_call_arguments.delta", "response.custom_tool_call_input.delta"].includes(eventType)) {
     state.toolArgumentGuard.observe(event.output_index ?? event.item_id ?? event.call_id, event.delta);

package/src/stream-performance.mjs

@@ -39,6 +39,39 @@ export function isResponsesOutputEvent(event, eventType = event?.type) {
   return RESPONSES_OUTPUT_EVENT_TYPES.has(eventType) && nonEmptyString(event?.delta);
 }
 
+// Timing evidence is separate from the output/compatibility-retry commitment.
+export function responsesTimingSource(event, eventType = event?.type) {
+  if (isResponsesOutputEvent(event, eventType)) return "delta";
+  const itemSource = (item, announced = false) => {
+    if (!item || typeof item !== "object") return null;
+    if (["function_call_output", "custom_tool_call_output", "computer_call_output", "additional_tools", "compaction", "compaction_summary", "mcp_approval_response"].includes(item.type)) return null;
+    if (["program_output", "shell_call_output", "tool_search_output"].includes(item.type)) return "runtime";
+    if (item.caller?.type === "program") return "runtime";
+    if (announced && ["reasoning", "function_call", "custom_tool_call", "web_search_call", "file_search_call", "computer_call", "tool_search_call", "mcp_call", "program", "multi_agent_call", "image_generation_call"].includes(item.type)) return "announcement";
+    const content = item.content || item.summary;
+    if (Array.isArray(content) && content.some(part => nonEmptyString(part?.text) || nonEmptyString(part?.refusal))) return "snapshot";
+    if (nonEmptyString(item.arguments) || nonEmptyString(item.input)) return "snapshot";
+    return null;
+  };
+  if (eventType === "response.output_item.added" || eventType === "response.output_item.done") {
+    return itemSource(event.item, eventType === "response.output_item.added");
+  }
+  if (["response.content_part.added", "response.content_part.done", "response.reasoning_summary_part.added", "response.reasoning_summary_part.done"].includes(eventType)
+    && (nonEmptyString(event.part?.text) || nonEmptyString(event.part?.refusal))) return "snapshot";
+  if (eventType === "response.shell_call_output_content.delta"
+    && (nonEmptyString(event.delta?.stdout) || nonEmptyString(event.delta?.stderr))) return "runtime";
+  if (["response.completed", "response.incomplete", "response.failed"].includes(eventType)) {
+    let runtime = null;
+    for (const item of Array.isArray(event.response?.output) ? event.response.output : []) {
+      const source = itemSource(item);
+      if (source && source !== "runtime") return source;
+      runtime ||= source;
+    }
+    return runtime;
+  }
+  return null;
+}
+
 export function isChatOutputDelta(delta) {
   if (!delta || typeof delta !== "object") return false;
   return nonEmptyString(delta.content)
@@ -101,6 +134,7 @@ function createRoutePerformance() {
     ttft: createHistogram(TTFT_EDGES_MS),
     tpot: createHistogram(TPOT_EDGES_US),
     requestTtft: createHistogram(TTFT_EDGES_MS),
+    outputSources: { delta: 0, announcement: 0, snapshot: 0, runtime: 0 },
     preparation: Object.fromEntries(PREPARATION_STAGES.map((stage) => [stage, createHistogram(PREPARATION_EDGES_MS)])),
     success_with_output: 0,
     errors_with_output: 0,
@@ -128,6 +162,9 @@ function routeSnapshot(route) {
     ttft_ms: histogramSnapshot(route.ttft, "ms"),
     tpot_us: histogramSnapshot(route.tpot, "us"),
     request_ttft_ms: histogramSnapshot(route.requestTtft, "ms"),
+    first_output_sources: { ...route.outputSources },
+    timing_boundary: "gateway_observed",
+    tpot_estimated: true,
     preparation_ms: Object.fromEntries(PREPARATION_STAGES.map((stage) => [stage, histogramSnapshot(route.preparation[stage], "ms")])),
   };
 }
@@ -143,6 +180,7 @@ export function createStreamPerformanceMetrics({ now = () => performance.now(),
       const requestStartedAt = now();
       let upstreamStartedAt = null;
       let firstOutputAt = null;
+      let firstOutputSource = null;
       let outputTokens = null;
       let failed = false;
       let finished = false;
@@ -196,8 +234,11 @@ export function createStreamPerformanceMetrics({ now = () => performance.now(),
           lastActivityAt = now();
           phase = "upstream_stream";
         },
-        firstOutput() {
-          if (firstOutputAt === null) firstOutputAt = now();
+        firstOutput(source = "delta") {
+          if (firstOutputAt === null) {
+            firstOutputAt = now();
+            firstOutputSource = Object.hasOwn(route.outputSources, source) ? source : "delta";
+          }
         },
         setOutputTokens(value) {
           const tokens = Number(value);
@@ -250,6 +291,7 @@ export function createStreamPerformanceMetrics({ now = () => performance.now(),
             failed: failed || aborted || (terminalOutcome !== null && terminalOutcome !== "completed"),
             http_status: Number.isInteger(statusCode) && statusCode >= 100 && statusCode <= 599 ? statusCode : null,
             upstream_attempts: attempts,
+            first_output_source: firstOutputSource,
             context: { ...context },
             timings_ms: {
               ...Object.fromEntries(PREPARATION_STAGES.map((stage) => [stage, Number(preparationMs[stage].toFixed(1))])),
@@ -260,6 +302,7 @@ export function createStreamPerformanceMetrics({ now = () => performance.now(),
           });
           if (recentRequests.length > MAX_RECENT_REQUESTS) recentRequests.shift();
           if (firstOutputAt !== null) observe(route.requestTtft, Math.max(0, firstOutputAt - requestStartedAt));
+          if (firstOutputSource) route.outputSources[firstOutputSource] += 1;
           if (upstreamStartedAt === null) {
             route.neutral += 1;
             return;
@@ -321,8 +364,8 @@ export function markUpstreamActivity() {
   tracker()?.upstreamActivity?.();
 }
 
-export function markFirstOutput() {
-  tracker()?.firstOutput();
+export function markFirstOutput(source) {
+  tracker()?.firstOutput(source);
 }
 
 export function markOutputTokens(value) {

package/src/usage-analysis.mjs

@@ -0,0 +1,45 @@
+import { summarizeUsageLogs, usageLogPath, usageSummaryVersion } from "./usage-store.mjs";
+import { createUsageAnalytics } from "./usage-analytics.mjs";
+
+const MAX_ENTRIES = 2;
+const MAX_BYTES = 2 * 1024 * 1024;
+const cache = new Map();
+
+// Only bounded, settled-file aggregates survive. No record index or payload cache.
+export async function analyzeUsageLogs(filePath = usageLogPath(), { timeZone = "UTC", now = Date.now(), warn = console.error } = {}) {
+  const analytics = createUsageAnalytics({ timeZone, now });
+  const zone = new Intl.DateTimeFormat("sv-SE", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" });
+  const version = warn === console.error ? await usageSummaryVersion(filePath) : null;
+  const key = version === null ? null : `${version}\0${zone.resolvedOptions().timeZone}\0${zone.format(new Date(now))}`;
+  if (key && cache.has(key)) return structuredClone(await cache.get(key).promise);
+  if (key) {
+    for (const [old, entry] of cache) if (entry.version !== version) cache.delete(old);
+    while (cache.size >= MAX_ENTRIES) cache.delete(cache.keys().next().value);
+  } else cache.clear();
+  const entry = { version, bytes: 0, promise: null };
+  entry.promise = (async () => {
+    let warned = false;
+    const summary = await summarizeUsageLogs(filePath, {
+      onRecord: analytics.record,
+      warn(message) { warned = true; warn(message); },
+    });
+    const result = { summary, analytics: analytics.snapshot() };
+    const after = key ? await usageSummaryVersion(filePath) : null;
+    if (key && cache.get(key) === entry) {
+      entry.bytes = Buffer.byteLength(JSON.stringify(result));
+      if (warned || after !== version || entry.bytes > MAX_BYTES || result.analytics.undated_records > 0) cache.delete(key);
+      else {
+        let bytes = [...cache.values()].reduce((total, item) => total + item.bytes, 0);
+        for (const [old, item] of cache) {
+          if (bytes <= MAX_BYTES) break;
+          cache.delete(old);
+          bytes -= item.bytes;
+        }
+      }
+    }
+    return result;
+  })();
+  if (key) cache.set(key, entry);
+  try { return structuredClone(await entry.promise); }
+  catch (error) { if (cache.get(key) === entry) cache.delete(key); throw error; }
+}

package/src/usage-store.mjs

@@ -312,7 +312,7 @@ const SUMMARY_CACHE_MAX_BYTES = 256 * 1024;
 const SUMMARY_CACHE_SETTLED_MS = 2000;
 let cachedSummary = null;
 
-async function usageSummaryVersion(filePath) {
+export async function usageSummaryVersion(filePath) {
   try {
     const files = await Promise.all([rotatedFilePath(filePath), filePath].map(async (file) => {
       try {

package/src/usage.mjs

@@ -2,6 +2,7 @@ import { cliOutputFormat, cliOutputWidth, formatResponsiveCliTable, terminalCell
 import { cacheReadTokens, summarizeUsageLogs, usageCacheHitRate, usageLogPath } from "./usage-store.mjs";
 
 export {
+  usageSummaryVersion,
   usageLoggingStats,
   usageLogPath,
   usageLogMaxBytes,