feat(client): looksLikeV3Capabilities — drop the v2-downgrade footgun on capabilities-validation failure

[bokelley]

Parent: #452

JS source

6.6.0 commit 27bd79d fix(client): don't downgrade obvious v3 agents to v2.

Bug class

SingleAgentClient.get_capabilities() falls back to v2 synthetic capabilities on any failure. This causes confusing "AdCP schema data for version v2.5 not found" cascades when a v3 agent has a single shape bug — e.g. one missing field on Account. The user sees a v2 error trail with no obvious connection to the actual v3 validation failure.

Fix

Tighten the heuristic — when result.success is False but result.data is structurally v3-shaped, parse anyway, surface the validation failure loudly, continue with v3 caps. Don't silently downgrade.

looks_like_v3_capabilities(data) heuristic: presence of v3-only fields (e.g., governance_agents, v3-shaped pricing_options, etc.) on the response shape.

Port the same heuristic from JS to Python's client.

Acceptance criteria

• looks_like_v3_capabilities helper in client.
• SingleAgentClient.get_capabilities() no longer silently downgrades to v2 when input is obviously v3.
• Surfaces the v3 validation error directly.
• Tests cover: clean v3 (passes), v3 with one shape bug (loud v3 error, no v2 cascade), genuine v2 (downgrades correctly).

[bokelley]

Triage

Classification: Bug (backport of JS 6.6.0 fix 27bd79d)
Bucket(s): client
Status: drafting-pr

What the experts said:

• code-reviewer: approved after fixing two blockers — TypeError guard on unhashable supported_protocols items; is_v3_capabilities_shape missing from __all__
• dx-expert: approved — naming (is_v3_capabilities_shape matches is_ predicate convention), suggestion-string double-label stripped before merge, "schema bug" wording softened

My take: Clear non-breaking fix. is_v3_capabilities_shape is a new public function (additive) and refresh_capabilities() raises the same ADCPError type with a more specific message — existing except ADCPError callers are unaffected. Draft PR opened at #470.

PR summary: Adds is_v3_capabilities_shape(data) heuristic to capabilities.py (exported from adcp), threads raw response data through _parse_response() metadata on ValueError, and uses both in refresh_capabilities() to surface a v3-specific error with the Pydantic field path in the suggestion field instead of an opaque generic failure.

---

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

---

Generated by Claude Code