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 returnCache-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_namein 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.
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 returnpublications: 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.