Skip to content

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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 } : {}),
};
}
}