@zhin.js/gateway 1.2.0 → 1.4.0

package/lib/supervisor/instance-supervisor.d.ts

@@ -17,7 +17,10 @@ export interface InstanceStatus {
     readonly pid?: number;
     /** Epoch ms of the current child's `ready`. */
     readonly startedAt?: number;
-    /** Runtime generation reported by the instance in `ready`. */
+    /**
+     * Committed Runtime generation of the current instance: reported in `ready`, then advanced by
+     * every route table the instance publishes after a hot reload commits (#1250).
+     */
     readonly generation?: number;
     /** Protocol version reported by the instance in `ready`. */
     readonly protocolVersion?: number;

package/lib/supervisor/instance-supervisor.js

@@ -55,6 +55,8 @@ export class InstanceSupervisor extends EventEmitter {
     #backoffTimer;
     #restartTimes = [];
     #ready;
+    /** Latest committed generation of the current child (`ready`, then each route table). */
+    #generation;
     #startedAt;
     #lastExit;
     #lastFailure;
@@ -76,7 +78,7 @@ export class InstanceSupervisor extends EventEmitter {
             state: this.#state,
             ...(child?.process.pid !== undefined ? { pid: child.process.pid } : {}),
             ...(this.#startedAt !== undefined && this.#state === 'running' ? { startedAt: this.#startedAt } : {}),
-            ...(this.#ready?.generation !== undefined ? { generation: this.#ready.generation } : {}),
+            ...(this.#generation !== undefined ? { generation: this.#generation } : {}),
             ...(this.#ready ? { protocolVersion: this.#ready.version } : {}),
             lastExitCode: this.#lastExit?.code ?? null,
             lastExitSignal: this.#lastExit?.signal ?? null,
@@ -153,6 +155,7 @@ export class InstanceSupervisor extends EventEmitter {
         const { spawn: spec } = this.#options;
         const output = this.#options.output ?? 'pipe';
         this.#ready = undefined;
+        this.#generation = undefined;
         this.#startedAt = undefined;
         this.#setState('starting');
         let processHandle;
@@ -250,12 +253,19 @@ export class InstanceSupervisor extends EventEmitter {
             }
             child.ready = true;
             this.#ready = message.payload;
+            this.#noteGeneration(message.payload.generation);
             this.#startedAt = Date.now();
             this.#setState('running');
             this.emit('ready', message.payload);
             child.settleStart?.();
             return;
         }
+        if (message.type === 'routes') {
+            // The instance republishes its route table on every generation commit (hot reload,
+            // configuration apply); the table carries that generation (#1250).
+            this.#noteGeneration(message.payload.table.generation);
+            return;
+        }
         if (message.type !== 'restart-request')
             return;
         this.emit('restart-request', message.payload);
@@ -273,6 +283,13 @@ export class InstanceSupervisor extends EventEmitter {
         this.#setState('stopping');
         void this.#terminate(child, `restart:${message.payload.reason}`);
     }
+    /** Generations only move forward; a late table of an older generation never rolls status back. */
+    #noteGeneration(generation) {
+        if (generation === undefined)
+            return;
+        if (this.#generation === undefined || generation > this.#generation)
+            this.#generation = generation;
+    }
     #onExit(child, code, signal) {
         if (this.#child !== child)
             return;

package/lib/terminal/modules.d.ts

@@ -85,3 +85,15 @@ export declare function createModuleCache(loaders?: TerminalModuleLoaders): {
     pty(): Promise<ModuleLoadResult<PtyModule>>;
     ssh(): Promise<ModuleLoadResult<SshModule>>;
 };
+/**
+ * Whether `error` says the package itself cannot be resolved (not installed), as opposed to the
+ * package loading but failing inside (e.g. node-pty's `pty.node` missing because pnpm skipped its
+ * build script, or an addon built for another Node.js ABI).
+ */
+export declare function isPackageNotInstalledError(name: string, error: unknown): boolean;
+/**
+ * Operator hint for an optional terminal module that failed to load (#1250). Distinguishes "not
+ * installed" from "installed but its native addon was not built" — the usual cause with pnpm, which
+ * skips dependency build scripts unless `allowBuilds` lets them run. Matches `zhin doctor`'s fix text.
+ */
+export declare function moduleLoadFailureHint(name: string, error: unknown): string;

package/lib/terminal/modules.js

@@ -38,7 +38,43 @@ async function settle(load, name) {
     try {
         return { ok: true, module: await load() };
     }
-    catch {
-        return { ok: false, reason: `${name} 不可用（可选依赖未安装或原生模块构建失败）：在项目中执行 pnpm add ${name} 后重启` };
+    catch (error) {
+        return { ok: false, reason: moduleLoadFailureHint(name, error) };
     }
 }
+/** Modules whose package ships a native addon pnpm builds only when allowed. */
+const NATIVE_MODULES = new Set(['node-pty']);
+/**
+ * Whether `error` says the package itself cannot be resolved (not installed), as opposed to the
+ * package loading but failing inside (e.g. node-pty's `pty.node` missing because pnpm skipped its
+ * build script, or an addon built for another Node.js ABI).
+ */
+export function isPackageNotInstalledError(name, error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const code = error.code;
+    if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND')
+        return false;
+    const message = String(error.message ?? '');
+    // `Cannot find package 'node-pty' imported from …` (ESM) / `Cannot find module 'node-pty'` (CJS).
+    // A missing file inside the package (`../build/Release/pty.node`) names a path, not the package.
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`Cannot find (?:package|module) '${escaped}(?:/[^']*)?'`).test(message)
+        && !/\.node'/.test(message);
+}
+/**
+ * Operator hint for an optional terminal module that failed to load (#1250). Distinguishes "not
+ * installed" from "installed but its native addon was not built" — the usual cause with pnpm, which
+ * skips dependency build scripts unless `allowBuilds` lets them run. Matches `zhin doctor`'s fix text.
+ */
+export function moduleLoadFailureHint(name, error) {
+    if (isPackageNotInstalledError(name, error)) {
+        return `${name} 未安装（可选依赖）：在项目中执行 pnpm add ${name} 后重启`;
+    }
+    if (NATIVE_MODULES.has(name)) {
+        return `${name} 已安装，但原生模块未构建或与当前 Node.js 不匹配（pnpm 默认跳过依赖的构建脚本）：`
+            + `在 pnpm-workspace.yaml 的 allowBuilds 中放行 ${name}（或运行 zhin migrate），然后执行 pnpm rebuild ${name} 并重启`
+            + '（需要 Python 与 C/C++ 编译工具链）';
+    }
+    return `${name} 已安装但加载失败：执行 pnpm install 修复依赖后重启`;
+}

package/lib/usage/aggregate.d.ts

@@ -1,3 +1,4 @@
+import { type PromptCacheHint } from './prompt-cache.js';
 export declare const DAY_MS = 86400000;
 export declare const HOUR_MS = 3600000;
 export declare const FIXED_SEGMENTS: ReadonlySet<string>;
@@ -28,6 +29,20 @@ export interface UsageStatsQuery {
     readonly until: number;
     readonly bucket: UsageBucket;
     readonly session?: string;
+    /** IANA zone for bucket boundaries; defaults to {@link defaultUsageTimeZone}. */
+    readonly timeZone?: string;
+}
+/**
+ * Resolves a recorded provider id (`services:<id>`, `accounts:<id>`, `profiles:<id>` or a
+ * legacy alias) to the service it belongs to. Traces record either the service or the account
+ * depending on the call path, so without this one model splits into two rows.
+ */
+export type UsageProviderResolver = (provider: string) => Readonly<{
+    key: string;
+    label: string;
+}> | undefined;
+export interface UsageStatsOptions {
+    readonly resolveProvider?: UsageProviderResolver;
 }
 export interface UsageStatsTokens {
     readonly calls: number;
@@ -51,37 +66,83 @@ export interface UsageStats {
             readonly p50: number;
             readonly p90: number;
         };
+        /** `inputTokens` is the provider-reported prompt tokens of every model call (all iterations, sub-agents included). */
+        readonly inputBasis: 'reported-all-calls';
     };
     readonly byModel: ReadonlyArray<UsageStatsTokens & {
+        /** Merge key: the resolved service id, or the recorded provider when it cannot be resolved. */
         readonly provider: string;
         readonly model: string;
+        /** `服务名 · 模型`, or just the model when the recorded provider is an opaque id. */
+        readonly displayName: string;
+        readonly providerLabel?: string;
+        /** Recorded provider ids merged into this row (e.g. `services:…` and `accounts:…`). */
+        readonly providerIds: readonly string[];
     }>;
     readonly bySession: ReadonlyArray<UsageStatsTokens & {
         readonly sessionKey: string;
         readonly platform?: string;
         readonly scope?: string;
         readonly sceneId?: string;
+        /** Readable conversation label from the trace origin (`平台 · 群 名称`), when recorded. */
+        readonly displayName?: string;
         readonly turns: number;
     }>;
+    /** `byModel` keys use `${provider}/${model}` of the merged rows; `modelLabels` maps them to display names. */
     readonly series: ReadonlyArray<UsageStatsTokens & {
         readonly bucketStart: number;
         readonly byModel: Readonly<Record<string, number>>;
     }>;
+    readonly modelLabels: Readonly<Record<string, string>>;
+    /**
+     * Estimated prompt composition of each turn's FIRST model request (`context_budget`), summed over
+     * turns that recorded it. Not comparable to `totals.inputTokens` (actual, every call); see `inputBreakdown`.
+     */
     readonly segments: {
         readonly history: number;
         readonly fixed: number;
         readonly user: number;
     };
+    readonly inputBreakdown: {
+        readonly basis: 'first-request-estimate';
+        /** Turns that carried a context budget. */
+        readonly turns: number;
+        readonly history: number;
+        readonly fixed: number;
+        readonly user: number;
+        /** Segments not counted as history / fixed / user (e.g. active skills). */
+        readonly other: number;
+        /** history + fixed + user + other. */
+        readonly estimatedTotal: number;
+        /** Provider-reported prompt tokens of the same first requests, for comparison with `estimatedTotal`. */
+        readonly firstRequestInputTokens: number;
+    };
     readonly filesRead: number;
     readonly malformedLines: number;
+    /**
+     * Services that likely do not support or pass through prompt caching (#1250): a long run of
+     * calls without cache reads while adjacent requests shared their prefix. Empty when none.
+     */
+    readonly promptCacheHints: readonly PromptCacheHint[];
 }
 export declare const USAGE_STATS_SESSION_LIMIT = 50;
-/** Start of the local hour/day containing `ms`. */
-export declare function bucketStartOf(ms: number, bucket: UsageBucket): number;
+/** `TZ` wins; otherwise the zone this process runs in (same rule as the instance Schedule Host). */
+export declare function defaultUsageTimeZone(environment?: Readonly<Record<string, string | undefined>>): string;
+export declare function isUsageTimeZone(value: unknown): value is string;
+/** Start of the hour/day containing `ms` in `timeZone` (default: the process zone). */
+export declare function bucketStartOf(ms: number, bucket: UsageBucket, timeZone?: string): number;
+/** `YYYY-MM-DD` of `ms` in `timeZone` (default: the process zone). */
+export declare function dayKeyOf(ms: number, timeZone?: string): string;
+/** Ids minted by the provider graph (`services:<uuid>` …) carry no meaning for a reader. */
+export declare function isOpaqueProviderId(provider: string): boolean;
+/** `服务名 · 模型`; an unresolved opaque id shows the model alone instead of a UUID. */
+export declare function usageModelDisplayName(provider: string, model: string, label?: string): string;
+/** Readable label for a trace's conversation, from its recorded IM origin; `undefined` otherwise. */
+export declare function sessionDisplayNameOf(trace: any): string | undefined;
 /** `platform:endpoint:scope:sceneId`; other shapes keep whatever parts they have. */
 export declare function parseSessionKey(key: string): {
     platform?: string;
     scope?: string;
     sceneId?: string;
 };
-export declare function buildUsageStats(dir: string, query: UsageStatsQuery): Promise<UsageStats>;
+export declare function buildUsageStats(dir: string, query: UsageStatsQuery, options?: UsageStatsOptions): Promise<UsageStats>;

package/lib/usage/aggregate.js

@@ -9,6 +9,7 @@ import { createReadStream } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
+import { PromptCacheProbe } from './prompt-cache.js';
 export const DAY_MS = 86_400_000;
 export const HOUR_MS = 3_600_000;
 export const FIXED_SEGMENTS = new Set(['system', 'tool_schemas', 'output_schema', 'tool_index', 'skill_catalog', 'agent_catalog', 'memory', 'bootstrap']);
@@ -80,21 +81,126 @@ export async function scanTraces(dir, options, visit) {
     return { files: names.length, filesRead, lines, malformed };
 }
 export const USAGE_STATS_SESSION_LIMIT = 50;
-/** Start of the local hour/day containing `ms`. */
-export function bucketStartOf(ms, bucket) {
-    const d = new Date(ms);
-    return bucket === 'day'
-        ? new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
-        : new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()).getTime();
-}
-function nextBucket(start, bucket) {
-    const d = new Date(start);
-    return bucket === 'day'
-        ? new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime()
-        : start + HOUR_MS;
+/** `TZ` wins; otherwise the zone this process runs in (same rule as the instance Schedule Host). */
+export function defaultUsageTimeZone(environment = process.env) {
+    const candidate = environment.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    return isUsageTimeZone(candidate) ? candidate : 'UTC';
+}
+export function isUsageTimeZone(value) {
+    if (typeof value !== 'string' || !value || value.length > 64)
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const zoneFormatters = new Map();
+/** Wall-clock fields of `ms` in `timeZone`. */
+function wallClock(ms, timeZone) {
+    let format = zoneFormatters.get(timeZone);
+    if (!format) {
+        format = new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric' });
+        zoneFormatters.set(timeZone, format);
+    }
+    const parts = {};
+    for (const part of format.formatToParts(new Date(ms)))
+        if (part.type !== 'literal')
+            parts[part.type] = Number(part.value);
+    return { year: parts.year, month: parts.month, day: parts.day, hour: parts.hour % 24, minute: parts.minute, second: parts.second };
+}
+/** Wall clock of `ms` in `timeZone`, encoded as if it were UTC. */
+function wallMs(ms, timeZone) {
+    const w = wallClock(ms, timeZone);
+    return Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute, w.second) + (((ms % 1000) + 1000) % 1000);
+}
+/** Start of the hour/day containing `ms` in `timeZone` (default: the process zone). */
+export function bucketStartOf(ms, bucket, timeZone) {
+    if (!timeZone) {
+        const d = new Date(ms);
+        return bucket === 'day'
+            ? new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+            : new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()).getTime();
+    }
+    const wall = wallMs(ms, timeZone);
+    const w = wallClock(ms, timeZone);
+    const target = bucket === 'day' ? Date.UTC(w.year, w.month - 1, w.day) : Date.UTC(w.year, w.month - 1, w.day, w.hour);
+    let start = ms - (wall - target);
+    // A daylight-saving change between `target` and `ms` shifts the estimate; correct it once.
+    for (let i = 0; i < 2; i++) {
+        const drift = wallMs(start, timeZone) - target;
+        if (drift === 0)
+            break;
+        start -= drift;
+    }
+    return start;
+}
+function nextBucket(start, bucket, timeZone) {
+    if (!timeZone) {
+        const d = new Date(start);
+        return bucket === 'day'
+            ? new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime()
+            : start + HOUR_MS;
+    }
+    // 26 h always lands inside the next local day (days are 23–25 h long).
+    return bucket === 'day' ? bucketStartOf(start + 26 * HOUR_MS, 'day', timeZone) : bucketStartOf(start + HOUR_MS + 1, 'hour', timeZone);
+}
+/** `YYYY-MM-DD` of `ms` in `timeZone` (default: the process zone). */
+export function dayKeyOf(ms, timeZone) {
+    if (!timeZone) {
+        const d = new Date(ms);
+        return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+    }
+    const w = wallClock(ms, timeZone);
+    return `${w.year}-${String(w.month).padStart(2, '0')}-${String(w.day).padStart(2, '0')}`;
+}
+/** Ids minted by the provider graph (`services:<uuid>` …) carry no meaning for a reader. */
+export function isOpaqueProviderId(provider) {
+    return /^(services|accounts|profiles):/u.test(provider);
+}
+/** `服务名 · 模型`; an unresolved opaque id shows the model alone instead of a UUID. */
+export function usageModelDisplayName(provider, model, label) {
+    if (label)
+        return `${label} · ${model}`;
+    if (!provider || provider === 'unknown' || isOpaqueProviderId(provider))
+        return model;
+    return `${provider} · ${model}`;
+}
+const SCOPE_LABELS = { private: '私聊', direct: '私聊', group: '群', channel: '频道', guild: '频道' };
+/** Readable label for a trace's conversation, from its recorded IM origin; `undefined` otherwise. */
+export function sessionDisplayNameOf(trace) {
+    const origin = trace?.origin;
+    if (!origin || typeof origin !== 'object')
+        return undefined;
+    if (origin.kind === 'im') {
+        const platform = typeof origin.platform === 'string' ? origin.platform : '';
+        const scope = typeof origin.scope === 'string' ? origin.scope : typeof origin.conversation?.kind === 'string' ? origin.conversation.kind : '';
+        const conversationName = typeof origin.conversation?.name === 'string' && origin.conversation.name.trim() ? origin.conversation.name.trim() : undefined;
+        const principalName = typeof trace?.principal?.display_name === 'string' && trace.principal.display_name.trim() ? trace.principal.display_name.trim() : undefined;
+        const sceneId = typeof origin.sceneId === 'string' ? origin.sceneId : typeof origin.conversation?.id === 'string' ? origin.conversation.id : '';
+        const name = conversationName ?? ((scope === 'private' || scope === 'direct') ? principalName : undefined) ?? sceneId;
+        const parts = [platform, `${SCOPE_LABELS[scope] ?? scope}${name ? ` ${name}` : ''}`.trim()].filter(Boolean);
+        return parts.length ? parts.join(' · ') : undefined;
+    }
+    if (origin.kind === 'http')
+        return 'HTTP';
+    if (origin.kind === 'schedule')
+        return `定时任务 ${String(origin.jobId ?? '')}`.trim();
+    if (origin.kind === 'a2a')
+        return 'A2A';
+    if (origin.kind === 'mcp')
+        return 'MCP';
+    if (origin.kind === 'internal')
+        return `内部 ${String(origin.source ?? '')}`.trim();
+    return undefined;
 }
 /** `platform:endpoint:scope:sceneId`; other shapes keep whatever parts they have. */
 export function parseSessionKey(key) {
+    // Hashed identities (`personal-session:v1:<sha>`, `scene-task:v1:<sha>`) carry no address.
+    if (/^[a-z-]+:v\d+:[0-9a-f]{16,}$/u.test(key))
+        return {};
     const parts = key.split(':');
     if (parts.length >= 4)
         return { platform: parts[0], scope: parts[2], sceneId: parts.slice(3).join(':') };
@@ -113,40 +219,80 @@ function tokens(t) {
         cacheShare: t.input > 0 ? Math.min(1, t.cache / t.input) : 0,
     };
 }
+/** Sub-agent nesting depth the aggregate follows; deeper (malformed) trees are cut off. */
+const MAX_SUBAGENT_DEPTH = 16;
 function nearestRank(sorted, p) {
     if (sorted.length === 0)
         return 0;
     return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1))];
 }
-export async function buildUsageStats(dir, query) {
+export async function buildUsageStats(dir, query, options = {}) {
     const { since, until, bucket } = query;
+    const timeZone = query.timeZone && isUsageTimeZone(query.timeZone) ? query.timeZone : defaultUsageTimeZone();
     const total = tally();
     let turns = 0;
     const callShares = [];
     const segments = { history: 0, fixed: 0, user: 0 };
+    const breakdown = { turns: 0, other: 0, firstRequestInputTokens: 0 };
     const models = new Map();
+    const resolved = new Map();
     const sessions = new Map();
     const buckets = new Map();
-    for (let t = bucketStartOf(since, bucket); t < until; t = nextBucket(t, bucket)) {
+    for (let t = bucketStartOf(since, bucket, timeZone); t < until; t = nextBucket(t, bucket, timeZone)) {
         buckets.set(t, { ...tally(), byModel: {} });
     }
+    const resolve = (provider) => {
+        if (!options.resolveProvider)
+            return undefined;
+        if (!resolved.has(provider)) {
+            let value;
+            try {
+                value = options.resolveProvider(provider);
+            }
+            catch {
+                value = undefined;
+            }
+            resolved.set(provider, value);
+        }
+        return resolved.get(provider);
+    };
+    const cacheProbe = new PromptCacheProbe({ resolveProvider: resolve });
     const scan = await scanTraces(dir, { since, until, session: query.session }, (trace, startedAt) => {
         turns++;
+        cacheProbe.visit(trace);
         const session = sessions.get(trace.session_key) ?? { ...tally(), turns: 0 };
         session.turns++;
+        session.displayName ??= sessionDisplayNameOf(trace);
         sessions.set(trace.session_key, session);
-        const calls = Array.isArray(trace.model_calls) ? trace.model_calls : [];
-        for (const raw of calls) {
+        // Every model call of the turn: the root's, then each sub-agent's (nested, up to MAX_SUBAGENT_DEPTH). A
+        // sub-agent trace's own `model_calls` are not repeated in its parent's, so nothing counts twice;
+        // its calls count toward the root turn's session. `firstPrompt` is the root's first request.
+        const calls = [];
+        const collect = (node, depth) => {
+            if (!node || typeof node !== 'object' || depth > MAX_SUBAGENT_DEPTH)
+                return;
+            if (Array.isArray(node.model_calls))
+                calls.push(...node.model_calls);
+            if (Array.isArray(node.subagents))
+                for (const child of node.subagents)
+                    collect(child, depth + 1);
+        };
+        collect(trace, 0);
+        const rootCalls = Array.isArray(trace.model_calls) ? trace.model_calls.length : 0;
+        let firstPrompt;
+        for (const [index, raw] of calls.entries()) {
             const call = raw;
             const prompt = num(call?.prompt_tokens);
             if (prompt === undefined)
                 continue;
+            if (index < rootCalls)
+                firstPrompt ??= prompt;
             const output = num(call?.completion_tokens) ?? 0;
             const cache = num(call?.cache_read_tokens) ?? 0;
             const cacheWrite = num(call?.cache_write_tokens) ?? 0;
             if (prompt > 0)
                 callShares.push(Math.min(1, cache / prompt));
-            const provider = typeof call?.provider === 'string' && call.provider ? call.provider : 'unknown';
+            const recorded = typeof call?.provider === 'string' && call.provider ? call.provider : 'unknown';
             const model = typeof call?.model === 'string' && call.model ? call.model : 'unknown';
             const at = num(call?.started_at) ?? num(call?.at) ?? startedAt;
             for (const t of [total, session]) {
@@ -156,15 +302,19 @@ export async function buildUsageStats(dir, query) {
                 t.cache += cache;
                 t.cacheWrite += cacheWrite;
             }
-            const modelKey = `${provider}/${model}`;
-            const m = models.get(modelKey) ?? { ...tally(), provider, model };
+            // One row per (service, model): `services:` and `accounts:` ids of the same service merge.
+            const service = resolve(recorded);
+            const groupKey = service ? `${service.key}\n${model}` : isOpaqueProviderId(recorded) ? `\n${model}` : `${recorded}\n${model}`;
+            const m = models.get(groupKey) ?? { ...tally(), provider: service?.key ?? recorded, model, ...(service ? { label: service.label } : {}), providerIds: new Set() };
             m.calls++;
             m.input += prompt;
             m.output += output;
             m.cache += cache;
             m.cacheWrite += cacheWrite;
-            models.set(modelKey, m);
-            const slot = buckets.get(bucketStartOf(at, bucket)) ?? buckets.get(bucketStartOf(startedAt, bucket));
+            m.providerIds.add(recorded);
+            models.set(groupKey, m);
+            const modelKey = `${m.provider}/${m.model}`;
+            const slot = buckets.get(bucketStartOf(at, bucket, timeZone)) ?? buckets.get(bucketStartOf(startedAt, bucket, timeZone));
             if (slot) {
                 slot.calls++;
                 slot.input += prompt;
@@ -176,6 +326,8 @@ export async function buildUsageStats(dir, query) {
         }
         const budget = trace.context_budget?.segments;
         if (budget && typeof budget === 'object') {
+            breakdown.turns++;
+            breakdown.firstRequestInputTokens += firstPrompt ?? 0;
             for (const [key, value] of Object.entries(budget)) {
                 const n = num(value) ?? 0;
                 if (key === 'history')
@@ -184,29 +336,50 @@ export async function buildUsageStats(dir, query) {
                     segments.user += n;
                 else if (FIXED_SEGMENTS.has(key))
                     segments.fixed += n;
+                else
+                    breakdown.other += n;
             }
         }
     });
     callShares.sort((a, b) => a - b);
+    const byModel = [...models.values()]
+        .map(m => ({
+        provider: m.provider,
+        model: m.model,
+        displayName: usageModelDisplayName(m.provider, m.model, m.label),
+        ...(m.label ? { providerLabel: m.label } : {}),
+        providerIds: [...m.providerIds].sort(),
+        ...tokens(m),
+    }))
+        .sort((a, b) => b.inputTokens - a.inputTokens);
     return {
-        range: { since, until, bucket, timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone },
+        range: { since, until, bucket, timeZone },
         totals: {
             turns,
             ...tokens(total),
             cacheShareByCall: { p50: nearestRank(callShares, 50), p90: nearestRank(callShares, 90) },
+            inputBasis: 'reported-all-calls',
         },
-        byModel: [...models.values()]
-            .map(m => ({ provider: m.provider, model: m.model, ...tokens(m) }))
-            .sort((a, b) => b.inputTokens - a.inputTokens),
+        byModel,
         bySession: [...sessions.entries()]
-            .map(([sessionKey, s]) => ({ sessionKey, ...parseSessionKey(sessionKey), turns: s.turns, ...tokens(s) }))
+            .map(([sessionKey, s]) => ({ sessionKey, ...parseSessionKey(sessionKey), ...(s.displayName ? { displayName: s.displayName } : {}), turns: s.turns, ...tokens(s) }))
             .sort((a, b) => b.inputTokens - a.inputTokens)
             .slice(0, USAGE_STATS_SESSION_LIMIT),
         series: [...buckets.entries()]
             .sort(([a], [b]) => a - b)
             .map(([bucketStart, b]) => ({ bucketStart, ...tokens(b), byModel: b.byModel })),
+        modelLabels: Object.fromEntries(byModel.map(m => [`${m.provider}/${m.model}`, m.displayName])),
         segments,
+        inputBreakdown: {
+            basis: 'first-request-estimate',
+            turns: breakdown.turns,
+            ...segments,
+            other: breakdown.other,
+            estimatedTotal: segments.history + segments.fixed + segments.user + breakdown.other,
+            firstRequestInputTokens: breakdown.firstRequestInputTokens,
+        },
         filesRead: scan.filesRead,
         malformedLines: scan.malformed,
+        promptCacheHints: cacheProbe.hints(),
     };
 }

package/lib/usage/prompt-cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * #1250 usage-cache-unsupported-hint: spots a provider that never reports prompt-cache reads
+ * although its adjacent requests share the cacheable prefix (system prompt + tool definitions,
+ * recorded per model call as `prefix_hash`). Read-only over the trace archive records.
+ */
+import type { UsageProviderResolver } from './aggregate.js';
+/** Defaults: at least 20 consecutive zero-cache calls across at least 3 sessions. */
+export declare const PROMPT_CACHE_HINT_MIN_CALLS = 20;
+export declare const PROMPT_CACHE_HINT_MIN_SESSIONS = 3;
+/** Share of adjacent same-session requests with an identical prefix needed as evidence. */
+export declare const PROMPT_CACHE_HINT_MIN_SAME_PREFIX = 0.5;
+export interface PromptCacheHint {
+    /** Merge key: resolved service id, else the recorded provider id. */
+    readonly provider: string;
+    /** Service display name when resolvable. */
+    readonly label?: string;
+    /** Recorded provider ids merged into this row. */
+    readonly providerIds: readonly string[];
+    /** Most recent run of consecutive calls without a cache read. */
+    readonly zeroCacheCalls: number;
+    /** Sessions those calls came from. */
+    readonly sessions: number;
+    /** Calls in that run that reported `cacheRead = 0` (the rest did not report it at all). */
+    readonly reportedZeroCalls: number;
+    /** Adjacent same-session request pairs in that run whose prefix hashes were compared. */
+    readonly comparedPairs: number;
+    /** Of those, pairs with an identical prefix. */
+    readonly samePrefixPairs: number;
+    /** samePrefixPairs / comparedPairs. */
+    readonly samePrefixRatio: number;
+    /** Readable hint, e.g. for CLI output. */
+    readonly message: string;
+}
+export interface PromptCacheProbeOptions {
+    readonly resolveProvider?: UsageProviderResolver;
+    readonly minCalls?: number;
+    readonly minSessions?: number;
+    readonly minSamePrefixRatio?: number;
+}
+/**
+ * Feed trace records in chronological order ({@link visit}), then read {@link hints}.
+ * Sub-agent turns are included with their own session keys.
+ */
+export declare class PromptCacheProbe {
+    #private;
+    constructor(options?: PromptCacheProbeOptions);
+    visit(trace: any): void;
+    hints(): PromptCacheHint[];
+}