Skip to content

bug(decisioning): PlatformRouter/LazyPlatformRouter advertise optional tools no tenant implements, because every specialism method gets a delegate #1299

Closed

Description

@bokelley

Summary

On 8.0.0, PlatformRouter, LazyPlatformRouter and _RegistryPlatformAdapter synthesize a delegate for every method in _all_specialism_methods(). This happens in their constructors (adcp/decisioning/platform_router.py:441-451, :921-925, :1265-1270), whether or not any child platform implements the method.

PlatformHandler.advertised_tools_for_instance decides whether to advertise optional tools by checking callable(getattr(self._platform, adopter_name, None)). It does this for the legacy creative tools (adcp/decisioning/handler.py:1349-1351) and for compact lifecycle tools (handler.py:1319-1322). A router delegate is always callable, so a router advertises list_creative_formats even when every tenant is canonical-only.

When a buyer calls the tool, the router returns UNSUPPORTED_FEATURE. The SDK's own error message (platform_router.py:1048-1072) assumes the opposite of what happened: "The router advertises this method because at least one tenant supports it".

Reproduction (adcp 8.0.0)

import asyncio
import logging
import warnings

warnings.simplefilter("ignore")
logging.disable(logging.CRITICAL)

from adcp.decisioning import DecisioningCapabilities, DecisioningPlatform, LazyPlatformRouter, SingletonAccounts
from adcp.decisioning.serve import create_adcp_server_from_platform
from adcp.server.mcp_tools import create_tool_caller
from adcp.server.base import ToolContext

CAPS = DecisioningCapabilities(specialisms=["sales-non-guaranteed"], supported_billing=["operator"])
ACCOUNTS = SingletonAccounts(account_id="acct", metadata_factory=lambda: {"tenant_id": "t1"})


class Seller(DecisioningPlatform):  # canonical-only: no list_creative_formats_legacy / preview_creative_legacy
    capabilities = CAPS
    accounts = ACCOUNTS

    def get_products(self, req, ctx): return {"products": []}
    def create_media_buy(self, req, ctx): raise NotImplementedError
    def update_media_buy(self, media_buy_id, patch, ctx): raise NotImplementedError
    def sync_creatives(self, req, ctx): raise NotImplementedError
    def get_media_buy_delivery(self, req, ctx): raise NotImplementedError


router = LazyPlatformRouter(accounts=ACCOUNTS, factory=lambda tenant_id: Seller(), capabilities=CAPS)
direct, _, _ = create_adcp_server_from_platform(Seller())
routed, _, _ = create_adcp_server_from_platform(router)

legacy = {"list_creative_formats", "preview_creative"}
print("direct advertises:", sorted(legacy & direct.advertised_tools_for_instance()))
print("router advertises:", sorted(legacy & routed.advertised_tools_for_instance()))
print("router has delegate:", callable(getattr(router, "list_creative_formats_legacy", None)))


async def main():
    try:
        await create_tool_caller(routed, "list_creative_formats")({"adcp_version": "3.0"}, ToolContext())
    except Exception as exc:
        err = exc.errors[0] if hasattr(exc, "errors") else exc
        print("calling it via router:", getattr(err, "code", None), "|", getattr(err, "message", err))

asyncio.run(main())

Output:

direct advertises: []
router advertises: ['list_creative_formats']
router has delegate: True
calling it via router: UNSUPPORTED_FEATURE | AdcpError[UNSUPPORTED_FEATURE / terminal]: Tenant 't1''s platform (Seller) does not implement 'list_creative_formats_legacy'. The router advertises this method because at least one tenant supports it, but this tenant's platform doesn't.

Why an adopter hits this

Embedded Sales Agent serves a canonical-only creative surface through LazyPlatformRouter. Its tools/list advertised list_creative_formats, which every tenant then refused. build_router in core/main.py now deletes the synthetic delegate after construction: router.__dict__.pop("list_creative_formats_legacy", None). That works only because the delegate lives in the instance __dict__, which is an implementation detail. Any other optional method added to a specialism Protocol will over-advertise the same way.

Ask

  1. Let routers declare which optional methods their children implement. For example, LazyPlatformRouter(..., optional_methods={"list_creative_formats_legacy"}), defaulting to none for optional/legacy methods. The eager PlatformRouter can compute the set from its platforms.
  2. Or have the advertisement filter ask the router, through something like router.implements(method_name), instead of using callable(getattr(...)) on a synthesized delegate.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): handlers (no handlers label exists in this repo — flagged as gap)
    Status: ready-to-implement

    What the experts said:

    • code-reviewer: Option A (implements protocol) is non-breaking; compact lifecycle tool check at handler.py:1324-1325 has the identical flaw and must be patched in the same change — it is a second affected site, not a separate issue.
    • dx-expert: "Safe by default" (frozenset()) is the right default; prefers Option B (optional_methods attribute on all three routers, auto-computed for PlatformRouter, explicit kwarg for lazy routers) — avoids an asymmetric API surface where one router has a method the other doesn't; CHANGELOG entry required.

    My take: Both experts converge. Option B is the right shape: uniform optional_methods: frozenset[str] attribute on all three router classes, auto-derived for PlatformRouter from child platforms, declared at construction for LazyPlatformRouter/_RegistryPlatformAdapter. The handler reads the attribute duck-typically, falling through to the existing callable(getattr(...)) path for non-router platforms.

    Implementation scope:

    • src/adcp/decisioning/platform_router.py — add optional_methods attribute to PlatformRouter (auto-computed from _platforms at end of __init__), LazyPlatformRouter (optional_methods: frozenset[str] = frozenset() constructor param), and _RegistryPlatformAdapter (same); update the _platform_for error message at line ~489 to reflect the corrected invariant
    • src/adcp/decisioning/handler.py — patch both gating sites: lines 1324-1325 (compact lifecycle tools additive gate) and 1354-1356 (_OPTIONAL_LEGACY_WIRE_TO_ADOPTER prune); if platform has optional_methods, use method_name in platform.optional_methods; else fall through to existing callable(getattr(...)) check
    • CHANGELOG.md — document behavior change: canonical-only lazy routers no longer advertise list_creative_formats / preview_creative; migration path is optional_methods={"list_creative_formats_legacy"} for routers whose tenants implement the legacy surface
    • Tests — assert LazyPlatformRouter with a canonical-only platform does not advertise list_creative_formats; assert it does with optional_methods={"list_creative_formats_legacy"}

    Non-breaking rationale: New optional constructor param defaulting to frozenset(); existing non-router DecisioningPlatform subclasses are unaffected (handler path unchanged for them); behavioral correction for routers is the fix, not a regression.


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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions