cleveragents/cleveragents-core

Fork 3

UAT: `agents actor run` uses exit code 3 for unexpected errors — conflicts with `EXIT_NOT_FOUND=3` in constants.py #5028

New issue

Open

opened 2026-04-09 00:49:30 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 00:49:30 +00:00

Owner

Bug Report

Feature Area: CLI Commands — exit codes
Severity: Medium
Discovered by: UAT Testing (uat-pool-1, worker: CLI Commands)

What Was Tested

Reviewed exit code usage in agents actor run against the standardized exit codes defined in constants.py.

Expected Behavior (from spec)

constants.py defines the following standardized exit codes:

EXIT_SUCCESS: int = 0   # Command completed successfully
EXIT_ERROR: int = 1     # General runtime error
EXIT_USAGE: int = 2     # Invalid command-line usage
EXIT_NOT_FOUND: int = 3 # Requested entity was not found
EXIT_CONFLICT: int = 4  # Operation conflicts with existing state

Actual Behavior

agents actor run in actor.py uses exit codes 1, 2, and 3 with non-standard semantics:

except UnsafeConfigurationError as exc:
    typer.echo(f"Error: {exc}", err=True)
    raise typer.Exit(code=1) from exc   # OK: EXIT_ERROR

except CleverAgentsError as exc:
    typer.echo(f"Error: {exc}", err=True)
    raise typer.Exit(code=2) from exc   # WRONG: EXIT_USAGE (2) used for runtime error

except Exception as exc:
    typer.echo(f"Unexpected error: {exc}", err=True)
    raise typer.Exit(code=3) from exc   # WRONG: EXIT_NOT_FOUND (3) used for unexpected error

The problems:

Exit code 2 is used for CleverAgentsError (a runtime error), but EXIT_USAGE=2 is defined as "Invalid command-line usage (bad arguments, unknown command)". A CleverAgentsError is not a usage error.
Exit code 3 is used for unexpected/unhandled exceptions, but EXIT_NOT_FOUND=3 is defined as "Requested entity was not found". An unexpected exception is not a "not found" error.

Code Location

src/cleveragents/cli/commands/actor.py — run() function, error handling section.

Steps to Reproduce

# Trigger a CleverAgentsError (e.g., invalid actor name)
agents actor run nonexistent/actor "test prompt"
echo $?
# Returns: 2 (EXIT_USAGE)
# Expected: 1 (EXIT_ERROR) or 3 (EXIT_NOT_FOUND) depending on error type

Impact

Scripts that check exit codes to determine error type will misinterpret actor run failures:

Exit code 2 will be interpreted as "bad arguments" when it's actually a runtime error
Exit code 3 will be interpreted as "entity not found" when it's actually an unexpected exception

Suggested Fix

Align exit codes with the spec-defined constants:

except UnsafeConfigurationError as exc:
    typer.echo(f"Error: {exc}", err=True)
    raise typer.Exit(code=EXIT_ERROR) from exc  # 1

except CleverAgentsError as exc:
    typer.echo(f"Error: {exc}", err=True)
    raise typer.Exit(code=EXIT_ERROR) from exc  # 1 (runtime error, not usage error)

except Exception as exc:
    typer.echo(f"Unexpected error: {exc}", err=True)
    raise typer.Exit(code=EXIT_ERROR) from exc  # 1 (unexpected = general error)

Or if the intent was to distinguish error types, use a new constant (e.g., EXIT_INTERNAL=5) rather than reusing EXIT_NOT_FOUND.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** CLI Commands — exit codes **Severity:** Medium **Discovered by:** UAT Testing (uat-pool-1, worker: CLI Commands) --- ## What Was Tested Reviewed exit code usage in `agents actor run` against the standardized exit codes defined in `constants.py`. ## Expected Behavior (from spec) `constants.py` defines the following standardized exit codes: ```python EXIT_SUCCESS: int = 0 # Command completed successfully EXIT_ERROR: int = 1 # General runtime error EXIT_USAGE: int = 2 # Invalid command-line usage EXIT_NOT_FOUND: int = 3 # Requested entity was not found EXIT_CONFLICT: int = 4 # Operation conflicts with existing state ``` ## Actual Behavior `agents actor run` in `actor.py` uses exit codes 1, 2, and 3 with non-standard semantics: ```python except UnsafeConfigurationError as exc: typer.echo(f"Error: {exc}", err=True) raise typer.Exit(code=1) from exc # OK: EXIT_ERROR except CleverAgentsError as exc: typer.echo(f"Error: {exc}", err=True) raise typer.Exit(code=2) from exc # WRONG: EXIT_USAGE (2) used for runtime error except Exception as exc: typer.echo(f"Unexpected error: {exc}", err=True) raise typer.Exit(code=3) from exc # WRONG: EXIT_NOT_FOUND (3) used for unexpected error ``` The problems: 1. Exit code `2` is used for `CleverAgentsError` (a runtime error), but `EXIT_USAGE=2` is defined as "Invalid command-line usage (bad arguments, unknown command)". A `CleverAgentsError` is not a usage error. 2. Exit code `3` is used for unexpected/unhandled exceptions, but `EXIT_NOT_FOUND=3` is defined as "Requested entity was not found". An unexpected exception is not a "not found" error. ## Code Location `src/cleveragents/cli/commands/actor.py` — `run()` function, error handling section. ## Steps to Reproduce ```bash # Trigger a CleverAgentsError (e.g., invalid actor name) agents actor run nonexistent/actor "test prompt" echo $? # Returns: 2 (EXIT_USAGE) # Expected: 1 (EXIT_ERROR) or 3 (EXIT_NOT_FOUND) depending on error type ``` ## Impact Scripts that check exit codes to determine error type will misinterpret `actor run` failures: - Exit code 2 will be interpreted as "bad arguments" when it's actually a runtime error - Exit code 3 will be interpreted as "entity not found" when it's actually an unexpected exception ## Suggested Fix Align exit codes with the spec-defined constants: ```python except UnsafeConfigurationError as exc: typer.echo(f"Error: {exc}", err=True) raise typer.Exit(code=EXIT_ERROR) from exc # 1 except CleverAgentsError as exc: typer.echo(f"Error: {exc}", err=True) raise typer.Exit(code=EXIT_ERROR) from exc # 1 (runtime error, not usage error) except Exception as exc: typer.echo(f"Unexpected error: {exc}", err=True) raise typer.Exit(code=EXIT_ERROR) from exc # 1 (unexpected = general error) ``` Or if the intent was to distinguish error types, use a new constant (e.g., `EXIT_INTERNAL=5`) rather than reusing `EXIT_NOT_FOUND`. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 00:50:29 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 01:01:47 +00:00

HAL9000 commented

2026-04-09 01:01:56 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — Spec compliance bug; deviates from documented behavior
Milestone: v3.2.0
Story Points: 3 — M
MoSCoW: Must Have — Spec compliance is required

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — Spec compliance bug; deviates from documented behavior - **Milestone**: v3.2.0 - **Story Points**: 3 — M - **MoSCoW**: Must Have — Spec compliance is required --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 referenced this issue

2026-04-09 02:56:12 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 4) #5160

HAL9000 referenced this issue

2026-04-09 03:09:06 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 5) #5200