<!-- Generated by scripts/gen-docs.ts from the TSDoc in src/. Do not edit by hand. -->

# `usage`

Source: [`src/usage.ts`](https://github.com/AI-for-dev/combo/blob/main/src/usage.ts)

Measurements: time and tokens, per subagent.

Nothing is estimated. Tokens and cost come from pi, read by the session
(`src/session.ts`); the only things we add are **time** - which pi does not
measure - and **attribution per subagent**.

## `CALLED_NO_TOOL`

*const*

```typescript
export const CALLED_NO_TOOL = "called no tool";
```

What every display says of a turn that called no tool its agent had to call.

## `compact`

*function*

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

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

## `deltaUsage`

*function*

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

Usage of one turn: what `after` has more than `before`, two readings of a
session's cumulative counters.

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*

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

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

## `formatUsage`

*function*

```typescript
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*

```typescript
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*

```typescript
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 prompt to the session, however many tools it ran. */
	turns: number;
	/**
	 * Tool calls the model made, as pi counts them in the transcript: every one
	 * it asked for, refused or not. Never read from what the model wrote.
	 */
	toolCalls: 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.