Skip to main content

Live application diagnostics

This contract supplies execution evidence to application inspectors. It does not change the generic connector’s conversation-reader authority. Prompts, memory, provider bodies and tool arguments require operator access to the selected agent. Application servers must enforce their own developer access policy before proxying these operator endpoints. Never embed an operator token in a browser or native app. The backend owns recorded execution facts. Client SDKs own transport/replay and normalization. Applications own screen context, rendering observations and access to their inspector. No renderer is part of this backend change.

Contract

A versioned run diagnostic snapshot joins the existing execution trace to a pre-inference input manifest. An ordered durable change feed carries references, not private bodies, and tells clients when to reload that snapshot. Cursor order is database commit-safe; timestamps are evidence, not replay cursors. Existing runs have no retroactively manufactured manifests or change history. Model-input manifests describe the actual normalized request, prompt assembly accounting, effective profile revision, requested model and offered tools. Text and schema bodies remain in the existing retained request/prompt records. Token estimates are labeled with their estimator; provider usage remains separate. Missing measurements and pruned content are explicit, never invented zeros. SDK and application integration follow separately.

Endpoints (version 1)

All routes below require the same session/API-token and agent grant as the operator trace API. They return Cache-Control: no-store. Cursors are decimal strings, scoped to one run, not timestamps or JavaScript numbers. cursor is the last returned event; latest_cursor may be further ahead. Drain has_more pages before waiting. A future cursor returns resnapshot:true. The snapshot’s cursor and execution records come from one repeatable-read database transaction. Reads fail closed when that facility is unavailable. Take a snapshot, then subscribe after its cursor. The stream polls committed records once per second, emits diagnostics.changed pages, and sends heartbeat comments when idle. It closes after two minutes: reconnect with the last received cursor. Each poll rechecks operator authorization, including session/token revocation and grants. A transport interruption is not evidence that the run stopped. Events identify the changed ledger table and entity UUID. They invalidate the snapshot; they are not chat messages and must not be appended to the conversation. Run, step, model, tool, observation, progress, decision and manifest changes are recorded transactionally. No prompt or result bytes are copied into this feed. There is no fabricated pre-migration event history. Events remain for the lifetime of their run; deleting a run cascades its diagnostic references.

Input manifest

Each primary inference attempt records a version-1 manifest before dispatch. Failure to record prevents provider dispatch and fails the recorded call. Its model-call ID joins directly to the run trace. This is independent of successful reply metadata, so failed inference attempts remain inspectable. Existing runs and non-primary classifier calls may have no manifest; absence is not an empty input. Classifier evidence remains in the trace’s decisions lane. A manifest contains:
  • The requested model, output reservation, estimated total input and estimator ID.
  • The prompt snapshot reference and digest of the recorded request audit body.
  • Agent display identity and profile revision from the call’s context plan when available. current_display_name in the envelope is explicitly current metadata.
  • An input configuration digest over system instructions, requested model and offered tool definitions. This is a fingerprint of those effective inputs, not a version of all mutable agent settings.
  • Additive contribution estimates for protocol framing, every normalized message and each offered tool schema. Instructions, assembled context, tool results and runtime context are identified structurally. Message components include image reserve counts and tool-call argument/framing estimates where applicable.
  • Memory revision and history message references selected for the call, memory candidates omitted by the context budget, and the assembly report’s inclusion, omission and budget counts. Included means supplied to the request, not read or followed by the model.
Component indexes refer to the provider-neutral request before wire encoding; request bodies can have provider-specific layouts. Digests preserve comparison without copying text. Each message also supplies content_digest, the SHA-256 of its UTF-8 text alone, so SDKs can compare a submitted serialization across languages without reproducing Go JSON encoding. A match proves byte inclusion, not that the model followed the content. Memory/history estimates in assembly are subdivisions of the assembled input, not additional tokens to sum onto components. Provider-reported prompt/output/cache-write/cached/reasoning usage and cost are separate model-call fields; null means not reported. Cached tokens are a subset of input usage, not additional input. No exact per-source provider measurement is claimed.

Content and coverage

Prompt bodies are retrieved through the existing agent-scoped /prompt-snapshots/{snapshotID} endpoint, which explicitly reports pruning. Request bodies contain the actual offered schemas and request content; image bytes are excluded by the existing audit-body capture. Existing retention removes request/prompt bodies while preserving body-free manifest metadata and cursors. The new snapshot redacts credential-shaped strings; this is defense in depth, not permission to expose operator evidence to ordinary conversation readers. Application-supplied context currently embedded in message text remains a conversation component. Formation does not infer trusted source boundaries from text or treat client claims as proof of inclusion. The next SDK/application phase must supply structured source attribution if it needs subdivisions within that component. Client transport clocks, screen context revisions, first paint and render/validation outcomes remain client observations. Backend timestamps share the server-wall domain; do not subtract device timestamps without clock handling. For an agent Overview before its first run, reuse existing agent detail, persona and tools reads. For historical turn inspection use captured prompts, manifests and recorded requests, never replace them with today’s configuration. This PR introduces no model-generated summaries and no inspector UI dependency.

Public response correlation and timing

Snapshots also return publications: public message IDs explicitly associated with this run, their opening time, first nonempty text recording time, current status and current terminal recording time. These records survive bounded application token-event retention. Successive text deltas do not generate a new diagnostic event each time; first-text and lifecycle changes do. Reopening a message clears its terminal time. First text is the first observed publication for that run/message across attempts, not a provider’s first token measurement. A canonical reply without a run ID is correlated only through a unique recorded trigger; ambiguous or absent provenance is left unavailable. Ledger and publication timestamps use database_wall. captured_at is marked with its own application_server_wall domain. Provider-call latency is an elapsed measurement. The envelope’s current_backend_build identifies the process serving this read; it is not attributed retroactively to historical calls. redaction identifies credential-shape scrubbing: a digest refers to the original recorded input and need not match a scrubbed body displayed by an inspector.