Skip to content

FastMCP output validator rejects 'submitted' status on CreateMediaBuyResponse oneOf #570

Closed

Description

@bokelley

What

CreateMediaBuyResponse has three valid branches per spec (schemas/cache/media-buy/create-media-buy-response.json):

  1. Success — media_buy_id + packages, status from media-buy-status enum (pending_creatives | pending_start | active | paused | completed | rejected | canceled)
  2. Error — errors array
  3. Submitted — status: 'submitted' + task_id (async task envelope)

When a platform returns the third branch (e.g., salesagent's _create_media_buy_impl maps internal pending_approval → wire status='submitted' for tenants with human_review_required=True), FastMCP's per-tool output validator rejects with:

mcp_error: Output validation error: 'submitted' is not one of ['pending_creatives', 'pending_start', 'active', 'paused', 'completed', 'rejected', 'canceled']

The validator is checking against the media-buy-status enum unconditionally instead of resolving the response oneOf based on shape. The submitted branch's status: Literal['submitted'] discriminator should produce a clean branch resolution but doesn't.

Repro

salesagent kill-nginx greenfield (core/platforms/_delegate.py:_delegate_create_media_buy) calls _create_media_buy_impl. With wonderstruck tenant human_review_required=True, the impl returns the submitted-branch envelope. FastMCP rejects.

Workaround

tenant.human_review_required = False — forces the synchronous success branch. Production tenants needing manual approval can't ship until the validator resolves the oneOf.

What we'd want

The output validator should:

  • Recognize CreateMediaBuyResponse as a discriminated union
  • Resolve the branch by looking at top-level fields (status='submitted' + task_id → submitted branch; errors → error branch; media_buy_id + packages → success branch)
  • Validate the resolved branch's schema, not the wrong one's enum

Current behavior makes the async-approval flow unreachable on MCP transport.

Filed by

salesagent live GAM CRUD probe — surfaced when driving real create_media_buy against Wonderstruck tenant. Tracked as salesagent #41.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 4, 2026
  2. bokelley commented on May 4, 2026

    @bokelley
    ContributorAuthor

    Triage — claude-agent

    Root cause

    The SDK's generated outputSchema for create_media_buy is a correct 3-branch anyOf union (success / error / submitted). The error is not a oneOf disambiguation failure — the submitted branch (Branch 2) is properly formed with status: const "submitted".

    The failure is caused by the submitted response missing task_id. Branch 2 of the union has required: ["task_id"]. When task_id is absent:

    • Branch 0 (success): fails — media_buy_id/packages missing AND status: "submitted" is not in MediaBuyStatus enum
    • Branch 1 (error): fails — errors missing
    • Branch 2 (submitted): fails — task_id missing

    All three branches fail. jsonschema's error-surfacing heuristic picks the deepest schema-path error, which happens to be the enum constraint on status inside Branch 0 (anyOf → 0 → properties → status → anyOf → 0 → enum, depth 7) rather than the required error for task_id in Branch 2 (depth 3). This surfaces the thoroughly misleading 'submitted' is not one of ['pending_creatives', ...], completely obscuring the real failure.

    Verified empirically:

    jsonschema.validate({'status': 'submitted', 'task_id': 'task_abc'}, union_schema)
    # PASSES
    
    jsonschema.validate({'status': 'submitted'}, union_schema)
    # FAILS: "'submitted' is not one of ['pending_creatives', ...]"   ← exact reported error

    The task_id field is required by the AdCP async task contract — a status: submitted response without task_id leaves the buyer with no polling handle (protocol violation, consistent with AdCP DBCFM async-agent interop pattern).

    What needs fixing

    Primary (salesagent — not this PR): core/platforms/_delegate.py:_create_media_buy_impl must include task_id in the submitted-branch envelope. Tracked as salesagent #41.

    Secondary (this repo — 3 non-breaking SDK changes):

    1. Wrong return type on PlatformHandler.create_media_buy (src/adcp/decisioning/handler.py:1308): annotation says -> CreateMediaBuySuccessResponse but the method can legitimately return a submitted response. This is a static lie that misleads mypy users and reviewers. Fix: -> CreateMediaBuyResponse + update the cast().

    2. Missing CreateMediaBuySubmittedResponse alias (src/adcp/types/aliases.py:287): Response1 → CreateMediaBuySuccessResponse, Response2 → CreateMediaBuyErrorResponse, but Response3 has no semantic alias. Implementors must import the internal CreateMediaBuyResponse3 name. Fix: add CreateMediaBuySubmittedResponse = CreateMediaBuyResponse3 + export from __init__.py.

    3. create-media-buy-async-response-submitted.json underspecified (schemas/cache/media-buy/create-media-buy-async-response-submitted.json): lists only context/ext in properties, says "usually empty or just context." The main create-media-buy-response.json Branch 3 requires both status and task_id. With opt-in response_mode="strict", the SDK's validate_response() uses this file after routing on status="submitted" — but currently validates nothing useful. Fix: add status (const "submitted") and task_id (string) to both properties and required. This makes the SDK's own schema validator catch a missing task_id with a clear message instead of letting it propagate to FastMCP's misleading error.

    Classification

    • Severity: P1 blocker for any tenant with human_review_required=True on MCP transport
    • Bucket: protocol-correctness + DX
    • Outcome: Execute — all three SDK changes are non-breaking (additive or annotation-only). Drafting PR.

    Expert consultation: code-reviewer ✓ · ad-tech-protocol-expert ✓ · empirical validation via jsonschema ✓


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 4, 2026
  4. bokelley commented on May 4, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (misleading validator error masks missing task_id)
    Bucket(s): client, validation
    Status: drafting-pr
    Milestone: (omitted)

    What the experts said:

    • code-reviewer: approved after one fixup iteration — flagged guards alias excluding submitted branch, stale generated file, missing snapshot update, missing top-level package export; all fixed
    • ad-tech-protocol-expert: approved — task_id unambiguously required per AdCP async contract (create-media-buy-response.json Branch 2 + compliance schema enforce it); additionalProperties: true correct and consistent with established pattern

    My take: The validator error is a red herring — the real issue is task_id absent from the submitted envelope (protocol violation). This PR fixes the SDK's static lie on the return type, adds the missing CreateMediaBuySubmittedResponse alias with a proper is_create_media_buy_submitted() guard, and tightens the standalone schema so strict-mode gives a clear error instead of passing through silently.

    Draft PR: #573


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


    Generated by Claude Code

  5. added a commit that references this issue on May 4, 2026
    60d0894
  6. added a commit that references this issue on May 13, 2026
    f7960ed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions