[Feature]: Expose stable physical LLM request identity, retry correlation, and settlement outcome to host observers

[kumanday]

Product or interface

Source build or repository tooling

Use case and problem

MiniMax Code already has useful instrumentation around the distinction between a logical LLM call and the one or more physical provider requests used to satisfy it. I would like to consume that lifecycle reliably from external observability, evaluation, and tracing systems.

The current host-facing PiLLMRequestObserver in:
packages/agent-core/src/pi-turn-runner/metrics.ts
provides request-start information such as:

• sessionId
• turnId
• startedAtMs
• provider
• model
• caller

and its settlement callback currently provides:

• endedAtMs
• cacheOutcome

This leaves out the identities and causal information needed to reconstruct physical request trajectories reliably.

Importantly, much of this information already exists elsewhere in the retry layer. In:
packages/agent-core/src/pi-turn-runner/llm-retry.ts

the runtime already has:

• a logical callId
• a one-based requestAttempt
• physical request outcome
• retry events and retry reasons
• a symbol-keyed identity shared across physical attempts of one logical call
• a physical-request settlement observer used internally by the retry machinery

Physical failures are also exposed separately through PiLLMRequestFailureHook.

The gap is therefore less about generating new telemetry and more about making the existing correlation information available through a coherent host-facing physical-request lifecycle contract.

Without this, a host that consumes PiLLMRequestObserver cannot reliably answer questions such as:

• Which physical requests belonged to the same logical call?
• Was this request the initial attempt or a retry?
• Which request eventually recovered the logical call?
• Which failure event corresponds to which observed request?
• How much latency was attributable to failed attempts?
• Did two nearby requests belong to retries, concurrent calls, or separate sessions/subagents?

Correlating these streams using timestamps or ordering heuristics becomes fragile once retries or concurrent activity are involved.

Desired behavior

Expose enough stable identity and correlation information through the host-facing physical request observer to reconstruct the request lifecycle without heuristics.

For example, request-start information could include fields along the lines of:

{
  requestId,
  callId,
  requestAttempt,
  sessionId,
  turnId,
  scope,
  startedAtMs,
  provider,
  model,
  caller
}

and settlement information could include:

{
  requestId,
  endedAtMs,
  outcome,        // success | error | abort
  cacheOutcome,
  errorKind?      // normalized classification when applicable
}

The exact API shape is less important than preserving these properties:

• Every physical provider request has a stable identity.
• Every request can be correlated to its logical LLM call.
• Physical attempts have an explicit ordinal.
• Settlement records distinguish success, failure, and cancellation.
• Normalized failure classification is available when appropriate.
• Existing retry-layer identities and observations are reused where possible rather than duplicated.
• Observer behavior remains fail-open and cannot affect provider requests or turn execution.
• The contract works independently of whether cloud metrics or diagnostic upload are enabled.

This would provide a clean foundation for tracing, OpenTelemetry projection, reliability analysis, provider evaluation, and other external observability consumers.

Platform

Multiple platforms

Alternatives and additional context

Possible alternatives today include:

1. Correlating the existing observer, failure hook, retry events, and logical-call events by timestamp/order. This is ambiguous under concurrency and retries.
2. Having individual hosts consume retry-layer symbol-keyed internals directly. This exposes useful information but couples each host to implementation details instead of providing a coherent observability contract.
3. Recording only aggregate retry counts. This answers how many requests occurred but not what happened during each request.

Related: #179 covers retaining individual physical request attempts and retry lineage in the LLM Context Inspector, while #180 covers capture completeness and evidence-loss reporting. This issue remains specifically scoped to the generic physical-request observation contract.

[hetaoBackend]

Thanks for the detailed proposal. The current host observer exposes request timing and cache outcome but lacks the correlation and settlement fields you describe. A stable contract for physical attempts is a useful extension.

I would keep this separate from the immediate TUI bug-fix batch and review it as an observability API change. The main design points are reusing the retry layer's logical-call identity, assigning one identity per physical attempt, defining success/error/abort settlement exactly once, preserving fail-open observers, and covering concurrency and cancellation without depending on cloud telemetry.

The proposed separation from Context Inspector retention and capture-integrity reporting makes sense. Leaving this open for that contract review; no implementation or release date is committed yet.