Preserve ACP error details in saved Prompt failures #1039

Story

When an agent Prompt fails through ACP, preserve the available failure details in XMD's saved Prompt evidence so a person or Sidekick can distinguish an adapter/request failure from a backend failure without reproducing the request or reading private session files.

For example, an adapter returns the generic message Internal error with a more specific supported error code or diagnostic. XMD shows the readable failure and retains the safe structured detail for later inspection, including after reopening the REPL.

Observed incident and limits

In REPL execution a5544ec760b14ac84c36bd563106f292, Sidekick conversation 1558fa639e162a825c3e7772bc0a1bce, turn 32 records a failed Codex Prompt with empty reply text and only:

{"message":"Internal error"}

The preceding turn completed and announced a correction from the unsupported 3h duration to 180min. The experiment itself had sent no Luna prompt. Sidekick's next prompt failed before a new turn appeared in the inspected native Codex history. The ACPX record references an event-log file that was unavailable during investigation.

The underlying cause remains unknown. We have not established that this particular response contained richer error data, or whether the fault originated in the adapter or Codex. The missing log does not establish who removed it.

Current gap

packages/acp/src/events.ts maps a failed runtime result to new Error(result.error.message). The installed runtime result type also exposes optional code, detailCode and retryable fields; this mapping drops them. ACP adapters may place further diagnostics in JSON-RPC error data, which requires tracing the earlier normalization boundary rather than assuming that data reaches XMD.

The Prompt consumer subsequently serializes the normalized error. Once detail is discarded, reopening history cannot recover it. A generic message is insufficient to identify the failing boundary, and diagnosis currently depends on separate runtime logs that may not remain available.

Contract

• Trace failure information from the adapter response through ACPX normalization, the normalized Prompt failure, its saved record and the existing diagnostic presentation. Preserve supported error classification and useful safe detail that is actually available; identify where unavailable information is lost rather than inventing a cause.
• Retain a compact, structured diagnostic with the failing operation/stage and existing request/conversation correlation where available. Use existing error and history mechanisms; avoid a general tracing framework or a second outcome authority.
• Keep useful diagnostics in the owning saved Prompt evidence, so basic investigation does not depend on an ephemeral ACP log. Preserve distinctions between absent details and explicitly reported causes.
• Show the readable summary and make the retained details inspectable through the existing Prompt/history surfaces. Do not concatenate diagnostics into the agent's reply text.
• Protect credentials and explicitly identified secrets. Do not persist arbitrary raw protocol payloads, environment variables, full prompts, authentication headers or unrelated conversation history merely to retain an error.
• Preserve the original failure, cancellation, permission refusal, cleanup and uncertainty semantics. A retryable hint is diagnostic information, not authorization to resend. Inspection and reopen launch no agent call or entry.
• Keep existing saved failures readable. Extend their diagnostic representation only as required by this outcome; no unrelated journal migration.

Acceptance and evidence

1. A deterministic adapter/runtime failure supplies Internal error plus a supported specific code/detail. Assert that meaningful fields survive into the saved Prompt failure and its diagnostic read. The test fails against the current message-only mapping.
2. Two failures with the same message and different supported classifications remain distinguishable after cold reopen without runtime logs. Count provider calls to establish that inspection performs no resend.
3. A message-only upstream failure remains explicitly undiagnosed; XMD does not infer nonacceptance, a backend defect or a successful retry.
4. Sensitive diagnostic input is excluded or screened while ordinary useful details remain available. Cover ordinary errors and cancellation/refusal using the affected existing regressions.
5. Trace any upstream field that the current ACPX result cannot represent. Make the smallest necessary correction at its owning boundary and record the actual limitation; retaining only fields already exposed is not evidence that unavailable adapter data was recovered.

Start with packages/acp/tests/provider.test.ts, packages/core/tests/agent-function-components.test.ts, packages/acp/src/events.ts, packages/core/src/agent/errors.ts and existing REPL Prompt-inspection tests. Select focused files for the boundaries actually changed.

Relationships and scope

• Recover xmd repl Sidekick conversations after uncertain feedback delivery #987 owns explicit recovery after uncertain Sidekick feedback delivery. This issue improves evidence; it does not authorize continuing an uncertain conversation.
• Inspect saved command failures from Sidekick in xmd repl #1006 owns inspection of saved shell-command stdout/stderr and exit status. This issue concerns agent Prompt failures.
• Make ACPX session saves reliable at prompt completion #933 owns a separately demonstrated ACPX session-save failure. The incident above does not establish that as its cause.
• Start headless XMD sessions through Agent and attach an interactive REPL #1005's active headless implementation retains its current source ownership; this issue creates no parallel edit to that work.

Exclude fixing the unknown Codex internal error without evidence, automatic retries, provider replacement, broad log retention, and changing duration syntax.