feat: add typed Python SDK

[fly1d]

Summary

• add a synchronous typed Python client for health, agent lifecycle, approvals, and audit APIs
• return the existing Pydantic public contract models and expose the client from the package root
• support optional bearer authentication and caller-injected httpx.Client transports
• distinguish structured API, transport, and invalid-response failures
• publish PEP 561 typing metadata and document a first integration workflow

Closes #17.

Risk classification

Medium. This adds an SDK and promotes httpx from a development-only dependency to a runtime dependency. It does not change server behavior, storage, or HTTP schemas.

Review focus

• method and model coverage matches every current API operation
• all non-2xx responses become stable API errors, including redirects and unstructured proxy failures
• bearer tokens are confined to request headers and not included in exception messages
• injected HTTP clients remain caller-owned; internally created clients are closed by the SDK
• writes are not automatically retried while server-side idempotency is unavailable
• wheel includes client.py and py.typed for external type checkers

Evidence

• make check: 37 passed, 1 PostgreSQL integration test skipped without a database; 98.02% coverage
• strict Ruff and Mypy checks pass
• MockTransport tests cover the complete API surface, query serialization, authentication headers, ownership, structured/unstructured/redirect errors, transport failures, and invalid contracts
• built wheel contains agent_control_plane/client.py and agent_control_plane/py.typed
• clean virtual environment installs the wheel and executes a typed SDK request
• real FastAPI smoke completed register -> activate -> approval -> decision -> audit, producing revision 2 and four audit events

Compatibility and rollback

• additive package API; existing imports and server behavior are unchanged
• httpx>=0.28,<1 moves to required dependencies because the distributed SDK imports it
• rollback is the previous package version; no database or data migration is involved

Remaining risks

• synchronous client only; an async client can be added after validated demand
• no automatic pagination because current endpoints return bounded response pages
• no automatic retries or idempotency keys yet
• SDK version remains coupled to the service package until separate distribution is justified

[fly1d]

Final technical review completed after all required CI checks passed.

Findings resolved before submission:

• Python 3.12 generic syntax was replaced with Python 3.11-compatible overloads and TypeVar
• all non-2xx responses, including redirects, now become stable API errors instead of response-contract errors
• py.typed was added and verified inside the built wheel so external type checkers consume SDK annotations
• path parameters are URL-escaped and HTTP client ownership is explicit
• the SDK deliberately avoids write retries until server-side idempotency exists

No unresolved blocking code findings remain. The wheel was installed in a clean virtual environment, and the SDK completed a real register -> activate -> approval -> decision -> audit flow against the FastAPI service.

Merge remains pending the independent approval required for medium-risk changes by docs/QUALITY_GATES.md.

[fly1d]

Solo-maintainer owner decision

• Risk: medium; adds a public SDK adapter and moves httpx from development-only to runtime dependencies, without changing server API or database state.
• Final material push: 2026-08-12 01:44 UTC.
• Earliest merge: 2026-08-13 01:44 UTC. The 24-hour cooling period has elapsed.
• Rebase on 2026-08-14 changed only the base and retained both additive changelog entries; it did not change SDK behavior, dependencies, contracts, or risk analysis, so the cooling period did not reset.
• Evidence: rebased make check passed with 39 tests passing, 1 local PostgreSQL skip, and 98.32% coverage; a real HTTP SDK flow passed from readiness through four audit events. Clean-wheel and package-content evidence is recorded in the earlier technical review.
• Failure mode: an ambiguous write timeout could tempt callers to retry and duplicate a write. The client intentionally performs no write retries and README documents state inspection until server idempotency exists.
• Rollback: revert the squash commit and remove the additive SDK exports; no schema or stored-state migration is involved.
• Owner decision: merge after all rebased GitHub CI checks pass.

This decision follows the solo-maintainer policy merged in #23.