> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Live application diagnostics

> Versioned operator-authorized evidence for embedded agent inspectors.

# 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`.

| GET route under `/api/agents/{slug}` | Purpose |
| - | - |
| `/diagnostics/conversation?install_id=…&conversation_key=…` | Resolve the generic application's opaque conversation key to its scoped graph ID. |
| `/conversations/{conversationID}/diagnostics?before=…` | Discover up to 50 runs, newest first. Pass `next_before` to read the next page. |
| `/runs/{runID}/diagnostics` | Consistent run trace, input manifests and change cursor. Private bodies are omitted. |
| `/runs/{runID}/diagnostics?include_content=true` | Explicitly include retained request, response, tool and decision content, with credential-shape redaction. |
| `/runs/{runID}/diagnostics/events?after=0` | Up to 500 durable reference events after the cursor. |
| `/runs/{runID}/diagnostics/stream?after=0` | Resumable SSE over the same durable events; alternatively use `Last-Event-ID`. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.