Repository navigation
Remove envelope workarounds: status stripped from four tools, every response root relaxed #3481
Description
adcontextprotocol/adcp#8547 fixes the root cause in the spec. Task response schemas now compose core/protocol-envelope.json, closed ones included, so every response accepts and declares the envelope fields: status, task_id, context_id, message, timestamp, replayed, adcp_error, push_notification_config, governance_context, adcp_version and adcp_major_version. A 3.2.x backport with the same design is coming. Background: adcontextprotocol/adcp#8518.
The SDK has workarounds for the old schemas, and they become wrong once the fix lands:
statusis stripped from four tools.genericResponse()(src/lib/server/create-adcp-server.ts:2910) deletesstatusfromstructuredContentforSTATUS_FREE_SYNC_RESPONSE_TOOLS(list_products,decline_proposals,list_collections,list_proposals, defined insrc/lib/utils/envelope-status-compat.ts:54). Line:4433skips the defaultstatusinjection for the same tools, andenvelope-status-compat.ts:123returns early for them. The envelope makesstatusREQUIRED on every task response, so servers built on the SDK now send non-conforming responses for these four tools. The AdCP training agent'stenant-smokelist_productstest fails for exactly this reason.- Every response root is relaxed.
relaxResponseRoot()(src/lib/validation/schema-loader.ts:706) setsadditionalProperties: trueon every response root and on itsoneOf/anyOf/allOfbranches. Once the envelope is composed, closed schemas already accept envelope fields, so the relaxation only hides real drift at the root.
What needs to change:
- Emit
statuson every task response, and deleteSTATUS_FREE_SYNC_RESPONSE_TOOLS. - Drop
relaxResponseRoot()for schema bundles built with the composed envelope. - Where compat is still needed for released schemas that predate the fix (3.2.7 and earlier), choose it by the served version, not by tool name.
Activity
KonstantinMirin commentedon Oct 28, 2026
Adding the reason this change isn't optional: AdCP 3.x is additive-only.
statushas been REQUIRED on every task response since 3.1 (core/protocol-envelope.json). 3.2 doesn't say otherwise anywhere. No doc or changeset makes compact responses status-free. The only source is that the closed 3.2.7 compact schemas didn't compose the envelope, so they never declaredstatus.STATUS_FREE_SYNC_RESPONSE_TOOLSturned that gap into intent ("3.2 synchronous response arms that intentionally forbid task-envelope status", added in e0d722b) and deletes a required field inside a minor version. If it were ever meant to go, it would have had to stay present and deprecated until 4.0. This also regresses #1897 ("Envelopestatusmissing on every sync wire response").3.2.x is affected too. rc.53 strips
statusfromlist_productsanddecline_proposals. With adcontextprotocol/adcp#8547 and its 3.2.x backport, the AdCP training agent fails nine storyboard steps on exactly this, acrosscompact_direct_buy_lifecycle,compact_product_lifecycle,declined_proposal_refinementanddeclined_proposal_execution. We're not working around it on the training-agent side, so both PRs stay red on these steps until the SDK sendsstatusagain.bokelley commentedon Oct 28, 2026
Fix in progress: #3493.
Approach (per served release, DR-0024). Konstantin is right that
statusis REQUIRED on every task response since 3.1 and that the 3.2.7 compact schemas only dropped it by being closed. Two further facts shaped the fix:list_productsclosed with nostatusproperty, and thedecline_proposalssuccess arm carriesnot: required status. A valid 3.2.x response is therefore invalid under #8547's 3.3 schema, and the reverse. A blanket "always send status" would break strict validation against 3.2.x.omitsEnvelopeStatusForRelease):statusis kept forlist_products,decline_proposals,list_collectionsandlist_proposalswhenever that release composescore/protocol-envelope.json, and omitted only where the release's schema for the tool has nostatus(3.2.x). When the 3.2.x backport of #8547 ships, the answer flips without a code change.STATUS_FREE_SYNC_RESPONSE_TOOLSis gone.relaxResponseRoot()is removed. A bundle that composes the envelope is validated exactly as published,statusrequired, nothing filled in. For closed pre-composition roots (3.2.7 and earlier) the validator accepts only the envelope fields that release's ownprotocol-envelope.jsondefines, on the closed nodes; body typos are still rejected and no envelope field is added or removed.Verified against #8547 (head
3da19611): with the PR's schema root registered, the SDK passescompact_direct_buy_lifecycle,compact_product_lifecycle,declined_proposal_refinement,declined_proposal_execution,outcome_target_list_products_inert,product_coverage_filters,sales_doohandavailability_windows(0 failed steps). Unmodifiedmainfails the same steps withmust have required property 'status'.Caveat. The SDK pin stays on the published 3.3.0-beta.0 bundle for now (it forbids
statuson these arms), so a seller on the default pin keeps omitting it until the pin moves to beta.1 or a composed bundle. #8547's training agent opts into the composed contract by registering its built schema root; I'll leave the exact change on #8547.fix(validation): stop stripping task-envelope status and relaxing res…
KonstantinMirin commentedon Oct 29, 2026
Thanks. #3493 is in 17.0.0-beta.6, and #8547 is moving to it now.
The 3.2.x side still needs it. adcontextprotocol/adcp#8567 (the 3.2.x backport of the envelope fix, shipping in 3.2.9) runs the training agent on
@adcp/sdk14.0.0-rc.53. Every SDK release a 3.2.x seller can use still hasSTATUS_FREE_SYNC_RESPONSE_TOOLS: 14.0.0-rc.53, 16.5.0 (adcp-3.2) and 16.6.1 (latest). So #8567'scompact_direct_buy_lifecyclestep stays red, and sellers on 3.2.9 would keep losingstatusonlist_productsanddecline_proposals.Could #3493 be backported to the 3.2 line (the
adcp-3.2dist-tag)? Its gating on the served release's schema already covers the transition. Against 3.2.8's published schemas it keeps omittingstatus. Once 3.2.9 publishes schemas that compose the envelope, it keeps it, with no code change. Once that release is out, #8567 will bump to it.