Skip to content

feat(adagents): inline-resolution path for publisher_properties selectors + directory inverse-lookup wrapper #749

Closed

Description

@bokelley

Two related pieces of SDK work coming out of adcp#4825 and adcp#4823.

Part 1 — Inline-resolution path for publisher_properties selectors

adcp#4825 (spec PR adcp#4827) endorses parent-file inline resolution: when a parent file's top-level properties[] entries carry a publisher_domain matching one in the selector's publisher_domains[], the consumer MAY satisfy the selector from those inline properties without per-child adagents.json fetches.

This SDK has two related bugs at adcp/adagents.py:953-957:

  1. Returns raw selector dicts instead of resolved properties. get_properties_by_agent(cafemedia_data, "https://interchange.io") returns 1 selector dict instead of the 6,843 inline properties.

  2. No publisher_domains[] fan-out. _resolve_agent_properties doesn't expand the compact-form publisher_domains[] array into per-domain resolution. This is the bug adcp#4825's triage identified as orthogonal to the spec change.

Both need fixing. The fix:

if authorization_type == "publisher_properties":
    selectors = agent.get("publisher_properties", [])
    if not isinstance(selectors, list):
        return []
    resolved: list[Property] = []
    parent_properties = adagents_data.get("properties", []) or []
    for selector in selectors:
        if not isinstance(selector, dict):
            continue
        domains = _selector_domains(selector)  # publisher_domain | publisher_domains
        for domain in domains:
            inline = _resolve_inline(selector, parent_properties, domain)
            if inline is not None:
                resolved.extend(inline)
                continue  # inline succeeded; skip federated fetch
            resolved.extend(_resolve_federated(selector, domain))
    return resolved

_resolve_inline returns None (not []) when no matched property carries the expected publisher_domain, so federated fallback fires. Empty inline match with at least one inline candidate counts as a real empty resolution.

Divergence rule (from spec): if both paths resolve to the same (publisher_domain, property_id) and disagree, federated wins; SDK SHOULD log the divergence.

Revocation: inline path MUST honor revoked_publisher_domains[] on the parent file.

Part 2 — Directory inverse-lookup wrapper

adcp#4823 (spec PR adcp#4828) defines GET /v1/agents/{agent_url}/publishers. SDK needs a wrapper:

def fetch_agent_authorizations_from_directory(
    agent_url: str,
    directory_url: str = "https://agenticadvertising.org",
    *,
    since: datetime | None = None,
    status: list[str] = ["authorized"],
    cursor: str | None = None,
    limit: int = 200,
    timeout: float = 30.0,
) -> AgentDirectoryLookup:
    """Inverse of fetch_agent_authorizations — returns the publishers
    that authorize this agent, sourced from the AAO directory's index.

    Mirrors the existing AdAgentsValidationResult provenance fields
    (discovery_method, manager_domain) so consumers can route directory-
    sourced and per-domain results through the same code path.
    """

Return type mirrors the response envelope schema. Iterator support for paginated responses is a plus.

Acceptance

Part 1:

  • get_properties_by_agent(cafemedia_data, "https://interchange.io") returns the 6,843 inline properties matching tags ∋ "raptive_managed" and publisher_domain ∈ publisher_domains[...], not the selector dicts.
  • publisher_domains[] compact form is fanned into per-domain resolution.
  • When inline and federated diverge, SDK logs the divergence and uses the federated result.
  • Parent-file revoked_publisher_domains[] revokes inline matches for that domain.

Part 2:

  • fetch_agent_authorizations_from_directory returns spec-conformant AgentDirectoryLookup with discovery_method, manager_domain, properties_authorized, properties_total, signing_keys_pinned, status, last_verified_at per publisher.
  • Cursor pagination handled transparently or exposed as iterator.
  • Reuses AdAgentsValidationResult provenance fields where the vocabulary overlaps.

