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, which models it touched, and whether any per-session governor tripped.

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 step count, the resolved model mix, the session-level cost, and the session status. The step 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 model mix names the distinct models the loop touched, so a session that planned on a flagship and formatted tool args on a cheap model shows both.

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 replay reads the route-decision row 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.

The envelope also feeds the per-session governor. When an operator sets a session budget cap, the gateway tracks the running cost against the cap and trips the governor when the session crosses it. A tripped governor stops further calls under that session id so a runaway loop cannot keep spending past the cap.

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 budget 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 the same columns the list shows: session id, start time, step count, model mix, session cost, and status. 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.