BUG: [type-safety] Improve type safety in agents module with more specific types #3449

New issue

Open

opened 2026-04-05 17:16:32 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 17:16:32 +00:00

Owner

Metadata

Branch: bugfix/agents-type-safety-specific-types
Commit Message: fix(agents): replace dict[str, Any] with specific TypedDict types in agents module
Milestone: Backlog
Parent Epic: #2810

Background

The agents module (auto_debug.py, context_analysis.py, plan_generation.py) uses dict[str, Any] for method arguments and return types in several locations. This reduces readability, weakens static analysis, and makes it harder to catch type errors at development time. Replacing these with more specific TypedDict definitions (or other appropriate concrete types) will improve maintainability and help the nox -e typecheck CI gate surface real type errors rather than silently accepting Any.

Affected Locations

File	Class	Lines	Issue
`src/cleveragents/agents/graphs/auto_debug.py`	`AutoDebugAgent`	285, 290, 295, 300	`config: dict[str, Any] \| None` parameter
`src/cleveragents/agents/graphs/context_analysis.py`	`ContextAnalysisAgent`	411, 416, 421, 426	`config: dict[str, Any] \| None` parameter
`src/cleveragents/agents/graphs/plan_generation.py`	`PlanGenerationGraph`	630, 645, 661	`-> dict[str, Any]` return type

Evidence

# src/cleveragents/agents/graphs/auto_debug.py:285
def invoke(
    self, input_state: AutoDebugState, config: dict[str, Any] | None = None
) -> AutoDebugState:

# src/cleveragents/agents/graphs/context_analysis.py:411
def invoke(
    self, input_state: ContextAnalysisState, config: dict[str, Any] | None = None
) -> ContextAnalysisState:

# src/cleveragents/agents/graphs/plan_generation.py:630
def invoke(
    self,
    project: Project,
    plan: Plan,
    contexts: list[Context],
    thread_id: str = "default",
    actor_context: ActorInvocationContext | None = None,
) -> dict[str, Any]:

Subtasks

Audit all dict[str, Any] usages in auto_debug.py, context_analysis.py, and plan_generation.py
Define appropriate TypedDict classes (or use existing domain types) for the config parameter pattern used in invoke() methods
Define a concrete return TypedDict (or existing domain type) to replace -> dict[str, Any] in PlanGenerationGraph.invoke()
Update all affected method signatures with the new specific types
Write Behave unit tests (in features/) covering the updated type contracts
Verify nox -e typecheck passes with no new suppressions
Verify nox -e unit_tests passes
Verify nox -e coverage_report reports ≥ 97%

Definition of Done

All subtasks above are checked
No dict[str, Any] remains for the identified locations
No # type: ignore or type suppression added
Commit pushed to bugfix/agents-type-safety-specific-types with message: fix(agents): replace dict[str, Any] with specific TypedDict types in agents module
PR opened, linked to this issue, and merged
All nox stages pass
Coverage >= 97%

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

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `bugfix/agents-type-safety-specific-types` - **Commit Message**: `fix(agents): replace dict[str, Any] with specific TypedDict types in agents module` - **Milestone**: Backlog - **Parent Epic**: #2810 ## Background The agents module (`auto_debug.py`, `context_analysis.py`, `plan_generation.py`) uses `dict[str, Any]` for method arguments and return types in several locations. This reduces readability, weakens static analysis, and makes it harder to catch type errors at development time. Replacing these with more specific `TypedDict` definitions (or other appropriate concrete types) will improve maintainability and help the `nox -e typecheck` CI gate surface real type errors rather than silently accepting `Any`. ### Affected Locations | File | Class | Lines | Issue | |------|-------|-------|-------| | `src/cleveragents/agents/graphs/auto_debug.py` | `AutoDebugAgent` | 285, 290, 295, 300 | `config: dict[str, Any] \| None` parameter | | `src/cleveragents/agents/graphs/context_analysis.py` | `ContextAnalysisAgent` | 411, 416, 421, 426 | `config: dict[str, Any] \| None` parameter | | `src/cleveragents/agents/graphs/plan_generation.py` | `PlanGenerationGraph` | 630, 645, 661 | `-> dict[str, Any]` return type | ### Evidence ```python # src/cleveragents/agents/graphs/auto_debug.py:285 def invoke( self, input_state: AutoDebugState, config: dict[str, Any] | None = None ) -> AutoDebugState: ``` ```python # src/cleveragents/agents/graphs/context_analysis.py:411 def invoke( self, input_state: ContextAnalysisState, config: dict[str, Any] | None = None ) -> ContextAnalysisState: ``` ```python # src/cleveragents/agents/graphs/plan_generation.py:630 def invoke( self, project: Project, plan: Plan, contexts: list[Context], thread_id: str = "default", actor_context: ActorInvocationContext | None = None, ) -> dict[str, Any]: ``` ## Subtasks - [ ] Audit all `dict[str, Any]` usages in `auto_debug.py`, `context_analysis.py`, and `plan_generation.py` - [ ] Define appropriate `TypedDict` classes (or use existing domain types) for the `config` parameter pattern used in `invoke()` methods - [ ] Define a concrete return `TypedDict` (or existing domain type) to replace `-> dict[str, Any]` in `PlanGenerationGraph.invoke()` - [ ] Update all affected method signatures with the new specific types - [ ] Write Behave unit tests (in `features/`) covering the updated type contracts - [ ] Verify `nox -e typecheck` passes with no new suppressions - [ ] Verify `nox -e unit_tests` passes - [ ] Verify `nox -e coverage_report` reports ≥ 97% ## Definition of Done - [ ] All subtasks above are checked - [ ] No `dict[str, Any]` remains for the identified locations - [ ] No `# type: ignore` or type suppression added - [ ] Commit pushed to `bugfix/agents-type-safety-specific-types` with message: `fix(agents): replace dict[str, Any] with specific TypedDict types in agents module` - [ ] PR opened, linked to this issue, and merged - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 17:16:50 +00:00

#2810 Epic: CI Quality Gates Restoration — Restore All 11 CI Jobs to Passing on Master

freemo added this to the v3.7.0 milestone

2026-04-05 17:19:38 +00:00

freemo referenced this issue

2026-04-05 17:19:48 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 17:22:50 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo removed this from the v3.7.0 milestone