UAT: `agents session create` missing `--max-cost` budget flag — CostBudgetService exists but has no CLI integration #3226

New issue

Open

opened 2026-04-05 08:02:12 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 08:02:12 +00:00

Owner

Background and Context

The CostBudgetService in src/cleveragents/application/services/cost_budget_service.py implements per-session cost budgets with configure_session_budget(session_id, max_cost_usd=...), but the agents session create CLI command does not expose any --max-cost or --budget flag to configure this budget at session creation time.

Current Behavior

src/cleveragents/cli/commands/session.py has a comment at line ~419:

# Cost budget (per-session budget cap, #584)

But no --max-cost or --budget option is defined on the session_create command. The CostBudgetService is implemented and wired into the DI container, but the CLI never calls configure_session_budget() with a user-provided budget.

This means:

Users cannot set per-session cost limits from the CLI
The CostBudgetService session budget feature is effectively inaccessible
The check_budget_hierarchy() method's session-level check will never trigger because no session budgets are ever configured via the CLI

Steps to reproduce:

Run agents session create --help
Observe: no --max-cost or --budget flag is available
Check session.py source — the # Cost budget comment exists but no implementation follows

Expected Behavior

Per the spec (docs/specification.md line 28601): "Per-session budgets: Aggregate limits across all plans in a session. Prevents a single interactive session from consuming excessive resources."

The agents session create command should accept a --max-cost <USD> flag that configures the per-session budget via CostBudgetService.configure_session_budget().

Acceptance Criteria

agents session create --max-cost <USD> flag is available and documented in --help
The flag calls CostBudgetService.configure_session_budget(session_id, max_cost_usd=<value>) at session creation time
agents session create --help output includes the --max-cost flag with a clear description
agents session show displays the configured budget and current utilization
Budget enforcement triggers correctly when the session cost exceeds the configured limit
Unit tests cover the new CLI flag and its integration with CostBudgetService

Supporting Information

What was tested:

Code analysis of src/cleveragents/application/services/cost_budget_service.py — configure_session_budget() method
Code analysis of src/cleveragents/cli/commands/session.py — session_create command
Searched for max_cost and budget in session.py

Code locations:

src/cleveragents/cli/commands/session.py — session_create command (missing --max-cost option)
src/cleveragents/application/services/cost_budget_service.py — configure_session_budget() (implemented but not called from CLI)

Impact:
Per-session cost budgets are completely inaccessible from the CLI. Users cannot prevent runaway costs in a single session. The CostBudgetService implementation is wasted.

Backlog note: This issue was discovered during autonomous operation
on milestone v3.6.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Metadata

Branch: fix/cli-session-create-max-cost-flag
Commit Message: fix(cli): add --max-cost budget flag to agents session create command
Milestone: None (backlog)
Parent Epic: #584

Subtasks

Add --max-cost option to session_create command in src/cleveragents/cli/commands/session.py
Wire the --max-cost value to CostBudgetService.configure_session_budget(session_id, max_cost_usd=...) at session creation time
Update agents session show to display configured budget and utilization
Add unit tests for the new --max-cost CLI flag and its integration with CostBudgetService
Add Behave scenario: features/cli/session_create_budget.feature covering --max-cost flag
Add Robot Framework integration test for session budget enforcement via CLI
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.
All nox stages pass
Coverage >= 97%

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

## Background and Context The `CostBudgetService` in `src/cleveragents/application/services/cost_budget_service.py` implements per-session cost budgets with `configure_session_budget(session_id, max_cost_usd=...)`, but the `agents session create` CLI command does not expose any `--max-cost` or `--budget` flag to configure this budget at session creation time. ## Current Behavior `src/cleveragents/cli/commands/session.py` has a comment at line ~419: ```python # Cost budget (per-session budget cap, #584) ``` But no `--max-cost` or `--budget` option is defined on the `session_create` command. The `CostBudgetService` is implemented and wired into the DI container, but the CLI never calls `configure_session_budget()` with a user-provided budget. This means: 1. Users cannot set per-session cost limits from the CLI 2. The `CostBudgetService` session budget feature is effectively inaccessible 3. The `check_budget_hierarchy()` method's session-level check will never trigger because no session budgets are ever configured via the CLI **Steps to reproduce:** 1. Run `agents session create --help` 2. Observe: no `--max-cost` or `--budget` flag is available 3. Check `session.py` source — the `# Cost budget` comment exists but no implementation follows ## Expected Behavior Per the spec (docs/specification.md line 28601): *"**Per-session budgets**: Aggregate limits across all plans in a session. Prevents a single interactive session from consuming excessive resources."* The `agents session create` command should accept a `--max-cost <USD>` flag that configures the per-session budget via `CostBudgetService.configure_session_budget()`. ## Acceptance Criteria - [ ] `agents session create --max-cost <USD>` flag is available and documented in `--help` - [ ] The flag calls `CostBudgetService.configure_session_budget(session_id, max_cost_usd=<value>)` at session creation time - [ ] `agents session create --help` output includes the `--max-cost` flag with a clear description - [ ] `agents session show` displays the configured budget and current utilization - [ ] Budget enforcement triggers correctly when the session cost exceeds the configured limit - [ ] Unit tests cover the new CLI flag and its integration with `CostBudgetService` ## Supporting Information **What was tested:** - Code analysis of `src/cleveragents/application/services/cost_budget_service.py` — `configure_session_budget()` method - Code analysis of `src/cleveragents/cli/commands/session.py` — `session_create` command - Searched for `max_cost` and `budget` in `session.py` **Code locations:** - `src/cleveragents/cli/commands/session.py` — `session_create` command (missing `--max-cost` option) - `src/cleveragents/application/services/cost_budget_service.py` — `configure_session_budget()` (implemented but not called from CLI) **Impact:** Per-session cost budgets are completely inaccessible from the CLI. Users cannot prevent runaway costs in a single session. The `CostBudgetService` implementation is wasted. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Metadata - **Branch**: `fix/cli-session-create-max-cost-flag` - **Commit Message**: `fix(cli): add --max-cost budget flag to agents session create command` - **Milestone**: None (backlog) - **Parent Epic**: #584 ## Subtasks - [ ] Add `--max-cost` option to `session_create` command in `src/cleveragents/cli/commands/session.py` - [ ] Wire the `--max-cost` value to `CostBudgetService.configure_session_budget(session_id, max_cost_usd=...)` at session creation time - [ ] Update `agents session show` to display configured budget and utilization - [ ] Add unit tests for the new `--max-cost` CLI flag and its integration with `CostBudgetService` - [ ] Add Behave scenario: `features/cli/session_create_budget.feature` covering `--max-cost` flag - [ ] Add Robot Framework integration test for session budget enforcement via CLI - [ ] 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. - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-05 08:07:56 +00:00

#584 feat(guardrails): implement Per-Session and Per-Org Cost Budgets

freemo added the

labels

2026-04-05 08:08:18 +00:00