feat: port cueapi PR #630 — Agent Directory roster + describe MCP tools

[mikemolinet]

Summary

Phase A of the Agent Directory productization (PRD: trydock.ai/mike/agent-directory-productization-prd). Ports cueapi PR #630 (OPEN at port time per CTO greenlight) — surfaces the new GET /v1/agents/roster + the existing GET /v1/agents/{name} as MCP tools so the LLM can discover peers natively instead of remembering 6+ fields per recipient.

Branch base: feat/parity-port-619-message-bcc-light (PR #25). The new test stub client signature from #25 (extraHeaders) is reused; rebases cleanly to main once #25 merges.

What this PR adds

Tool	Endpoint	Notes
cueapi_agents_list	GET /v1/agents/roster	NEW per cueapi PR #630. Display-optimized snapshot: always-full list, drops opaque IDs, derived online/last_seen_relative/preferred_contact. Server-side ETag/304 (delegated to client).
cueapi_agents_describe	GET /v1/agents/{name}	Existing endpoint; just hadn't been wrapped. Richer management view (webhook_url, full metadata).
cueapi_send_message (description tightened)	POST /v1/messages	Now references cueapi_agents_list as the discovery primitive + positions itself as "the natural primitive for inter-agent comm" per PRD §Migration.

Why this matters (PRD context)

The 2026-05-04 silent-drop incident (CMA's outbound replies dropped for 24h on wrong task name) was the trigger for the PRD. The 6-field cue-fire dance + no roster discovery meant agents had to memorize cue_id + task name + payload_override shape per recipient. With these tools the LLM:

1. Calls cueapi_agents_list once → sees all peers + their reachability state.
2. Picks recipient by name → calls cueapi_send_message with to: <name>.
3. Server resolves routing internally — no cue_id, no task name extrapolation.

Surface 5 (session-boot prompt-injection) shipped end-to-end on the cue-mac-app side at commit ee31508 with a manually-curated stub roster. When cueapi PR #630 merges + this PR ships in a new cueapi-mcp release, cue-mac-app's Desktop poller (5min cadence) calls cueapi_agents_list and writes the response to the local roster file — replacing the stub with live data. The handler-template prompt-injection already shipped reads the roster automatically; no further handler change needed.

Tests

5 new (46 → 51 in tests/tools.test.ts, 92/92 total pass across all 5 test files):

Test	What it pins
agents_list uses GET /v1/agents/roster (NOT /v1/agents)	Critical: /v1/agents/roster is the prompt-injection surface; /v1/agents is the management list (paginated, tenancy metadata). Don't confuse them.
agents_list takes no parameters (no pagination, no filters)	PR #630 spec: always-full list. Future client trying to filter shouldn't slip through.
agents_describe uses GET /v1/agents/{name}	Path + method pinning.
agents_describe URL-encodes the name in the path	Slug-form agt_pm@mike needs @ encoded — verify URL-encoding works for cross-tenant slugs.
agents_describe rejects empty name at the schema layer	Zod min(1) before HTTP.

$ npm test
Test Files  5 passed (5)
     Tests  92 passed (92)

$ npm run build
(clean)

Placeholder caveats

PR #630 was OPEN at port time. Self-described response shape in the PR description + diff is stable. Tests pin path/method but not field shape (handler is pure passthrough — when the server PR shape evolves, tools forward whatever the server returns). If PR #630 lands with a meaningfully different shape, this PR can be revised before its own merge.

Parity manifest

• endpoints_covered: GET /v1/agents/roster + GET /v1/agents/{name} added.
• endpoints_missing.\"Messaging primitive (...)\" retitled to clarify residual gap (agent CRUD beyond list/describe; message read-side lifecycle).
• ported_pr_history: PR #630 marked PORTED placeholder with caveats.

Test plan

• npm test → 92/92 pass
• npm run build → clean
• Manual smoke against staging cueapi (after PR #630 merges):
  • cueapi_agents_list → returns {generated_at, agents: [...]} with online state derivation correct
  • cueapi_agents_describe { name: "cue-mac-app" } → returns full AgentResponse
  • cueapi_agents_describe { name: "agt_x@mike" } → URL-encoding works, single round-trip
  • LLM dogfood: spawn a fresh CC session, prompt-inject roster from cueapi_agents_list, verify it can pick the right recipient + send via cueapi_send_message

Companion PRs

• cueapi-mcp feat: port cueapi PR #619 — §17 BCC-light to MCP (cueapi_send_message) #25 (PR #619 BCC-light port) — open, this PR bases off it for extraHeaders test-stub signature
• cue-mac-app ee31508 (Surface 5 stub end-to-end) — shipped 2026-05-05; adds 5min poller wiring after this lands + #630 merges
• cueapi-cli — agents_list / agents_describe expansion already in chore(dependabot): ignore zod major bumps until v4 migration is scheduled #28 + feat(fire-cue): expose send_at + exit_criteria + idempotency_key (cueapi #618/#632/#683 parity) #29 family
• cueapi-action / cueapi-python — pending downstream ports

🤖 Generated with Claude Code