Cost and usage on the session
Every session exposes what it has spent and consumed so far, without a separate billing call. Money is always integer micro-USD on the wire (1 USD = 1,000,000 micro-USD); clients convert for display.
The session object carries
consumed_micro_usd, token_usage (the five tiers above), started_at, ended_at?, stop_reason?, deployment_id?, agent_version, and last_seq — enough to attribute cost per run, per deployment, and per agent version.
The session.usage event
Before a session transitions to idle or any terminal state, the runtime emits a session.usage event carrying the cumulative snapshot. Because it precedes every yield, a stream consumer always sees the final cost of a turn before it sees the turn end.
active_secondsis metered running time — paused/idle time is excluded, matching how the computer bills.tool_callsis the count of tool invocations in the run so far.- The event rides the ordinary
seqcursor, so it is replayable like any other event.
The span model
Every session records a trace of its turns, tool calls, and model requests as ordinary events on its log — read it withnaive session events --session $SID. The timing events are .start / .end pairs:
Tool calls are the
tool.started / tool.completed pair, and a turn ends at session.usage then session.idle. Order a turn’s spans by created_at to see which model request or tool call drove its latency and cost.
Coming soon: OTLP export of these spans to an OpenTelemetry-compatible collector you control.
Next: deployments
Run an agent on a schedule and collect every fire’s cost and result.