cleveragents/cleveragents-core

Fork 3

UAT: `agents actor run` has undocumented `--config` option not in spec — bypasses actor registry #5077

New issue

Open

opened 2026-04-09 00:55:24 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 00:55:24 +00:00

Owner

Bug Report

Feature Area: Actor System — agents actor run command
Severity: Medium
Discovered by: UAT Testing (uat-pool-1, worker: Actor System)

What Was Tested

Reviewed the agents actor run command signature in src/cleveragents/cli/commands/actor.py against the specification.

Expected Behavior (from spec)

The spec defines agents actor run as:

agents actor run [(--output|-o) <OUTPUT_FILE>]
                 [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>]
                 [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>]
                 [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode]
                 [--skill <SKILL>]... <NAME> <PROMPT>

The <NAME> argument is the actor name resolved from the actor registry. The spec does not define a --config option for actor run — the config-as-source-of-truth pattern applies only to actor add.

Actual Behavior

The implementation adds an undocumented --config / -c option that allows bypassing the registry entirely:

# src/cleveragents/cli/commands/actor.py
config: Annotated[
    list[Path] | None,
    typer.Option(
        "--config",
        "-c",
        exists=True,
        file_okay=True,
        dir_okay=False,
        readable=True,
        resolve_path=True,
        help="YAML config paths (overrides registry-based name resolution)",
    ),
] = None,

This means users can run agents actor run --config ./my-actor.yaml "prompt" without registering the actor first, which is not part of the spec contract.

Code Location

src/cleveragents/cli/commands/actor.py — run() function, config parameter

Impact

The --config option is not documented in the spec and creates an undocumented API surface
Users relying on --config for actor run may be surprised when this is removed
The -c short flag conflicts with the spec's -c for actor add --config
Bypassing the registry undermines the actor registration lifecycle

Steps to Reproduce

# This works but is not in the spec:
agents actor run --config ./my-actor.yaml "Summarize the README"

# The spec only supports registry-based resolution:
agents actor run local/my-actor "Summarize the README"

Suggested Fix

Either:

Remove the --config option from actor run to align with the spec
Document it in the spec as an intentional extension (requires spec update)

If the option is kept, it should be clearly marked as an extension and the -c short flag should be avoided to prevent confusion with actor add -c.

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

## Bug Report **Feature Area:** Actor System — `agents actor run` command **Severity:** Medium **Discovered by:** UAT Testing (uat-pool-1, worker: Actor System) --- ## What Was Tested Reviewed the `agents actor run` command signature in `src/cleveragents/cli/commands/actor.py` against the specification. ## Expected Behavior (from spec) The spec defines `agents actor run` as: ``` agents actor run [(--output|-o) <OUTPUT_FILE>] [-v...] [--unsafe|-u] [--context <CONTEXT_NAME>] [--context-dir <CONTEXT_PATH>] [--load-context <LOAD_CONTEXT_NAME>] [(--temperature|-t) <TEMP>] [--allow-rxpy-in-run-mode] [--skill <SKILL>]... <NAME> <PROMPT> ``` The `<NAME>` argument is the actor name resolved from the **actor registry**. The spec does not define a `--config` option for `actor run` — the config-as-source-of-truth pattern applies only to `actor add`. ## Actual Behavior The implementation adds an undocumented `--config` / `-c` option that allows bypassing the registry entirely: ```python # src/cleveragents/cli/commands/actor.py config: Annotated[ list[Path] | None, typer.Option( "--config", "-c", exists=True, file_okay=True, dir_okay=False, readable=True, resolve_path=True, help="YAML config paths (overrides registry-based name resolution)", ), ] = None, ``` This means users can run `agents actor run --config ./my-actor.yaml "prompt"` without registering the actor first, which is not part of the spec contract. ## Code Location `src/cleveragents/cli/commands/actor.py` — `run()` function, `config` parameter ## Impact - The `--config` option is not documented in the spec and creates an undocumented API surface - Users relying on `--config` for `actor run` may be surprised when this is removed - The `-c` short flag conflicts with the spec's `-c` for `actor add --config` - Bypassing the registry undermines the actor registration lifecycle ## Steps to Reproduce ```bash # This works but is not in the spec: agents actor run --config ./my-actor.yaml "Summarize the README" # The spec only supports registry-based resolution: agents actor run local/my-actor "Summarize the README" ``` ## Suggested Fix Either: 1. **Remove** the `--config` option from `actor run` to align with the spec 2. **Document** it in the spec as an intentional extension (requires spec update) If the option is kept, it should be clearly marked as an extension and the `-c` short flag should be avoided to prevent confusion with `actor add -c`. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 00:55:31 +00:00

HAL9000 commented

2026-04-09 01:02:08 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Minor spec deviation; undocumented option or cosmetic inconsistency
Milestone: Not assigned (backlog)
Story Points: 2 — S
MoSCoW: Could Have — Minor polish item; does not block core functionality

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Minor spec deviation; undocumented option or cosmetic inconsistency - **Milestone**: Not assigned (backlog) - **Story Points**: 2 — S - **MoSCoW**: Could Have — Minor polish item; does not block core functionality --- **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

HAL9000 added a new dependency

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

#5203 EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses

HAL9000 added this to the v3.2.0 milestone

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