cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [type-safety] Agent processing returns inconsistent types violating static type checking requirements #7220

New issue

Open

opened 2026-04-10 09:15:24 +00:00 by HAL9000 · 3 comments

HAL9000 commented

2026-04-10 09:15:24 +00:00

Owner

Background and Context

The process() method of SimpleToolAgent in src/cleveragents/reactive/stream_router.py is annotated to return Any and uses # type: ignore[override] to suppress Pyright errors. Different operations dispatched through this method can return values of entirely different types (strings, ints, dicts, etc.), but downstream code such as _create_agent_mapper() assumes string results. This violates the project's mandatory static typing requirements (CONTRIBUTING.md: "Full type annotations everywhere. Never use # type: ignore or any suppression mechanism. Pyright runs in CI — must pass.").

Current Behavior

def process(
    self,
    content: Any,
    metadata: dict[str, Any] | None = None,
    context: dict[str, Any] | None = None,
) -> Any:  # type: ignore[override]
    # ... processing ...
    return fn(content, meta, ctx)  # Could return any type

The return type is Any, which defeats Pyright's ability to catch downstream type errors at static analysis time.
The # type: ignore[override] suppression hides a real type contract violation — the override does not honour the parent class's return type contract.
Downstream callers (e.g. _create_agent_mapper()) assume the result is a str, but the actual return type is unconstrained.
Different operations dispatched through fn(content, meta, ctx) can return str, int, dict, or other types, causing silent type mismatches at runtime.

Expected Behavior

SimpleToolAgent.process() must have a concrete, specific return type annotation (e.g. str, a Protocol, or a properly bounded TypeVar) that accurately reflects what all dispatched operations return.
The # type: ignore[override] suppression must be removed; the override must satisfy the parent class's type contract.
All operations dispatched through process() must return a consistently typed value.
nox -s typecheck must pass with zero errors and zero suppressions after the fix.

Acceptance Criteria

SimpleToolAgent.process() return type is changed from Any to a specific, accurate type annotation
The # type: ignore[override] comment is removed
All operations dispatched through fn(content, meta, ctx) are verified to return the declared type
Downstream callers (e.g. _create_agent_mapper()) are updated if needed to reflect the correct type contract
nox -s typecheck passes with zero errors and zero # type: ignore suppressions
BDD scenarios cover the type contract for process() return values
All nox stages pass; coverage ≥ 97%

Supporting Information

File: src/cleveragents/reactive/stream_router.py
Function: SimpleToolAgent.process()
Lines: 180–220
Severity: Medium — code quality / static type safety violation
Likelihood: High — occurs whenever agents are invoked
Impact: Runtime type errors and violations of the project's static typing requirements; downstream code silently receives wrong types
Suggested Fix: Define a proper return type contract (e.g. str or a bounded Protocol/TypeVar), ensure all dispatched operations return that type, and remove the # type: ignore[override] suppression
Reference: CONTRIBUTING.md §"Type Safety" — "Full type annotations everywhere. Never use # type: ignore or any suppression mechanism."

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

Metadata

Branch: bugfix/reactive-simple-tool-agent-process-return-type
Commit Message: fix(reactive): replace Any return type and remove type: ignore suppression in SimpleToolAgent.process()
Milestone: (none — backlog)
Parent Epic: #7052

Subtasks

Audit all operations dispatched through fn(content, meta, ctx) in SimpleToolAgent.process() to determine the actual return type set
Define a concrete return type annotation (e.g. str, a Protocol, or a bounded TypeVar) that covers all dispatched operations
Update SimpleToolAgent.process() signature to use the new return type
Remove the # type: ignore[override] suppression comment
Audit and update downstream callers (e.g. _create_agent_mapper()) to reflect the correct type contract
Write BDD scenarios covering the type contract for process() return values
Run nox -s typecheck and confirm zero errors and zero suppressions
Run nox -s unit_tests and nox -s coverage_report — coverage ≥ 97%

Definition of Done

SimpleToolAgent.process() has a specific, accurate return type annotation (not Any)
No # type: ignore comments remain in the modified code
All dispatched operations return the declared type
nox -s typecheck passes with zero errors
BDD scenarios cover the type contract
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: Bug Hunt | Agent: new-issue-creator

## Background and Context The `process()` method of `SimpleToolAgent` in `src/cleveragents/reactive/stream_router.py` is annotated to return `Any` and uses `# type: ignore[override]` to suppress Pyright errors. Different operations dispatched through this method can return values of entirely different types (strings, ints, dicts, etc.), but downstream code such as `_create_agent_mapper()` assumes string results. This violates the project's mandatory static typing requirements (CONTRIBUTING.md: "Full type annotations everywhere. Never use `# type: ignore` or any suppression mechanism. Pyright runs in CI — must pass."). ## Current Behavior ```python def process( self, content: Any, metadata: dict[str, Any] | None = None, context: dict[str, Any] | None = None, ) -> Any: # type: ignore[override] # ... processing ... return fn(content, meta, ctx) # Could return any type ``` - The return type is `Any`, which defeats Pyright's ability to catch downstream type errors at static analysis time. - The `# type: ignore[override]` suppression hides a real type contract violation — the override does not honour the parent class's return type contract. - Downstream callers (e.g. `_create_agent_mapper()`) assume the result is a `str`, but the actual return type is unconstrained. - Different operations dispatched through `fn(content, meta, ctx)` can return `str`, `int`, `dict`, or other types, causing silent type mismatches at runtime. ## Expected Behavior - `SimpleToolAgent.process()` must have a concrete, specific return type annotation (e.g. `str`, a `Protocol`, or a properly bounded `TypeVar`) that accurately reflects what all dispatched operations return. - The `# type: ignore[override]` suppression must be removed; the override must satisfy the parent class's type contract. - All operations dispatched through `process()` must return a consistently typed value. - `nox -s typecheck` must pass with zero errors and zero suppressions after the fix. ## Acceptance Criteria - [ ] `SimpleToolAgent.process()` return type is changed from `Any` to a specific, accurate type annotation - [ ] The `# type: ignore[override]` comment is removed - [ ] All operations dispatched through `fn(content, meta, ctx)` are verified to return the declared type - [ ] Downstream callers (e.g. `_create_agent_mapper()`) are updated if needed to reflect the correct type contract - [ ] `nox -s typecheck` passes with zero errors and zero `# type: ignore` suppressions - [ ] BDD scenarios cover the type contract for `process()` return values - [ ] All nox stages pass; coverage ≥ 97% ## Supporting Information - **File**: `src/cleveragents/reactive/stream_router.py` - **Function**: `SimpleToolAgent.process()` - **Lines**: 180–220 - **Severity**: Medium — code quality / static type safety violation - **Likelihood**: High — occurs whenever agents are invoked - **Impact**: Runtime type errors and violations of the project's static typing requirements; downstream code silently receives wrong types - **Suggested Fix**: Define a proper return type contract (e.g. `str` or a bounded Protocol/TypeVar), ensure all dispatched operations return that type, and remove the `# type: ignore[override]` suppression - **Reference**: CONTRIBUTING.md §"Type Safety" — *"Full type annotations everywhere. Never use `# type: ignore` or any suppression mechanism."* > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Metadata - **Branch**: `bugfix/reactive-simple-tool-agent-process-return-type` - **Commit Message**: `fix(reactive): replace Any return type and remove type: ignore suppression in SimpleToolAgent.process()` - **Milestone**: *(none — backlog)* - **Parent Epic**: #7052 ## Subtasks - [ ] Audit all operations dispatched through `fn(content, meta, ctx)` in `SimpleToolAgent.process()` to determine the actual return type set - [ ] Define a concrete return type annotation (e.g. `str`, a Protocol, or a bounded TypeVar) that covers all dispatched operations - [ ] Update `SimpleToolAgent.process()` signature to use the new return type - [ ] Remove the `# type: ignore[override]` suppression comment - [ ] Audit and update downstream callers (e.g. `_create_agent_mapper()`) to reflect the correct type contract - [ ] Write BDD scenarios covering the type contract for `process()` return values - [ ] Run `nox -s typecheck` and confirm zero errors and zero suppressions - [ ] Run `nox -s unit_tests` and `nox -s coverage_report` — coverage ≥ 97% ## Definition of Done - [ ] `SimpleToolAgent.process()` has a specific, accurate return type annotation (not `Any`) - [ ] No `# type: ignore` comments remain in the modified code - [ ] All dispatched operations return the declared type - [ ] `nox -s typecheck` passes with zero errors - [ ] BDD scenarios cover the type contract - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: Bug Hunt | Agent: new-issue-creator

HAL9000 added a new dependency

2026-04-10 09:15:39 +00:00

#7052 [Bug Hunt][Cycle 2][Reactive] Thread Safety Violation in ReactiveEventBus

HAL9000 added the

State

Unverified

label

2026-04-10 09:17:53 +00:00

HAL9000 referenced this issue

2026-04-10 10:08:15 +00:00

[AUTO-BUG-HUNT] Worker worker-reactive-1 Started #7177

HAL9000 referenced this issue

2026-04-10 12:42:33 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 15) #7255

HAL9000 referenced this issue

2026-04-10 13:02:08 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 20) #7258

HAL9000 referenced this issue

2026-04-10 13:12:06 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 25) #7259

freemo added the

labels

2026-04-12 18:36:21 +00:00

HAL9000 added

and removed

labels

2026-04-14 06:24:30 +00:00

HAL9000 commented

2026-04-14 06:24:30 +00:00

Author

Owner

✅ Verified — Type safety bug: agent processing returns inconsistent types. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Type safety bug: agent processing returns inconsistent types. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:30:07 +00:00

Author

Owner

✅ Verified — Type safety bug: agent processing returns inconsistent types. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor