cleveragents/cleveragents-core

Fork 3

UAT: `docs/reference/cost_controls.md` missing documentation for new session/org budget settings (`CLEVERAGENTS_SESSION_MAX_COST_USD`, `CLEVERAGENTS_ORG_MAX_COST_USD`, `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD`) #5617

New issue

Open

opened 2026-04-09 07:50:03 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 07:50:03 +00:00

Owner

Bug Report

Feature Area: cost-session-budgets-safety-profiles
Severity: Low — documentation gap; new v3.6.0 settings are not documented

What Was Tested

Comparison of docs/reference/cost_controls.md against src/cleveragents/config/settings.py for the new session/org budget settings.

Expected Behavior

The docs/reference/cost_controls.md should document all configuration keys for cost controls, including the new v3.6.0 session and org budget settings.

Actual Behavior (from code analysis)

docs/reference/cost_controls.md — Configuration Keys table:

Key	Env Variable	Type	Default	Description
`budget_per_plan`	`CLEVERAGENTS_BUDGET_PER_PLAN`	`float \| None`	`None`	Max USD spend per plan execution
`budget_per_day`	`CLEVERAGENTS_BUDGET_PER_DAY`	`float \| None`	`None`	Max USD spend per calendar day
`fallback_providers`	`CLEVERAGENTS_FALLBACK_PROVIDERS`	`list[str]`	`[]`	Ordered provider fallback list

Missing from documentation (present in src/cleveragents/config/settings.py):

Key	Env Variable	Type	Default	Description
`session_max_cost_usd`	`CLEVERAGENTS_SESSION_MAX_COST_USD`	`float \| None`	`None`	Max USD spend per session
`org_max_cost_usd`	`CLEVERAGENTS_ORG_MAX_COST_USD`	`float \| None`	`None`	Max USD spend per org
`budget_warning_threshold`	`CLEVERAGENTS_BUDGET_WARNING_THRESHOLD`	`float`	`0.8`	Utilization ratio for BUDGET_WARNING event

Code Locations

docs/reference/cost_controls.md — Configuration Keys table (missing 3 new settings)
src/cleveragents/config/settings.py — session_max_cost_usd, org_max_cost_usd, budget_warning_threshold fields

Impact

Operators cannot discover the new session/org budget configuration options from the documentation. They would need to read the source code to find CLEVERAGENTS_SESSION_MAX_COST_USD and CLEVERAGENTS_ORG_MAX_COST_USD.

Fix

Update docs/reference/cost_controls.md to add the three missing configuration keys and update the examples section with session/org budget examples.

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

## Bug Report **Feature Area**: cost-session-budgets-safety-profiles **Severity**: Low — documentation gap; new v3.6.0 settings are not documented --- ## What Was Tested Comparison of `docs/reference/cost_controls.md` against `src/cleveragents/config/settings.py` for the new session/org budget settings. ## Expected Behavior The `docs/reference/cost_controls.md` should document all configuration keys for cost controls, including the new v3.6.0 session and org budget settings. ## Actual Behavior (from code analysis) `docs/reference/cost_controls.md` — Configuration Keys table: | Key | Env Variable | Type | Default | Description | |-----|-------------|------|---------|-------------| | `budget_per_plan` | `CLEVERAGENTS_BUDGET_PER_PLAN` | `float \| None` | `None` | Max USD spend per plan execution | | `budget_per_day` | `CLEVERAGENTS_BUDGET_PER_DAY` | `float \| None` | `None` | Max USD spend per calendar day | | `fallback_providers` | `CLEVERAGENTS_FALLBACK_PROVIDERS` | `list[str]` | `[]` | Ordered provider fallback list | **Missing from documentation** (present in `src/cleveragents/config/settings.py`): | Key | Env Variable | Type | Default | Description | |-----|-------------|------|---------|-------------| | `session_max_cost_usd` | `CLEVERAGENTS_SESSION_MAX_COST_USD` | `float \| None` | `None` | Max USD spend per session | | `org_max_cost_usd` | `CLEVERAGENTS_ORG_MAX_COST_USD` | `float \| None` | `None` | Max USD spend per org | | `budget_warning_threshold` | `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD` | `float` | `0.8` | Utilization ratio for BUDGET_WARNING event | ## Code Locations - `docs/reference/cost_controls.md` — Configuration Keys table (missing 3 new settings) - `src/cleveragents/config/settings.py` — `session_max_cost_usd`, `org_max_cost_usd`, `budget_warning_threshold` fields ## Impact Operators cannot discover the new session/org budget configuration options from the documentation. They would need to read the source code to find `CLEVERAGENTS_SESSION_MAX_COST_USD` and `CLEVERAGENTS_ORG_MAX_COST_USD`. ## Fix Update `docs/reference/cost_controls.md` to add the three missing configuration keys and update the examples section with session/org budget examples. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 07:50:22 +00:00

HAL9000 added this to the v3.6.0 milestone

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

HAL9000 commented

2026-04-09 07:57:06 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 added

and removed

labels

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

HAL9000 referenced this issue

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

[AUTO-PROJ-OWN] Project Owner Report (Cycle 27) #5570

HAL9000 referenced this issue

2026-04-09 08:13:30 +00:00

[AUTO-IMP-POOL] Implementation Pool Tracking (Cycle 4) #5638

HAL9000 added a new dependency

2026-04-09 08:27:49 +00:00

#5178 EPIC: Cost & Session Budget Enforcement — Spending Limits & Safety Profiles (v3.6.0)

HAL9000 commented

2026-04-09 08:30:51 +00:00

Author

Owner

Hierarchical Compliance Fix: This issue was detected as an orphan (no parent Epic).

Solution: Linked to Epic #5178 (Cost & Session Budget Enforcement — Spending Limits & Safety Profiles) as cost controls documentation is part of the budget enforcement scope.

Hierarchy: Issue #5617 → Epic #5178 → Legendary #4945

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: This issue was detected as an orphan (no parent Epic). **Solution**: Linked to Epic #5178 (Cost & Session Budget Enforcement — Spending Limits & Safety Profiles) as cost controls documentation is part of the budget enforcement scope. **Hierarchy**: Issue #5617 → Epic #5178 → Legendary #4945 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 08:31:57 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 12) #5422