refactor(agents): extract _create_initial_state and _get_config helpers to eliminate duplicate invocation setup in PlanGenerationGraph and AutoDebugAgent #3274

New issue

Open

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

freemo commented

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

Owner

Metadata

Branch: refactor/agents-extract-invocation-helpers
Commit Message: refactor(agents): extract _create_initial_state and _get_config helpers to eliminate duplicate invocation setup
Milestone: (none — backlog)
Parent Epic: #368

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

Background and Context

The invoke, ainvoke, and stream methods of PlanGenerationGraph and AutoDebugAgent each independently construct identical initial-state and config dictionaries. This violates the DRY principle and the Single Responsibility Principle: any future change to the state schema (e.g., adding a new field, renaming a key, or changing a default) must be applied in three separate places per class, creating a high risk of divergence and silent inconsistencies.

The affected locations are:

File	Class	Lines
`src/cleveragents/agents/graphs/plan_generation.py`	`PlanGenerationGraph.invoke`	664–686
`src/cleveragents/agents/graphs/plan_generation.py`	`PlanGenerationGraph.ainvoke`	713–735
`src/cleveragents/agents/graphs/plan_generation.py`	`PlanGenerationGraph.stream`	761–783
`src/cleveragents/agents/graphs/auto_debug.py`	`AutoDebugAgent.invoke`	307–312
`src/cleveragents/agents/graphs/auto_debug.py`	`AutoDebugAgent.ainvoke`	314–319
`src/cleveragents/agents/graphs/auto_debug.py`	`AutoDebugAgent.stream`	321–328

Current Behavior

The initial-state dictionary (with fields such as project, plan, contexts, context_summary, actor_name, actor_options, actor_graph_descriptor, actor_initial_context, prompt, analyzed_requirements, generated_changes, validation_result, retry_count, error) is constructed inline in each of the three invocation methods of PlanGenerationGraph. Similarly, the config fallback (config = config or {"configurable": {"thread_id": "auto-debug"}}) is repeated in each of the three invocation methods of AutoDebugAgent.

Expected Behavior

Each class should expose private helper methods:

PlanGenerationGraph._create_initial_state(project, plan, contexts, actor_context) -> dict[str, Any]
AutoDebugAgent._get_config(config: dict | None) -> dict

The invoke, ainvoke, and stream methods delegate to these helpers, ensuring the state/config construction logic lives in exactly one place per class.

Acceptance Criteria

PlanGenerationGraph._create_initial_state encapsulates all initial-state dictionary construction; invoke, ainvoke, and stream call it instead of duplicating the dict literal.
AutoDebugAgent._get_config encapsulates the config fallback logic; invoke, ainvoke, and stream call it instead of duplicating the expression.
No functional change to observable behaviour — all existing BDD scenarios pass unchanged.
The helper methods are covered by BDD unit scenarios verifying their output for representative inputs (including actor_context=None and config=None).
Static type annotations are present on all new methods; mypy/pyright reports no new errors.

Supporting Information

Bug reported by ca-bug-hunter (Bug Hunting supervisor) during consistency sweep.
Related pattern: SOLID SRP and DRY principle violations as described in CONTRIBUTING.md § Code Style & Best Practices.
Files: src/cleveragents/agents/graphs/plan_generation.py, src/cleveragents/agents/graphs/auto_debug.py.

Subtasks

