@rivus/agent-kit/transcript/usage
scanUsage, isUsageRecord, noCacheInputTokens, UsageRecord — anywhere, with a platform; no imports
Functions
isUsageRecord()
function isUsageRecord(item: UsageRecord | UsageDecodeFailure | UsageSourceFailure): item is UsageRecord;Whether a stream item is a record rather than a failure.
Parameters
item
UsageRecord | UsageDecodeFailure | UsageSourceFailure
Returns
item is UsageRecord
noCacheInputTokens()
function noCacheInputTokens(usage: Usage): number | undefined;Input tokens that were neither read from nor written to a cache: inputTokens − cacheReadTokens − cacheWriteTokens, the base-rate input of a price table. A missing cache count is taken as 0; without
inputTokens the result is unknown.
Parameters
usage
Usage
Returns
number | undefined
scanUsage()
function scanUsage(platform: UsagePlatform & Pick<Platform, "env" | "home" | "clock">, options?: ScanUsageOptions): UsageScan;Scans the usage of every source listUsageSources finds, continuing each from its cursor in state, so a scan that
runs again reads only what was written since. A source last written more than 30 minutes ago, as its decode finds it,
is decoded with final, so a running session's last requests are reported at the latest 30 minutes after it went
quiet.
A record counts once in the window, by a key its agent's rules give (UsageDecoder.usageKey): Claude Code's subagent
files repeat requests, Gemini CLI migrates an older chat into a .jsonl file, and a source rewritten under its cursor
(SourceChanged) is read again from its start. Claude Code's key is its request id, unique everywhere; the other
agents' keys hold the session, because their ids are unique only within it. A record without a key (an older Codex
token_count) is left out of a source read again up to the latest such record read from it, by time and by count
at that time.
Once the loop has run to its end, a source that this scan did not find is dropped when its modification time is
before since, or when the listing of the root or directory that held it did not fail.
Parameters
platform
UsagePlatform & Pick<Platform, "env" | "home" | "clock">
options?
Returns
UsageScan
Interfaces
UsageDecoder
Where one CodingAgent keeps its usage and how to decode it; the shell supplies built-in decoders. The use cases select decoders from that table. Provider implementations use this interface.
Properties
agent
readonly agent: string;home?
readonly home?: HomeRule;This agent's home rule, used instead of catalog's; required for an agent catalog has no rule for.
specificationVersion
readonly specificationVersion: "usage-v1";Methods
decode()
decode(
platform: UsagePlatform,
target: UsageTarget,
options?: DecodeUsageOptions
): UsageStream;Decodes one source, from its start or from options.from. until is the use case's.
Parameters
platform
target
UsageTarget
options?
DecodeUsageOptions
Returns
UsageStream
sources()
sources(
platform: UsagePlatform,
home: AgentHome,
options?: UsageSourceOptions
): AsyncIterable<UsageSourceFailure | UsageSource>;The sources under the agent's home. A missing root or an unreadable directory is a failure item.
Parameters
platform
home
AgentHome
options?
UsageSourceOptions
Returns
AsyncIterable<UsageSourceFailure | UsageSource>
usageKey()
usageKey(record: UsageRecord): string | undefined;The key under which scanUsage counts a record once in its window, unique within the scope where the agent's
files repeat records; undefined for a record without one.
Parameters
record
Returns
string | undefined
UsagePlatform
The part of Platform that decoding usage uses: file reads, and SQLite for an agent that keeps a database.
Extends
SessionPlatform
Properties
decompress?
readonly decompress?: Decompress;Present when the host can decode a compressed session file.
Inherited from
SessionPlatform.decompress
fs
readonly fs: Pick<PlatformFs, "stat" | "list" | "read">;Inherited from
SessionPlatform.fs
sqlite?
readonly sqlite?: PlatformSqlite;Present when the host has SQLite, for an agent whose sessions live in a database.
Overrides
SessionPlatform.sqlite
UsageRecord
Usage of one agent, session and source location, in the convention of Usage. A count, cost or field the log does
not record is absent, never 0.
Properties
agent
agent: string;agentLaneId?
agentLaneId?: string;The subagent lane that made the calls; absent for the main agent.
costSource?
costSource?: CostSource;costUsd?
costUsd?: number;granularity
granularity: UsageGranularity;model?
model?: string;gen_ai.request.model
modelCalls?
modelCalls?: number;How many model calls a turn or session record covers.
pricingMultiplier?
pricingMultiplier?: number;A price factor the request was billed with, such as 2 for a priority service tier. Absent means 1.
provider?
provider?: string;gen_ai.provider.name, when the agent records it.
requestId?
requestId?: string;The agent's id of the model request. With responseId, it identifies a request that several files repeat.
responseId?
responseId?: string;gen_ai.response.id
sessionId
sessionId: string;source
source: SourcePointer;The record the usage was read from; for a request written as several records, the first one.
timestamp
timestamp: number;Epoch milliseconds of the request, or of the end of the aggregate.
usage
usage: Usage;usageByModel?
usageByModel?: Record<string, ModelUsage>;The same usage split by model. A total takes usage or this split, never both added together.
Type Aliases
ScanUsageOptions
type ScanUsageOptions = object & (
| {
since?: number;
state?: undefined;
}
| {
since: number;
state?: UsageScanState;
}) & object;Type Declaration
agents?
readonly agents?: readonly CodingAgentId[];Agents to scan, by id or alias; defaults to every agent with a usage decoder.
signal?
readonly signal?: AbortSignal;until?
readonly until?: number;Stops each source at its first record at or after this time.
providers?
readonly providers?: readonly Provider[];