FastMCP output validator rejects 'submitted' status on CreateMediaBuyResponse oneOf

[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.

[bokelley]

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

[bokelley]

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