__init__.py module docstring lists fewer error exports than `__all__` actually exposes

[dgenio]

Type

Documentation

Priority

P3

Newcomer impact

A newcomer who reads help(agent_kernel) (a natural first move) and the module's top-of-file docstring will think TokenRevoked, AdapterParseError, CapabilityAlreadyRegistered, and HandleConstraintViolation are not part of the public API. They are.

Evidence

• src/agent_kernel/__init__.py:36-42 — docstring's Errors:: block lists:

  AgentKernelError, TokenExpired, TokenInvalid, TokenScopeError,
  PolicyDenied, PolicyConfigError, DriverError, FirewallError,
  BudgetExhausted, BudgetConfigError,
  CapabilityNotFound, HandleNotFound, HandleExpired
  

• __all__ (__init__.py:139-155) also exports: TokenRevoked, AdapterParseError, CapabilityAlreadyRegistered, HandleConstraintViolation.
• Verified: python -c "from agent_kernel import HandleConstraintViolation; print(HandleConstraintViolation)" works fine.

Steps to reproduce

1. python -c "import agent_kernel; help(agent_kernel)" (or read the file).
2. Note the Errors:: block in the docstring omits four publicly-exported error classes.

Proposed fix

Add the four missing names to the Errors:: block in the module docstring at src/agent_kernel/__init__.py:36-42:

    from agent_kernel import (
        AgentKernelError,
        TokenExpired, TokenInvalid, TokenScopeError, TokenRevoked,
        PolicyDenied, PolicyConfigError,
        DriverError, FirewallError, AdapterParseError,
        BudgetExhausted, BudgetConfigError,
        CapabilityNotFound, CapabilityAlreadyRegistered,
        HandleNotFound, HandleExpired, HandleConstraintViolation,
    )

Implementation notes for AI

• Likely files to inspect/change: src/agent_kernel/__init__.py only.
• Relevant tests to add or update: optional — a tests/test_public_api.py that asserts every name in __all__ also appears in the module docstring would prevent future drift.
• Edge cases: keep the docstring grouped by topic the way it is.

Acceptance criteria

• Every error name in __all__ either appears in the docstring's Errors:: block or is intentionally omitted (with a comment explaining why).
• Diff is doc-only.

Duplicate check

Searched open issues for: __all__, public API, docstring, TokenRevoked, HandleConstraintViolation.
Result: no open duplicate.