cleveragents/cleveragents-core

Fork 3

refactor(cli): align `actor run` command signature with specification positional arguments #901

New issue

Closed

opened 2026-03-13 23:47:43 +00:00 by freemo · 2 comments

freemo commented

2026-03-13 23:47:43 +00:00

Owner

Metadata

Commit Message: refactor(cli): align actor run signature with spec positional args
Branch: feature/m4-actor-run-signature

Background and Context

The specification defines agents actor run with two positional arguments:

agents actor run [flags...] <NAME> <PROMPT>

The current implementation in both actor_run.py and actor.py uses options instead of positional arguments:

--config/-c (list of Paths, required) — replaces what the spec calls <NAME> (an actor name reference)
--prompt/-p (string, required) — replaces what the spec calls <PROMPT> (positional text)

Neither file has a positional NAME or PROMPT argument. The spec's design is actor-name-based invocation (agents actor run myactor "Fix the bug"), while the code uses config-file-based invocation (agents actor run -c config.yaml -p "Fix the bug").

This is a fundamental signature mismatch that means the spec's documented examples cannot be typed verbatim on the CLI.

Related: #887 tracks the missing --skill flag on the same command.

Spec reference: Lines 4562–4566

Expected Behavior

agents actor run local/reviewer "Review the authentication module"
agents actor run --skill local/web-tools --temperature 0.2 myactor "Do something"

Acceptance Criteria

<NAME> is a required positional argument (actor name, resolved from registry)
<PROMPT> is a required positional argument (prompt text)
--config/-c is removed or made optional (for direct YAML invocation as a convenience)
Actor is resolved by name from the Actor Registry when positional <NAME> is used
Backward compatibility: if --config is provided, it takes precedence over name-based resolution
Both actor.py and actor_run.py implementations are aligned

Subtasks

Add positional NAME argument to actor_run.py
Add positional PROMPT argument to actor_run.py
Make --config/-c optional (fallback when no positional name is provided)
Add registry-based actor resolution when name is used
Apply same changes to actor.py run command
Tests (Behave): Verify both invocation styles work
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata - **Commit Message**: `refactor(cli): align actor run signature with spec positional args` - **Branch**: `feature/m4-actor-run-signature` ## Background and Context The specification defines `agents actor run` with two positional arguments: ``` agents actor run [flags...] <NAME> <PROMPT> ``` The current implementation in both `actor_run.py` and `actor.py` uses **options** instead of positional arguments: - `--config/-c` (list of Paths, required) — replaces what the spec calls `<NAME>` (an actor name reference) - `--prompt/-p` (string, required) — replaces what the spec calls `<PROMPT>` (positional text) Neither file has a positional `NAME` or `PROMPT` argument. The spec's design is actor-name-based invocation (`agents actor run myactor "Fix the bug"`), while the code uses config-file-based invocation (`agents actor run -c config.yaml -p "Fix the bug"`). This is a fundamental signature mismatch that means the spec's documented examples cannot be typed verbatim on the CLI. **Related**: #887 tracks the missing `--skill` flag on the same command. **Spec reference**: Lines 4562–4566 ## Expected Behavior ```bash agents actor run local/reviewer "Review the authentication module" agents actor run --skill local/web-tools --temperature 0.2 myactor "Do something" ``` ## Acceptance Criteria - [x] `<NAME>` is a required positional argument (actor name, resolved from registry) - [x] `<PROMPT>` is a required positional argument (prompt text) - [x] `--config/-c` is removed or made optional (for direct YAML invocation as a convenience) - [x] Actor is resolved by name from the Actor Registry when positional `<NAME>` is used - [x] Backward compatibility: if `--config` is provided, it takes precedence over name-based resolution - [x] Both `actor.py` and `actor_run.py` implementations are aligned ## Subtasks - [x] Add positional `NAME` argument to `actor_run.py` - [x] Add positional `PROMPT` argument to `actor_run.py` - [x] Make `--config/-c` optional (fallback when no positional name is provided) - [x] Add registry-based actor resolution when name is used - [x] Apply same changes to `actor.py` run command - [x] Tests (Behave): Verify both invocation styles work - [x] Verify coverage >= 97% via `nox -s coverage_report` - [x] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

freemo added the

labels

2026-03-13 23:48:35 +00:00

freemo added this to the v3.4.0 milestone

2026-03-13 23:48:39 +00:00

freemo commented

2026-03-13 23:48:50 +00:00

Author

Owner

Dependencies / Related Issues:

Related: #887 (missing --skill flag on same command — should be implemented together)
This issue covers the broader signature refactoring; #887 covers the specific --skill flag addition.

