usage

Source: src/usage.ts

Measurements: time and tokens, per subagent.

Nothing is estimated. Tokens and cost come from pi (session.getSessionStats()); the only things we add are time - which pi does not measure - and attribution per subagent.

compact

function

export function compact(n: number): string { /* … */ }

12k, 2.1k, 1.4M - a token count that fits in a narrow column.

deltaUsage

function

export function deltaUsage(before: Usage, after: Usage): Usage { /* … */ }

Usage of one turn: what after has more than before.

Counters are clamped at 0 - a compacted session can see its totals go backwards, and a negative usage means nothing. contextTokens is not a cumulative counter but a level, so we take the one from after.

emptyUsage

function

export function emptyUsage(): Usage { /* … */ }

A zeroed Usage. The starting point of a freshly spawned subagent.

formatUsage

function

export function formatUsage(usage: Usage): string { /* … */ }

Compact usage line: 3 turns 12.4s ↑12k ↓2.1k R8k $0.0412 ctx:34k. The tokens wait for a turn to end and the cost for pi to report one, as in {@link showTokens} and {@link showCost}.

sumUsage

function

export function sumUsage(parts: readonly Usage[], wallMs: number): Usage { /* … */ }

Aggregates the usage of several subagents - typically a fan-out.

We sum, we never average. And wallMs is passed separately rather than summed: it is the real duration of the whole, not the total of the branches. The busyMs / wallMs ratio then gives the parallelism actually achieved - which is precisely the number we want to read.

contextTokens is not aggregated: adding up the contexts of distinct sessions describes nothing.

Usage

type

export type Usage = {
	/** From spawn to close, waiting included. Monotonic clock. */
	wallMs: number;
	/** Time actually spent working: the sum of the `ask` calls. */
	busyMs: number;
	/** Completed `ask` calls. A turn is one `session.prompt()`, however many tools it ran. */
	turns: number;

	/** Input tokens, as pi reported them. `0` when the provider does not say. */
	input: number;
	/** Output tokens, as pi reported them. Never estimated from characters. */
	output: number;
	/** Tokens served from the prompt cache. */
	cacheRead: number;
	/** Tokens written to the prompt cache. */
	cacheWrite: number;
	/** What pi says it cost, in the provider's currency. Summed, never recomputed. */
	cost: number;

	/** Current context size. Mostly relevant for a persistent agent. */
	contextTokens?: number;
};

Measurements of a subagent, or of a single turn of work.