import type { AggregateUsage, ChatMessage } from '@genesislcap/foundation-ai';
/**
 * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
 * accumulate into the returned object.
 *
 * @beta
 */
export declare function emptyUsage(): AggregateUsage;
/**
 * Total tokens processed — the four buckets added up. Safe to sum because the
 * buckets are disjoint (see {@link AggregateUsage}); the equivalent sum over
 * per-message fields would double-count the prompt.
 *
 * Bear in mind what this number is: because every turn resends the conversation,
 * a turn's prompt is counted again in the next turn's. It is billed throughput,
 * NOT the count of distinct tokens in the conversation, so it grows
 * super-linearly with turn count and is expected to dwarf the context size.
 *
 * @beta
 */
export declare function totalTokens(usage: AggregateUsage): number;
/**
 * `a + b`, per bucket, as a new object.
 *
 * Used to lay a row's banked (pre-transcript) spend over what the live transcript
 * proves. Pure rather than in-place because both operands are live state a caller
 * must not mutate.
 *
 * @beta
 */
export declare function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage;
/**
 * The four buckets plus USD for ONE message — the per-message fields projected into
 * the disjoint, addable shape, or `undefined` when the message reports no usage at
 * all (a user turn, a display-only reasoning/narration split, a provider that
 * reports none).
 *
 * Shallow by design: it does NOT recurse into `toolCalls[].subAgentTrace` and does
 * NOT count `compaction.rolledUpUsage`, so it answers "what did this one request
 * cost" rather than "what did this message and everything under it cost". Use
 * {@link sumUsage} for the latter — passing a whole transcript through this one
 * message at a time would silently drop both.
 *
 * `costUsd` folds in `externalCostUsd` (non-LLM spend a widget reported), matching
 * `sumUsage`. It is `0` when the provider priced nothing, which is NOT a claim that
 * the call was free — see {@link AggregateUsage}; `UsageRow.costUsd` is the
 * shape that keeps unpriced distinguishable, and is the right tool for a ledger.
 *
 * @beta
 */
export declare function messageUsage(m: ChatMessage): AggregateUsage | undefined;
/**
 * Sum cost and per-bucket token usage across a message list.
 *
 * One walk produces everything a usage display needs, replacing separate cost and
 * token passes over the same (potentially deep) transcript. Recurses into each
 * tool call's `subAgentTrace`, so LLM work a sub-agent did — possibly on another
 * provider at other rates — lands in the total; the driver embeds a whole
 * sub-agent conversation in the parent's tool result, so this is the only place
 * that spend is visible.
 *
 * Splitting the prompt into buckets is the point: `cost` already has the cache
 * discount applied, but a single token total cannot show that a session was cheap
 * because most of its prompt was a cache hit. The three input buckets are derived
 * from the per-message fields, where `inputTokens` is the whole prompt and the
 * cache fields break it down — so uncached input is the remainder, never an
 * addition.
 *
 * Also counts `compaction.rolledUpUsage`: compaction destroys the messages it
 * summarises, and without their banked usage every total re-derived from the
 * transcript would drop by whatever those turns had already spent.
 *
 * Returns a zeroed total when no message carries usage — providers that report
 * none (e.g. Chrome built-in) are skipped silently rather than guessed at.
 *
 * @remarks
 * This sums the WHOLE array, which is the right answer only when the array is the
 * whole of the work being billed. A driver whose conversation **continues across
 * rounds** opens its history with turns an earlier round already paid for, so
 * summing it again bills them twice — and the session total then grows
 * quadratically in the number of rounds while every individual figure in it stays
 * correct. Nothing about the result looks wrong, which is why it is called out
 * here rather than left to the caller to notice.
 *
 * Do NOT solve this with a "sum from this message onwards" marker. Compaction
 * *replaces* the messages it summarises — and compaction is one of this function's
 * own call sites — so the marker message can be absent from history by the time
 * the sum runs, leaving the caller to either fail or silently sum everything,
 * which is the double-count the marker was meant to prevent.
 *
 * Instead hold a **banked baseline**: spend that predates the current transcript,
 * carried as a value, with `usage = banked + live` composed via {@link addUsage}.
 * `resolveBankedUsage` in `utils/cost-session-history.ts` is the worked form, and
 * the shape of its signature is the load-bearing part. It separates three cases:
 *
 * 1. no prior record — a genuine first round, so nothing is banked;
 * 2. prior record, and the live transcript already accounts for it (a restored
 *    session) — carry the prior record's own banked figure forward;
 * 3. prior record, and the transcript starts empty — bank the prior record's
 *    whole total, because nothing in the transcript can re-derive it.
 *
 * Case 1 and case 3 take the same arithmetic and mean opposite things, so the
 * prior record must be a **required** input with no zero-defaulting path: a
 * caller who carries a transcript and forgets its baseline reports the entire
 * prior conversation as this round's spend. Distinguishing 2 from 3 is a separate
 * decision, and getting it wrong is destructive in the other direction — it
 * rewrites a total down to the current page-load and drops earlier spend.
 *
 * @beta
 */
export declare function sumUsage(messages: readonly ChatMessage[]): AggregateUsage;
//# sourceMappingURL=sum-usage.d.ts.map