Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
fix(tokens): count every step of a turn in token usage
parz1valc8bc78a4fd33
diff --git a/src/core/agent.ts b/src/core/agent.tsindex a2cbdd37..5848236e 100644--- a/src/core/agent.ts+++ b/src/core/agent.ts@@ -134,6 +134,7 @@ const NOTE_COOLDOWN_MS = 3 * 60 * 1000;import { runReflection } from '../learning/reflection.js';import { createOwnerSectionsMemo } from '../learning/owner-brief.js';import type { ApplyResult } from '../memory/beliefs.js';+import { TurnUsage, type StepUsageLike } from './turn-usage.js';/*** Step-aware text stream for the TUI. The SDK's textStream concatenates@@ -2212,7 +2213,7 @@ export class Agent {/** Mechanically force the first step to contain a tool call. */forceFirstTool?: boolean;toolDiscovery: ToolDiscovery;- onStep: (toolCalls: any[] | undefined, toolResults: any[] | undefined) => void | Promise<void>;+ onStep: (toolCalls: any[] | undefined, toolResults: any[] | undefined, usage?: StepUsageLike) => void | Promise<void>;}): Promise<{ text: string; usage: any; reasoning?: any; finishReason?: string }> {this.markProgress(`Resuming with ${opts.provider.name}...`);const deadlineAt = Date.now() + MAX_PROVIDER_ATTEMPT_MS;@@ -2245,8 +2246,8 @@ export class Agent {},abortSignal: opts.abortController.signal,experimental_include: { requestBody: false },- onStepFinish: async ({ toolCalls, toolResults }) => {- await opts.onStep(toolCalls as any[], toolResults as any[]);+ onStepFinish: async ({ toolCalls, toolResults, usage }) => {+ await opts.onStep(toolCalls as any[], toolResults as any[], usage);},});const text = (opts.channel@@ -3249,7 +3250,15 @@ export class Agent {[Symbol.iterator](): this.providers.getFallbackIterator();let result: any = null;+ // Every model step this turn adds its own usage here (main loop,+ // continuations, guard, verification). Report THIS, never result.usage:+ // that is the SDK's last step only, and later rounds replace result.+ const turnUsage = new TurnUsage();let usedProvider: { name: string; model: string } | null = null;+ // The provider most recently called, even if that attempt never+ // completed (/stop, abort, error). Usage accounting falls back to it so+ // a stopped turn's billed steps aren't filed under "unknown".+ let attemptedProvider: { name: string; model: string } | null = null;let lastError: any = null;let hasCompletedTool = false;let hasStreamedOutput = false;@@ -3445,8 +3454,9 @@ export class Agent {// non-streaming): they were two ~295-line copies that differed only// in their memory-checkpoint label and drifted on every change. The// continuation rounds (resume / verification) share a lighter handler.- const stepHandler = (path: 'stream' | 'gen') => async ({ toolCalls, toolResults }: { toolCalls?: any[]; toolResults?: any[] }): Promise<void> => {+ const stepHandler = (path: 'stream' | 'gen') => async ({ toolCalls, toolResults, usage }: { toolCalls?: any[]; toolResults?: any[]; usage?: StepUsageLike }): Promise<void> => {this.completedStepCount++;+ turnUsage.add(usage);// Completion-contract tracking: per-round step usage and how// the step ended (tool calls pending = work in progress).lastRoundSteps++;@@ -3746,8 +3756,9 @@ export class Agent {}}};- const continuationStepHandler = async (toolCalls: any[] | undefined, toolResults: any[] | undefined): Promise<void> => {+ const continuationStepHandler = async (toolCalls: any[] | undefined, toolResults: any[] | undefined, usage?: StepUsageLike): Promise<void> => {this.completedStepCount++;+ turnUsage.add(usage);lastRoundSteps++;lastStepHadToolCalls = !!(toolCalls && toolCalls.length > 0);const cliChResume = this.channels.get('cli');@@ -3784,6 +3795,7 @@ export class Agent {// Per-attempt latency accounting: the only way to answer "why is// coding slow" with data instead of guesses.const attemptStartedAt = Date.now();+ attemptedProvider = { name: provider.name, model: provider.getModel() };try {const providerDeadlineAt = Date.now() + MAX_PROVIDER_ATTEMPT_MS;this.markProgress(`Calling ${provider.name}...`);@@ -3958,6 +3970,8 @@ export class Agent {stopWhen: stepCountIs(effectiveMaxSteps),abortSignal: loopAbortController.signal,experimental_include: { requestBody: false },+ // Billed like any other step: count it in the turn total.+ onStepFinish: ({ usage }) => { turnUsage.add(usage); },})),loopAbortController,providerDeadlineAt,@@ -4373,8 +4387,9 @@ export class Agent {},abortSignal: loopAbortController.signal,experimental_include: { requestBody: false },- onStepFinish: async ({ toolCalls, toolResults }) => {+ onStepFinish: async ({ toolCalls, toolResults, usage }) => {this.completedStepCount++;+ turnUsage.add(usage);// Completion-contract tracking for the guard round.lastRoundSteps++;lastStepHadToolCalls = !!(toolCalls && toolCalls.length > 0);@@ -4694,22 +4709,40 @@ export class Agent {logger.info({ planLength: preGuardText.length }, 'Plan captured from plan-mode response');}+ // Who billed this turn: the provider that completed, else the last one+ // called (a stopped or failed attempt still billed its finished steps).+ const billedProvider = usedProvider ?? attemptedProvider;+ // Whole-turn usage: every step of every round. Fall back to the last+ // result only if no step reported (a path without step callbacks).+ const turnTotals = turnUsage.totals().steps > 0+ ? turnUsage.totals()+ : (() => {+ const fallback = new TurnUsage();+ fallback.add(result.usage);+ return fallback.totals();+ })();this.tokenBudget.recordUsage({- provider: usedProvider?.name ?? 'unknown',- model: usedProvider?.model ?? 'unknown',- inputTokens: result.usage?.inputTokens ?? 0,- outputTokens: result.usage?.outputTokens ?? 0,- totalTokens: (result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0),+ provider: billedProvider?.name ?? 'unknown',+ model: billedProvider?.model ?? 'unknown',+ inputTokens: turnTotals.inputTokens,+ outputTokens: turnTotals.outputTokens,+ totalTokens: turnTotals.totalTokens,+ // The split lets tokens.cachedWeight discount cache hits in the budget.+ cachedInputTokens: turnTotals.cachedInputTokens,+ noCacheInputTokens: turnTotals.noCacheInputTokens,channelType: msg.channelType,agentId: this.config.cloud.agentId || undefined,});logger.info({- provider: usedProvider?.name,- model: usedProvider?.model,- inputTokens: result.usage?.inputTokens ?? 0,- cachedInputTokens: result.usage?.cachedInputTokens ?? 0,- outputTokens: result.usage?.outputTokens ?? 0,+ provider: billedProvider?.name,+ model: billedProvider?.model,+ inputTokens: turnTotals.inputTokens,+ cachedInputTokens: turnTotals.cachedInputTokens,+ noCacheInputTokens: turnTotals.noCacheInputTokens,+ outputTokens: turnTotals.outputTokens,+ reasoningTokens: turnTotals.reasoningTokens,steps: this.completedStepCount,+ usageSteps: turnTotals.steps,toolCalls: turnToolTrace.length,historyEntries: recentMemory.length,activeTools: activeTools?.length ?? 'all',@@ -4720,7 +4753,7 @@ export class Agent {// Estimate tokens saved by Saver Mode (cap headroom + history trim).// Rough: (default_cap - actual_output) when capped, plus history-window delta.if (saverWasActive) {- const actualOutput = result.usage?.outputTokens ?? 0;+ const actualOutput = turnTotals.outputTokens;const outputHeadroom = Math.max(0, MODEL_OUTPUT_TOKEN_LIMIT - effectiveMaxOutputTokens);const outputSaved = Math.max(0, Math.min(outputHeadroom, MODEL_OUTPUT_TOKEN_LIMIT - actualOutput));// Rough proxy: each trimmed history message ~120 tokens average.@@ -4756,7 +4789,7 @@ export class Agent {role: 'assistant',content: finalText,externalMessageId: `${msg.id}:assistant`,- tokenCount: (result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0),+ tokenCount: turnTotals.totalTokens,reasoning: typeof result.reasoning === 'string'? result.reasoning: result.reasoning@@ -4766,14 +4799,15 @@ export class Agent {channelType: msg.channelType,channelId: msg.channelId,...(typeof msg.metadata?.requestId === 'string' ? { requestId: msg.metadata.requestId } : {}),- ...(usedProvider ? { provider: usedProvider.name, model: usedProvider.model } : {}),+ ...(billedProvider ? { provider: billedProvider.name, model: billedProvider.model } : {}),// Per-turn trace, shown by /trace <id>.traceId,elapsedMs: Date.now() - startTime,steps: this.completedStepCount,- inputTokens: result.usage?.inputTokens ?? 0,- cachedInputTokens: result.usage?.cachedInputTokens ?? 0,- outputTokens: result.usage?.outputTokens ?? 0,+ inputTokens: turnTotals.inputTokens,+ cachedInputTokens: turnTotals.cachedInputTokens,+ noCacheInputTokens: turnTotals.noCacheInputTokens,+ outputTokens: turnTotals.outputTokens,...(lastVerificationNote ? { verification: lastVerificationNote } : {}),...(turnArtifacts.length ? { artifacts: turnArtifacts.map(artifactRef) } : {}),...(researchRun ? { research: researchRun.snapshot() } : {}),@@ -4787,7 +4821,7 @@ export class Agent {this.shortTerm.add(msg.channelId, { id: msg.id, timestamp: msg.timestamp, role: 'user', content: msg.content });this.shortTerm.add(msg.channelId, {id: Date.now().toString(36), timestamp: Date.now(), role: 'assistant', content: finalText,- tokenCount: (result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0), reasoning: result.reasoning || undefined,+ tokenCount: turnTotals.totalTokens, reasoning: result.reasoning || undefined,});}@@ -4814,11 +4848,11 @@ export class Agent {const elapsed = Date.now() - startTime;const stepCount = this.completedStepCount;const completionMeta = {- provider: usedProvider?.name ?? 'unknown',- model: usedProvider?.model ?? 'unknown',- inputTokens: result.usage?.inputTokens ?? 0,- outputTokens: result.usage?.outputTokens ?? 0,- totalTokens: (result.usage?.inputTokens ?? 0) + (result.usage?.outputTokens ?? 0),+ provider: billedProvider?.name ?? 'unknown',+ model: billedProvider?.model ?? 'unknown',+ inputTokens: turnTotals.inputTokens,+ outputTokens: turnTotals.outputTokens,+ totalTokens: turnTotals.totalTokens,budgetUsed: this.tokenBudget.getDailyUsed(),budgetTotal: this.tokenBudget.getBudget(),budgetPercentage: this.tokenBudget.getUsagePercentage(),@@ -5521,7 +5555,8 @@ Is this productive iteration or a stuck loop?`,} else if (action === 'cancel' || action === '4') {await channel.send(`Cancelled. ${this.tokenBudget.getStatusText()}`, channelId);} else if (!action || action === 'status') {- await channel.send(this.tokenBudget.getStatusText(), channelId);+ const split = this.tokenBudget.getCacheSplitText();+ await channel.send(split ? `${this.tokenBudget.getStatusText()}\n${split}` : this.tokenBudget.getStatusText(), channelId);} else {await channel.send(`Unknown budget command "${action}". Available: /budget, /budget override, /budget reset, /budget set <number>, /budget status`, channelId);}diff --git a/src/core/turn-usage.test.ts b/src/core/turn-usage.test.tsnew file mode 100644index 00000000..73162fef--- /dev/null+++ b/src/core/turn-usage.test.ts@@ -0,0 +1,68 @@+import { describe, expect, it } from 'vitest';+import { TurnUsage } from './turn-usage.js';++// The per-step input figures from the 4-step gateway probe in the bug report:+// the SDK's result.usage returned only the last (574); the turn spent 1,902.+const probeSteps = [+ { inputTokens: 351, outputTokens: 60, inputTokenDetails: { cacheReadTokens: 0, noCacheTokens: 351 } },+ { inputTokens: 460, outputTokens: 50, inputTokenDetails: { cacheReadTokens: 300, noCacheTokens: 160 } },+ { inputTokens: 517, outputTokens: 53, inputTokenDetails: { cacheReadTokens: 450, noCacheTokens: 67 } },+ { inputTokens: 574, outputTokens: 2, inputTokenDetails: { cacheReadTokens: 500, noCacheTokens: 74 } },+];++describe('TurnUsage', () => {+ it('sums every step, not just the last one', () => {+ const u = new TurnUsage();+ for (const step of probeSteps) u.add(step);+ const t = u.totals();+ expect(t.inputTokens).toBe(1902);+ expect(t.outputTokens).toBe(165);+ expect(t.totalTokens).toBe(2067);+ expect(t.steps).toBe(4);+ });++ it('splits input into cache hits and uncached', () => {+ const u = new TurnUsage();+ for (const step of probeSteps) u.add(step);+ const t = u.totals();+ expect(t.cachedInputTokens).toBe(1250);+ expect(t.noCacheInputTokens).toBe(652);+ expect(t.cachedInputTokens + t.noCacheInputTokens).toBe(t.inputTokens);+ });++ it('keeps counting across rounds, including rounds that return no text', () => {+ // Main loop, then a tool-only guard round, then a verification round:+ // the old code kept only the newest round with text.+ const u = new TurnUsage();+ u.add({ inputTokens: 1000, outputTokens: 10 }); // main loop+ u.add({ inputTokens: 1200, outputTokens: 0 }); // guard, tool call only+ u.add({ inputTokens: 1300, outputTokens: 40 }); // verification+ expect(u.totals()).toMatchObject({ inputTokens: 3500, outputTokens: 50, steps: 3 });+ });++ it('keeps steps already counted when a later step never arrives', () => {+ // A stream that errors after two steps: step callbacks have fired for+ // both, so they stay counted even though totalUsage would reject.+ const u = new TurnUsage();+ u.add({ inputTokens: 400, outputTokens: 5 });+ u.add({ inputTokens: 450, outputTokens: 7 });+ expect(u.totals()).toMatchObject({ inputTokens: 850, outputTokens: 12, steps: 2 });+ });++ it('falls back to deprecated fields and derives uncached input', () => {+ const u = new TurnUsage();+ u.add({ inputTokens: 100, outputTokens: 20, cachedInputTokens: 80, reasoningTokens: 5 });+ expect(u.totals()).toMatchObject({ cachedInputTokens: 80, noCacheInputTokens: 20, reasoningTokens: 5 });+ });++ it('treats missing or malformed usage as zero', () => {+ const u = new TurnUsage();+ u.add(undefined);+ u.add(null);+ u.add({ inputTokens: Number.NaN, outputTokens: -3 });+ u.add({});+ const t = u.totals();+ expect(t).toMatchObject({ inputTokens: 0, outputTokens: 0, cachedInputTokens: 0, noCacheInputTokens: 0, totalTokens: 0 });+ expect(t.steps).toBe(2);+ });+});diff --git a/src/core/turn-usage.ts b/src/core/turn-usage.tsnew file mode 100644index 00000000..521e03b3--- /dev/null+++ b/src/core/turn-usage.ts@@ -0,0 +1,84 @@+/**+ * Turn-scoped token accounting.+ *+ * One agent turn makes many model calls: tool steps in the main loop, then+ * truncation continuations, the guard round, step-budget continuations and+ * verification. The SDK's `result.usage` is the LAST step only (ai@6:+ * "The token usage of the last step"), and each later round replaced+ * `result`, so the turn used to report a single step's tokens.+ *+ * The fix is to add every step's own usage here, from the step callbacks+ * (`onStepFinish`). A step callback fires for every step that finished, so a+ * stream that later errors, aborts or falls back to another provider still+ * has its billed steps counted — `totalUsage` would reject in those cases.+ */++/** The subset of the SDK's `LanguageModelUsage` this module reads. */+export interface StepUsageLike {+ inputTokens?: number;+ outputTokens?: number;+ inputTokenDetails?: {+ noCacheTokens?: number;+ cacheReadTokens?: number;+ };+ outputTokenDetails?: {+ reasoningTokens?: number;+ };+ /** @deprecated in ai@6 — read as a fallback for cache hits. */+ cachedInputTokens?: number;+ /** @deprecated in ai@6 — read as a fallback for reasoning tokens. */+ reasoningTokens?: number;+}++export interface TurnUsageTotals {+ inputTokens: number;+ /** Input tokens served from the provider's prompt cache. */+ cachedInputTokens: number;+ /** Input tokens billed at the full rate (input minus cache hits). */+ noCacheInputTokens: number;+ outputTokens: number;+ reasoningTokens: number;+ totalTokens: number;+ /** Number of steps whose usage was added. */+ steps: number;+}++const count = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);++export class TurnUsage {+ private input = 0;+ private cached = 0;+ private noCache = 0;+ private output = 0;+ private reasoning = 0;+ private stepCount = 0;++ /** Add one step's usage. Missing or malformed fields count as 0. */+ add(usage: StepUsageLike | null | undefined): void {+ if (!usage || typeof usage !== 'object') return;+ const input = count(usage.inputTokens);+ const cached = count(usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens);+ const noCacheReported = usage.inputTokenDetails?.noCacheTokens;+ const noCache = typeof noCacheReported === 'number'+ ? count(noCacheReported)+ : Math.max(0, input - cached);+ this.input += input;+ this.cached += cached;+ this.noCache += noCache;+ this.output += count(usage.outputTokens);+ this.reasoning += count(usage.outputTokenDetails?.reasoningTokens ?? usage.reasoningTokens);+ this.stepCount++;+ }++ totals(): TurnUsageTotals {+ return {+ inputTokens: this.input,+ cachedInputTokens: this.cached,+ noCacheInputTokens: this.noCache,+ outputTokens: this.output,+ reasoningTokens: this.reasoning,+ totalTokens: this.input + this.output,+ steps: this.stepCount,+ };+ }+}diff --git a/src/utils/config.ts b/src/utils/config.tsindex 75a00766..3984c058 100644--- a/src/utils/config.ts+++ b/src/utils/config.ts@@ -226,6 +226,13 @@ export interface MercuryConfig {saverAutoEnabled?: boolean;/** Lifetime estimated tokens saved by saver mode (informational). */saverTokensSavedLifetime?: number;+ /**+ * How much one cache-hit input token counts toward `dailyBudget`, 0–1.+ * Default 1: every token counts. 0.1 roughly tracks cost, since providers+ * bill cache hits at a fraction of the input price. Out-of-range values+ * are clamped; anything non-numeric counts as 1.+ */+ cachedWeight?: number;};subagents: {enabled: boolean;diff --git a/src/utils/tokens.test.ts b/src/utils/tokens.test.tsindex 736494ca..97d18dc2 100644--- a/src/utils/tokens.test.ts+++ b/src/utils/tokens.test.ts@@ -133,4 +133,94 @@ describe('TokenBudget hardening', () => {expect(budget.isOverBudget()).toBe(true);expect(budget.getRemaining()).toBe(0);});-});\ No newline at end of file+});+describe('TokenBudget cache weighting (tokens.cachedWeight)', () => {+ beforeEach(() => {+ mercuryHome = mkdtempSync(join(tmpdir(), 'mercury-token-test-'));+ });++ afterEach(() => {+ if (mercuryHome) rmSync(mercuryHome, { recursive: true, force: true });+ });++ const turn = {+ provider: 'litellm',+ model: 'gpt-5',+ inputTokens: 100_000,+ outputTokens: 2_000,+ totalTokens: 102_000,+ cachedInputTokens: 90_000,+ noCacheInputTokens: 10_000,+ channelType: 'cli',+ };+ const withWeight = (cachedWeight: unknown) => ({ tokens: { dailyBudget: 1_000_000, cachedWeight } } as unknown as MercuryConfig);++ it('counts every token when the weight is unset (default 1)', () => {+ const budget = new TokenBudget(configWith(1_000_000));+ budget.recordUsage(turn);+ expect(budget.getDailyUsed()).toBe(102_000);+ });++ it('counts cache hits at the configured weight', () => {+ const budget = new TokenBudget(withWeight(0.1));+ budget.recordUsage(turn);+ // 10,000 uncached + 2,000 out + 90,000 × 0.1+ expect(budget.getDailyUsed()).toBe(21_000);+ });++ it('excludes cache hits at weight 0', () => {+ const budget = new TokenBudget(withWeight(0));+ budget.recordUsage(turn);+ expect(budget.getDailyUsed()).toBe(12_000);+ });++ it('clamps out-of-range weights and treats non-numbers as 1', () => {+ const over = new TokenBudget(withWeight(5));+ over.recordUsage(turn);+ expect(over.getDailyUsed()).toBe(102_000);++ rmSync(join(mercuryHome, 'token-usage.json'), { force: true });+ const under = new TokenBudget(withWeight(-2));+ under.recordUsage(turn);+ expect(under.getDailyUsed()).toBe(12_000);++ rmSync(join(mercuryHome, 'token-usage.json'), { force: true });+ const junk = new TokenBudget(withWeight('cheap'));+ junk.recordUsage(turn);+ expect(junk.getDailyUsed()).toBe(102_000);+ });++ it('counts requests without a cache split at their plain total', () => {+ const budget = new TokenBudget(withWeight(0.1));+ budget.recordUsage({ provider: 'openai', model: 'm', inputTokens: 400, outputTokens: 100, totalTokens: 500, channelType: 'internal' });+ expect(budget.getDailyUsed()).toBe(500);+ });++ it('shows the cache split and the weight in /budget', () => {+ const budget = new TokenBudget(withWeight(0.1));+ expect(budget.getCacheSplitText()).toBe('');+ budget.recordUsage(turn);+ expect(budget.getCacheSplitText()).toBe('Today: 100,000 in (90,000 cached · 90%, counted at 0.1) · 10,000 uncached · 2,000 out');+ });++ it('leaves the weight out of the /budget line at the default', () => {+ const budget = new TokenBudget(configWith(1_000_000));+ budget.recordUsage(turn);+ expect(budget.getCacheSplitText()).toBe('Today: 100,000 in (90,000 cached · 90%) · 10,000 uncached · 2,000 out');+ });++ it('keeps the split and the weighted total across a restart', () => {+ const first = new TokenBudget(withWeight(0.1));+ first.recordUsage(turn);+ const second = new TokenBudget(withWeight(0.1));+ expect(second.getDailyUsed()).toBe(21_000);+ expect(second.getDailySplit()).toEqual({ inputTokens: 100_000, cachedInputTokens: 90_000, noCacheInputTokens: 10_000, outputTokens: 2_000 });+ });++ it('clears the split on reset', () => {+ const budget = new TokenBudget(withWeight(0.1));+ budget.recordUsage(turn);+ budget.resetUsage();+ expect(budget.getCacheSplitText()).toBe('');+ });+});diff --git a/src/utils/tokens.ts b/src/utils/tokens.tsindex 2395c030..8e8c3fa7 100644--- a/src/utils/tokens.ts+++ b/src/utils/tokens.ts@@ -11,6 +11,18 @@ export interface TokenTracker {dailyBudget: number;lastResetDate: string;requestLog: TokenLogEntry[];+ /** Today's cache split, for /budget. Absent in files written before it existed. */+ dailySplit?: DailySplit;+}++/** Today's input/output split across every recorded request. */+export interface DailySplit {+ inputTokens: number;+ /** Input tokens served from the provider's prompt cache. */+ cachedInputTokens: number;+ /** Input tokens billed at the full rate. */+ noCacheInputTokens: number;+ outputTokens: number;}export interface TokenLogEntry {@@ -22,6 +34,15 @@ export interface TokenLogEntry {totalTokens: number;channelType: string;agentId?: string;+ /** Cache-hit input tokens, when the caller knows the split. */+ cachedInputTokens?: number;+ /** Full-rate input tokens, when the caller knows the split. */+ noCacheInputTokens?: number;+ /**+ * What this request added to `dailyUsed`: `totalTokens`, or with a cache+ * split, uncached input + output + cache hits × `tokens.cachedWeight`.+ */+ countedTokens?: number;}const TOKEN_FILE = 'token-usage.json';@@ -32,8 +53,35 @@ function safeNumber(value: any): number {return isNaN(n) ? 0 : n;}+const emptySplit = (): DailySplit => ({ inputTokens: 0, cachedInputTokens: 0, noCacheInputTokens: 0, outputTokens: 0 });++/** `tokens.cachedWeight`, clamped to 0–1; anything non-numeric is 1 (count everything). */+export function cachedWeightOf(config: MercuryConfig): number {+ const raw = (config.tokens as { cachedWeight?: unknown } | undefined)?.cachedWeight;+ if (typeof raw !== 'number' || !Number.isFinite(raw)) return 1;+ return Math.min(1, Math.max(0, raw));+}++/**+ * Tokens one request adds to the daily budget. Without a cache split this is+ * the plain total; with one, cache hits count at `weight`.+ */+export function countedTokensFor(+ entry: { inputTokens: number; outputTokens: number; totalTokens: number; cachedInputTokens?: number },+ weight: number,+): number {+ if (entry.cachedInputTokens === undefined) return entry.totalTokens;+ const cached = Math.min(entry.inputTokens, Math.max(0, entry.cachedInputTokens));+ const uncached = Math.max(0, entry.inputTokens - cached);+ return Math.round(uncached + entry.outputTokens + cached * weight);+}++const pct = (part: number, whole: number) => (whole > 0 ? Math.round((part / whole) * 100) : 0);+export class TokenBudget {private dailyUsed = 0;+ /** Today's cache split (resets daily). */+ private dailySplit: DailySplit = emptySplit();private dailyBudget: number;private lastResetDate: string;private requestLog: TokenLogEntry[] = [];@@ -95,6 +143,7 @@ export class TokenBudget {resetUsage(): void {this.dailyUsed = 0;+ this.dailySplit = emptySplit();this.requestLog = [];this.perAgentUsage.clear();this.persist();@@ -123,15 +172,35 @@ export class TokenBudget {const inputTokens = safeNumber(entry.inputTokens);const outputTokens = safeNumber(entry.outputTokens);const totalTokens = safeNumber(entry.totalTokens) || inputTokens + outputTokens;- const safeEntry = { ...entry, inputTokens, outputTokens, totalTokens };+ const hasSplit = entry.cachedInputTokens !== undefined;+ const cachedInputTokens = hasSplit ? Math.min(inputTokens, this.sanitizeCount(entry.cachedInputTokens)) : undefined;+ const noCacheInputTokens = hasSplit+ ? (entry.noCacheInputTokens !== undefined ? this.sanitizeCount(entry.noCacheInputTokens) : Math.max(0, inputTokens - (cachedInputTokens ?? 0)))+ : undefined;+ const countedTokens = countedTokensFor({ inputTokens, outputTokens, totalTokens, cachedInputTokens }, cachedWeightOf(this.config));+ const safeEntry = {+ ...entry,+ inputTokens,+ outputTokens,+ totalTokens,+ ...(hasSplit ? { cachedInputTokens, noCacheInputTokens } : {}),+ countedTokens,+ };const logEntry: TokenLogEntry = { ...safeEntry, timestamp: Date.now() };- this.dailyUsed += totalTokens;+ this.dailyUsed += countedTokens;+ this.dailySplit.inputTokens += inputTokens;+ this.dailySplit.outputTokens += outputTokens;+ if (hasSplit) {+ this.dailySplit.cachedInputTokens += cachedInputTokens ?? 0;+ this.dailySplit.noCacheInputTokens += noCacheInputTokens ?? 0;+ }this.requestLog.push(logEntry);+ // History keeps raw token counts; the weight only shapes the budget.recordDay(inputTokens, outputTokens, totalTokens, logEntry.timestamp);if (entry.agentId) {const agentUsed = this.perAgentUsage.get(entry.agentId) ?? 0;- this.perAgentUsage.set(entry.agentId, agentUsed + totalTokens);+ this.perAgentUsage.set(entry.agentId, agentUsed + countedTokens);}this.persist();@@ -194,6 +263,25 @@ export class TokenBudget {return `Token budget: ${formatNumber(used)} / ${formatNumber(this.dailyBudget)} used (${pct}%), ${formatNumber(remaining)} remaining`;}+ /** Today's cache split, for display. */+ getDailySplit(): DailySplit {+ this.resetIfNewDay();+ return { ...this.dailySplit };+ }++ /**+ * One line for /budget showing what the bar counts: input with its cache+ * hits and hit rate, uncached input, output, and the cache weight when it+ * is not 1. Empty when nothing was recorded today.+ */+ getCacheSplitText(): string {+ const s = this.getDailySplit();+ if (s.inputTokens <= 0 && s.outputTokens <= 0) return '';+ const weight = cachedWeightOf(this.config);+ const weightNote = weight !== 1 ? `, counted at ${weight}` : '';+ return `Today: ${formatNumber(s.inputTokens)} in (${formatNumber(s.cachedInputTokens)} cached · ${pct(s.cachedInputTokens, s.inputTokens)}%${weightNote}) · ${formatNumber(s.noCacheInputTokens)} uncached · ${formatNumber(s.outputTokens)} out`;+ }+/*** Record an estimated savings from Token Saver Mode. Updates both the* per-day counter (resets at day rollover) and the lifetime counter@@ -226,6 +314,7 @@ export class TokenBudget {const today = new Date().toISOString().split('T')[0];if (today !== this.lastResetDate) {this.dailyUsed = 0;+ this.dailySplit = emptySplit();this.lastResetDate = today;this.requestLog = [];this.perAgentUsage.clear();@@ -243,6 +332,7 @@ export class TokenBudget {dailyBudget: this.dailyBudget,lastResetDate: this.lastResetDate,requestLog: this.requestLog.slice(-200),+ dailySplit: this.dailySplit,};writeFileSync(path, JSON.stringify(data, null, 2), 'utf-8');} catch (err) {@@ -273,7 +363,7 @@ export class TokenBudget {this.dailyUsed = restored;} else {// Recompute from valid log entries when dailyUsed is corrupted/null- this.dailyUsed = restoredLogs.reduce((sum, entry) => sum + entry.totalTokens, 0);+ this.dailyUsed = restoredLogs.reduce((sum, entry) => sum + (entry.countedTokens ?? entry.totalTokens), 0);repaired = true;}this.requestLog = (data.requestLog ?? []).map((entry: any) => ({@@ -282,6 +372,15 @@ export class TokenBudget {outputTokens: safeNumber(entry.outputTokens),totalTokens: safeNumber(entry.totalTokens),}));+ const split = data.dailySplit;+ if (split && typeof split === 'object') {+ this.dailySplit = {+ inputTokens: this.sanitizeCount(split.inputTokens),+ cachedInputTokens: this.sanitizeCount(split.cachedInputTokens),+ noCacheInputTokens: this.sanitizeCount(split.noCacheInputTokens),+ outputTokens: this.sanitizeCount(split.outputTokens),+ };+ }}this.lastResetDate = data.lastResetDate ?? today;if (repaired) {@@ -306,6 +405,11 @@ export class TokenBudget {const rawTotal = this.sanitizeCount(entry.totalTokens);const totalTokens = rawTotal > 0 ? rawTotal : inputTokens + outputTokens;+ const optional = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined);+ const cachedInputTokens = optional(entry.cachedInputTokens);+ const noCacheInputTokens = optional(entry.noCacheInputTokens);+ const countedTokens = optional(entry.countedTokens);+return {timestamp: this.sanitizeTimestamp(timestamp),provider: typeof entry.provider === 'string' && entry.provider ? entry.provider : 'unknown',@@ -314,6 +418,9 @@ export class TokenBudget {outputTokens,totalTokens,channelType: typeof entry.channelType === 'string' && entry.channelType ? entry.channelType : 'unknown',+ ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),+ ...(noCacheInputTokens !== undefined ? { noCacheInputTokens } : {}),+ ...(countedTokens !== undefined ? { countedTokens } : {}),};}}