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

[truenorth-lj]

Issue for this PR

Closes #24494

Prior report: #24494 by @hancengiz — the original ACP-side observation with source-level evidence pointing to where the failure stays internal in session/processor.ts. This PR is the wiring change on the agent-loop side. — halt() never emits an ACP frame when the LLM call fails after retries are exhausted. The turn appears silently stuck to ACP clients.

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; rebase will be clean.

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?

Context: When the retry policy in session/retry.ts is exhausted, session/processor.ts halt() updates internal state (ctx.assistantMessage.error, Bus.Session.Event.Error, EventV2.SessionEvent.Step.Failed.Sync) but never emits any ACP session/update notification or other frame to the connected client. From an ACP client's perspective the turn is silently stuck:

• No stopReason
• No error notification
• No final session/update

Symptom: send session/prompt to a backend that returns a non-retriable failure (or a 429/502 storm that exhausts the retry budget). Client emits some agent_message_chunks (or zero, for an immediate failure), then nothing. The session looks indistinguishable from "agent hung."

Fix: Add a case "session.error": branch in packages/opencode/src/acp/agent.ts handleEvent() that translates the SDK error variant into an LLMErrorPayload (defined in acp/agent-error.ts from #26306) and emits the new agent_error session/update kind with stopReason: "error".

The payload extraction prefers headers set by a classifying upstream proxy:

• 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

Falls back to status-code heuristics when headers are absent (401 → auth, 5xx → provider_unavailable, else → unknown). ProviderAuthError and ContextOverflowError SDK variants are mapped to their typed forms by name.

ContextOverflowError is intentionally not emitted as a turn-ending error — halt() routes that variant into in-process compaction; the turn continues on a smaller context window. Surfacing it as agent_error would race with the compaction path and produce a confusing FE state.

The existing event subscription in acp/agent.ts already receives session.error events via Bus.subscribeAll() → SDK SSE /event stream → runEventSubscription (the same channel that delivers permission.asked, message.part.updated, etc.) — there was simply no case for it. No bus / SDK / event-stream wiring changes were required.

How did you verify your code works?

packages/opencode/test/acp/halt-emits-agent-error.test.ts (new) — 10 tests covering:

llmErrorPayloadFromSDK unit tests (pure mapping):

• APIError with x-llm-error-type=budget headers → typed budget payload, retryable=false, reset_at_epoch_ms populated
• APIError with x-llm-error-type=rate_limit + retry-after → retry_after_seconds populated
• APIError no headers, status 503 → provider_unavailable retriable
• APIError no headers, status 401 → auth non-retriable
• ContextOverflowError variant → context_overflow non-retriable
• ProviderAuthError variant → auth non-retriable
• Explicit x-llm-error-retryable: "false" overrides type-derived retryable

Integration tests (event push → connection.sessionUpdate assertion via createFakeAgent mirroring event-subscription.test.ts):

• APIError with classification headers → exactly one agent_error session/update emitted, payload fields preserved, stopReason: "error"
• ContextOverflowError → no agent_error emit (compaction path)
• session.error with unknown sessionID → no emit (defensive, no cross-session leak)

$ bun test test/acp/halt-emits-agent-error.test.ts
 10 pass
 0 fail
 23 expect() calls
Ran 10 tests across 1 file. [4.89s]

$ bun test test/acp/
 33 pass
 0 fail
 79 expect() calls
Ran 33 tests across 4 files. [1.60s]

$ bun run typecheck
 Tasks:    12 successful, 12 total

Screenshots / recordings

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

Checklist

• All tests pass locally
• Code follows the existing event-handling style (case per event type, connection.sessionUpdate(...).catch(log) per the prevailing pattern in handleEvent)
• Diff confined to packages/opencode/src/acp/{agent.ts,agent-error.ts} plus the new test file
• No new dependencies, no schema migrations, no protocol breaking changes (the new agent_error kind is additive and is the subject of feat(acp): add AgentErrorUpdate session/update kind for typed LLM error propagation #26306)
• 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).