Skip to content

A2A webhook builder emits invalid 'unspecified' state when status is unknown #603

Closed

Description

@bokelley

Surfaced during the protocol review of #602 (to_wire_dict seam).

Bug

create_a2a_webhook_payload in src/adcp/webhooks.py defaults to pb.TaskState.TASK_STATE_UNSPECIFIED when the input status doesn't match any known AdCP status:

adcp_to_task_state: dict[str, int] = {
    "completed": pb.TaskState.TASK_STATE_COMPLETED,
    ...
}
task_state_enum = adcp_to_task_state.get(status_value, pb.TaskState.TASK_STATE_UNSPECIFIED)

_normalize_a2a_task_state_to_v03 then rewrites TASK_STATE_UNSPECIFIED → unspecified on the wire. unspecified is not a valid A2A v0.3 TaskState — the spec enum is submitted | working | input-required | completed | canceled | failed | rejected | auth-required | unknown. A buyer receiver that validates against the A2A schema will reject the webhook.

Fix options

  1. Fail fast in the builder. Raise ValueError on unknown status — callers shouldn't be silently producing payloads buyers will reject.
  2. Map to unknown. A2A 0.3 has a defined unknown state; defaulting unknown AdCP statuses to it preserves delivery and signals the ambiguity to the buyer.

(1) is more correct (loud failure beats silent wire violation); (2) is more lenient. Recommend (1) since the AdCP→A2A status table is closed and any miss is a bug in the caller.

Additional spec-walking gap

_normalize_a2a_task_state_to_v03 doesn't traverse Task.artifacts[].parts[] for nested Message parts, nor TaskStatusUpdateEvent.metadata if a future caller stuffs role-bearing payloads there. Rare today (create_a2a_webhook_payload doesn't emit those), but worth tightening if hand-built Task payloads start flowing through to_wire_dict.

References

Activity

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

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): client (src/adcp/webhooks.py) — note: no matching repo label found for this bucket
    Status: drafting-pr
    Milestone: omitted

    What the experts said:

    • code-reviewer: confirmed 4 enum members missing from map (canceled, rejected, auth_required, unknown); is_terminated needs expansion; ValueError approach correct; pre-existing mypy no-any-return also fixed
    • ad-tech-protocol-expert: canceled/rejected correctly classified as terminal; auth-required correctly intermediate; actual wire failure is missing state field (proto3 zero omitted by MessageToDict), not "unspecified" string as described in issue

    My take: The issue description has a minor factual error — TASK_STATE_UNSPECIFIED (proto3 zero value) is omitted by MessageToDict entirely, producing {"status": {}} rather than "state": "unspecified". The underlying bug is real and equally invalid. Drafted PR #606 with all four missing states added, ValueError guard, and expanded is_terminated.

    Drafting PR: Add canceled, rejected, auth_required to adcp_to_task_state; raise ValueError for unmapped values (including unknown, which has no pb.TaskState constant); expand is_terminated to include canceled/rejected.


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


    Generated by Claude Code

  5. added 3 commits that reference this issue on May 9, 2026
    1f7d3da
    ae8a916
    89f9491
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