feat: emit capabilities envelope status and expose dynamic portfolio hook

[bokelley]

Summary

Seller applications should not need to monkey-patch PlatformHandler.get_adcp_capabilities() to emit a spec-compliant AdCP v3 capabilities response.

Prebid Sales Agent currently carries a local patch for two things:

1. Add top-level envelope status: "completed" when the SDK capabilities handler omits it.
2. Add tenant-specific portfolio.publisher_domains because the SDK capabilities path does not expose a clean per-request/per-tenant portfolio hook.

The first item should be native SDK behavior. The second may need an extension point rather than SDK-owned data access, but it should not require replacing the SDK handler method.

Current local workaround

Sales Agent imports a side-effect module that monkey-patches:

adcp.decisioning.handler.PlatformHandler.get_adcp_capabilities

The patch:

• Calls the original SDK handler.
• Adds status: "completed" if missing.
• Looks up current tenant publisher domains and adds:

{
  "portfolio": {
    "publisher_domains": ["example.com"]
  }
}

This works, but it is fragile because it depends on SDK internals and has to be installed via import side effect.

Expected SDK behavior

The SDK/server layer should:

• Always emit a protocol-envelope status field for get_adcp_capabilities responses when serving AdCP v3.
• Preserve existing major_versions and supported_versions behavior.
• Provide an adopter-owned extension point for dynamic capabilities fields, especially portfolio.publisher_domains, with request context available so sellers can resolve tenant-specific data.

Possible shape:

async def get_adcp_capabilities_extra(context: RequestContext) -> dict[str, Any]:
    return {
        "portfolio": {
            "publisher_domains": [...]
        }
    }

The exact API does not matter as much as the property that seller code should compose with the SDK capabilities handler, not monkey-patch it.

Why this matters

Capabilities discovery is the first interoperability surface for buyers and storyboards. If the SDK emits a response missing the protocol envelope status, adopter apps either fail schema checks or carry local handler patches. If tenant-specific portfolio data has no first-class hook, every multi-tenant seller has to invent its own patch point.

Moving this upstream keeps SDK behavior consistent and keeps seller applications out of SDK internals.

[bokelley]

Triage

Classification: Feature request (two-item bundle)
Bucket(s): handlers
Status: ready-to-implement

What the experts said:

• code-reviewer: Item 1 is already present in the current SDK (responses.py:272 emits "status": "completed" unconditionally); item 2 is sound but must use ToolContext, not RequestContext — capabilities is unauthenticated and _resolve_account is never called on this path.
• dx-expert: Merge semantics and error handling need explicit contracts: fail-closed on hook exception (propagate SERVICE_UNAVAILABLE), and deep-merge must protect framework-owned keys (adcp, specialisms, supported_protocols, status).

My take: Item 1 appears resolved by the current SDK — worth verifying you're on ≥6.2.0b3 before carrying the patch. Item 2 is a clean non-breaking addition; the two design questions (context type, protected-key list) are settled by the expert review above.

Implementation scope:

• src/adcp/decisioning/platform.py — Add a noop stub get_adcp_capabilities_extra(self, context: ToolContext) -> dict[str, Any] (returns {}) with docstring on DecisioningPlatform; list in _OPTIONAL_PLATFORM_METHODS.
• src/adcp/decisioning/handler.py — In get_adcp_capabilities, detect the hook via hasattr, call it (handle sync/async via inspect.iscoroutinefunction, already imported at line 35), deep-merge result; protect adcp, specialisms, supported_protocols, status from override.
• Error path — Hook exception → AdcpError("SERVICE_UNAVAILABLE", recovery="transient"); fail-open would ship incorrect capabilities to buyers.
• Tests — (a) hook present: fields appear, static media_buy.* fields preserved; (b) hook absent: response unchanged; (c) hook raises: SERVICE_UNAVAILABLE; (d) hook targets protected key: policy enforced.

---

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

---

Generated by Claude Code

[bokelley]

Post-merge update from Prebid Sales Agent #615 / adcp==6.2.0b4:

• status: "completed" on the capabilities envelope is native now; Sales Agent pins this with capabilities_response(["media_buy"])["status"] == "completed".
• Tenant-specific media_buy.portfolio.publisher_domains now flows through DecisioningPlatform.get_adcp_capabilities_for_request() instead of a raw response patch.
• The remaining local PlatformHandler.get_adcp_capabilities() patch is no longer for status or portfolio; it is only for tenant-specific webhook_signing, because SDK validation currently requires an SDK-wired WebhookSender for webhook_signing.supported=True. I split that residual gap out to feat: allow adopter-owned webhook_signing capability without SDK WebhookSender #875.

So this issue looks mostly resolved by beta 4 unless there is still desire for a dict/deep-merge-style extra hook in addition to the typed DecisioningCapabilities request hook.

[bokelley]

Triage

Classification: Feature request — status update
Bucket(s): handlers
Status: ready-for-human

What changed: @bokelley confirms adcp==6.2.0b4 resolves both original items natively: status: "completed" is emitted unconditionally, and DecisioningPlatform.get_adcp_capabilities_for_request() covers dynamic per-tenant portfolio data. The webhook-signing validation gap is cleanly split to #875.

Open question for the team: Is there still value in a get_adcp_capabilities_extra(self, context: ToolContext) -> dict[str, Any] dict/deep-merge escape hatch alongside the typed request hook? The prior expert review found it sound (with fail-closed error semantics and protected-key guardrails on adcp, specialisms, supported_protocols, status), but if the typed path covers all known adopter use cases it's at most a forward-compat convenience. Worth closing this issue once that call is made; #875 is the live tracker for the remaining monkey-patch surface.

---

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

---

Generated by Claude Code

[bokelley]

Resolved on main for the release. Beta 4 now covers capabilities status and dynamic media-buy portfolio projection via request-aware capability construction. The remaining webhook_signing capabilities gap was split to #875 and closed by #876. Closing this unless we decide to track a separate dict/deep-merge extension hook later.