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).