feat(config): add config service with multi-level resolution #258

Closed
opened 2026-02-22 23:40:38 +00:00 by freemo · 2 comments
Owner

Metadata

  • Commit Message: feat(config): add config service with multi-level resolution
  • Branch: feature/m3-config-service

Background

ConfigService manages TOML file operations at ~/.cleveragents/config.toml with auto-creation. Multi-level resolution follows: CLI flag > env var > project-scoped > global config > default. A typed config key registry maps all keys from the spec catalog.

Acceptance Criteria

  • Implement ConfigService with TOML file management (~/.cleveragents/config.toml), read/write operations, and parent directory auto-creation.
  • Implement multi-level resolution chain: CLI flag > environment variable > project-scoped > global config > default. Each config get call returns the winning value plus the source level that provided it.
  • Add config key registry with typed entries: key name, Python type, default value, env var mapping (CLEVERAGENTS_*), project-scopability flag, and description. Register the complete catalog per spec (core.*, plan.*, provider.*, sandbox.*, context.*, index.*).
  • Wire config get output to display the resolution chain (which level provided the winning value) when --verbose is passed.
  • Add env var interpolation for all registered keys following the CLEVERAGENTS_<SECTION>_<KEY> convention.

Definition of Done

This issue is complete when:

  • All subtasks below 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 body should be appropriate in size for a commit message and relatively
    complete in describing what was done.
  • 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.

Subtasks

  • Implement ConfigService with TOML file management (~/.cleveragents/config.toml), read/write operations, and parent directory auto-creation.
  • Implement multi-level resolution chain: CLI flag > environment variable > project-scoped > global config > default. Each config get call returns the winning value plus the source level that provided it.
  • Add config key registry with typed entries: key name, Python type, default value, env var mapping (CLEVERAGENTS_*), project-scopability flag, and description. Register the complete catalog per spec (core.*, plan.*, provider.*, sandbox.*, context.*, index.*).
  • Wire config get output to display the resolution chain (which level provided the winning value) when --verbose is passed.
  • Add env var interpolation for all registered keys following the CLEVERAGENTS_<SECTION>_<KEY> convention.
  • Add validation that rejects unknown keys and type-mismatched values with actionable error messages.
  • Add docs/reference/config_resolution.md documenting the resolution chain, all config keys, their types, defaults, and env var mappings.
  • Tests (Behave): Add features/config_resolution.feature with scenarios for each resolution level, env var overrides, unknown key rejection, and type validation.
  • Tests (Robot): Add robot/config_resolution.robot for end-to-end config get/set with env var interactions.
  • Tests (ASV): Add benchmarks/config_resolution_bench.py for resolution chain performance.
  • Verify coverage >=97% via nox -s coverage_report.
  • Run nox (all default sessions, including benchmark).

Section: #### Section 3 Notes
Status: Open

## Metadata - **Commit Message**: `feat(config): add config service with multi-level resolution` - **Branch**: `feature/m3-config-service` ## Background `ConfigService` manages TOML file operations at `~/.cleveragents/config.toml` with auto-creation. Multi-level resolution follows: CLI flag > env var > project-scoped > global config > default. A typed config key registry maps all keys from the spec catalog. ## Acceptance Criteria - [ ] Implement `ConfigService` with TOML file management (`~/.cleveragents/config.toml`), read/write operations, and parent directory auto-creation. - [ ] Implement multi-level resolution chain: CLI flag > environment variable > project-scoped > global config > default. Each `config get` call returns the winning value plus the source level that provided it. - [ ] Add config key registry with typed entries: key name, Python type, default value, env var mapping (`CLEVERAGENTS_*`), project-scopability flag, and description. Register the complete catalog per spec (`core.*`, `plan.*`, `provider.*`, `sandbox.*`, `context.*`, `index.*`). - [ ] Wire `config get` output to display the resolution chain (which level provided the winning value) when `--verbose` is passed. - [ ] Add env var interpolation for all registered keys following the `CLEVERAGENTS_<SECTION>_<KEY>` convention. ## Definition of Done This issue is complete when: - All subtasks below 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 body should be appropriate in size for a commit message and relatively complete in describing what was done. - 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. ## Subtasks - [ ] Implement `ConfigService` with TOML file management (`~/.cleveragents/config.toml`), read/write operations, and parent directory auto-creation. - [ ] Implement multi-level resolution chain: CLI flag > environment variable > project-scoped > global config > default. Each `config get` call returns the winning value plus the source level that provided it. - [ ] Add config key registry with typed entries: key name, Python type, default value, env var mapping (`CLEVERAGENTS_*`), project-scopability flag, and description. Register the complete catalog per spec (`core.*`, `plan.*`, `provider.*`, `sandbox.*`, `context.*`, `index.*`). - [ ] Wire `config get` output to display the resolution chain (which level provided the winning value) when `--verbose` is passed. - [ ] Add env var interpolation for all registered keys following the `CLEVERAGENTS_<SECTION>_<KEY>` convention. - [ ] Add validation that rejects unknown keys and type-mismatched values with actionable error messages. - [ ] Add `docs/reference/config_resolution.md` documenting the resolution chain, all config keys, their types, defaults, and env var mappings. - [ ] Tests (Behave): Add `features/config_resolution.feature` with scenarios for each resolution level, env var overrides, unknown key rejection, and type validation. - [ ] Tests (Robot): Add `robot/config_resolution.robot` for end-to-end config get/set with env var interactions. - [ ] Tests (ASV): Add `benchmarks/config_resolution_bench.py` for resolution chain performance. - [ ] Verify coverage >=97% via `nox -s coverage_report`. - [ ] Run `nox` (all default sessions, including benchmark). **Section**: #### Section 3 Notes **Status**: Open
freemo added this to the v3.4.0 milestone 2026-02-22 23:40:38 +00:00
freemo self-assigned this 2026-02-22 23:40:38 +00:00
Author
Owner

Expected completion (Day 15 rebaseline): Day 22 / 2026-03-02

**Expected completion (Day 15 rebaseline):** Day 22 / 2026-03-02
freemo added the due date 2026-02-22 2026-02-23 18:41:50 +00:00
Author
Owner

Implementation Notes — A9.service: Config Service with Multi-Level Resolution

  • 2026-02-23 [Jeff]: Implemented ConfigService in src/cleveragents/application/services/config_service.py with:
    • Five-level resolution chain: CLI flag > env var > project-scoped > global config > default
    • Typed config key registry with 24 entries across 6 sections: core.* (7), plan.* (3), provider.* (4), sandbox.* (3), context.* (3), index.* (4)
    • TOML file management (~/.cleveragents/config.toml) with auto-created parent directories via tomlkit
    • ResolvedValue return type includes winning value, source level, and optional verbose chain
    • Env var interpolation following CLEVERAGENTS_<SECTION>_<KEY> convention
    • Validation: unknown keys raise ValueError with sample of valid keys; type mismatches raise TypeError with actionable messages
    • Boolean coercion from string: true/false, 1/0, yes/no (case-insensitive)
  • 2026-02-23 [Jeff]: Added docs/reference/config_resolution.md documenting all 24 config keys with types, defaults, env var mappings, and precedence rules
  • 2026-02-23 [Jeff]: Added features/config_resolution.feature with 31 Behave scenarios covering every resolution level, env var overrides, type coercion, unknown key rejection, TOML roundtrips, and verbose chain output
  • 2026-02-23 [Jeff]: Added robot/config_resolution.robot with 8 Robot Framework end-to-end tests exercising default/global/env/CLI resolution, unknown key rejection, type coercion, and env var convention
  • 2026-02-23 [Jeff]: Added benchmarks/config_resolution_bench.py with 6 ASV benchmark suites for resolution performance at each level, bulk operations, and validation throughput
  • 2026-02-23 [Jeff]: Exported ConfigService, ConfigEntry, ConfigLevel, ResolvedValue from application.services.__init__; updated vulture whitelist for new public API

(Migrated from docs/implementation-notes.md)

## Implementation Notes — A9.service: Config Service with Multi-Level Resolution - **2026-02-23** [Jeff]: Implemented `ConfigService` in `src/cleveragents/application/services/config_service.py` with: - Five-level resolution chain: CLI flag > env var > project-scoped > global config > default - Typed config key registry with 24 entries across 6 sections: `core.*` (7), `plan.*` (3), `provider.*` (4), `sandbox.*` (3), `context.*` (3), `index.*` (4) - TOML file management (`~/.cleveragents/config.toml`) with auto-created parent directories via `tomlkit` - `ResolvedValue` return type includes winning value, source level, and optional verbose chain - Env var interpolation following `CLEVERAGENTS_<SECTION>_<KEY>` convention - Validation: unknown keys raise `ValueError` with sample of valid keys; type mismatches raise `TypeError` with actionable messages - Boolean coercion from string: true/false, 1/0, yes/no (case-insensitive) - **2026-02-23** [Jeff]: Added `docs/reference/config_resolution.md` documenting all 24 config keys with types, defaults, env var mappings, and precedence rules - **2026-02-23** [Jeff]: Added `features/config_resolution.feature` with 31 Behave scenarios covering every resolution level, env var overrides, type coercion, unknown key rejection, TOML roundtrips, and verbose chain output - **2026-02-23** [Jeff]: Added `robot/config_resolution.robot` with 8 Robot Framework end-to-end tests exercising default/global/env/CLI resolution, unknown key rejection, type coercion, and env var convention - **2026-02-23** [Jeff]: Added `benchmarks/config_resolution_bench.py` with 6 ASV benchmark suites for resolution performance at each level, bulk operations, and validation throughput - **2026-02-23** [Jeff]: Exported `ConfigService`, `ConfigEntry`, `ConfigLevel`, `ResolvedValue` from `application.services.__init__`; updated vulture whitelist for new public API *(Migrated from `docs/implementation-notes.md`)*
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

2026-02-22

Reference
cleveragents/cleveragents-core#258
No description provided.