Export the error-details models from adcp.types (14 of 15 are unreachable outside generated_poc)

[KonstantinMirin]

Summary

adcp/types/generated_poc/error_details/ contains a generated pydantic model for every
error-details/*.json schema in the bundle — 15 modules, e.g. ActionNotAllowedDetails,
AgentPermissionDeniedDetails, StaleResponseDetails, VersionUnsupportedDetails. Only
one of them, AuthorizationRequiredDetails, is re-exported from adcp.types:

from adcp.types import AuthorizationRequiredDetails   # works
from adcp.types import ActionNotAllowedDetails        # ImportError

Verified against adcp==6.6.0 / spec 3.1.1. dir(adcp.types) yields exactly one name
ending in Details, and the generated_poc path is documented as not-for-consumers.

Please export the rest.

Why a consumer needs them

error.details is typed dict on the Error model, so nothing at a raise site
constrains what goes in it. Five of these schemas declare required fields —
action-not-allowed (attempted_action, reason), agent-permission-denied
(scope, reason), billing-not-permitted-for-agent (rejected_billing),
stale-response (served_from_cache, cache_age_seconds), version-unsupported
(supported_versions) — and a seller that wants a missing required key to be a
typecheck error rather than a runtime surprise needs the model at the call site.

The models already exist and already encode exactly that. They are simply unreachable,
so every consumer that wants this has to re-declare them locally and then maintain a
guard asserting the local copy still matches the bundle schema — a transcription of
something you already ship, kept in sync by hand.

This is a small, additive change: the models are generated, the schemas are in the
bundle, and AuthorizationRequiredDetails already establishes the precedent for
exporting one.

Suggested shape

Re-export all 15 from adcp/types/__init__.py alongside AuthorizationRequiredDetails.
If a stable public name is wanted for the family, an adcp.types.error_details
subpackage re-exporting them would work equally well for consumers — the requirement is
just that they are importable from a supported path.

Note on extra

The generated models carry extra="allow", which is right for these: several of the
schemas omit additionalProperties, so draft-07 permits extension keys, and a seller
adding diagnostic fields should not be rejected. Two of the schemas do declare
additionalProperties: false; if the generator can reflect that as extra="forbid" on
just those two, the models would carry the distinction the schemas make. Not a blocker
for exporting them.

Related

• Reserve RootModel for value types: RootModel wrappers make extra-field policy unsettable by consumers #1077 — RootModel wrappers make extra policy
  unsettable by consumers. Same underlying theme: the generated types encode the spec
  correctly, but consumers cannot reach or adjust them.

[bokelley]

Triage

Classification: Bug
Bucket(s): client (adcp.types public surface)
Status: ready-to-implement

What the experts said:

• code-reviewer: Bug, not enhancement — AuthorizationRequiredDetails and UnsupportedRefinementDimensionDetails establish an unambiguous export precedent; 16 sibling classes from the same generated_poc/error_details/ family are simply missing. Change is purely additive (no existing imports disturbed); test_lazy_types.py provides a built-in completeness check that will fail if the three locations aren't updated atomically.
• dx-expert: Clear yes — error.details typed as dict means every consumer who constructs a structured error payload must re-declare the model locally; exporting from adcp.types (not a subpackage) matches the established pattern and removes the maintenance burden.

My take: The internal count is 18 error-details modules (the issue says 15, spec may have grown). All 16 unexported classes should be added in one PR; _generated.py already imports all of them, so this is a two-file wiring change. The single naming outlier is VendorErrorCodeRegistry (from vendor_error_codes.py) — the implementer should confirm whether ActionNotAllowedReason (an enum dependency already present in _generated.__all__) should be co-exported alongside ActionNotAllowedDetails.

Implementation scope:

• Files to change (only these two): src/adcp/types/_eager.py and src/adcp/types/__init__.py
• Three locations must be updated atomically or test_lazy_types.py will fail:
  1. _eager.py — add the 16 names to the from adcp.types._generated import (...) block and to _eager.__all__
  2. __init__.py — add the same 16 names to __all__
  3. __init__.py — add the same 16 names to the TYPE_CHECKING re-export block (mypy sees only this path)
• Classes to add (already in _generated.py at lines 1955–1997): AccessibilityViolationDetails, AccountMovedDetails, AccountSetupRequiredDetails, ActionNotAllowedDetails, AgentPermissionDeniedDetails, AudienceTooSmallDetails, BillingNotPermittedForAgentDetails, BillingNotSupportedDetails, BudgetTooLowDetails, ConflictDetails, CreativeRejectedDetails, PolicyViolationDetails, RateLimitedDetails, StaleResponseDetails, VendorErrorCodeRegistry, VersionUnsupportedDetails
• Required checks: make lint && make typecheck-all && pytest tests/test_lazy_types.py tests/test_import_layering.py (no generated-file edits needed)
• Non-breaking rationale: purely additive — new names in __all__, no existing symbols changed or removed

---

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

---

Generated by Claude Code

[KonstantinMirin]

Hi, of course it should be exported. How else would one create an object with that enum?One wants an error detail class for every error detail defined in the spec with the fields typed so that the proper enums or classes could be used to populate it.Sent from my iPhoneOn 24.08.2026., at 22:43, bokelley ***@***.***> wrote:bokelley left a comment (adcontextprotocol/adcp-client-python#1080) Triage Classification: Bug Bucket(s): client (adcp.types public surface) Status: ready-to-implement What the experts said: code-reviewer: Bug, not enhancement — AuthorizationRequiredDetails and UnsupportedRefinementDimensionDetails establish an unambiguous export precedent; 16 sibling classes from the same generated_poc/error_details/ family are simply missing. Change is purely additive (no existing imports disturbed); test_lazy_types.py provides a built-in completeness check that will fail if the three locations aren't updated atomically. dx-expert: Clear yes — error.details typed as dict means every consumer who constructs a structured error payload must re-declare the model locally; exporting from adcp.types (not a subpackage) matches the established pattern and removes the maintenance burden. My take: The internal count is 18 error-details modules (the issue says 15, spec may have grown). All 16 unexported classes should be added in one PR; _generated.py already imports all of them, so this is a two-file wiring change. The single naming outlier is VendorErrorCodeRegistry (from vendor_error_codes.py) — the implementer should confirm whether ActionNotAllowedReason (an enum dependency already present in _generated.__all__) should be co-exported alongside ActionNotAllowedDetails. Implementation scope: Files to change (only these two): src/adcp/types/_eager.py and src/adcp/types/__init__.py Three locations must be updated atomically or test_lazy_types.py will fail: _eager.py — add the 16 names to the from adcp.types._generated import (...) block and to _eager.__all__ __init__.py — add the same 16 names to __all__ __init__.py — add the same 16 names to the TYPE_CHECKING re-export block (mypy sees only this path) Classes to add (already in _generated.py at lines 1955–1997): AccessibilityViolationDetails, AccountMovedDetails, AccountSetupRequiredDetails, ActionNotAllowedDetails, AgentPermissionDeniedDetails, AudienceTooSmallDetails, BillingNotPermittedForAgentDetails, BillingNotSupportedDetails, BudgetTooLowDetails, ConflictDetails, CreativeRejectedDetails, PolicyViolationDetails, RateLimitedDetails, StaleResponseDetails, VendorErrorCodeRegistry, VersionUnsupportedDetails Required checks: make lint && make typecheck-all && pytest tests/test_lazy_types.py tests/test_import_layering.py (no generated-file edits needed) Non-breaking rationale: purely additive — new names in __all__, no existing symbols changed or removed Triaged by Claude Code. Session: https://claude.ai/code/session_01ESj4BDECaB5A3UBPyFYiev Generated by Claude Code —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>