feat(acp): emit agent_error session/update when LLM call fails after retries

[truenorth-lj]

Issue for this PR

Closes #24494
Closes #28453

Stacks on #26306, which adds the agent_error SessionUpdate kind and the LLMErrorPayload shape this PR uses. Diffs from that PR are included here until it merges.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement / new feature (non-breaking change which adds functionality)

What does this PR do?

When the retry policy in session/retry.ts is exhausted, session/processor.ts halt() records the failure internally but does not emit an ACP frame to the connected client. From an ACP client perspective, the turn can look silently stuck: no final error notification and no stopReason.

This PR adds a case "session.error": branch in packages/opencode/src/acp/agent.ts that translates the SDK error variant into an LLMErrorPayload and emits the new agent_error session/update kind with stopReason: "error".

The payload extraction prefers classification headers when present:

• x-llm-error-type: budget | rate_limit | provider_unavailable | context_overflow | auth | unknown
• x-llm-error-retryable: "true" / "false" (overrides type-derived retryable)
• x-llm-error-reset-at: epoch ms - populates reset_at_epoch_ms
• retry-after: seconds - populates retry_after_seconds

It falls back to status-code heuristics when headers are absent (401 -> auth, 5xx -> provider_unavailable, else -> unknown). ProviderAuthError and ContextOverflowError SDK variants are mapped by name.

Two session.error variants are intentionally not emitted as agent_error:

• ContextOverflowError: compaction handles this path and the turn can continue on a smaller context window.
• MessageAbortedError: this is the normal user-stop path triggered by session/cancel; the prompt RPC reports cancellation via stopReason: "cancelled", so emitting agent_error would make one user action look like both an error and a cancellation.

The existing event subscription already receives session.error events through the SDK event stream. No bus, SDK, or event-stream wiring changes are required.

How did you verify your code works?

packages/opencode/test/acp/halt-emits-agent-error.test.ts covers:

• APIError classification headers -> typed payload fields preserved
• fallback status-code classification for 503 and 401
• ContextOverflowError and ProviderAuthError mapping
• explicit retryability override from headers
• session.error emits exactly one agent_error update for a classified API error
• ContextOverflowError emits no agent_error
• MessageAbortedError emits no agent_error
• unknown session IDs emit no update

$ bun test test/acp/halt-emits-agent-error.test.ts
 11 pass
 0 fail
 24 expect() calls

$ bun run typecheck
# clean

# push hook
$ bun turbo typecheck
 Tasks:    12 successful, 12 total

Screenshots / recordings

N/A - backend / ACP wire change. Client rendering of the agent_error frame is downstream consumer work.

Checklist

• All tests pass locally
• Code follows the existing event-handling style
• Diff is confined to ACP error mapping / event handling and tests
• No new dependencies, schema migrations, or breaking protocol changes
• bun run typecheck clean

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search, PR #26306 is a related PR but not a duplicate:

• PR feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306: feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation
  • feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306
  • Relationship: This PR is a dependency that PR feat(acp): emit agent_error session/update when LLM call fails after retries #26352 stacks on. PR feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306 defines the agent_error SessionUpdate kind and LLMErrorPayload shape that PR feat(acp): emit agent_error session/update when LLM call fails after retries #26352 uses. Per the PR description, diffs from feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306 are included in feat(acp): emit agent_error session/update when LLM call fails after retries #26352 until feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306 merges.

The other PRs found (26292, 26192, 19116, 24369, 18443) address different aspects of retry/error handling but are not duplicates of the current PR.

Conclusion: No duplicate PRs found. The only related PR is #26306 (a required dependency that this PR builds upon).

[github-actions]

Automated PR Cleanup

Thank you for contributing to opencode.

Due to the high volume of PRs from users and AI agents, we periodically close older PRs using automated criteria so maintainers can focus review time on the most active and community-supported contributions.

This PR was closed because it matched the following cleanup criteria:

• The PR was created more than 1 month ago
• The PR had fewer than 2 positive reactions
• Positive reactions are counted as thumbs-up, heart, celebration, or rocket reactions on the PR

PRs created within the last month are not affected by this cleanup.

If you believe this PR was closed incorrectly, or if you are still actively working on it, please leave a comment explaining why it should be reopened. A maintainer can review and reopen it if appropriate.

Thanks again for taking the time to contribute.

[alshain]

Leaving a comment so the bot will reopen. I'm still affected by this behavior when using ACP.