Skip to content

bug(adagents): agent URL matching ignores host case and default ports, crashes on a non-string url, and can't report "listed but unbound" #1307

Closed

Description

@bokelley

Summary

On 8.0.0, get_properties_by_agent / resolve_properties_for_agent match agents through adcp.adagents.normalize_url. That function drops the scheme and trailing slash but keeps host case and explicit default ports. The SDK already has a stricter canonicalizer, adcp.canonical_formats.identity.canonicalize_agent_url, which lowercases the host and strips :443/:80; the adagents helpers just don't use it.

Two related gaps in the same code path:

  • one authorized_agents entry with a non-string url raises AttributeError for every lookup in the file;
  • the resolvers return [] both when the agent is listed with a selector that matches nothing and when the agent isn't listed at all.

Reproduction (adcp 8.0.0)

from adcp import get_properties_by_agent
from adcp.adagents import normalize_url
from adcp.canonical_formats.identity import canonicalize_agent_url

AGENT = "https://sales.example.com/mcp"
PROPS = [{"property_id": "site", "property_type": "website", "name": "Site",
          "identifiers": [{"type": "domain", "value": "pub.example"}], "tags": ["all"]}]


def entry(url, tags):
    return {"url": url, "authorized_for": "x", "authorization_type": "property_tags", "property_tags": tags}


# 1. URL equivalence
for url in ("https://Sales.Example.com/mcp", "https://sales.example.com:443/mcp"):
    print(f"normalize_url={normalize_url(url)!r}  canonicalize_agent_url={canonicalize_agent_url(url)!r}")
listed = {"authorized_agents": [entry(AGENT, ["all"])], "properties": PROPS}
print("same agent, host case + :443 ->", len(get_properties_by_agent(listed, "https://SALES.example.com:443/mcp")), "properties")

# 2. Listed but unbound vs not listed
unbound = {"authorized_agents": [entry(AGENT, ["no-such-tag"])], "properties": PROPS}
unlisted = {"authorized_agents": [entry("https://other.example/mcp", ["all"])], "properties": PROPS}
print("listed but unbound ->", get_properties_by_agent(unbound, AGENT))
print("not listed         ->", get_properties_by_agent(unlisted, AGENT))

# 3. One malformed sibling entry breaks resolution for every agent
bad = {"authorized_agents": [entry(["https://oops.example"], ["all"]), entry(AGENT, ["all"])], "properties": PROPS}
try:
    get_properties_by_agent(bad, AGENT)
except Exception as exc:
    print("non-string sibling url ->", type(exc).__name__, "|", exc)

Output:

normalize_url='Sales.Example.com/mcp'  canonicalize_agent_url='https://sales.example.com/mcp'
normalize_url='sales.example.com:443/mcp'  canonicalize_agent_url='https://sales.example.com/mcp'
same agent, host case + :443 -> 0 properties
listed but unbound -> []
not listed         -> []
non-string sibling url -> AttributeError | 'list' object has no attribute 'decode'

fetch_adagents accepts a file like bad, because validate_adagents (adcp/validation/legacy.py:264) never checks the url type. The crash therefore reaches callers through the normal fetch-then-resolve path.

Code: normalize_url (adcp/adagents.py:420-431); matching loop in _resolve_properties_for_agent (adagents.py:1902-1917); the same normalize_url comparison in verify_agent_authorization (adagents.py:558-570).

Why an adopter hits this

Embedded Sales Agent keeps src/services/_adagents_shapes.py (206 LOC) in front of the SDK resolver:

  • normalize_agent_url_for_compare lowercases the host and strips default ports, because tenant-configured agent URLs and storefront-canonicalized URLs differ only in those ways;
  • find_agent_entry drives a separate "listed but not bound" state in the publisher-partner UI. That state needs different publisher outreach from "not listed".
  • _adagents_with_string_agent_urls deep-copies the file and drops entries whose url isn't a string, so one bad row doesn't take down every lookup.

Without these, a publisher that authorized ESA shows as unauthorized, and a single typo in someone else's entry makes the whole file unusable.

Ask

  1. Match agent URLs with RFC 3986 equivalence (host case, default port) in the adagents resolvers, e.g. by reusing canonicalize_agent_url's rules inside normalize_url.
  2. Skip, or report through validate_adagents_structure, entries whose url isn't a non-empty string, rather than raising AttributeError.
  3. Add a public lookup that returns the matching entry or entries for an agent (e.g. find_authorized_agent_entries(adagents, agent_url)), or a resolution result carrying listed: bool alongside the properties.

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): client (note: client and validation labels don't exist in this repo — gap noted in run summary)
    Status: ready-to-implement
    Milestone: omitted (no target version specified)

    What the experts said:

    • ad-tech-protocol-expert: All three bugs confirmed; Bugs 1 and 2 are spec-compliance/crash blockers and non-breaking; Bug 3 is an additive client-convenience nit — all patch-level, no RFC needed.
    • code-reviewer: Concurs on all three. Flags one implementation nuance for Bug 1: canonicalize_agent_url returns a full URL with scheme, but the existing protocol-agnostic matching (http://… matches https://…) depends on normalize_url stripping the scheme. A naive replacement breaks test_get_properties_by_agent_protocol_agnostic. Also notes zero direct unit tests for normalize_url itself, and no lookup-path tests for Bug 2.

    My take: The report is precise and well-scoped. Bugs 1 and 2 share the same two loop sites and should ship together. Bug 3 (new find_authorized_agent_entries helper) can ride the same PR or follow independently.

    Implementation brief:

    • Bug 1 — RFC 3986 host/port normalization in matching loops. In both verify_agent_authorization (line 570) and _resolve_properties_for_agent (line 1915), replace normalize_url(agent_url_from_json) != normalized_agent_url with a comparison over canonicalize_agent_url — but preserve scheme-stripping for protocol-agnostic matching. Correct pattern: canonicalize_agent_url(url) then re-extract netloc + path (i.e., the existing urlparse step applied to the canonical URL, not the raw one). The normalize_url helper can stay for display/redirect paths; only the comparison call sites need updating. Required checks: add tests for normalize_url("https://SALES.Example.com:443/mcp") == normalize_url("https://sales.example.com/mcp") and for get_properties_by_agent with an uppercase-host entry matched by a lowercase-host caller URL.

    • Bug 2 — Guard non-string url in both loops. After agent_url_from_json = agent.get("url", ""), add if not isinstance(agent_url_from_json, str) or not agent_url_from_json: continue at both sites (adagents.py:565 and adagents.py:1911). Optionally add a url type check to validate_adagents in adcp/validation/legacy.py:264 to surface the structural error before lookup. Required: add a test that a non-string url entry does not crash get_properties_by_agent or resolve_properties_for_agent.

    • Bug 3 — New public find_authorized_agent_entries function. Add find_authorized_agent_entries(adagents_data, agent_url) -> list[dict] to adcp/adagents.py (and re-export from adcp/__init__.py). Extract the URL-matching loop from _resolve_properties_for_agent into this new function and have the private helper call it. Purely additive — no changes to any existing signature. Add to the public-API test matrix.

    All three items are non-breaking at the patch level. Suggested PR title: fix(adagents): RFC 3986 URL equivalence, non-string url guard, find_authorized_agent_entries.


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

  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