feat(events): events + subscriptions top-level command groups (PR-1b)

[mikemolinet]

Summary

Adds two top-level command groups for the event-emit primitive — third + final layer of PR-1b parity (cueapi-core #71 merged @ 03:53Z; cueapi-python #38 merged @ 03:55Z; this is the cli).

• cueapi events list <ref> — pull events for an agent
• cueapi subscriptions create <ref> — create a subscription
• cueapi subscriptions list <ref> — list active subscriptions
• cueapi subscriptions delete <ref> <subscription-id> — soft-detach

Closes Backlog row cmp0h2nzd000204l8acl5j6w0.

Top-level vs agents-nested

Top-level groups per primary's kickoff doc suggestion. Events + subscriptions are conceptually distinct primitives, not agent metadata. Same pattern as top-level messages and executions groups (also user-scoped operations on a sub-resource).

CLI architecture note

This port uses cueapi-cli's own httpx-based CueAPIClient, NOT the cueapi-python SDK. The kickoff doc said the cli port "uses cueapi-python SDK so blocked on #2 landing" — that's incorrect re: the actual cli architecture. cli has its own client.py with no runtime dependency on cueapi-python. cli port is INDEPENDENT of python SDK timing.

(Flagged to PM in the earlier status cue.)

Wire format pinned

Command	HTTP
events list	GET /v1/agents/{ref}/events?limit=100[&since=N&event_type=X]
subscriptions create	POST /v1/agents/{ref}/subscriptions body {event_type, delivery_target, webhook_url?}
subscriptions list	GET /v1/agents/{ref}/subscriptions
subscriptions delete	DELETE /v1/agents/{ref}/subscriptions/{id} (idempotent)

Client-side guards

• subscriptions create: --webhook-url required when --delivery-target=webhook. Raised as click.UsageError at parse time vs letting server 400.
• Both subscriptions create and events list surface 404 agent-not-found with friendly error messages.

One-shot webhook secret discipline

When subscriptions create --delivery-target=webhook returns a webhook_secret, the cli surfaces it with "save now — only shown once" labeling. Same pattern as the existing agents webhook-secret regenerate command.

Tests

12 new tests in tests/test_cli.py:

• events list: basic, with --since + --event-type, defaults only limit, 404 agent not found
• subscriptions create: pull-minimal, webhook-with-url, webhook-without-url errors client-side
• subscriptions list: basic, empty
• subscriptions delete: basic
• Help: events lists list subcommand, subscriptions lists create/list/delete

12 passed, 179 deselected

Full suite: 191 tests pass, zero regressions.

Depends on

• cueapi-core PR #71 (merged 2026-05-11 03:53Z, commit 50d2b2c2)
• cueapi-python PR chore(parity-manifest): reflect 2026-05-04 parity wave shipped state #38 (merged 2026-05-11 03:55Z, commit 72fb628e) — not a runtime dep, but completes the SDK side

Test plan

• 12 new tests pass locally
• Verified server contract (POST/GET/DELETE shapes + query semantics)
• Client-side guards (webhook-url required, mutex enforcement)
• 404 friendly error
• Idempotent DELETE handled
• CI green
• Admin-merge per agents-merge-own-PRs directive

🤖 Generated with Claude Code