feat: add cueapi agents command group (messaging primitive — identity + inbox + sent)

[mikemolinet]

Summary

First half of the messaging-primitive CLI port. Closes the Messaging primitive endpoints_missing entry in cueapi-cli #25's manifest by exposing the entire /v1/agents API surface as a cueapi agents command group.

The complementary cueapi messages group (send / get / read / ack for the message lifecycle) ships in a follow-up PR for review-burden reasons (per CTO call to keep parity-port PRs small).

Commands shipped (9)

Command	Endpoint	Notes
cueapi agents create	POST /v1/agents	Webhook secret is shown ONLY in this response when --webhook-url is set; UI copy says "save now — only shown once"
cueapi agents list	GET /v1/agents	filters: --status / --include-deleted / --limit / --offset
cueapi agents get	GET /v1/agents/{ref}	renders metadata pretty-printed; null webhook_url renders as — (poll-only) so push-vs-poll is visible at a glance
cueapi agents update	PATCH /v1/agents/{ref}	--webhook-url and --clear-webhook-url are mutually exclusive; the latter sends literal JSON null
cueapi agents delete	DELETE /v1/agents/{ref}	soft delete; confirmation prompt unless --yes
cueapi agents webhook-secret get	GET /v1/agents/{ref}/webhook-secret	reveal current secret
cueapi agents webhook-secret regenerate	POST /v1/agents/{ref}/webhook-secret/regenerate	confirmation warns current secret will be revoked immediately
cueapi agents inbox	GET /v1/agents/{ref}/inbox	filters: --state / --limit / --offset
cueapi agents sent	GET /v1/agents/{ref}/sent	filters: --limit / --offset

Design notes worth flagging

• --clear-webhook-url sends literal JSON null, not field omission. The server uses model_fields_set to disambiguate "field omitted = no change" vs "field explicitly null = clear." The CLI matches by sending {"webhook_url": null} in the patch body when --clear-webhook-url is present. Pinned by a dedicated test so a future refactor can't silently collapse the two semantics.

• --include-deleted is a flag, only sent when True. Same pattern as executions list --has-evidence (PR feat: add executions-list filters — outcome-state / result-type / has-evidence / triggered-by #27): omit when False rather than send false (which would mean the same thing server-side but adds URL noise).

• --webhook-url and --clear-webhook-url are mutually exclusive. Click UsageError enforced before any HTTP call.

• Webhook-secret one-time view. Both agents create (when --webhook-url is set) and agents webhook-secret regenerate print the secret with explicit copy: "save now — only shown once." Matches the server's behavior of populating webhook_secret only on those two responses.

Tests

24 new (36 → 60 total). Mock-based body / params capture mirroring PR #26 + #27's _FakeClient pattern. Pinned behaviors:

• agents_create minimal vs all-optional body shape
• --include-deleted only sent when True
• --clear-webhook-url sends explicit null (key present, value None)
• --webhook-url + --clear-webhook-url mutex enforced
• Delete confirmation prompt path + abort path
• Webhook-secret one-time-view UI copy is rendered
• Inbox / sent rendering of common message shape

All 60 pass locally.

No hosted-PR dependency

All 9 endpoints already shipped on prod via Phase 12.1 messaging primitive (per MEMORY.md). Pure CLI catch-up.

Test plan

• python3 -m pytest tests/test_cli.py -q → 60 passed
• Manual smoke against staging: cueapi agents create --display-name "test" → confirm 201 + slug derived; cueapi agents list → confirm renders; cueapi agents update <ref> --clear-webhook-url → confirm webhook_url cleared on subsequent get

Parity Impact

Closes endpoints_missing.Messaging primitive from cueapi-cli #25's parity-manifest.json (partial — agents portion only). Manifest update follows after #25 merges to main, alongside the cueapi messages follow-up PR.

🤖 Generated with Claude Code

[govindkavaturi-art]

Comprehensive cueapi agents group port. Quality details: webhook-secret one-time-view UX (save now — only shown once), --include-deleted only sent when true (URL hygiene), idiomatic click patterns. Approve.