Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* session-stats — what a finished claudish session cost, did, and took.
*
* The proxy is gone by the time the summary prints, so this reads the one durable
* artefact it leaves behind: `~/.claudish/tokens-<port>.json`, written by `TokenTracker`
* on every update and deliberately NOT deleted on exit. That file is also what the
* status line reads, so the summary can never disagree with the number the user watched
* all session.
*/
import { readFileSync } from "node:fs";
import { type Baseline, baselineCost, getBaselines } from "./baseline-pricing.js";
import { resolveTokenFilePath } from "./token-file.js";
/** One tool's share of the session. */
export interface ToolCall {
name: string;
count: number;
}
/** A comparison against one Anthropic tier. */
export interface Saving {
label: string;
modelId: string;
/** What the same tokens would have cost at the baseline's first-party rates. */
baselineUsd: number;
/**
* `baselineUsd - actual`. NEGATIVE when the routed model cost MORE than the
* baseline, which is a real outcome (a premium aggregator, a reasoning-heavy run)
* and is reported as such rather than clamped — see `session-summary.ts`, which
* relabels the row instead of hiding the sign.
*/
savedUsd: number;
}
export interface SessionStats {
inputTokens: number;
outputTokens: number;
totalTokens: number;
costUsd: number;
/** True when the provider bills nothing (local model, free tier). */
isFree: boolean;
/** True when `costUsd` came from a rate estimate rather than a billed figure. */
isEstimated: boolean;
providerName: string;
modelName: string;
contextWindow: number | null;
/** Fraction of the context window occupied by the final request, 0..1. Null if unknown. */
contextUsed: number | null;
toolCalls: ToolCall[];
toolCallTotal: number;
durationMs: number;
savings: Saving[];
/**
* How `costUsd` divides between reading and writing tokens.
*
* Derived from the published per-million rates and then RESCALED so the two parts sum
* to `costUsd` exactly. The rescale is what keeps this honest on the actual-cost path,
* where the provider's billed total is authoritative and our rate arithmetic is only a
* proportion. Both zero when rates are unknown or the session was free.
*/
inputCostUsd: number;
outputCostUsd: number;
/**
* Cumulative input tokens the session was BILLED for, across every turn.
*
* `inputTokens` above is the CURRENT context size — most TokenTracker strategies
* assign rather than accumulate it, because that is what the status line's occupancy
* bar needs. Cost, by contrast, accumulates. Anything that compares tokens against
* cost must therefore use this field, or it holds one turn's input against N turns of
* spending — which understates the saving and can flip its sign.
*/
billedInputTokens: number;
}
export { resolveTokenFilePath };
const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
/**
* Read and interpret the token file. Returns `null` when there is nothing to report —
* the file is missing (the session died before its first response), unparseable, or
* records no tokens at all. The caller prints no panel in that case, which is correct:
* a summary of a session that never ran is noise, not information.
*/
export function readSessionStats(
port: number,
opts?: { readonly processStartMs?: number }
): SessionStats | null {
let raw: unknown;
try {
raw = JSON.parse(readFileSync(resolveTokenFilePath(port), "utf-8"));
} catch {
return null;
}
if (!raw || typeof raw !== "object") return null;
const d = raw as Record<string, unknown>;
// Freshness gate — the token file is keyed by PORT, and a port is reusable.
//
// TokenTracker never truncates or pre-creates the file; its only write happens
// on a response (token-tracker.ts:382). findAvailablePort() scans from the
// bottom of the range, so two back-to-back runs on an idle machine land on the
// same port and therefore the same path. Without this check, a run that died
// before its first response — bad key, 400, crash — renders the PREVIOUS
// session's tokens, cost, savings and duration as its own, and index.ts then
// derives a resume id from that stale window.
//
// `started_at` is stamped when the tracker is constructed (token-tracker.ts:82),
// which is necessarily after this process began. So a value earlier than our own
// start belongs to somebody else. A file with no `started_at` predates that field
// and cannot be dated, and an undatable summary is exactly the one worth
// suppressing — a missing panel is cheaper than a confidently wrong one.
const processStartMs = opts?.processStartMs ?? Date.now() - Math.round(process.uptime() * 1000);
const trackerStartedAt = num(d.started_at);
if (trackerStartedAt <= 0 || trackerStartedAt < processStartMs) return null;
const inputTokens = num(d.input_tokens);
const outputTokens = num(d.output_tokens);
if (inputTokens <= 0 && outputTokens <= 0) return null;
const costUsd = num(d.total_cost);
const isFree = d.is_free === true;
// `context_window` is the string "unknown" when the catalog had no entry, so a
// typeof check is load-bearing here rather than defensive.
const contextWindow = typeof d.context_window === "number" ? d.context_window : null;
const contextUsed =
contextWindow && contextWindow > 0
? Math.min(1, Math.max(0, inputTokens / contextWindow))
: null;
const toolCalls: ToolCall[] = Array.isArray(d.tool_calls)
? (d.tool_calls as unknown[])
.map((t) => t as Record<string, unknown>)
.filter((t) => typeof t?.name === "string" && num(t.count) > 0)
.map((t) => ({ name: String(t.name), count: num(t.count) }))
: [];
// A clock that runs backwards (an NTP step mid-session) would otherwise render a
// negative duration; clamping to 0 shows "0s", which reads as "not measured".
const startedAt = num(d.started_at);
const updatedAt = num(d.updated_at);
const durationMs = startedAt > 0 && updatedAt > startedAt ? updatedAt - startedAt : 0;
// Fall back to `input_tokens` only for a token file written before this field
// existed. It is the wrong basis (see the field's doc comment) but it is what those
// files have, and it is closer than zero.
const billedInputTokens = num(d.billed_input_tokens) || inputTokens;
const rawIn = (billedInputTokens / 1_000_000) * num(d.input_per_m);
const rawOut = (outputTokens / 1_000_000) * num(d.output_per_m);
const rawTotal = rawIn + rawOut;
// Rescale onto the authoritative total so the two parts always sum to what the user
// is told they paid. Without this, an OpenRouter session (whose `total_cost` is the
// provider's own billed figure) would show a split that visibly disagreed with it.
const scale = rawTotal > 0 && costUsd > 0 ? costUsd / rawTotal : 0;
return {
inputTokens,
outputTokens,
totalTokens: num(d.total_tokens) || inputTokens + outputTokens,
costUsd,
isFree,
isEstimated: d.is_estimated === true,
providerName: typeof d.provider_name === "string" ? d.provider_name : "",
modelName: typeof d.model_name === "string" ? d.model_name : "",
contextWindow,
contextUsed,
toolCalls,
toolCallTotal: toolCalls.reduce((a, t) => a + t.count, 0),
durationMs,
// Billed volume, NOT the current context — the two differ by a factor of the turn
// count and only one of them is comparable with a cumulative `total_cost`.
savings: computeSavings(billedInputTokens, outputTokens, costUsd),
inputCostUsd: rawIn * scale,
outputCostUsd: rawOut * scale,
billedInputTokens,
};
}
/**
* Compare the session's real cost against each resolvable Anthropic tier.
*
* Empty when the catalog cannot supply a first-party rate — see `baseline-pricing.ts`.
* The comparison uses the SESSION's own token counts, so it answers the only question
* worth asking: what this exact work would have cost on Claude.
*/
export function computeSavings(
inputTokens: number,
outputTokens: number,
actualUsd: number
): Saving[] {
return getBaselines().map((b: Baseline) => {
const baselineUsd = baselineCost(b, inputTokens, outputTokens);
return {
label: b.label,
modelId: b.modelId,
baselineUsd,
savedUsd: baselineUsd - actualUsd,
};
});
}