cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [type-safety] Missing type enforcement in router.py detect_provider_format allows invalid tool call objects #7240

New issue

Open

opened 2026-04-10 10:55:19 +00:00 by HAL9000 · 5 comments

HAL9000 commented

2026-04-10 10:55:19 +00:00

Owner

Background and Context

The detect_provider_format function in src/cleveragents/tool/router.py has a type annotation mismatch: its signature declares payload: dict[str, Any] but the function body contains a runtime guard if not isinstance(payload, dict) that handles non-dict inputs (including None). This creates a contradiction between the static type contract and the runtime behaviour.

Per the project's strict type safety requirements (CONTRIBUTING.md: "Full type annotations everywhere. Never use # type: ignore or any suppression mechanism. Pyright runs in CI — must pass."), the type signature must accurately reflect what the function actually accepts and handles.

Current Behavior

# src/cleveragents/tool/router.py, line 226
def detect_provider_format(payload: dict[str, Any]) -> ProviderFormat:
    """Detect the provider format from a tool call payload."""
    if not isinstance(payload, dict):   # ← handles non-dict / None at runtime…
        return ProviderFormat.UNKNOWN   # …but signature says dict[str, Any] only
    # ...

Type safety issues:

Signature/runtime contract mismatch — The type annotation dict[str, Any] promises callers that only dicts are accepted, yet the body silently handles None and other non-dict values. Pyright strict mode will flag callers that pass None even though the function handles it correctly at runtime.
None not in type contract — If a caller passes None (e.g., from an optional tool call field), Pyright raises a type error at the call site, even though the function would return ProviderFormat.UNKNOWN safely.
Weak type constraints — dict[str, Any] allows any values; the function expects specific structures per provider format but does not document or enforce the expected shape beyond the runtime heuristics.
Missing None guard in normalize_tool_call — The downstream normalize_tool_call function (line 294) calls detect_provider_format(payload) after its own isinstance check, but the type chain is not fully propagated.

Expected Behavior

The function signature should accurately reflect the runtime behaviour:

def detect_provider_format(payload: dict[str, Any] | None) -> ProviderFormat:
    """Auto-detect provider format from payload shape.

    Returns ProviderFormat.UNKNOWN for None or non-dict inputs.
    """
    if not isinstance(payload, dict):
        return ProviderFormat.UNKNOWN
    # ... rest unchanged

This aligns the static type contract with the existing runtime guard, eliminates Pyright errors at call sites that pass optional values, and satisfies the project's fail-fast + full-type-enforcement requirements.

Impact

Type safety: Violates project's strict Pyright compliance requirement — signature does not match runtime behaviour
Caller confusion: Callers receiving optional tool call objects from provider APIs must add unnecessary casts or suppressions
Spec alignment: Violates CONTRIBUTING.md "Full type enforcement with no suppression — every function must have complete type annotations" and "Fail-fast principle — validate all inputs at function entry"

Acceptance Criteria

detect_provider_format signature updated to payload: dict[str, Any] | None
All call sites updated to pass the correct type (no # type: ignore added)
Pyright strict mode passes with zero errors on src/cleveragents/tool/router.py
Existing BDD unit tests for detect_provider_format updated to cover None input
New BDD scenario added: detect_provider_format(None) returns ProviderFormat.UNKNOWN

Supporting Information

File: src/cleveragents/tool/router.py
Function: detect_provider_format (line 226)
Related: normalize_tool_call (line 294) — downstream caller

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

Metadata

Branch: bugfix/type-safety-detect-provider-format-none-annotation
Commit Message: fix(tool): align detect_provider_format type signature with runtime None guard
Milestone: (backlog — see note above)
Parent Epic: #5502

Subtasks

Update detect_provider_format signature to accept dict[str, Any] | None
Audit all call sites in src/cleveragents/tool/router.py for type correctness
Run nox -s typecheck and confirm zero Pyright errors on the file
Add BDD scenario: detect_provider_format(None) → ProviderFormat.UNKNOWN
Update existing BDD unit tests to cover the None input path
Run nox -s unit_tests and confirm all scenarios pass
Run nox -s coverage_report and confirm coverage ≥ 97%

Definition of Done

detect_provider_format type signature accepts dict[str, Any] | None
No # type: ignore annotations added anywhere
Pyright strict mode passes with zero errors (nox -s typecheck)
BDD scenario for None input exists and passes
All nox stages pass
Coverage >= 97%

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

## Background and Context The `detect_provider_format` function in `src/cleveragents/tool/router.py` has a type annotation mismatch: its signature declares `payload: dict[str, Any]` but the function body contains a runtime guard `if not isinstance(payload, dict)` that handles non-dict inputs (including `None`). This creates a contradiction between the static type contract and the runtime behaviour. Per the project's strict type safety requirements (CONTRIBUTING.md: *"Full type annotations everywhere. Never use `# type: ignore` or any suppression mechanism. Pyright runs in CI — must pass."*), the type signature must accurately reflect what the function actually accepts and handles. ## Current Behavior ```python # src/cleveragents/tool/router.py, line 226 def detect_provider_format(payload: dict[str, Any]) -> ProviderFormat: """Detect the provider format from a tool call payload.""" if not isinstance(payload, dict): # ← handles non-dict / None at runtime… return ProviderFormat.UNKNOWN # …but signature says dict[str, Any] only # ... ``` **Type safety issues:** 1. **Signature/runtime contract mismatch** — The type annotation `dict[str, Any]` promises callers that only dicts are accepted, yet the body silently handles `None` and other non-dict values. Pyright strict mode will flag callers that pass `None` even though the function handles it correctly at runtime. 2. **`None` not in type contract** — If a caller passes `None` (e.g., from an optional tool call field), Pyright raises a type error at the call site, even though the function would return `ProviderFormat.UNKNOWN` safely. 3. **Weak type constraints** — `dict[str, Any]` allows any values; the function expects specific structures per provider format but does not document or enforce the expected shape beyond the runtime heuristics. 4. **Missing `None` guard in `normalize_tool_call`** — The downstream `normalize_tool_call` function (line 294) calls `detect_provider_format(payload)` after its own `isinstance` check, but the type chain is not fully propagated. ## Expected Behavior The function signature should accurately reflect the runtime behaviour: ```python def detect_provider_format(payload: dict[str, Any] | None) -> ProviderFormat: """Auto-detect provider format from payload shape. Returns ProviderFormat.UNKNOWN for None or non-dict inputs. """ if not isinstance(payload, dict): return ProviderFormat.UNKNOWN # ... rest unchanged ``` This aligns the static type contract with the existing runtime guard, eliminates Pyright errors at call sites that pass optional values, and satisfies the project's fail-fast + full-type-enforcement requirements. ## Impact - **Type safety**: Violates project's strict Pyright compliance requirement — signature does not match runtime behaviour - **Caller confusion**: Callers receiving optional tool call objects from provider APIs must add unnecessary casts or suppressions - **Spec alignment**: Violates CONTRIBUTING.md *"Full type enforcement with no suppression — every function must have complete type annotations"* and *"Fail-fast principle — validate all inputs at function entry"* ## Acceptance Criteria - `detect_provider_format` signature updated to `payload: dict[str, Any] | None` - All call sites updated to pass the correct type (no `# type: ignore` added) - Pyright strict mode passes with zero errors on `src/cleveragents/tool/router.py` - Existing BDD unit tests for `detect_provider_format` updated to cover `None` input - New BDD scenario added: `detect_provider_format(None)` returns `ProviderFormat.UNKNOWN` ## Supporting Information - **File**: `src/cleveragents/tool/router.py` - **Function**: `detect_provider_format` (line 226) - **Related**: `normalize_tool_call` (line 294) — downstream caller --- > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Metadata - **Branch**: `bugfix/type-safety-detect-provider-format-none-annotation` - **Commit Message**: `fix(tool): align detect_provider_format type signature with runtime None guard` - **Milestone**: *(backlog — see note above)* - **Parent Epic**: #5502 ## Subtasks - [ ] Update `detect_provider_format` signature to accept `dict[str, Any] | None` - [ ] Audit all call sites in `src/cleveragents/tool/router.py` for type correctness - [ ] Run `nox -s typecheck` and confirm zero Pyright errors on the file - [ ] Add BDD scenario: `detect_provider_format(None)` → `ProviderFormat.UNKNOWN` - [ ] Update existing BDD unit tests to cover the `None` input path - [ ] Run `nox -s unit_tests` and confirm all scenarios pass - [ ] Run `nox -s coverage_report` and confirm coverage ≥ 97% ## Definition of Done - [ ] `detect_provider_format` type signature accepts `dict[str, Any] | None` - [ ] No `# type: ignore` annotations added anywhere - [ ] Pyright strict mode passes with zero errors (`nox -s typecheck`) - [ ] BDD scenario for `None` input exists and passes - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 added a new dependency

2026-04-10 10:55:37 +00:00

#5502 EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0)

HAL9000 added the

State

Unverified

label

2026-04-10 11:01:25 +00:00

HAL9000 commented

2026-04-10 11:27:28 +00:00

Author

Owner

UAT verified: Actor, Skills & Tools core functionality tests pass. The tool router, file tools, and related components have comprehensive test coverage including:

Actor YAML schema validation (LLM/TOOL/GRAPH types)
Tool registry operations and lifecycle
File read operations with offset/limit parameters
Path traversal prevention
Tool discovery and activation

While this issue identifies a specific type safety edge case in detect_provider_format, the core tool routing functionality is verified as working correctly through the test suite.

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

UAT verified: Actor, Skills & Tools core functionality tests pass. The tool router, file tools, and related components have comprehensive test coverage including: - Actor YAML schema validation (LLM/TOOL/GRAPH types) - Tool registry operations and lifecycle - File read operations with offset/limit parameters - Path traversal prevention - Tool discovery and activation While this issue identifies a specific type safety edge case in detect_provider_format, the core tool routing functionality is verified as working correctly through the test suite. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 commented

2026-04-10 11:42:38 +00:00

Author

Owner

UAT verified: Core Actor, Skills & Tools functionality tests pass. The tool router and related components have working baseline functionality:

Actor configuration creation and validation working
Tool registry instantiation and basic operations functional
Core imports and module loading successful
Tool routing infrastructure operational

While this issue identifies a specific type safety edge case in detect_provider_format, the core tool routing functionality is verified as working correctly.

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

UAT verified: Core Actor, Skills & Tools functionality tests pass. The tool router and related components have working baseline functionality: - Actor configuration creation and validation working - Tool registry instantiation and basic operations functional - Core imports and module loading successful - Tool routing infrastructure operational While this issue identifies a specific type safety edge case in detect_provider_format, the core tool routing functionality is verified as working correctly. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-10 11:58:36 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 10) #7252

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:16 +00:00

HAL9000 added

and removed

labels

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

HAL9000 commented

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

Author

Owner

✅ Verified — Type safety bug: missing type enforcement in router.py. MoSCoW: Should-have. Priority: Medium.

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

✅ **Verified** — Type safety bug: missing type enforcement in router.py. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

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

Author

Owner

✅ Verified — Type safety bug: missing type enforcement in router.py. MoSCoW: Should-have. Priority: Medium.

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