UAT: Budget environment variable names in `Settings` don't match spec — `CLEVERAGENTS_BUDGET_PER_PLAN` should be `CLEVERAGENTS_PLAN_BUDGET`, `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD` should be `CLEVERAGENTS_PLAN_BUDGET_WARN` #4111

New issue

Open

opened 2026-04-06 10:24:37 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 10:24:37 +00:00

Owner

Metadata

Branch: fix/providers-budget-env-var-names
Commit Message: fix(config): align budget environment variable names with specification
Milestone: (none — backlog)
Parent Epic: #3365 (Epic: Additional LLM Provider Integrations — Cohere, Groq, Together AI, and Provider Abstraction)

Backlog note: This issue was discovered during autonomous UAT testing
on the LLM Provider Integration feature area. It does not block milestone
completion and has been placed in the backlog for human review and future
milestone assignment.

Bug Report

What was tested: Budget configuration environment variable names against the specification

Expected behavior (from spec, section "Configuration Reference", lines 30577-30579):

Config Key	Env Var (spec)	Description
`plan.budget.per-plan`	`CLEVERAGENTS_PLAN_BUDGET`	Max USD per plan
`plan.budget.per-session`	`CLEVERAGENTS_SESSION_BUDGET`	Max USD per session
`plan.budget.warn-threshold`	`CLEVERAGENTS_PLAN_BUDGET_WARN`	Warning threshold fraction

Actual behavior (from code analysis):

src/cleveragents/config/settings.py uses different environment variable names:

Config Field	Env Var (implementation)	Spec Env Var
`budget_per_plan`	`CLEVERAGENTS_BUDGET_PER_PLAN`	`CLEVERAGENTS_PLAN_BUDGET` ❌
`budget_per_day`	`CLEVERAGENTS_BUDGET_PER_DAY`	(not in spec)
`budget_warning_threshold`	`CLEVERAGENTS_BUDGET_WARNING_THRESHOLD`	`CLEVERAGENTS_PLAN_BUDGET_WARN` ❌

The spec also defines plan.budget.per-session → CLEVERAGENTS_SESSION_BUDGET, but the implementation uses session_max_cost_usd → CLEVERAGENTS_SESSION_MAX_COST_USD.

Code location:

src/cleveragents/config/settings.py — lines 248-261 (budget_per_plan, budget_per_day, budget_warning_threshold)
Spec: docs/specification.md lines 30577-30579

Impact: Users following the spec documentation to set CLEVERAGENTS_PLAN_BUDGET will find their budget limit is silently ignored. The actual env var CLEVERAGENTS_BUDGET_PER_PLAN is not documented in the spec.

Steps to reproduce:

Set CLEVERAGENTS_PLAN_BUDGET=1.00 (as documented in spec)
Run a plan that costs more than $1.00
Observe: budget limit is not enforced (env var is not read)
Set CLEVERAGENTS_BUDGET_PER_PLAN=1.00 (undocumented)
Observe: budget limit is now enforced

Severity: Medium — users following the spec documentation cannot configure budget limits. This is a user-facing configuration mismatch.

Subtasks

Add CLEVERAGENTS_PLAN_BUDGET as an alias for CLEVERAGENTS_BUDGET_PER_PLAN in Settings
Add CLEVERAGENTS_PLAN_BUDGET_WARN as an alias for CLEVERAGENTS_BUDGET_WARNING_THRESHOLD
Add CLEVERAGENTS_SESSION_BUDGET as an alias for CLEVERAGENTS_SESSION_MAX_COST_USD
Update documentation to reflect the canonical env var names
Add Behave scenarios testing budget configuration via spec-documented env vars
Verify nox -e typecheck passes
Run nox (all default sessions)

Definition of Done

CLEVERAGENTS_PLAN_BUDGET env var is recognized and enforces per-plan budget
CLEVERAGENTS_PLAN_BUDGET_WARN env var is recognized and sets warning threshold
CLEVERAGENTS_SESSION_BUDGET env var is recognized and enforces per-session budget
All existing budget tests continue to pass
New Behave scenarios cover spec-documented env var names
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/providers-budget-env-var-names` - **Commit Message**: `fix(config): align budget environment variable names with specification` - **Milestone**: *(none — backlog)* - **Parent Epic**: #3365 (Epic: Additional LLM Provider Integrations — Cohere, Groq, Together AI, and Provider Abstraction) > **Backlog note:** This issue was discovered during autonomous UAT testing > on the LLM Provider Integration feature area. It does not block milestone > completion and has been placed in the backlog for human review and future > milestone assignment. ## Bug Report **What was tested:** Budget configuration environment variable names against the specification **Expected behavior (from spec, section "Configuration Reference", lines 30577-30579):** | Config Key | Env Var (spec) | Description | |------------|----------------|-------------| | `plan.budget.per-plan` | `CLEVERAGENTS_PLAN_BUDGET` | Max USD per plan | | `plan.budget.per-session` | `CLEVERAGENTS_SESSION_BUDGET` | Max USD per session | | `plan.budget.warn-threshold` | `CLEVERAGENTS_PLAN_BUDGET_WARN` | Warning threshold fraction | **Actual behavior (from code analysis):** `src/cleveragents/config/settings.py` uses different environment variable names: | Config Field | Env Var (implementation) | Spec Env Var | |--------------|--------------------------|--------------| | `budget_per_plan` | `CLEVERAGENTS_BUDGET_PER_PLAN` | `CLEVERAGENTS_PLAN_BUDGET` ❌ | | `budget_per_day` | `CLEVERAGENTS_BUDGET_PER_DAY` | *(not in spec)* | | `budget_warning_threshold` | `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD` | `CLEVERAGENTS_PLAN_BUDGET_WARN` ❌ | The spec also defines `plan.budget.per-session` → `CLEVERAGENTS_SESSION_BUDGET`, but the implementation uses `session_max_cost_usd` → `CLEVERAGENTS_SESSION_MAX_COST_USD`. **Code location:** - `src/cleveragents/config/settings.py` — lines 248-261 (`budget_per_plan`, `budget_per_day`, `budget_warning_threshold`) - Spec: `docs/specification.md` lines 30577-30579 **Impact:** Users following the spec documentation to set `CLEVERAGENTS_PLAN_BUDGET` will find their budget limit is silently ignored. The actual env var `CLEVERAGENTS_BUDGET_PER_PLAN` is not documented in the spec. **Steps to reproduce:** 1. Set `CLEVERAGENTS_PLAN_BUDGET=1.00` (as documented in spec) 2. Run a plan that costs more than $1.00 3. Observe: budget limit is not enforced (env var is not read) 4. Set `CLEVERAGENTS_BUDGET_PER_PLAN=1.00` (undocumented) 5. Observe: budget limit is now enforced **Severity:** Medium — users following the spec documentation cannot configure budget limits. This is a user-facing configuration mismatch. ## Subtasks - [ ] Add `CLEVERAGENTS_PLAN_BUDGET` as an alias for `CLEVERAGENTS_BUDGET_PER_PLAN` in `Settings` - [ ] Add `CLEVERAGENTS_PLAN_BUDGET_WARN` as an alias for `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD` - [ ] Add `CLEVERAGENTS_SESSION_BUDGET` as an alias for `CLEVERAGENTS_SESSION_MAX_COST_USD` - [ ] Update documentation to reflect the canonical env var names - [ ] Add Behave scenarios testing budget configuration via spec-documented env vars - [ ] Verify `nox -e typecheck` passes - [ ] Run `nox` (all default sessions) ## Definition of Done - [ ] `CLEVERAGENTS_PLAN_BUDGET` env var is recognized and enforces per-plan budget - [ ] `CLEVERAGENTS_PLAN_BUDGET_WARN` env var is recognized and sets warning threshold - [ ] `CLEVERAGENTS_SESSION_BUDGET` env var is recognized and enforces per-session budget - [ ] All existing budget tests continue to pass - [ ] New Behave scenarios cover spec-documented env var names - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:24:50 +00:00

#3365 Epic: Additional LLM Provider Integrations — Cohere, Groq, Together AI, and Provider Abstraction

freemo referenced this issue

2026-04-06 10:32:27 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:35:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added this to the v3.2.0 milestone

2026-04-06 18:06:56 +00:00

freemo removed this from the v3.2.0 milestone

2026-04-06 22:27:29 +00:00

freemo commented

2026-04-06 22:27:45 +00:00

Author

Owner

This issue has been moved to the backlog as part of an aggressive grooming of the v3.2.0 milestone. It has been deemed non-critical for the minimal viability of the milestone and will be addressed in a future release.