[Feature]: Expose LLM Context Inspector capture completeness and evidence-loss diagnostics

Product or interface

Source build or repository tooling

Use case and problem

The LLM Context Inspector is deliberately designed so observation and persistence cannot interfere with agent execution. That fail-open behavior is desirable, but it currently creates an important ambiguity for consumers of Inspector evidence: absence of evidence does not necessarily mean absence of the underlying event.

For example, capture-recorder.ts uses best-effort persistence helpers such as:

persistSettledCallIgnoringFailure(...)
persistIgnoringFailure(...)

whose errors are intentionally swallowed so capture failures cannot alter LLM calls or tool execution.

The Inspector does have useful payload-level states:

AVAILABLE
OMITTED_TOO_LARGE
CAPTURE_FAILED

These describe an individual captured request or response payload, but they do not provide an aggregate indication that the trajectory itself is complete or degraded.

A consumer inspecting a session, turn, logical call, or physical request therefore may be unable to distinguish cases such as:

• capture was disabled
• the event was outside the supported capture scope
• a request/response payload was intentionally omitted because it exceeded the size limit
• payload capture failed
• event persistence failed
• tool timing persistence failed
• some physical retry attempts were retained but others were lost
• the recorder shut down before all pending observations were committed
• no event actually occurred

This distinction matters for debugging, evaluation, reliability engineering, and external observability systems. A trajectory with missing evidence should not appear indistinguishable from a complete trajectory.

Desired behavior

Expose machine-readable capture-integrity information so consumers can determine the known completeness of Inspector evidence.

The exact representation can vary, but it should distinguish at least:

• capture available and no known loss
• intentionally omitted evidence
• partial/degraded capture
• capture or persistence failure
• capture disabled or unavailable
• completeness unknown when the instrumentation cannot establish it

Where possible, the status should include structured reasons rather than only a boolean such as complete: false.

For example, a logical call or turn could expose something conceptually similar to:

{
  captureStatus: "partial",
  degradations: [
    {
      kind: "persistence_failed",
      source: "physical_request",
      requestId: "..."
    },
    {
      kind: "payload_omitted",
      source: "response",
      reason: "too_large"
    }
  ]
}

This does not need to contain sensitive request or error contents.

Useful properties would include:

• Known capture failures are observable instead of silently disappearing.
• Payload omission because of size limits remains distinguishable from recorder/persistence failure.
• Capture-disabled or unsupported states are distinguishable from genuine absence of activity.
• Integrity state can be associated with the narrowest useful scope, such as request, logical call, turn, or session.
• If individual physical attempts are retained, consumers can determine whether the observed attempt sequence is known to be complete.
• Inspector overview/detail APIs expose the integrity state in a machine-readable form.
• Capture-health reporting itself remains fail-open and cannot interfere with agent execution.
• The implementation does not claim absolute completeness where the instrumentation cannot know whether an event was missed. An unknown or equivalent state is preferable to a false guarantee.

Platform

Multiple platforms

Alternatives and additional context

The existing per-payload CapturedPayloadState is useful but cannot report loss of an entire event or failed persistence of metadata.

Logging persistence errors would improve operator visibility, but logs alone are difficult for programmatic consumers to correlate with a particular session, turn, call, or request. A structured Inspector-level integrity state would be considerably more useful.

Inferring completeness by comparing attemptCount, event files, payload files, or other artifacts is also fragile and becomes especially difficult once retries, partial capture, or interrupted shutdown are involved.

Related: #162 establishes the physical-request correlation primitives, and #179 covers retaining those request attempts in Inspector history. This issue is specifically scoped to making the integrity and completeness of that Inspector evidence explicit and machine-readable.

Start with capture-recorder.ts and its persistSettledCallIgnoringFailure(...) and persistIgnoringFailure(...) paths, then inspect CapturedPayloadState and the Inspector overview/detail APIs. Trace the physical-request correlation and retained-attempt work in #162 and #179. Done means consumers can distinguish complete, omitted, degraded, failed, disabled, and unknown evidence without affecting agent execution.