Preserve agent context and diagnostics in replay errors #8

User and situation

AI-agent authors and evaluation maintainers inspect a failed controller run after a command or adapter operation throws. When the replay contains only an error message, they may not be able to tell which agent action failed, where the underlying failure originated, or how it relates to their action intent.

Direct evidence

• 2026-09-07 — Factorio Learning Environment PR #413: during a four-node, 64-step evaluation, one rollout failed about an hour in with a generic observation error; the wrapper discarded the underlying exception, making the cause unavailable in the evaluation log. Replaying the same action sequence succeeded twice on fresh servers. The PR's fix retained the underlying error text and logged retry attempts. Direct PR and report
• 2026-09-14 — FLE issue #417: an agent-evaluation user reported stale/dead connections returning plausible empty results and a status surface still saying “Connected”; the stated workaround for a dead RCON connection was to reconnect the client directly from inside execute. This is a separate environment and illustrates the cost of diagnostics that hide the failure state. Direct issue

These are reports from one benchmark project, not evidence of prevalence, and the failures occur in observation/server layers rather than OpenController itself.

What OpenController controls

OpenController already records command errors to replay JSONL. However, ControllerRuntime.send passes the command but not its CommandContext to the error logger, and ReplayLogger.error stores only the rendered error message and command. Context currently contains optional intent and source fields (types.ts). OpenController can preserve those fields and useful structured error details in its own replay; it cannot capture game observations or diagnose failures from an external game/server that never reach its adapter.

Proposed deliverable

Improve replay error events so an agent author can connect a failed controller command to its intent/source and inspect structured error details, while maintaining compatibility with existing replay readers. Keep this focused on error recording and inspection; do not add automatic retries.

Acceptance criteria

• Error replay events include the failed command's available intent and source context.
• For native Error values, record a stable message and useful diagnostic details such as error name and stack when present; safely handle non-Error values.
• Preserve existing event fields and make old and new error events readable by the replay summary/export paths.
• Add focused tests showing context and diagnostic details survive JSONL serialization and that older error-event fixtures remain readable.
• Document what error information is recorded and that external game/server observations are outside replay coverage.

Non-goals and risks

• No automatic retry or command replay: retries can duplicate stateful controller actions and need a separate safety design.
• No promise to capture secrets safely from arbitrary adapter error text; review/redact sensitive values before persisting error details.
• No game screenshots, environment observations, or external server exception capture.

Cycle 2 selection

Selected as Rank 1 by research issue #7, under umbrella issue #5. Implement the bounded error-context behavior and acceptance checks above.