How to read AgentSight audit provenance and confidence

The short answer: treat provenance as a type, not as decoration

The exported snapshot schema defines four row-level provenance values. view means the row was emitted from captured events in the live materialized view. sqlite means AgentSight reconstructed or reprojected the row while loading normalized persisted data. agent_native_sessionmeans the evidence came from a supported agent's own native session files. unknown is the compatibility value for legacy or otherwise unclassified evidence.

These values describe lineage. They do not say that one source is universally “better,” and they do not identify the logical operation by themselves. A directly captured LLM call row and a later reconstructed LLM request row can both describe the same interaction while correctly carrying different provenance. Review tools should keep that distinction instead of flattening all rows into one undifferentiated event stream.

The four sources answer different questions

`view_source`	What happened	Good use	Main caveat
`view`	A runtime event was normalized and projected directly into the live materialized view.	Reasoning about observed process, file, network, LLM, token, or tool activity near capture time.	Correlation can still be heuristic; direct capture does not make every semantic join exact.
`sqlite`	A saved database was loaded and a row was reconstructed or derived from persisted normalized rows.	Reopening completed runs, producing reports, and rebuilding audit views without the original live process.	A reconstructed row may summarize or infer relationships rather than reproduce one original capture event byte-for-byte.
`agent_native_session`	AgentSight parsed the agent's own local session history.	Conversation/session identity, prompts, responses, tool history, and token metadata available from supported agent formats.	Native history is application evidence, not an independent operating-system trace of every effect.
`unknown`	The old artifact or row does not carry a classified lineage.	Compatibility with captures created before provenance columns existed.	Do not silently promote it to a stronger source based on surrounding rows.

Confidence is local to the reconstruction rule that produced the row

AgentSight does not define confidence as a globally calibrated probability. The live LLM correlator illustrates why. When a response carries a request ID that exactly matches a pending request, the current code assigns 0.95. If there is only one pending request on the stream, the match is0.75. If there are several pending requests but only one viable request candidate, it uses0.70. A response that cannot be paired is retained as an orphan response at 0.35.

Those numbers describe confidence in one particular request/response correlation procedure. A reconstructed prompt from SQLite can carry 0.50. Agent-native rows can carry 0.95 for a different reason: confidence in extraction and lineage from the native session source. Therefore0.95 view and 0.95 agent_native_session are not interchangeable measurements. The numeric equality does not mean the evidence has the same semantics or failure modes.

One logical call can legitimately create more than one audit row

During live capture, AgentSight records a pending LLM request, keeps a bounded queue per PID/TID stream, and later attempts to pair a response. The queue is capped at 16 pending requests per stream and entries older than five minutes are pruned. The resulting call, token, tool, and LLM audit rows retain the correlation confidence used by that pairing.

When a saved database is reopened, AgentSight can project prompt-oriented audit rows from persisted LLM calls. That projection is useful for a report view, but it is a new row derived from normalized storage. Its view_source becomes sqlite instead of pretending it is the original direct capture. This is exactly the case where deduplicating by “same timestamp + same text” without preserving lineage can lose information.

The implementation prevents captured payloads from forging stronger provenance

Provenance is metadata assigned by AgentSight, not a field trusted from the application payload. The SQLite reconstruction path explicitly checks internally assigned call kinds when deciding whether a prompt came from an agent-native session. A captured request containing a user-controlled field that happens to say agent_native_session does not get promoted to that source. The regression tests in the pinned v1.0.30 source preserve the row as SQLite/captured evidence instead.

This distinction matters when the observed workload is itself untrusted. Audit metadata that decides how strongly a reviewer interprets a row should not be forgeable by putting reserved-looking keys inside the traced JSON body.

Legacy databases remain readable, but missing provenance stays missing

PR #204 added writable SQLite migrations for the provenance columns while retaining read fallbacks for older schemas. If an old audit_events or llm_calls table lacks the columns, AgentSight reads the source as unknown and confidence as null. That is preferable to inventing certainty retroactively.

Consumers should follow the same rule. Snapshot schema version 1 allows additive fields, so a parser should tolerate new fields and treat missing provenance on older example artifacts as unknown rather than failing the whole import or assigning a modern default score.

Use a small evidence hierarchy when reviewing a surprising finding

Start with the row's provenance and then ask whether the claim depends on correlation. A directly captured file-open event is different from a reconstructed process placeholder. A native session prompt is different from a TLS-captured request. If two sources agree, preserve both instead of converting the agreement into a higher made-up confidence number. If they disagree, identify which field is source-dependent and reproduce the bounded task before escalating.

Review question	What to inspect
Was this row observed or reconstructed?	`view_source` first; do not infer lineage from the row's text.
Does the finding depend on an LLM request/response pair?	Inspect the confidence and whether the row is a call, request, response, or orphan.
Do two rows describe the same logical operation?	Compare stable IDs, session/conversation context, PID/TID context, timestamps, and source-specific fields before deduplication.
Can absence be treated as proof?	Only after checking capture scope, source coverage, persistence, reconstruction rules, and any event/content bounds.

Export a snapshot, then keep the provenance fields in downstream tooling

agentsight report export -o snapshot.json writes schema version 1 of the materialized view. The same shape is available from GET /api/v1/snapshot. For a quick inspection, keepview_source and confidence beside the semantic fields instead of stripping them during normalization.

agentsight report export -o snapshot.json

jq '.audit_events[] |
  {audit_type, action, target, status, view_source, confidence}' snapshot.json

jq '.process_nodes[] |
  {pid, command, status, view_source, confidence}' snapshot.json

The top-level summary.source identifies the materialized-view source, while row-levelview_source identifies lineage for individual evidence. Do not substitute one for the other in an export pipeline.

Snapshot provenance does not make the snapshot safe to publish

The schema documentation marks several fields as captured content. Request paths, command lines,argv, working directories, audit targets/details, session attributes, and tool inputs/outputs can contain repository names, user paths, prompts, responses, credentials, or other sensitive material. Provenance tells you where evidence came from; it is not a redaction layer.

For a review artifact, keep only the fields needed to support the question, redact sensitive values, and preserve the provenance metadata for the rows you retain. A smaller evidence package with explicit lineage is usually easier to review than a raw snapshot with every captured detail.

The practical rule

Read view_source before interpreting confidence. Read the semantic row only after you know which evidence path produced it. Never rank heterogeneous sources by confidence score alone, and never convert agreement between sources into an invented probability. When the result matters, preserve the independent rows and reproduce the bounded run.

That turns provenance from a UI label into an audit contract: the reviewer can distinguish direct runtime observation, persistence-time reconstruction, native application history, and legacy uncertainty without pretending they are the same measurement.