**Dependencies / Related Issues:** - Related: #887 (missing `--skill` flag on same command — should be implemented together) - This issue covers the broader signature refactoring; #887 covers the specific `--skill` flag addition.

freemo referenced this issue

2026-03-13 23:59:45 +00:00

fix(cli): remove extra <NAME> positional from actor add — name should come from config #914

CoreRasurae was assigned by freemo

2026-03-14 04:27:03 +00:00

CoreRasurae added

and removed

labels

2026-03-19 12:11:19 +00:00

CoreRasurae referenced this issue from a commit

2026-03-19 14:53:41 +00:00

refactor(cli): align actor run signature with spec positional args

CoreRasurae referenced this issue from a pull request that will close it,

2026-03-19 14:55:26 +00:00

refactor(cli): align actor run signature with spec positional args #1072

CoreRasurae added

and removed

labels

2026-03-19 14:56:37 +00:00

CoreRasurae commented

2026-03-19 14:57:18 +00:00

Member

Implementation Notes

Design Decisions (commit `6f05be2c`)

Backward compatibility: --config/-c is preserved as an optional flag. When provided, it takes precedence over positional name-based resolution. This ensures existing scripts and documentation using --config continue to work.
Actor registry resolution: Added _resolve_config_files() helper that imports get_container and looks up the actor by name from the registry. If the actor is not found, it prints an error and calls typer.Exit(code=1).
Dual implementation: Both actor_run.py and actor.py were updated with identical changes since they contain duplicate run() commands.
typer.Exit propagation: Moved _resolve_config_files() call before the try/except block because typer.Exit inherits from RuntimeError -> Exception and was being caught by the generic error handler.

Key Code Locations (commit `6f05be2c`)

cleveragents.cli.commands.actor_run.run() — positional name and prompt args, optional --config
cleveragents.cli.commands.actor_run._resolve_config_files() — registry resolution helper
cleveragents.cli.commands.actor.run() — same changes applied to duplicate
cleveragents.cli.commands.actor._resolve_config_files() — same helper

Test Coverage

Behave: 7 scenarios in features/actor_run_signature.feature covering positional args, config fallback, and error handling
Robot: 3 integration tests in robot/actor_run_signature.robot
Updated 25 existing test invocations in features/steps/actor_cli_run_steps.py and 2 in robot/helper_skill_actor_run.py to use new positional syntax

Quality Gates

Session	Result
lint	PASS
typecheck	PASS
unit_tests	PASS (11,462 scenarios)
integration_tests	PASS
coverage_report	PASS (97%)

PR

PR #1072 — Closes #901

## Implementation Notes ### Design Decisions (commit `6f05be2c`) 1. **Backward compatibility**: `--config/-c` is preserved as an optional flag. When provided, it takes precedence over positional name-based resolution. This ensures existing scripts and documentation using `--config` continue to work. 2. **Actor registry resolution**: Added `_resolve_config_files()` helper that imports `get_container` and looks up the actor by name from the registry. If the actor is not found, it prints an error and calls `typer.Exit(code=1)`. 3. **Dual implementation**: Both `actor_run.py` and `actor.py` were updated with identical changes since they contain duplicate `run()` commands. 4. **`typer.Exit` propagation**: Moved `_resolve_config_files()` call before the try/except block because `typer.Exit` inherits from `RuntimeError -> Exception` and was being caught by the generic error handler. ### Key Code Locations (commit `6f05be2c`) - `cleveragents.cli.commands.actor_run.run()` — positional `name` and `prompt` args, optional `--config` - `cleveragents.cli.commands.actor_run._resolve_config_files()` — registry resolution helper - `cleveragents.cli.commands.actor.run()` — same changes applied to duplicate - `cleveragents.cli.commands.actor._resolve_config_files()` — same helper ### Test Coverage - **Behave**: 7 scenarios in `features/actor_run_signature.feature` covering positional args, config fallback, and error handling - **Robot**: 3 integration tests in `robot/actor_run_signature.robot` - Updated 25 existing test invocations in `features/steps/actor_cli_run_steps.py` and 2 in `robot/helper_skill_actor_run.py` to use new positional syntax ### Quality Gates | Session | Result | |---|---| | lint | PASS | | typecheck | PASS | | unit_tests | PASS (11,462 scenarios) | | integration_tests | PASS | | coverage_report | PASS (97%) | ### PR PR #1072 — `Closes #901`

CoreRasurae added

and removed

labels

2026-03-19 14:58:34 +00:00

CoreRasurae referenced this issue

2026-03-19 21:55:35 +00:00

refactor(cli): align actor run signature with spec positional args #1072

CoreRasurae referenced this issue from a commit