Skip to content

[UX] ACP session errors should include actionable remediation hints #176

Description

@yurtzy

When an ACP session fails (e.g., acpx run), the error output is often terse: "session ended" or "connection closed" without explaining why or how to fix it.

Example pain point: A session exits with code 1 but logs show no clear cause — was it a model error, network timeout, auth failure, or plugin crash?

Proposed improvement: Include in error summaries:

  • The exact failure point (which tool/agent threw)
  • Suggested next steps based on common causes:
    • If model API returns 429/500 → "check provider rate limits or switch model"
    • If session times out → "increase --session-ttl or check network"
    • If plugin error → "verify plugin is installed and compatible"
  • Reference to relevant config docs

Impact: Reduces debugging time for headless ACP users who lack interactive context.

This is a pure UX enhancement with no breaking changes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions