Skip to content

Type-annotation fixes for webhook helpers #598

Closed

Description

@bokelley

Issue

Two webhook helpers in 4.5.0 have type annotations that don't match runtime behavior, forcing adopters to cast or use `.model_construct()`:

1. `extract_webhook_result_data`

Declared return type: `AdcpAsyncResponseData | None`
Actual runtime return: `dict[str, Any]` (callers do `result.get(...)` immediately)

Adopter cast (from salesagent):

```python
result = cast(dict[str, Any] | None, extract_webhook_result_data(payload))
notification_type = result.get("notification_type") if result else None
```

2. `create_mcp_webhook_payload`

Two mismatches:

  • `result` parameter: typed narrowly but the function internally calls `hasattr(result, "model_dump")` and accepts any `BaseModel`. The narrow type rejects valid inputs.
  • Return type: declared `McpWebhookPayload` but returns `dict[str, Any]` — adopters then do `McpWebhookPayload.model_construct(**result)` to get the typed value back.

Adopter pattern (from salesagent):

```python
mcp_payload_dict = create_mcp_webhook_payload(
task_id=...,
task_type="media_buy_delivery",
result=delivery_response, # type: ignore[arg-type] # accepts any BaseModel via hasattr
status=AdcpTaskStatus.completed,
)
mcp_payload = McpWebhookPayload.model_construct(**mcp_payload_dict)
```

Proposed fix

  • `extract_webhook_result_data` → either return the typed model and parse internally, or change the declared return type to `dict[str, Any] | None` and document.
  • `create_mcp_webhook_payload` → accept `result: BaseModel | dict[str, Any]`, return `McpWebhookPayload`.

Affected callsites in salesagent

  • `src/services/protocol_webhook_service.py:200`
  • `src/services/delivery_webhook_scheduler.py:375`
  • `src/core/context_manager.py:714`
  • `src/admin/blueprints/creatives.py:247`

Filed as part of stale-annotation cleanup work in bokelley/salesagent#208 — the cleanup confirmed every other "library doesn't have it yet" claim was false-positive against 4.5.0; these two are the survivors.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 8, 2026
  2. bokelley commented on May 8, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): client
    Status: drafting-pr
    Milestone: (omitted — no target version named)

    What the experts said:

    • code-reviewer: non-breaking/safe — both annotation changes correct the lie, AdcpAsyncResponseData was never constructed at runtime; also flagged and fixed a CLAUDE.md layering violation (direct generated_poc/ import) and a missing test branch
    • dx-expert: fix improves DX — dict[str, Any] | None is the right return type, PydanticBaseModel | dict[str, Any] is the right parameter widening; existing docstring examples already used dict access so the annotation now matches them

    My take: Both annotations were actively wrong — callers couldn't use the declared return type without casting, and the parameter type rejected valid inputs that the runtime duck-typed fine. Non-breaking widening in both cases; drafted a PR covering all three affected signatures plus the bogus docstring example.

    Drafting PR: fix return type of extract_webhook_result_data to dict[str, Any] | None; widen result in create_mcp_webhook_payload and create_a2a_webhook_payload to PydanticBaseModel | dict[str, Any]; add 4 regression tests for the Pydantic model path.

    Draft PR: #600


    Triaged by Claude Code. Session: https://claude.ai/code/session_013oiysa4CAeiSFFdnvFTHqh


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions