Run Observability
Run observability is BMO’s session-facing family for understanding recent run state without opening the full debugger timeline.
It groups three read surfaces that share the same app-owned ledger-backed truth:
- Session summary — bounded recent-run usage, performance, and adaptive parity
- Cue ledger — who acts next, what evidence is expected, and which recovery controls are available
- Trace lens — tool-call-only history for one run
Use it when you need a fast operator read. Use the Agent Debugger when you need the full ordered event history.
Operator surfaces
Section titled “Operator surfaces”| Surface | Scope | Purpose |
|---|---|---|
bmo config show-run-observability | config only | Headless discoverability view of the family and its process-boundary truth contract |
/run-observability | current session family | TUI hub that summarizes recent run state and routes to /debugger, /run_cue_ledger, and trace reads |
GET /v1/sessions/{id}/observability | session family | Bounded session summary |
GET /v1/sessions/{id}/run-cue-ledger | session family | Cue-oriented next-step ledger |
GET /v1/agent-runs/{run_id}/trace | one run in one session family | Tool-call-only trace lens |
session_observability | session family | Native agent summary tool |
run_cue_ledger | session family | Native agent cue tool |
inspect_run_trace | one run in one session family | Native agent trace-lens tool |
bmo_get_session_observability | session family | MCP summary twin |
bmo_get_run_cue_ledger | session family | MCP cue twin |
bmo_inspect_run_trace | one run in one session family | MCP trace-lens twin |
The CLI surface is intentionally different from the others: it runs out of process and does not claim live access to the session service or run store.
The three views
Section titled “The three views”Session summary
Section titled “Session summary”Use session_observability or GET /v1/sessions/{id}/observability when you
need:
- bounded recent-run usage and token totals
- recent run latency and throughput
- aggregate cost state
- adaptive orchestration parity
This is the cheapest family surface when the question is “what does this session’s recent run history look like right now?”
Cue ledger
Section titled “Cue ledger”Use run_cue_ledger or GET /v1/sessions/{id}/run-cue-ledger when the
question is “who acts next, with what expected evidence?”
The cue ledger projects the same session-family run rows into:
- active actors
- cue state
- expected next action
- expected evidence
- recovery and control references
Trace lens
Section titled “Trace lens”Use inspect_run_trace or GET /v1/agent-runs/{run_id}/trace when you need a
single run’s ordered tool calls without loading the broader event stream. This
trace read stays session-scoped: bound callers inherit the current session
family, and unbound callers must provide session scope explicitly.
This surface is intentionally narrow:
- only
kind=toolevents are returned - phase, lifecycle, and other event kinds stay out
- it is a run-scoped lens, not a session summary
When you need full event history, use /debugger or get_agent_run_events
instead.
Truth boundary
Section titled “Truth boundary”Every live surface reads app-owned builders in internal/app:
SessionObservabilityPayloadRunCueLedgerPayloadRunTracePayload
That shared seam keeps HTTP, TUI, native tools, and MCP aligned without routing through HTTP as an internal dependency.
The out-of-process CLI reports only what it can truthfully know:
- the family exists
- which surfaces are available
- that live state must be read from the running app
Relationship to the debugger
Section titled “Relationship to the debugger”Run observability complements the debugger; it does not replace it.
| Use case | Best surface |
|---|---|
| ”What happened, step by step?” | /debugger or get_agent_run_events |
| ”What does this session’s recent run window look like?” | session_observability |
| ”Who acts next and what evidence should I expect?” | run_cue_ledger |
| ”Which tools ran in this one run?” | inspect_run_trace |