Diagnostics client and composites
DiagnosticsClient is the browser-side HTTP wrapper used by the diagnostic composites. It is stateless apart from its API base and uses the browser's current origin to resolve that base. Its methods read capabilities, users, connections, actions, history, pending RPCs, deduplication statistics, execution contexts, and worker summaries.
The client does not inspect Python objects directly. Every answer is limited by the inspectors composed into the server router, the backend selected for those inspectors, their pagination or sampling rules, and the caller's administrative access.
Discover capabilities before constructing the experience
getCapabilities() reports the current inspector families, including registry, history, RPC, deduplication, context, browser-window, and delivery support plus narrower feature flags. A custom surface should hide, disable, or explain views whose required capability is absent.
CapabilityMatrix summarizes five read-oriented families and the optional dispatch boundary. It does not currently visualize every capability flag. In particular, the reusable client has worker methods but no browser-window or delivery-inspector methods, and the maintained DevConsole has no dedicated browser-window, delivery-mailbox, reservation, or dispatcher-node panel. A true capability response is therefore broader than the current ready-made navigation.
Choose a composite by investigation task
| Reader task | Composite | Important behavior |
|---|---|---|
| read and filter one retained stream | HistoryStream | structured history is cursor-paginated; raw mode is one bounded sample with no load-more state |
| compare retained streams | HistoryStacks | each column owns its selected stream and refresh cycle |
| move through users, connections, and streams | UserNavigator | the host owns route or selection state through callbacks |
| inspect one client's identity, actions, and settings | ClientExplorer | read-only until a devApiBase adds the Dispatch tab |
| summarize recent command-bearing evidence | CommandActivity | samples bounded streams and messages; it is not a durable task ledger |
| reconstruct evidence for one command | CommandTrace | joins retained messages and bounded pending-RPC evidence; optional external links use fields that actually exist |
| triage pending waits | RpcMonitor | supports cursor pagination and highlights expiry or instance mismatch without claiming client cancellation |
| inspect reported contexts and worker pressure | ContextMonitor | requires the context inspector and derives worker counts from returned context snapshots |
| explain available inspector families | CapabilityMatrix | makes missing capabilities visible instead of presenting empty data as health |
Within a configured source integration, a composite can be mounted with one API base:
<HistoryStream
apiBase="/api/diag"
streamKey="user_a/jobs"
refreshInterval={5_000}
/>Polling is a view behavior, not a server-side subscription. A successful refresh proves only what that request returned. It does not prove the inspector is exhaustive, the scheduler is healthy, or no newer event exists.
Preserve pagination and completeness semantics
Structured history and several registry/RPC reads return pages with items, has_more, and an opaque next_cursor. Continue while the server says more data may exist and provides a cursor. Do not synthesize offsets or stop merely because one Redis-backed scan page is empty.
Raw history intentionally returns only {items, count}. It is a bounded diagnostic sample and has no continuation cursor. HistoryStream disables load-more behavior in raw mode rather than inventing pagination.
Some aggregate responses include a completeness block with complete, truncated sources, examined counts, and limits. Preserve that block in product UIs. An observed count is not a system total when a source was bounded or unavailable.
Connection client_type is optional free-form metadata supplied by the connecting client. Execution-context client_type is the closed browser | console | mobile | web diagnostic enum. Do not merge those contracts into one supposedly universal client-type list. Context and worker responses include a nullable window_id; absence is data, not a parsing error.
Browser authentication remains a host boundary
The current fetch wrapper has no option for caller-supplied headers. The ready-made browser UI therefore cannot attach Cheetah's X-Admin-Key credential itself. A direct API consumer can send that header, but the unchanged component client cannot.
Loopback development can use an intentionally local boundary. A non-loopback browser deployment needs a surrounding same-origin authenticated gateway or a deliberately designed session integration. Do not put a long-lived administrator key into browser JavaScript and do not weaken the diagnostics router to make the components load.
Dispatch is a separate write path
ClientExplorer adds ActionDispatcher only when devApiBase is supplied. The dispatcher posts the selected action and JSON arguments to /dispatch/{user}/{client} with a 30-second requested timeout. Its request currently supplies only Content-Type; it has the same browser-credential limit as the read client.
A successful HTTP response is an application result observed through the normal command path. A wait timeout does not prove cancellation, and a delivery acknowledgement does not prove the local handler completed. Keep those distinctions visible when linking the result to CommandTrace or retained history.
For the exact server-side routes and security contract, read Diagnostics API and security.