Agent sessions

An agent session is one logical run of an agent loop, grouped under a single session id so every model call the loop made lands on one row. The gateway opens a session the first time it sees a session header on a request, threads that id through every downstream call in the loop, and closes the session when the loop reports it is done or the session times out. The dashboard's Sessions surface lists those rows so an operator can see the full agent run at a glance: how many steps it took, what it cost, how much of that went to extended thinking, and whether the per-session governor tripped. Which models each step touched is one click away on the trajectory.

The list answers the question a finance team and an agent author both ask first: what did this agent run actually do, and what did it cost. Each row rolls up the underlying route decisions and the resolved capability aliases so the session view is the entry point and the per-step detail is one click away.

One row per session

The Sessions list shows one row per agent session. The row carries the session id, the start time, the last-activity time, the request count, the session-level cost, the extended-thinking tokens the session billed, the step class that produced the most requests, and the governor status. The request count is the number of model calls the loop made under the session id, so a long planning loop with many tool-arg calls reads higher than a single-shot completion. The top step class is the quickest read on what kind of work the loop was actually doing: a session dominated by tool-arg-formatter steps has a different cost shape from one dominated by planner steps.

The list is the rollup view. The per-step trajectory lives on the session detail page, which the row links to.

Trajectory and step replay

Opening a session loads its trajectory: the ordered list of steps the loop ran, each with its prompt class, its resolved model, its thinking budget, and its cost. The thinking budget reads as one of none, low, medium, or high, alongside where that budget came from, whether the client asked for it, the org default applied, or the org's auto mode had the complexity judge derive it. The replay reads the routing record the gateway wrote for each step, so the detail page shows what actually shipped rather than what the request asked for. A step that requested model="auto" shows the model the classifier picked; a step that resolved a cap: alias shows the concrete model the capability resolver returned plus the source of the mapping.

The step replay is the postmortem tool. When an agent run produces a bad output or an unexpected bill, the trajectory shows which step drove it, what the classifier decided, and where a focus-mode bias or a capability override changed the model from the default.

Session-level cost envelopes

Each session carries a cost envelope: the running total of every model call made under the session id. The envelope is the unit a finance team signs off on, because it maps to one agent run rather than one model call. An agent loop that fans out across a planner step, several tool-arg steps, and a synthesis step lands a single session cost that the operator can compare against the budget for that workload.

Repeated loops usually cost less than the step count suggests, because gateway response caching now covers multi-turn agent traffic: a conversation-scoped, short-TTL, org-isolated layer serves a step the loop has already run, and a cache hit is billed at zero, so it lands on the trajectory at no cost. Streaming steps are cached too, replayed frame by frame in the original wire shape, so a streaming client sees the same output it would have seen from a fresh call. See /docs/caching for the mechanics and the invalidation rules.

Alongside the envelope sits the per-session governor, which caps extended thinking rather than dollars. Each session carries a thinking-token cap, the gateway sums the thinking tokens spent under the session id, and once the next request would carry the running total past the cap the governor forces that step and the ones after it to run with thinking off. The session keeps serving; what stops is the open-ended reasoning spend, which is the line item a runaway loop inflates fastest. The breach writes an audit row and fires a webhook event, and the list marks the session as tripped so an operator can find it afterwards.

Filtering the list

The Sessions list supports a date range and a governor-tripped filter. The date range bounds the list to sessions that started inside the window, which keeps the view scoped to the period a finance team is reconciling. The governor-tripped filter narrows the list to sessions that crossed their thinking cap, so an operator can find the runaway loops without scrolling the full history.

The two filters compose. A finance team reconciling last month can set the date range to that month and flip the governor-tripped filter to see only the sessions that breached a cap inside the window.

CSV export

The list exports to CSV. The export carries session id, start time, end time, step count, session cost, and the dominant step class. The export honors the active date range and the governor-tripped filter, so the file matches what is on screen rather than the full unfiltered history. The CSV is the handoff format for a finance team that reconciles agent spend in a spreadsheet or feeds the rows into an ERP cost-event pipeline.

Routing explains how the classifier picks a model and a thinking budget for each step in a session. Capability aliases explain how a cap: reference resolves to a concrete model at routing time, which is the per-step decision the session trajectory replays.