§5 user-facing failure guidance: drive chat error-card CTA from structured user_action (#3408)

[maoxin1234]

Why

Part of the reliability epic #3408. The daemon now emits a canonical failure classification on run_finished (failure_category / failure_stage / retryable / user_action, via run-failure-classification.ts from #4431), and §3 safe-retry already consumes retryable. But the web error card still maps its CTA off the raw error_code (apps/web/src/runtime/amr-guidance.ts resolveRunFailureUi()), so the canonical user_action the daemon already decided is ignored. New classes (prompt_too_large -> reduce_context, model_unavailable -> switch_model, rate_limit -> retry-vs-switch, upstream_unavailable -> retry) do not drive a matching CTA. This is the last open proposal piece (§5) under #3408; §3 is confirmed done.

What users will see

Failed-run error cards show a CTA that matches the actual failure reason — e.g. "reduce context" for an over-large prompt, "switch model" for an unavailable model, "recharge" for AMR balance — instead of a generic retry/authorize derived from a coarse error code.

Proposal

1. resolveRunFailureUi() prefers the structured user_action from run_finished when present and maps it to the CTA at one choke point (login / recharge / retry / switch_model / reduce_context / install_cli / none), reusing the existing AMR promote path. CTA is driven by user_action, not re-derived from failure_category (trust the daemon decision; avoid the two layers diverging). failure_category is used for display only.
2. Fallback chain: when user_action is absent or none, fall through to the existing error_code map so older/unclassified runs — and partially-classified runs (category present, action unresolved) — still render a real CTA rather than a blank one.
3. Tests: resolver covered against every failure_category / user_action (mirroring the daemon classifier test as fixture source-of-truth); a classified run beats the raw-code map; an unclassified run still resolves via fallback; and the partial-classification edge (category set, user_action = none / absent -> reaches the error_code map, no blank CTA).

Scope is UI-side only; daemon classification and retry layers are untouched.

Relates to #3408.

[lefarcen]

Hey @maoxin1234 — solid write-up. I pulled the relevant files to verify the gap, and it's real.

resolveRunFailureUi() in apps/web/src/runtime/amr-guidance.ts currently takes (code, agentId) only, and ChatPane.tsx calls it with resolveRunFailureUi(failedRunErrorEvent?.code, retryAssistant.agentId) — user_action from the daemon is never passed. The daemon side is genuinely ready: run-failure-classification.ts (from #4431) produces the full { failure_category, failure_detail, failure_stage, retryable, user_action } shape, and TrackingRunFailureUserAction is already defined in packages/contracts as 'retry' | 'login' | 'recharge' | 'switch_model' | 'reduce_context' | 'install_cli' | 'fix_config' | 'none'.

A couple of things worth keeping in mind for the implementation:

1. Data path: failedRunErrorEvent in ChatPane is built from the persisted run event stream ({ kind: 'status', label: 'error' } events on the assistant message), not from the PostHog analytics payload. Worth confirming the IPC run_finished / terminal status event actually carries user_action — if it does, it flows through naturally; if not, the message-event shape may need a small extension alongside the resolver change.

2. Type mapping: The existing RunFailurePrimaryAction type doesn't include switch_model or reduce_context yet, so those will need to be added alongside the resolver update — and the error-card rendering layer will need matching branches.

3. The fallback chain is the right call for backward compat: older daemon versions and partially-classified runs (user_action = 'none') must still reach the existing error_code map so they don't regress to a blank CTA.

The test matrix you've outlined — every user_action value, classified beats raw-code, unclassified falls through, partial-classification edge — is exactly the right scope. Mirroring the daemon classifier fixture as source of truth keeps the two layers from drifting.

Overall the proposal is well-reasoned and the scope is cleanly UI-side. Happy to review a PR on this whenever you're ready.

[lefarcen]

If you'd like to take this on, comment /claim to pick it up — we'll assign the issue to you and follow up with a link once a PR is open.

[maoxin1234]

/claim

[lefarcen]

It's yours, @maoxin1234 — thanks for picking this up! Roughly how long do you think you'll need? (a few hours / 1-3 days / ~1 week / longer) — just helps us time any check-ins.

[lefarcen]

@maoxin1234 is addressing this in PR #4738. The approach surfaces the daemon's already-computed classifyRunFailure() output onto the status event at a single send() choke point in server.ts (covering both live SSE and persisted events), so user_action now reaches the client and drives the error card CTA directly — with a fallback to the existing error_code map for older daemons and partially-classified runs. 19 locales updated. Issue stays open until the fix lands.

[lefarcen]

Re-opening this issue for community contribution because linked PR #4738 has had no author activity.

The PR has been left open as draft so @maoxin1234 can resume later, and others may /claim this issue if they want to take it on.

[lefarcen]

Heads-up: PR #5308 is open with the frontend-only slice of this error-guidance work. It teaches the chat error card to show named failure types + actionable guidance for existing error_code paths (prompt-too-large, model-unavailable, rate-limited, upstream-unavailable, CLI-missing, tool-loop, invalid output/runtime config), and adds the locale/test coverage for that mapping.

It does not wire daemon user_action / failure_category through yet, so this issue still tracks the structured CTA path after #5308 lands.

[lefarcen]

Heads-up: PR #5321 is now open on top of #5308 to carry failureDetail / failureCategory from the daemon into the chat guidance layer. That follow-up is what lets the UI distinguish hard quota vs transient 429 and route CLI-not-installed cases to the install guidance instead of the generic failure path. Keeping this issue open until that stack lands.