References

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 20, 2026
  2. bokelley commented on May 20, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug (Part 1) + Feature request (Part 2)
    Bucket(s): client (no client label exists in this repo — gap noted)
    Status: drafting-pr (Part 1 shipped as #750) / clarify (Part 2 pending 3 questions below)

    What the experts said:

    • code-reviewer: Part 1 — buggy test encoded selector-passthrough behavior (fixed); by_id branch missing isinstance(str) filter (fixed); no dedup across multi-selector fan-out (fixed); missing by_id unit test (added). Part 2 — mutable default status=["authorized"] is a footgun; function must be async def to match the rest of the module.
    • ad-tech-protocol-expert: Part 1 inline path is spec-sound per adcp#4827; publisher_domains[] compact form is not in the 3.0 schema cache (needs regeneration after adcp#4827 merges). Part 2 — endpoint /v1/agents/{url}/publishers doesn't match the live /api/registry/ base already in the SDK; AgentDirectoryLookup return type is undefined; agent_url must be %-encoded in the path.

    My take: Part 1 is a clear bug fix with spec backing — draft PR #750 ships today. Part 2 has three unresolved protocol questions; implementing it now would produce a 404-ing endpoint wrapper with an undefined return type.

    Part 2 — 3 questions before I can proceed:

    1. Endpoint path: Is it /v1/agents/{encoded_url}/publishers or /api/registry/agents/{encoded_url}/publishers? The SDK's existing RegistryClient uses the /api/registry/ base — if /v1/ is a new tree on agenticadvertising.org, please link the changelog or confirm the route.

    2. Return type: Should AgentDirectoryLookup be a new Pydantic type (needs a schema file + _generated.py + stable.py export pipeline) or an extension/alias of the existing FederatedAgentWithDetails? The latter already carries publisher_domains: list[str] | None.

    3. Divergence rule: Is there a normative quote from adcp#4827 confirming "federated wins on disagreement"? The current PR defers divergence logging pending that confirmation — happy to add it once I can verify the trust-ordering direction.


    Part 1 shipped: #750

    Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}


    Generated by Claude Code

  3. added
    bugSomething isn't working
    enhancementNew feature or request
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 20, 2026
  4. bokelley commented on May 20, 2026

    @bokelley
    ContributorAuthor

    Refinements after merging adcp#4827 + adcp#4828 + adcp#4838 + adcp#4840

    Two additions to the work already scoped above:

    1. Canonical fixture: cafemedia.com / interchange.io

    After PR adcp#4840 deploys (the crawler write-path that fans publisher_properties[].publisher_domains[] into per-child rows), production has real data backing the inline-resolution path:

    • https://cafemedia.com/.well-known/adagents.json — 2.6 MB, 6,843 inline properties[], 6,800 unique child publisher_domains, all tagged raptive_managed. One authorized agent: https://interchange.io.
    • After the fan-out: GET https://agenticadvertising.org/api/v1/agents/https%3A%2F%2Finterchange.io/publishers returns ~6,800 rows with discovery_method='adagents_authoritative' and manager_domain='cafemedia.com'.

    Use this as the canonical fixture for the SDK's _resolve_agent_properties test suite — it's the production reference for the managed-network shape, sized large enough to catch O(N²) accidents and provenance edge cases.

    2. Part 3 — Divergence detector

    When the inline resolution path (Part 1) and federated resolution (per-child fetch) produce different (publisher_domain, property_id) sets, the spec says federated wins and the SDK SHOULD log a divergence warning (adagents.mdx Resolution paths). Today no consumer ever sees that signal because no one runs both paths.

    Add a verifier helper:

    def detect_publisher_properties_divergence(
        agent_url: str,
        directory_url: str = "https://agenticadvertising.org",
        *,
        sample_size: int | None = None,
        timeout: float = 30.0,
    ) -> DivergenceReport:
        """
        For each publisher_domain the directory returns under this agent_url:
        1. Read the directory's inline resolution result (counts + property_ids
           if `?include=properties` is supported, else just count).
        2. Fetch the publisher's own adagents.json directly.
        3. Apply the same selector against the child's properties[].
        4. Diff the (publisher_domain, property_id) sets.
    
        Returns: list of (publisher_domain, missing_in_inline, missing_in_federated,
        child_fetch_error) tuples. Empty list means no divergence detected.
    
        Intended use: periodic batch over a sales-agent operator's authorization
        set, surfacing publisher-side data-integrity warnings ("cafemedia claims
        site_X has property Y but site_X's own adagents.json doesn't").
        """

    sample_size is required for managed networks — running this against cafemedia's 6,800 children means 6,800 sequential HTTP fetches. Default to None (full sweep) but document the cost.

    Output should be machine-readable so a sales agent operator can hook it into their existing monitoring rather than reading SDK logs.

    This is Part 3 of the ticket — same SDK release as Parts 1 and 2.

    Updated acceptance

    Part 1 (inline resolution):

    • (covered above)
    • cafemedia.com / interchange.io fixture included in the test corpus; SDK returns ~6,843 properties for get_properties_by_agent(cafemedia_data, "https://interchange.io")

    Part 2 (directory wrapper):

    • (covered above)

    Part 3 (divergence detector):

    • detect_publisher_properties_divergence returns expected drift on a synthetic test fixture where parent and child disagree
    • Returns empty diff on cafemedia/interchange.io (production reference where parent and child are by-construction in agreement)
    • Documents the per-child fetch cost; sample_size parameter caps it
  5. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    and removed on May 20, 2026
  6. bokelley commented on May 20, 2026

    @bokelley
    ContributorAuthor

    Triage update — re-engaged on @bokelley's refinements comment

    New scope in the comment: cafemedia/interchange.io canonical fixture (Part 1), divergence detector (Part 3), and partial unblock of Part 2.

    What shipped:

    Part 1 additions → PR #750 (existing draft, new commits):

    • O(N×M) performance fix in _resolve_agent_properties: pre-builds a domain→properties index before the selector loop so each per-domain lookup is O(1) instead of O(N). At cafemedia scale (6,843 × 6,800 = 46 M comparisons without the index), the old code would have timed out in tests.
    • Cafemedia/interchange.io canonical fixture added to the test suite (6,843 inline properties across 6,800 raptive_managed child domains, publisher_domains[] compact form). Sized to catch O(N×M) regressions.

    Parts 2+3 → draft PR #752 (new):

    • fetch_agent_authorizations_from_directory — async wrapper for GET /api/v1/agents/{encoded_url}/publishers. Returns paged AgentDirectoryLookup + AgentPublisherEntry per publisher. Endpoint path confirmed by your comment; status uses repeated query params.
    • detect_publisher_properties_divergence — compares directory's properties_authorized count against per-child federated fetch. Returns DivergenceReport (list of PublisherDivergence). sample_size caps sweeps on large networks.
    • Known limitation (documented): directory currently returns counts, not property-ID lists. missing_in_inline / missing_in_federated are list[str] | None where None signals count-only mode. Count-equality ≠ set-equality (same-count property replacement is undetectable at this level). Will upgrade to full (publisher_domain, property_id) set-diff once ?include=properties is deployed.
    • All six new symbols exported from adcp.__init__.

    Part 2 questions (from prior triage), now resolved:

    • Q1 (endpoint path): /api/v1/agents/{encoded_url}/publishers ✓ confirmed by your comment
    • Q2 (return type): implemented as new AgentDirectoryLookup / AgentPublisherEntry dataclasses matching the schema fields from the issue acceptance criteria
    • Q3 (normative cite for "federated wins"): adcontextprotocol.org/docs/governance/property/adagents#resolution-paths ✓ confirmed by your comment

    What remains open:

    • Full (publisher_domain, property_id) set-diff in Part 3 (requires ?include=properties directory support)
    • revoked_publisher_domains[] revocation (deferred, pending schema definition)

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


    Generated by Claude Code

  7. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 20, 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