Skip to content

feat(negotiation): support AdCP 3.3 extend_hold and include_collections on refine_proposals - #3738

Open
bokelley wants to merge 3 commits into
mainfrom
fix/3601-refine-proposals-extend-hold
Open

bokelley wants to merge 3 commits into
mainfrom
fix/3601-refine-proposals-extend-hold

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Closes #3601
Refs #3724

Problem

validateRefineProposalsRequest accepted only revise and finalize. Every extend_hold entry failed with action must be revise or finalize before it was sent. AgentClient.refineProposals calls it, and the storyboard runner dispatches refine_proposals through that method, so the 3.3 media_buy_seller/hold_extension storyboard couldn't send the action. createAdcpServer runs the same validator before a seller's handler, so an SDK-hosted seller answered extend_hold with a validation error even when it declared media_buy.proposal_refinement.hold_extension.

#3725 left the other 3.3 additions to this task out of scope: top-level include_collections, and collections and expected_confirmation_at in the response.

Fix

Every shape comes from the vendored 3.3.0-rc.0 schemas (refine-proposals-request.json, proposal-refinement.json, refine-proposals-response.json, the capabilities response and core/response-collection.json).

Requests (negotiation/buyer.ts)

  • extend_hold is accepted on AdCP 3.3. Like finalize, an entry carries only proposal_id, action and ext. Every revise field and every unknown key is still rejected.
  • A batch that contains extend_hold must contain only extend_hold entries, as the schema's refinements rule requires.
  • When the seller's capabilities are known, proposal_refinement.hold_extension must be true. Otherwise the action fails with VALIDATION_ERROR, which is what the spec requires of a seller that doesn't declare it. Finalize and revise aren't gated.
  • include_collections is accepted as a boolean on 3.3.
  • Both additions are refused on 3.2 (extend_hold requires AdCP 3.3). This follows the existing installment_changes gate.
  • extractProposalRefinementSupport carries hold_extension through.

Responses (negotiation/verification.ts)

  • extend_hold may return only finalized or unable. The spec reports a successful extension as finalized. The existing finalize checks apply: one committed successor, parent_proposal_id equal to the source, a fresh ID, a future expires_at, and all-or-none across the batch.
  • The new keys are allowed only when the selected schema is 3.3. collections is allowed on a completed response and expected_confirmation_at on a submitted one (it must be an RFC 3339 date-time). A 3.2 contract still rejects both as undeclared keys.
  • Each collections entry is validated against core/response-collection.json. Returning collections when the request didn't set include_collections is a verification issue, because sellers MUST NOT do it. Duplicate keys and unreferenced entries are not failures, because the spec tells buyers to fall back or ignore them.
  • New verifyHoldExtension(source, successor). Response verification sees only the source's ID, so this check uses the source proposal itself. The successor must keep the source's terms_digest, hold_policy and hold_placed_at and carry a later expires_at. ProposalNegotiator.extendHold(proposal) sends the action and runs these checks. It doesn't check bounds against max_total_duration.