Add PlanGenerationGraph._create_initial_state private helper method with full type annotations
Refactor PlanGenerationGraph.invoke to call _create_initial_state
Refactor PlanGenerationGraph.ainvoke to call _create_initial_state
Refactor PlanGenerationGraph.stream to call _create_initial_state
Add AutoDebugAgent._get_config private helper method with full type annotations
Refactor AutoDebugAgent.invoke to call _get_config
Refactor AutoDebugAgent.ainvoke to call _get_config
Refactor AutoDebugAgent.stream to call _get_config
Tests (Behave): Add BDD scenarios for _create_initial_state (with and without actor_context)
Tests (Behave): Add BDD scenarios for _get_config (with None and explicit config)
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: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `refactor/agents-extract-invocation-helpers` - **Commit Message**: `refactor(agents): extract _create_initial_state and _get_config helpers to eliminate duplicate invocation setup` - **Milestone**: *(none — backlog)* - **Parent Epic**: #368 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context The `invoke`, `ainvoke`, and `stream` methods of `PlanGenerationGraph` and `AutoDebugAgent` each independently construct identical initial-state and config dictionaries. This violates the DRY principle and the Single Responsibility Principle: any future change to the state schema (e.g., adding a new field, renaming a key, or changing a default) must be applied in three separate places per class, creating a high risk of divergence and silent inconsistencies. The affected locations are: | File | Class | Lines | |---|---|---| | `src/cleveragents/agents/graphs/plan_generation.py` | `PlanGenerationGraph.invoke` | 664–686 | | `src/cleveragents/agents/graphs/plan_generation.py` | `PlanGenerationGraph.ainvoke` | 713–735 | | `src/cleveragents/agents/graphs/plan_generation.py` | `PlanGenerationGraph.stream` | 761–783 | | `src/cleveragents/agents/graphs/auto_debug.py` | `AutoDebugAgent.invoke` | 307–312 | | `src/cleveragents/agents/graphs/auto_debug.py` | `AutoDebugAgent.ainvoke` | 314–319 | | `src/cleveragents/agents/graphs/auto_debug.py` | `AutoDebugAgent.stream` | 321–328 | ## Current Behavior The initial-state dictionary (with fields such as `project`, `plan`, `contexts`, `context_summary`, `actor_name`, `actor_options`, `actor_graph_descriptor`, `actor_initial_context`, `prompt`, `analyzed_requirements`, `generated_changes`, `validation_result`, `retry_count`, `error`) is constructed inline in each of the three invocation methods of `PlanGenerationGraph`. Similarly, the config fallback (`config = config or {"configurable": {"thread_id": "auto-debug"}}`) is repeated in each of the three invocation methods of `AutoDebugAgent`. ## Expected Behavior Each class should expose private helper methods: - `PlanGenerationGraph._create_initial_state(project, plan, contexts, actor_context) -> dict[str, Any]` - `AutoDebugAgent._get_config(config: dict | None) -> dict` The `invoke`, `ainvoke`, and `stream` methods delegate to these helpers, ensuring the state/config construction logic lives in exactly one place per class. ## Acceptance Criteria - [ ] `PlanGenerationGraph._create_initial_state` encapsulates all initial-state dictionary construction; `invoke`, `ainvoke`, and `stream` call it instead of duplicating the dict literal. - [ ] `AutoDebugAgent._get_config` encapsulates the config fallback logic; `invoke`, `ainvoke`, and `stream` call it instead of duplicating the expression. - [ ] No functional change to observable behaviour — all existing BDD scenarios pass unchanged. - [ ] The helper methods are covered by BDD unit scenarios verifying their output for representative inputs (including `actor_context=None` and `config=None`). - [ ] Static type annotations are present on all new methods; `mypy`/`pyright` reports no new errors. ## Supporting Information - Bug reported by ca-bug-hunter (Bug Hunting supervisor) during consistency sweep. - Related pattern: SOLID SRP and DRY principle violations as described in `CONTRIBUTING.md` § Code Style & Best Practices. - Files: `src/cleveragents/agents/graphs/plan_generation.py`, `src/cleveragents/agents/graphs/auto_debug.py`. ## Subtasks - [ ] Add `PlanGenerationGraph._create_initial_state` private helper method with full type annotations - [ ] Refactor `PlanGenerationGraph.invoke` to call `_create_initial_state` - [ ] Refactor `PlanGenerationGraph.ainvoke` to call `_create_initial_state` - [ ] Refactor `PlanGenerationGraph.stream` to call `_create_initial_state` - [ ] Add `AutoDebugAgent._get_config` private helper method with full type annotations - [ ] Refactor `AutoDebugAgent.invoke` to call `_get_config` - [ ] Refactor `AutoDebugAgent.ainvoke` to call `_get_config` - [ ] Refactor `AutoDebugAgent.stream` to call `_get_config` - [ ] Tests (Behave): Add BDD scenarios for `_create_initial_state` (with and without `actor_context`) - [ ] Tests (Behave): Add BDD scenarios for `_get_config` (with `None` and explicit config) - [ ] 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: Bug Hunting | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 09:07:11 +00:00

#368 Epic: Subplans & Parallelism

freemo added this to the v3.8.0 milestone

2026-04-05 09:14:20 +00:00

freemo removed this from the v3.8.0 milestone

2026-04-07 00:11:14 +00:00