Skip to content

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

@yurtzy

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions