foundation.protocols.ai.cost

Overview

The foundation.protocols.ai.cost event is a general AI governance state event (not under ai.claude.*). It tracks cumulative cost for any AI vendor at the room level, keyed by session or user. The bridge updates this state event after every API turn.

Why a state event? State events in Matrix are overwritten in-place — only the latest value is returned by /state. This makes ai.cost a live accumulator: the messenger reads the current state to display running cost without scanning the full timeline.

Cost as String. All cost fields use string encoding (e.g., "0.094200"), not JSON floats. Matrix canonical JSON (spec §11.2) does not support floating-point numbers. Six decimal places for sub-cent precision.

State Keys

The state_key determines the granularity of cost tracking.

"session"

Current session cost snapshot. Overwritten each turn. Useful for displaying live cost in the messenger UI during an active session.

"@user:matrix.org"

Per-user cumulative cost across all sessions in this room. The state key is the Matrix user ID (MXID) of the user who initiated the session.

Space-level aggregation. To compute total cost across a space, sum the ai.cost state events from all child rooms. The messenger’s SessionMonitor already implements this pattern.

State Event

foundation.protocols.ai.cost

Vendor-agnostic cost accumulator. Updated by the bridge after every API turn. Read by the messenger to display running cost dashboards.

Fields

Field	Type	Description
userId	string	Matrix user ID of the session initiator
vendor	string	AI vendor identifier
Values: `anthropic`, `mistral`, `openai`, `google`, `local`, ...
sessionId	string	Session UUID linking to `ai.claude.session.start`
model	string	Model identifier used in this session
status	string	Current session status
Values: `running`, `paused`, `idle`, `terminated`
cumulativeCost	string	Running total cost (6 decimal places, e.g., `"0.094200"`)
currency	string	ISO 4217 currency code
Values: `USD`, `EUR`, `SEK`, `INR`, `CNY`, ...
cumulativeInputTokens	integer	Total input tokens consumed across all turns
cumulativeOutputTokens	integer	Total output tokens generated across all turns
sessionsCount	integer	Number of sessions (1 for session key, N for user key)
turnsCount	integer	Total prompt-response turns
lastUpdated	integer	Unix timestamp in milliseconds of last update

Example

{
  "type": "foundation.protocols.ai.cost",
  "state_key": "@user:matrix.org",
  "content": {
    "userId": "@user:matrix.org",
    "vendor": "anthropic",
    "sessionId": "session-uuid",
    "model": "claude-sonnet-4-20250514",
    "status": "running",
    "cumulativeCost": "0.094200",
    "currency": "USD",
    "cumulativeInputTokens": 15000,
    "cumulativeOutputTokens": 3000,
    "sessionsCount": 1,
    "turnsCount": 19,
    "lastUpdated": 1711929600000
  }
}

Related Events

The cost state event works alongside these Claude-specific metering events:

Event	Type	Relationship
ai.claude.usage.checkpoint	timeline	Periodic snapshot emitted every N turns. Timeline record complements the state accumulator.
ai.claude.cost.limit.reached	timeline	Emitted when cumulative cost exceeds the limit defined in `ai.policy`.
ai.policy	state	Defines `max_cost_per_session` and `max_cost_per_day` limits that the bridge enforces.
ai.claude.session.end	timeline	Contains final `totalCost` for the completed session.