Server (server/create-adcp-server.ts)

  • hold_extension reaches 3.3 callers only. The existing release projection already strips it for 3.2 callers, and a test now covers that.
  • When hold_extension is declared, media_buy.hold_extension is added to experimental_features. The 3.3 capabilities schema requires it (allOf/15). Without it, the buyer client flagged the seller's capabilities as invalid. These three lines are next to the proposal_refinement projection and don't touch version negotiation (createAdcpServer: a prerelease preview ceiling leaks into stable negotiation and stable response shapes #3597).
  • The MCP input hint for refine_proposals lists include_collections.

Seller engine (negotiation/seller.ts)
createProposalRefinementHandler can't place, transfer or supersede holds. That work is #3600. Until then, it refuses hold_extension: true when constructed, and its own validator answers extend_hold with VALIDATION_ERROR. This stops it from staging a committed successor without moving the hold. Sellers serve extend_hold from a custom refine_proposals handler, which now receives the request.

Types

  • ExtendHoldProposalRefinement is added to the ProposalRefinement union. Exhaustive switches on action need the new arm, as the 16→17 migration guide already says.
  • ProposalRefinementCapabilities.hold_extension
  • RefineProposalsRequest.include_collections
  • RefineProposalsCompletedResponse.collections (ResponseCollection[])
  • RefineProposalsSubmittedResponse.expected_confirmation_at
  • The hold_extension issue code
  • RefineProposalsVerificationRequest

The media-buy compatibility coordinator passes include_collections through to verification on the compact path.

Tests

  • test/lib/proposal-hold-extension.test.js (new, 17 tests):
    • Request validation: extend_hold accepted on 3.3, alone or in a batch, with ext; refused on 3.2. Each revise field, an unknown key, and a non-object ext are rejected at the right field. Mixed batches and duplicate IDs are rejected. The hold_extension gate returns VALIDATION_ERROR, and a non-boolean declaration is rejected. Discovery carries the flag. include_collections must be a boolean and is refused on 3.2.
    • Response verification:
      • A successful single or batch extension passes, and so do unable results with hold_unavailable, batch_aborted and source_unavailable.
      • A revised outcome fails, and so does a partly successful batch. Wrong lineage, an expired hold and a reused ID also fail.
      • collections passes when requested and fails when it wasn't requested, is empty, or has a malformed entry.
      • expected_confirmation_at passes only on a submitted response.
      • A 3.2 contract rejects both new response fields.
    • verifyHoldExtension passes a correct successor. It fails on each changed field: expiry, hold_placed_at, hold_policy, parent or terms, and it fails when the source is a draft.
    • ProposalNegotiator.extendHold returns a verified successor. It catches a seller that changed the terms, and it gates on the capability before any transport call.
    • The engine refuses hold_extension and returns VALIDATION_ERROR for extend_hold.
    • End to end over MCP: AgentClient.refineProposals, the method the storyboard runner dispatches through, sends extend_hold and include_collections to a 3.3 createAdcpServer seller. The response, including collections, passes strict validation and verification. Without the declaration, the call is refused before it is sent.
  • test/lib/proposal-negotiation-server.test.js, through createAdcpServer with strict validation:
    • extend_hold and include_collections reach the handler, and a finalized successor with collections passes strict response validation.
    • A submitted extension's expected_confirmation_at passes strict response validation.
    • An undeclared hold_extension is refused with VALIDATION_ERROR at refinements[0].action before the handler runs.
    • A malformed entry, a mixed batch, and the 3.3 fields from a 3.2 caller are refused before the handler runs.
    • hold_extension and media_buy.hold_extension reach 3.3 callers only.
  • test/lib/proposal-negotiation-validation.test.js: updated the unknown-action message.

Local:

  • typecheck, build:lib, lint (0 errors) and prettier pass, and generate-agent-docs shows no drift.
  • All 342 tests across test/lib/proposal-*.test.js pass.
  • 1073 related tests pass: create-adcp-server, from-platform, v3 compatibility, lifecycle coordinator, compact lifecycle storyboards and runner, zod schemas, response unwrapper and conformance.

Storyboards

The vendored media_buy_seller/hold_extension storyboard (3.3.0-rc.0) builds bare { proposal_id, action: "extend_hold" } entries. It sends them through AgentClient.refineProposals, and the storyboard's own narrative names this issue as the blocker. The end-to-end test above shows the request now reaches the seller and the result passes verification.

I did not run the full storyboard. No seller in this repo implements hold policy and seeding, which is #3600 here and the training agent in adcontextprotocol/adcp#8181. Grading the storyboard needs one of those. The known-failing skips in that training-agent matrix can come off once this ships.

Not included

  • Holds in the seller engine (Proposal refinement engine: support experimental 3.3 holds (hold_policy, extend_hold, hold_rank, holds) #3600). See above.
  • Restricting which reason codes an unable extension may use. The spec describes hold_unavailable, batch_aborted and source_unavailable for this action but doesn't limit them, so the verifier doesn't either, as with finalize.
  • Checking expires_at against hold_placed_at + max_total_duration. That is duration arithmetic, and the storyboard grades it as advisory.
  • A 16.x backport. 3.2 has no extend_hold or include_collections.

🤖 Generated with Claude Code

bokelley and others added 2 commits November 17, 2026 21:11
…ns on refine_proposals

validateRefineProposalsRequest accepted only revise and finalize, so
AgentClient.refineProposals (and the storyboard runner that dispatches
through it) could not send extend_hold, and createAdcpServer refused it
before a seller's handler ran.

- Requests: extend_hold is accepted on AdCP 3.3 with only proposal_id,
  action and ext; a batch containing it contains only extend_hold
  entries; a known seller capability set must declare
  proposal_refinement.hold_extension (VALIDATION_ERROR otherwise).
  include_collections is a 3.3 boolean. Both are refused on 3.2, and
  unknown keys are still rejected.
- Responses: an extension verifies like a finalize (one committed
  successor, parent is the source, future expiry, all-or-none). A 3.3
  contract accepts collections (when requested, each checked against
  core/response-collection.json) and expected_confirmation_at on a
  submitted response; a 3.2 contract still rejects them.
- verifyHoldExtension and ProposalNegotiator.extendHold check the
  successor against the source: same terms_digest, hold_policy and
  hold_placed_at, later expires_at.
- createAdcpServer projects hold_extension to 3.3 callers only and adds
  media_buy.hold_extension to experimental_features when declared.
- createProposalRefinementHandler refuses hold_extension until #3600.

Closes #3601
Refs #3724

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
aao-secretariat[bot]
aao-secretariat Bot previously approved these changes Nov 18, 2026

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — clean PR adding AdCP 3.3 refine_proposals support (extend_hold, include_collections/collections, expected_confirmation_at).

Verified against repo-specific mandates:

  • DR-0033 pathway-back: extend_hold and related wire changes are fail-closed on 3.2 (both request and response refused), satisfying the previous-minor handling requirement.
  • Witness-not-translator: verifyHoldExtension provides anti-fabrication/witness checks catching term and hold mutation on extension; no re-shaping or placeholder injection.
  • Changeset correctness: correct minor changeset present for the src/lib/** wire change.
  • Schema validation: collections handled via schema-backed validation.

No Critical/High/Medium findings; no inline comments posted.

Decision table: no blocking findings (rows 1, 6 N/A); gated_paths is false (row 2 N/A); high_risk is false (rows 3, 5 N/A); no medium findings in data-loss/schema/infra (row 4 N/A); no prior escalation (row 6 N/A); no no-auto-approve team match (row 7 N/A); fewer than three medium findings (row 8 N/A). Falls through to row 9 → approve.

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-approval: no reviewable delta since the prior approval; re-submitting after stale-review dismissal.

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — additive AdCP 3.3 refine_proposals support (extend_hold action, include_collections/collections, expected_confirmation_at).

No critical/high/medium findings. Traced every load-bearing path:

  • Request validation gates extend_hold/include_collections to 3.3 and fails closed on an undeclared hold_extension capability.
  • Response verification flags collections without include_collections and strips the 3.3 keys for 3.2 contracts (RESPONSE_KEYS_33) — DR-0033 backward-compat pathway handled.
  • verifyHoldExtension anchors on terms_digest/hold_policy/hold_placed_at plus a later expires_at.
  • Engine refuses extend_hold at construction per #3600; capabilities projection adds media_buy.hold_extension only for 3.3 callers.
  • Witness-not-translator intact (no fabrication).
  • Changeset present and correctly minor.

Comprehensive tests including an end-to-end MCP round-trip. Non-blocking nit: the 3.2-refusal (DR-0033) pathway is tested in the feature's own test files rather than version-translation.test.js, but coverage is thorough and a regression would not be silent — does not meet the medium threshold.

gated_paths is false; review_decision is APPROVED; no author team gate; high_risk false. No rows 1–8 fire → row 9 approve.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refine_proposals client validation rejects action extend_hold, so storyboards can't dispatch it

1 participant