eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
55 lines (54 loc) • 2.42 kB
TypeScript
/**
* Per-turn rolling token-usage accumulator for `$eve.*` observability
* tags. Lives on `session.state` so the totals survive workflow step
* boundaries the way the rest of the harness state does.
*
* The harness runs each turn as a sequence of `"use step"` invocations
* (one per tool-loop iteration). Each step knows its own
* `result.usage`, but the dashboard cares about totals **per turn**.
* The workflow runtime's attribute store is "last write wins" per key,
* so the simplest cumulative pattern is: read the previous total from
* `session.state`, add the new step's usage, write the running total
* back. The most recent emit then carries the final per-turn total.
*
* `turnId` keys the state so a fresh turn starts at zero without
* relying on a separate "reset" code path — when the harness moves to
* a new turn, the stale totals are discarded automatically.
*/
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
/**
* Rolling token usage for the in-flight turn.
*
* `turnId` is the in-flight turn's stable id; when the harness step
* runs in a different turn (or with the empty-string between-turns
* sentinel), totals are reset.
*/
export interface TurnUsageState {
readonly cacheReadTokens: number;
readonly cacheWriteTokens: number;
readonly inputTokens: number;
readonly outputTokens: number;
readonly turnId: string;
}
/** Reads the stored per-turn token state, or `undefined` when absent. */
export declare function getTurnUsageState(state: SessionStateMap | undefined): TurnUsageState | undefined;
/** Writes per-turn token state onto a new copy of the session. */
export declare function setTurnUsageState(session: HarnessSession, next: TurnUsageState): HarnessSession;
/**
* Folds one step's `usage` into the running per-turn totals. When
* `turnId` differs from the stored state (e.g. a new turn just
* started), the previous totals are discarded — fresh turns start at
* zero without an explicit reset path.
*/
export declare function accumulateTurnUsage(input: {
readonly previous: TurnUsageState | undefined;
readonly turnId: string;
readonly usage: {
readonly cachedInputTokens?: number;
readonly inputTokens?: number;
readonly inputTokenDetails?: {
readonly cacheWriteTokens?: number;
};
readonly outputTokens?: number;
};
}): TurnUsageState;