Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* TokenTracker — unified token tracking and cost accounting.
*
* Replaces the 8 independent writeTokenFile implementations scattered
* across handlers. Supports three token tracking strategies:
*
* 1. Standard (most handlers): assign input, accumulate output
* 2. Accumulate-both (OllamaCloud): both input and output are accumulated
* 3. Delta-aware (OpenAI): tracks input delta with race-condition detection
* for concurrent conversations sharing the same handler
*/
import { mkdirSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";
import { TOOL_NAME_SHAPE } from "../../adapters/tool-name-utils.js";
import { type PlanUsage, isPlanStale } from "../../auth/quota/types.js";
import { log } from "../../logger.js";
import { resolveTokenFilePath } from "../../session/token-file.js";
import {
type ModelPricing,
type RequestBilling,
getModelPricing,
} from "./remote-provider-types.js";
export interface TokenTrackerConfig {
contextWindow: number;
providerName: string;
modelName: string;
/** Display name for the provider (e.g., "OpenAI", "Gemini") */
providerDisplayName?: string;
/**
* `false` keeps every counter but never writes the status-line token file.
* An `--advisor` panel handler sets it: the file is keyed by
* `CLAUDISH_TOKEN_FILE` before the port, so no port value can keep a panel
* call from repainting the main session's status line. Default `true`.
*/
writesTokenFile?: boolean;
}
/**
* The cached breakdown of a turn's input tokens, for COST ONLY.
*
* Every `update*` method below still takes the FULL context size as its
* `inputTokens` argument — that number answers "how full is the conversation"
* and drives the status line's occupancy bar. This object rides alongside and
* answers a different question: how much of that context the provider served
* from its prompt cache, and therefore may bill at a lower rate.
*
* Both counts are SUBSETS of `inputTokens`, not additions to it.
*/
export interface UsageCacheDetail {
/** Tokens served from the provider's prompt cache this turn. */
cacheReadTokens: number;
/** Tokens written into the provider's prompt cache this turn. */
cacheCreationTokens: number;
}
/**
* Strip a `provider@` routing prefix from a model spec.
*
* The status line renders `"<provider_name> <model_name>"`, so a model_name that
* still carries its routing prefix names the provider twice — `[email protected]`
* under the "Alibaba Token Plan" label reads as "Alibaba Token Plan [email protected]".
* ComposedHandler already enforces a bare `modelName`, but a fallback override
* comes from a transport and this is cheap insurance.
*/
export function stripProviderPrefix(name: string): string {
const at = name.indexOf("@");
return at === -1 ? name : name.slice(at + 1);
}
/**
* The amount to SUBTRACT from a turn's computed cost because part of its input
* was served from the provider's prompt cache.
*
* Written as a subtraction rather than folded into the input term on purpose:
* with no `cacheReadCostPer1M` anywhere in the tree the rate defaults to
* `inputCostPer1M`, the difference is exactly 0, and every existing session's
* cost is bit-identical to what it was before the cache split landed. A
* rewritten input term could not make that claim as cheaply.
*
* `billedInputTokens` is what the CALLING STRATEGY actually charged for, and
* the `Math.min` against it is load-bearing — not defensive tidiness. The
* delta-aware strategy charges only the GROWTH in context, so on the real xAI
* capture (`grok-4.6-openai-advisor-turn1.sse`: prompt 20379, cached 20352) an
* unclamped discount would subtract 20352 tokens' worth from a 27-token charge
* and drive `sessionTotalCost` negative. Clamped, the discount can never exceed
* the charge it is discounting, so per-turn cost stays >= 0 and the session
* total stays non-negative.
*
* Exported because it is the whole of the money change and the only part with
* arithmetic worth pinning: the field it reads has no producer yet, so a test
* has to hand it a pricing object to reach any non-zero branch at all.
*/
export function computeCacheReadDiscount(
pricing: ModelPricing,
billedInputTokens: number,
detail?: UsageCacheDetail
): number {
const cacheReadTokens = detail?.cacheReadTokens ?? 0;
if (cacheReadTokens <= 0 || billedInputTokens <= 0) return 0;
// Absent rate => cache reads are priced as ordinary input => no discount.
// See ModelPricing.cacheReadCostPer1M for why this is a rule, not a ratio.
const rate = pricing.cacheReadCostPer1M ?? pricing.inputCostPer1M;
const perMillionSaved = pricing.inputCostPer1M - rate;
if (!(perMillionSaved > 0)) return 0;
const discountedTokens = Math.min(cacheReadTokens, billedInputTokens);
return (discountedTokens / 1_000_000) * perMillionSaved;
}
/**
* Every cost-bearing update below takes an optional `billing`: the decision of
* the request whose usage it records (`RequestBilling`, decided when that
* request was signed). Absent, pricing falls back to `isSubscriptionProvider`,
* which for a credential-decided provider (`openai-codex`) reads the
* process-wide last-signed arm. The tracker never stores it: one tracker is
* shared by every request of its handler, so a stored arm would be the same
* race one level down.
*/
export class TokenTracker {
private port: number;
private config: TokenTrackerConfig;
private sessionTotalCost = 0;
private sessionInputTokens = 0;
private sessionOutputTokens = 0;
/**
* The input-token count from the MOST RECENT request, verbatim — never a
* high-water mark. `sessionInputTokens` is a billing baseline that the
* delta-aware strategy deliberately refuses to lower (see updateWithDelta),
* so it is the wrong number to show a user or to seed a placeholder with.
*/
private lastInputTokens = 0;
/** Override model name in status line (e.g., after capacity fallback) */
private modelNameOverride: string | undefined;
/**
* Plan usage for the subscription this session is SPENDING, published under
* the `plan` key for status lines. Held in memory and serialized by
* writeFile — never fetched there, so publishing costs no extra I/O.
*/
private planUsage: PlanUsage | undefined;
/** Last plan written, so setPlanUsage can write on change only. */
private lastPlanSerialized = "";
/**
* Tool calls the model emitted this session, by tool name.
*
* Counted at the point a tool call is COMPLETE (name known, arguments closed),
* never per streamed fragment — an `input_json_delta` path would count one
* `Edit` twenty times. The session summary renders this as a distribution, which
* is why the per-name breakdown is kept rather than a bare total: "47 calls" is a
* number, "Read 18 · Edit 12 · Bash 9" is a shape.
*/
private toolCallsByName = new Map<string, number>();
/**
* Wall-clock start of this tracker, i.e. of the proxied session.
*
* The token file already carries `updated_at`; a duration needs both ends. Taken
* at construction because that is when the proxy begins serving, which is the
* span the user experiences as "the session".
*/
private readonly startedAt = Date.now();
/**
* Every input token this session was BILLED for, summed across turns.
*
* Distinct from `sessionInputTokens`, which most strategies ASSIGN rather than
* accumulate because it answers "how full is the context right now" for the status
* line. `sessionTotalCost` meanwhile accumulates, so the two are on different bases —
* a ten-turn session holds one turn's input against ten turns of cost.
*
* That mismatch is invisible for the status line and fatal for a savings comparison:
* pricing one turn of input at Sonnet's rate and subtracting ten turns of real cost
* understates the saving and can invert its sign, reporting "over by $X" for a session
* that in fact saved money. This counter is the honest denominator, and it mirrors
* whatever each strategy actually charged for — the delta on the delta-aware path, the
* full context on the assignment paths, the running total on accumulate-both.
*/
private sessionBilledInputTokens = 0;
/**
* Cache-read tokens summed across the session, for the accumulate-both
* strategy ALONE.
*
* That strategy ASSIGNS `sessionTotalCost` from cumulative totals rather than
* accumulating per-turn costs, so a per-turn discount subtracted there is
* simply overwritten on the next turn. The discount has to be recomputed from
* a cumulative cache-read total to survive, which is what this counter is.
* Every other strategy accumulates and needs no such counter.
*/
private sessionCacheReadTokens = 0;
constructor(port: number, config: TokenTrackerConfig) {
this.port = port;
this.config = config;
}
/**
* Record one COMPLETED tool call. Unnamed calls are counted under `unknown`
* rather than dropped: a tool call whose name never arrived is still a tool call,
* and silently discarding it would make the summary's total disagree with the
* transcript.
*/
recordToolUse(name: string): void {
const trimmed = name.trim();
// A tool name is an identifier. A name that is not one did not come from a
// tool: it is text a parser swallowed, and it can carry ARGUMENT VALUES.
// This map is written to `stats/*.json` and printed in the session summary,
// neither of which is a redacted surface, so the value must not land here.
// The call is still counted, under `malformed`, so the total keeps agreeing
// with the transcript.
const key = !trimmed ? "unknown" : TOOL_NAME_SHAPE.test(trimmed) ? trimmed : "malformed";
this.toolCallsByName.set(key, (this.toolCallsByName.get(key) ?? 0) + 1);
}
/** Total completed tool calls this session. */
getToolCallCount(): number {
let n = 0;
for (const v of this.toolCallsByName.values()) n += v;
return n;
}
/** Per-tool counts, descending by count. */
getToolCalls(): Array<{ name: string; count: number }> {
return [...this.toolCallsByName]
.map(([name, count]) => ({ name, count }))
.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
}
/** Set an override model name (shown in status line instead of original) */
setActiveModelName(name: string): void {
this.modelNameOverride = name;
}
/** Update provider display name (e.g., after OAuth resolves the tier) */
setProviderDisplayName(name: string): void {
this.config.providerDisplayName = name;
}
/**
* Record plan usage for the provider being spent.
*
* Writes the file when the value actually CHANGES, and only then.
*
* An earlier version stored without writing, on the reasoning that writeFile
* already runs on every token update so the next one would pick it up free.
* That left two holes. A background poll that resolves after a turn's final
* token write published nothing until the *next* turn — and for a provider
* polled every 5 minutes on an idle session, that could be never. Worse, an
* expired reading was only dropped at write time, so a stale `plan` sat in
* the file indefinitely and the frozen consumer rendered it as current, which
* is exactly the failure the omit-when-stale rule exists to prevent.
*
* Change-triggered is still effectively free: a plan changes at most once per
* scrape or poll interval, not once per token, so this adds a write every few
* minutes rather than the per-delta amplification the original note feared.
*/
setPlanUsage(plan: PlanUsage | undefined): void {
const next = plan ? JSON.stringify(plan) : "";
if (next === this.lastPlanSerialized) return;
this.planUsage = plan;
this.lastPlanSerialized = next;
this.rewrite();
}
/** Force rewrite the token file with current state */
rewrite(): void {
this.writeFile(this.getLastInputTokens(), this.sessionOutputTokens);
}
/**
* Standard update: assign input (latest context), accumulate output.
* Used by most remote providers (Gemini, AnthropicCompat, Vertex, RemoteProvider, etc.)
*/
update(
inputTokens: number,
outputTokens: number,
detail?: UsageCacheDetail,
billing?: RequestBilling
): void {
this.sessionInputTokens = inputTokens;
this.lastInputTokens = inputTokens;
this.sessionOutputTokens += outputTokens;
this.sessionBilledInputTokens += inputTokens;
this.sessionCacheReadTokens += detail?.cacheReadTokens ?? 0;
const pricing = this.getPricing(billing);
// This strategy charges the whole context every turn, so the whole context
// is what the cache discount is clamped against.
const cost =
(inputTokens / 1_000_000) * pricing.inputCostPer1M +
(outputTokens / 1_000_000) * pricing.outputCostPer1M -
this.cacheReadDiscount(pricing, inputTokens, detail);
this.sessionTotalCost += cost;
this.writeFile(inputTokens, this.sessionOutputTokens, pricing.isEstimate, pricing);
}
/**
* Accumulate both input and output tokens.
* Used by OllamaCloud where cost is calculated on cumulative totals.
*/
accumulateBoth(
inputTokens: number,
outputTokens: number,
detail?: UsageCacheDetail,
billing?: RequestBilling
): void {
this.sessionInputTokens += inputTokens;
this.lastInputTokens = this.sessionInputTokens;
this.sessionOutputTokens += outputTokens;
this.sessionCacheReadTokens += detail?.cacheReadTokens ?? 0;
const pricing = this.getPricing(billing);
// ASSIGNED from cumulative totals, so the discount must be cumulative too: a
// per-turn subtraction here would be thrown away by the next turn's
// assignment. `sessionCacheReadTokens` is the running total, clamped against
// the running input total this line is already pricing.
const cost =
(this.sessionInputTokens / 1_000_000) * pricing.inputCostPer1M +
(this.sessionOutputTokens / 1_000_000) * pricing.outputCostPer1M -
this.cacheReadDiscount(pricing, this.sessionInputTokens, {
cacheReadTokens: this.sessionCacheReadTokens,
cacheCreationTokens: 0,
});
// OllamaCloud recalculates total cost each time (not incremental)
this.sessionTotalCost = cost;
// Assigned, not accumulated, for the same reason the cost above is: this strategy
// already sums input itself, so `+=` here would count every earlier turn again.
this.sessionBilledInputTokens = this.sessionInputTokens;
this.writeFile(this.sessionInputTokens, this.sessionOutputTokens, pricing.isEstimate, pricing);
}
/**
* Charge input that an EARLIER upstream leg of the current request already
* consumed: cost and the billed-input counter only.
*
* A Responses turn whose leg was retried (a stalled or degenerate leg, see
* `responses-turn.ts`) sent the same body more than once. The last leg is
* charged by the strategy as usual (`onTokenUpdate`); each earlier leg was a
* separate upstream request that the provider billed in full (minus cache),
* and nothing else in the session will ever charge it. Strategy-independent
* on purpose: under `delta-aware` the last leg is still charged only its
* growth over the session high-water, which is that strategy's model of the
* conversation, not of a retry.
*
* Never touches the context figures (`sessionInputTokens`, `lastInputTokens`)
* or output, and does not write the token file: the strategy update that
* follows does. The cache discount uses the same clamp as `update()`, so a
* retry that re-sent a cached body is charged as cached.
*/
addBilledInputTokens(
inputTokens: number,
detail?: UsageCacheDetail,
billing?: RequestBilling
): void {
if (!(inputTokens > 0)) return;
this.sessionBilledInputTokens += inputTokens;
this.sessionCacheReadTokens += detail?.cacheReadTokens ?? 0;
const pricing = this.getPricing(billing);
this.sessionTotalCost +=
(inputTokens / 1_000_000) * pricing.inputCostPer1M -
this.cacheReadDiscount(pricing, inputTokens, detail);
}
/**
* Delta-aware update with race-condition detection for concurrent conversations.
* Used by OpenAI handler where multiple conversations may share one handler.
*
* inputTokens = full context size from the API (not incremental)
* Only charges for the delta (new tokens added since last request).
*/
updateWithDelta(
inputTokens: number,
outputTokens: number,
detail?: UsageCacheDetail,
billing?: RequestBilling
): void {
let incrementalInputTokens: number;
// The status file always reports THIS request's context, even when the
// billing baseline below refuses to move.
this.lastInputTokens = inputTokens;
if (inputTokens >= this.sessionInputTokens) {
// Normal: context grew (continuation)
incrementalInputTokens = inputTokens - this.sessionInputTokens;
this.sessionInputTokens = inputTokens;
} else if (inputTokens < this.sessionInputTokens * 0.5) {
// Different conversation with much smaller context. The baseline is left
// where it is on purpose: a concurrent conversation must not reset the
// main thread's billing high-water and get its own growth charged twice.
// A compaction lands here too — hence the separate lastInputTokens, which
// is what the status line reads. Conflating them pinned the status bar at
// the pre-compaction peak forever ("0% context left" after a clean
// /compact) because the file was written with a Math.max().
incrementalInputTokens = inputTokens;
log(
`[TokenTracker] Detected concurrent conversation (${inputTokens} < ${this.sessionInputTokens}), charging full input`
);
} else {
// Ambiguous decrease — charge full and update
incrementalInputTokens = inputTokens;
this.sessionInputTokens = inputTokens;
log(
`[TokenTracker] Ambiguous token decrease (${inputTokens} vs ${this.sessionInputTokens}), charging full input`
);
}
this.sessionOutputTokens += outputTokens;
this.sessionCacheReadTokens += detail?.cacheReadTokens ?? 0;
const pricing = this.getPricing(billing);
this.sessionBilledInputTokens += incrementalInputTokens;
// The clamp matters MOST here: this strategy charges only the growth, which
// on a cached continuation is a handful of tokens against a cache read of
// tens of thousands. Discounting the raw cache-read count would make the
// turn cost negative. See cacheReadDiscount for the measured capture.
const cost =
(incrementalInputTokens / 1_000_000) * pricing.inputCostPer1M +
(outputTokens / 1_000_000) * pricing.outputCostPer1M -
this.cacheReadDiscount(pricing, incrementalInputTokens, detail);
this.sessionTotalCost += cost;
this.writeFile(inputTokens, this.sessionOutputTokens, pricing.isEstimate, pricing);
}
/**
* Update with actual cost from the API (e.g., OpenRouter returns cost directly).
* Falls back to calculated cost when actualCost is 0 or unavailable.
*/
updateWithActualCost(
inputTokens: number,
outputTokens: number,
actualCost: number | undefined,
detail?: UsageCacheDetail,
billing?: RequestBilling
): void {
this.sessionInputTokens = inputTokens;
this.lastInputTokens = inputTokens;
this.sessionOutputTokens += outputTokens;
this.sessionBilledInputTokens += inputTokens;
this.sessionCacheReadTokens += detail?.cacheReadTokens ?? 0;
if (typeof actualCost === "number" && actualCost > 0) {
// NO DISCOUNT on this branch. The provider's own figure is already net of
// whatever caching it applied; subtracting a cache discount from it would
// double-count the saving and under-report real spend.
this.sessionTotalCost += actualCost;
log(`[TokenTracker] Actual cost from API: $${actualCost.toFixed(6)}`);
} else {
// The computed fallback is the `update` arithmetic, so it takes the
// `update` treatment: full context charged, discount clamped against it.
const pricing = this.getPricing(billing);
const inputCost = (inputTokens / 1_000_000) * pricing.inputCostPer1M;
const outputCost = (outputTokens / 1_000_000) * pricing.outputCostPer1M;
this.sessionTotalCost +=
inputCost + outputCost - this.cacheReadDiscount(pricing, inputTokens, detail);
}
this.writeFile(inputTokens, this.sessionOutputTokens, undefined, this.getPricing(billing));
}
/**
* For local models: assign input (API reports full context), accumulate output.
* Cost is always 0 for local models.
*/
updateLocal(inputTokens: number, outputTokens: number, _detail?: UsageCacheDetail): void {
// No discount: local models have no pricing at all, so there is nothing to
// discount. The parameter exists only so every strategy shares one shape and
// the caller does not have to know which ones care.
if (inputTokens > 0) {
this.sessionInputTokens = inputTokens;
this.lastInputTokens = inputTokens;
}
this.sessionOutputTokens += outputTokens;
this.sessionBilledInputTokens += inputTokens;
// Local models are free
this.writeFile(this.sessionInputTokens, this.sessionOutputTokens);
}
/** Update just the context window (e.g., after fetching from model API) */
setContextWindow(contextWindow: number): void {
this.config.contextWindow = contextWindow;
}
/** Current context window in tokens. 0 means "not resolved yet / unknown". */
getContextWindow(): number {
return this.config.contextWindow;
}
/** Get the current session total cost */
getTotalCost(): number {
return this.sessionTotalCost;
}
/** Get current session input tokens (billing baseline — may lag a compaction) */
getInputTokens(): number {
return this.sessionInputTokens;
}
/**
* Input tokens from the most recent request — the live context size.
* Use this for anything user-facing or for seeding a placeholder; use
* getInputTokens() only for cost accounting.
*/
getLastInputTokens(): number {
return this.lastInputTokens || this.sessionInputTokens;
}
/** Get current session output tokens */
getOutputTokens(): number {
return this.sessionOutputTokens;
}
private getPricing(billing?: RequestBilling): ModelPricing {
return getModelPricing(this.config.providerName, this.config.modelName, billing);
}
/** Instance shim over `computeCacheReadDiscount` — see that function. */
private cacheReadDiscount(
pricing: ModelPricing,
billedInputTokens: number,
detail?: UsageCacheDetail
): number {
return computeCacheReadDiscount(pricing, billedInputTokens, detail);
}
private getDisplayName(): string {
if (this.config.providerDisplayName) return this.config.providerDisplayName;
const name = this.config.providerName;
if (name === "opencode-zen") return "Zen";
if (name === "glm") return "GLM";
if (name === "openai") return "OpenAI";
return name.charAt(0).toUpperCase() + name.slice(1);
}
private writeFile(
inputTokens: number,
outputTokens: number,
isEstimate?: boolean,
requestPricing?: ModelPricing
): void {
// The choke point of every write: each update path ends here.
if (this.config.writesTokenFile === false) return;
try {
const total = inputTokens + outputTokens;
const cw = this.config.contextWindow;
// Context occupancy is the CURRENT conversation size, which is `inputTokens` —
// every strategy passes the latest request's context here (see lastInputTokens).
// `outputTokens` is a session-CUMULATIVE counter, so folding it in made this
// percentage decay with session AGE instead of with context use: once lifetime
// output passed the window the value pinned at 0 and stopped carrying any signal.
// Measured on a 3-day session: input 94,018 against a 372,000 window, output
// 2,280,419 cumulative — reported 0% left when 75% was free, which is why a
// 200K compaction clamp went unnoticed for three days. `total` stays cumulative
// for `total_tokens`, which is a billing figure and genuinely session-wide.
//
// context_left_percent: -1 means "unknown" (no catalog entry for this model)
const leftPct =
cw > 0 ? Math.max(0, Math.min(100, Math.round(((cw - inputTokens) / cw) * 100))) : -1;
// The pricing of the update that is writing, when it has one, so the
// published rates match the request just charged.
const pricing = requestPricing ?? this.getPricing();
const isFreeModel =
pricing.isFree || (pricing.inputCostPer1M === 0 && pricing.outputCostPer1M === 0);
const data: Record<string, any> = {
input_tokens: inputTokens,
output_tokens: outputTokens,
total_tokens: total,
total_cost: this.sessionTotalCost,
context_window: cw > 0 ? cw : "unknown",
context_left_percent: leftPct,
provider_name: this.getDisplayName(),
updated_at: Date.now(),
is_free: isFreeModel,
is_estimated: isEstimate || false,
// Session-summary fields. The status line ignores both; they exist because
// the token file is the only durable record of a session that survives the
// proxy exiting, and the summary is printed AFTER shutdown (see
// `session/session-summary.ts`). `started_at` pairs with `updated_at` to
// give a duration; `tool_calls` is the distribution, not just a total.
started_at: this.startedAt,
tool_calls: this.getToolCalls(),
// The savings baseline's denominator. `input_tokens` above is the CURRENT
// context (assigned, for the status line's occupancy bar); this is the
// cumulative billed volume. Pricing the former against a cumulative
// `total_cost` compares one turn to N and can invert the sign of the result.
billed_input_tokens: this.sessionBilledInputTokens,
// The per-million RATES, not a split of the total. Cost accumulates through four
// different strategies above (standard, accumulate-both, delta-aware,
// actual-cost), so maintaining a parallel input/output split in each would be
// four chances to drift from `total_cost`. Publishing the rates lets the summary
// derive the split and rescale it to whatever `total_cost` actually says, which
// stays correct even on the actual-cost path where the provider's billed figure
// overrides our arithmetic entirely.
input_per_m: pricing.inputCostPer1M,
output_per_m: pricing.outputCostPer1M,
};
// model_name is ALWAYS written, not just when a fallback override is active.
// The status line's fallback for a missing key is $CLAUDISH_ACTIVE_MODEL_NAME,
// which is the full routed spec (`[email protected]`) — rendered next to the
// provider label that produces "Alibaba Token Plan [email protected]". The override
// still wins when set, because a capacity fallback legitimately needs to show
// the SUBSTITUTED model rather than the one the user asked for.
const displayModel = stripProviderPrefix(
this.modelNameOverride || this.config.modelName || ""
);
if (displayModel) {
data.model_name = displayModel;
}
// Plan usage for the subscription actually being spent. Status lines
// render this INSTEAD of Anthropic's rate limits, which under claudish
// describe an account the session is not using.
//
// Stale readings are OMITTED rather than flagged. The consumer
// (statusline.sh) reads only `.plan.label` and `.plan.windows[]` and
// ignores keys it does not know — so a `stale: true` field would be
// dropped while the numbers beside it still rendered as current. Absence
// is the only signal the frozen contract can carry, and the consumer
// already degrades silently on it.
if (this.planUsage && !isPlanStale(this.planUsage)) {
data.plan = {
label: this.planUsage.label,
windows: this.planUsage.windows,
source: this.planUsage.source,
};
}
// CLAUDISH_TOKEN_FILE lets a parent process dictate where these stats land.
// The default path is keyed to a port the child picks for itself, so an
// orchestrator spawning N children has no way to tell which file belongs
// to which model. Pointing each child at a known path is what makes
// per-model token/cost reporting possible.
// The ONE rule the status line and the end-of-session summary read by.
const outPath = resolveTokenFilePath(this.port);
mkdirSync(dirname(outPath), { recursive: true });
writeFileSync(outPath, JSON.stringify(data), "utf-8");
} catch (e) {
log(`[TokenTracker] Error writing token file: ${e}`);
}
}
}