feat: add AgentsResource (messaging primitive identity surface)

[mikemolinet]

Summary

Wraps the entire /v1/agents surface from the messaging primitive (Phase 12.1.5). Closes the agents portion of the Messaging primitive endpoints_missing entry in cueapi-python #24's parity manifest.

The companion MessagesResource (send/get/read/ack lifecycle) ships in a follow-up PR for review-burden reasons. Both PRs are independent (different files, different test classes) and can land in either order.

Surface

client.agents exposes:

Method	Endpoint
.create(display_name, slug=None, webhook_url=None, metadata=None)	POST /v1/agents
.list(status=None, include_deleted=False, limit=50, offset=0)	GET /v1/agents
.get(ref, include_deleted=False)	GET /v1/agents/{ref}
.update(ref, ...)	PATCH /v1/agents/{ref}
.delete(ref)	DELETE /v1/agents/{ref}
.webhook_secret_get(ref)	GET /v1/agents/{ref}/webhook-secret
.webhook_secret_regenerate(ref)	POST /v1/agents/{ref}/webhook-secret/regenerate
.inbox(ref, state=None, ...)	GET /v1/agents/{ref}/inbox
.sent(ref, ...)	GET /v1/agents/{ref}/sent

Client extension

client._request now accepts an optional headers kwarg. Extends (doesn't replace) the client's default Authorization + Content-Type + User-Agent. Used here for the X-Confirm-Destructive guard; will also be used by the upcoming MessagesResource for X-Cueapi-From-Agent + Idempotency-Key. Backwards-compatible (existing callers don't change).

Design notes pinned by tests

• include_deleted=True sends \"true\", False (default) omits. Same omit-when-default pattern as the executions-list filters and cueapi-cli's similar flags. Pinned by test_include_deleted_only_sent_when_true.

• clear_webhook_url=True sends literal JSON null, not field omission. Server uses model_fields_set to disambiguate "omitted = no change" from "explicit null = clear," so the SDK MUST send the key with explicit None. Pinned by test_clear_webhook_url_sends_explicit_null. Mirror of cueapi-cli feat: add MessagesResource (messaging primitive lifecycle) #28's --clear-webhook-url.

• webhook_url + clear_webhook_url mutex enforced with a clear ValueError before any HTTP call.

• webhook_secret_regenerate adds X-Confirm-Destructive: true automatically. The server requires it; the SDK handles it so callers don't have to know about the header. Pinned by test_regenerate_sends_destructive_header.

Tests

18 new across 9 test classes. Mock-based, mirrors the existing ExecutionsResource test pattern. All 46 unit tests pass (excluding the pre-existing test_cues.py staging-cred flake which is captured in a separate Backlog item).

No hosted-PR dependency

All 9 endpoints already shipped on prod via Phase 12.1 messaging primitive (per MEMORY.md / CLAUDE.md).

Companion PRs from this session

• #25 — mark_verified bug fix + replay()
• #26 — WorkersResource + UsageResource
• (next) MessagesResource — message lifecycle, separate PR

🤖 Generated with Claude Code

[govindkavaturi-art]

AgentsResource wraps the messaging-primitive identity surface. The headers param plumbed through _request() is the right place to add support for X-Cueapi-From-Agent / X-Idempotency-Key passthrough. Approve.