feat(webhooks): create_mcp_webhook_payload should return McpWebhookPayload

[bokelley]

Follow-up to the optional bonus in #601 that PR #602 (`to_wire_dict` seam) and #600 (annotation fixes) deliberately deferred.

Current behaviour

```python
def create_mcp_webhook_payload(...) -> dict[str, Any]:
...
```

Adopters who want a typed shape do the ceremony manually. From `salesagent/context_manager.py`:

```python

TODO: Fix in adcp python client - create_mcp_webhook_payload should return

McpWebhookPayload instead of dict[str, Any] for proper type safety

mcp_payload_dict = create_mcp_webhook_payload(step.step_id, status_enum, step.response_data)
payload = McpWebhookPayload.model_construct(**mcp_payload_dict)
```

Proposed change

```python
def create_mcp_webhook_payload(...) -> McpWebhookPayload:
...
```

Adopters drop `.model_construct(**dict)` and get a typed instance directly. Anyone who needs the wire dict calls `to_wire_dict(payload)` (#602) — the seam handles both shapes uniformly, so this is purely an ergonomics win.

Why this didn't ship in #602 / #600

• feat(webhooks): public to_wire_dict() serialization seam #602 scope was the serialization seam. Changing the builder's return type was orthogonal and would have required its own deprecation discussion.
• fix(webhooks): correct type annotations for extract_webhook_result_data and payload builders #600 scope was correcting type annotations to match runtime behavior. This change would change runtime behavior.

Compatibility

Breaking for any adopter that mutates the dict, calls `.update()`, or reads keys without unwrapping. Migration:

Old (dict)	New (McpWebhookPayload)
`payload["task_id"]`	`payload.task_id`
`payload.update(extra)`	n/a — use the builder kwargs
`json.dumps(payload)`	`to_wire_dict(payload)` (or `payload.model_dump(mode="json", exclude_none=True)`)
HTTP transport (`json=payload`)	`json=to_wire_dict(payload)`

Suggested rollout

One minor with widened return type `dict[str, Any] | McpWebhookPayload` and a deprecation note in the builder docstring, then drop `dict` in the next minor. Or skip the widening since runtime callers see no shape difference if they switch to `to_wire_dict` — strictly a typing-surface change for adopters who type-check.

Acceptance criteria

• `create_mcp_webhook_payload` returns `McpWebhookPayload`.
• Test asserts the returned instance is a `McpWebhookPayload` and that `to_wire_dict(payload)` produces the same wire bytes as before.
• CHANGELOG / MIGRATION note covering the type narrowing.
• Update the salesagent TODO referenced above (cross-link from the PR).

References

• Original ask: Uniform serialization seam for create_a2a/mcp_webhook_payload return shapes #601 (Out-of-scope-then bonus)
• Seam that makes this safe: feat(webhooks): public to_wire_dict() serialization seam #602 (`to_wire_dict`)
• Annotation fixes that overlapped: fix(webhooks): correct type annotations for extract_webhook_result_data and payload builders #600
• Downstream waiting on this: `bokelley/salesagent` `context_manager.py` TODO

[bokelley]

Triage

Classification: Feature request — ergonomics improvement
Bucket(s): client (label not in repo; flagged in run summary)
Status: ready-for-human
Milestone: omit — no milestone named in issue

What the experts said:

• dx-expert: The DX gain is real — receiver already returns McpWebhookPayload, so the dict-returning sender is the existing asymmetry. Ship as a clean breaking change, not a widened union (dict | McpWebhookPayload is strictly worse DX for every caller). Two pre-requisites must land in the same PR or it's a regression.
• code-reviewer (from code analysis): webhook_sender.py:565 does payload["idempotency_key"] — dict subscript that becomes AttributeError if the return type changes without updating that line. Multiple conformance tests do json.dumps(payload) directly on the return value — these become TypeError after the change.

Two blockers the issue doesn't fully address:

1. task_type schema mismatch (design question for @bokelley). McpWebhookPayload.task_type is a required, non-optional TaskType enum (20-value closed set, no default). create_mcp_webhook_payload takes task_type: str | None = None and passes None silently. An adopter calling the builder without task_type — common for working-status heartbeats — gets an immediate Pydantic ValidationError on construction. The implementation PR needs an explicit decision: (a) make task_type required in the builder signature (breaking in a second dimension), (b) make McpWebhookPayload.task_type optional (schema change), or (c) add BeforeValidator coercion plus a None sentinel fallback. The issue's acceptance criteria don't mention this gap.

2. webhook_sender.py:565 dict subscript. str(payload["idempotency_key"]) must become payload.idempotency_key in the same PR — this is the one internal caller that breaks at runtime.

My take: The change is worth shipping — asymmetry between a dict-returning sender and a McpWebhookPayload-returning receiver is genuine friction, and to_wire_dict (already merged) handles the serialization seam. But the task_type required/optional tension is a design question only @bokelley can resolve; it affects both the builder's public signature and the generated model. Flag rather than execute on that basis.

---

Label gap: No client label exists in this repo. Bucket name included in comment per triage protocol.

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code