feat: cueapi message-to <name> + agents --online-only + describe alias#39
Closed
mikemolinet wants to merge 1 commit into
Closed
feat: cueapi message-to <name> + agents --online-only + describe alias#39mikemolinet wants to merge 1 commit into
mikemolinet wants to merge 1 commit into
Conversation
Per the agent-directory productization PRD (https://trydock.ai/mike/agent-directory-productization-prd), this adds the CLI surface for the universal inter-agent comm primitive the PRD calls for, plus two `agents` group conveniences. ## `cueapi message-to <agent-name> <body>` — universal inter-agent comm The PRD's stated goal: agents address peers by stable name; the 6-field cue-fire incantation goes away from agent code. This command is the CLI realization of that. Hides the messaging-primitive routing details (X-Cueapi-From-Agent header, Idempotency-Key header, /v1/messages POST shape) so callers don't need to remember them. Replaces the per-agent bash-script anti-pattern (cma-reply.sh and siblings) with a single canonical CLI command. Behavior: - AGENT_NAME pre-flight: by default, `GET /v1/agents/<name>` is called before the POST to validate the recipient exists. Typo'd names fail fast with a clear error ("Unknown agent 'foo'. Run `cueapi agents list` to see available agents.") instead of being silently routed. --skip-resolve opts out of the pre-flight for callers who want to save the API call. - BODY positional or stdin: `cueapi message-to alice "hi"` OR `echo "msg" | cueapi message-to alice` OR `cueapi message-to alice -` (explicit stdin marker). Useful for multi-line messages. - --from defaults from $CUEAPI_MY_AGENT_SLUG env var. Required either via flag or env. The PRD's vision is each agent sets the env once at session boot and the CLI auto-fills it from there. - --token auto-fills subject as `[TOKEN] <first-body-line>` and stashes in metadata.token for thread traceability. Matches the existing cue-fire convention used by PM/CTO threads. Explicit --subject takes precedence. - --idempotency-key max 255 enforced client-side. Same client-side cap as `cueapi messages send` — fails fast. - --priority click.IntRange(1, 5). Same validation as `messages send`. - Surfaces server's X-CueAPI-Priority-Downgraded response header when receiver-pair limits apply. - 200 vs 201 distinction surfaced as "Idempotency-Key dedup hit" UI copy on 200; matches messages send. ## `cueapi agents list --online-only` One-line alias for `--status online`. Mutually exclusive with --status (raises UsageError before any HTTP call). ## `cueapi agents describe <ref>` Verb alias for `cueapi agents get <ref>` — same Click command registered under both names (via `agents.add_command(agents_get, name="describe")`). Per the agent-directory PRD's discovery vocabulary ("describe this agent to me"). Both verbs invoke the same callback, same options, same behavior; new options added to `agents_get` auto-apply to `agents describe`. ## Tests 15 new (133 → 148 total): - `--online-only` flag in help, mutex with --status, translates to status=online query param - `agents describe` alias visible in group help, accepts ref - `message-to` help shows all flags - env-var `CUEAPI_MY_AGENT_SLUG` auto-fills --from - pre-flight resolve happens before POST - unknown recipient → clear error + no POST attempted - --skip-resolve skips the pre-flight GET - --token auto-fills subject + stashes in metadata - --idempotency-key length cap enforced client-side - --priority Click IntRange validation - explicit --subject wins over token-derived ## Skipped from PRD scope `cueapi agents roster` (wraps GET /v1/agents/roster) is gated on cueapi shipping the roster endpoint. Will follow in a small PR once that endpoint lands. Rest of Surface 3 work tracked under PRD's Phase A status board. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Collaborator
Author
|
Superseded by #40 — opened 3 min later with the broader scope ( |
auto-merge was automatically disabled
May 5, 2026 23:13
Pull request was closed
mikemolinet
added a commit
that referenced
this pull request
May 11, 2026
…out (#52) Mike body-verify directive 2026-05-11 — Phase 2 SDK auto-verify layer for cueapi-cli. Sibling to cueapi-python PR #39 (auto_verify default- on at the resource layer). Wire shape locked via cueapi/cueapi-core PR #86 + cueapi/cueapi PR #795 (Layer 1 substrate echo-back, merged 22:55Z). Changes: cueapi/cli.py: - _first_divergence_byte(a, b) — pure helper returning byte index of first differing position; -1 when one is a proper prefix of the other. - _emit_body_verify_mismatch_diagnostic — pretty-prints sent vs received diff (first 200 chars each side) + byte position + msg_id + actionable mitigation hint. All to stderr. - messages_send + message_to: new --no-verify flag (default verify-on). Sends X-CueAPI-Verify-Echo: true header; on 201 response, diffs m["body_received"] against sent body; on mismatch emits diagnostic + ctx.exit(7) (distinct from generic failure exit codes 1-5). - Backward-compat: when substrate omits body_received field (pre- Layer-1 deploy), no-op + return normally. tests/test_cli.py: - 5 new Phase 2 tests pin: default-on header, --no-verify omits header, byte-identical echo passes, mismatched echo exits 7 with MISMATCH in output, no-op when substrate omits echo field. - Plus 9 prior Phase 3 tests preserved. - Plus 45 prior existing tests preserved. - 205 tests in suite; 65 messaging-related; all pass. Exit code 7 distinct from generic 1-5 so callers can branch on verify-mismatch specifically (CI workflows can retry with --message-file). CHANGELOG entry under [Unreleased]. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the CLI portion of the agent-directory productization PRD — Surface 3, items locked in CTO-AGENT-DIRECTORY-PRD-SEC-V2-RESPONSE-ACK.
What ships
cueapi message-to <agent-name> <body>— the universal inter-agent comm primitiveThe PRD's stated goal: agents address peers by stable name; the 6-field cue-fire incantation goes away from agent code. This command is the CLI realization. Replaces the per-agent bash-script anti-pattern (
Scripts/cma-reply.shetc.) with a single canonical CLI command.Behavior pinned by tests:
Unknown agent 'foo'. Runcueapi agents listto see available agents.instead of being silently routed somewhere bad.--skip-resolveopts out for callers who want to save the API call.--fromdefaults from$CUEAPI_MY_AGENT_SLUG— every agent sets the env once at session boot, the CLI auto-fills.--tokenauto-fills--subjectas[TOKEN] <first-body-line>and stashes inmetadata.tokenfor thread traceability. Explicit--subjectwins.--idempotency-keymax 255 chars enforced client-side (matches server's hard limit).--priorityClickIntRange(1, 5)— bad values fail fast without HTTP round-trip.X-CueAPI-Priority-Downgraded: truerendered when receiver-pair limits apply.cueapi agents list --online-onlyConvenience alias for
--status online. Mutually exclusive with--status(raisesUsageErrorbefore any HTTP call).cueapi agents describe <ref>Verb alias for
cueapi agents get <ref>— same Click command registered under both names. Per the PRD's discovery vocabulary ("describe this agent to me" reads better than "get"). Both verbs invoke the same callback, same options, same behavior — adding new options toagents_getauto-applies toagents describe.Skipped from PRD scope
cueapi agents roster(wrapsGET /v1/agents/roster) is gated on cueapi shipping the roster endpoint. Will follow in a small PR once that endpoint lands.Tests
15 new (133 → 148 total). Mock-based, mirrors the patterns established in cueapi-cli #28 + #29.
--online-only--status, translates tostatus=onlinequery paramagents describerefmessage-tohelpmessage-toenvCUEAPI_MY_AGENT_SLUGauto-fills--frommessage-toresolveGET /agents/<name>happens before POSTmessage-tounknownagents list; no POST attemptedmessage-to--skip-resolvemessage-to--tokenmessage-to--token + --subjectmessage-to--idempotency-keymessage-to--priorityAll 148 pass locally.
No hosted-PR dependency
All endpoints already shipped on prod via Phase 12.1 messaging primitive. Pure CLI ergonomics layer.
Migration story
cue-mac-app shipped
Scripts/cma-reply.shthis morning as their prevention layer. Per CTO direction (CTO-AGENT-DIRECTORY-PRD-SEC-V2-RESPONSE-ACK), once this PR ships,cma-reply.shbecomes a transitional artifact:cueapi message-to(this PR). Existing scripts keep working.cma-reply.shand equivalents as 1-line shims that callcueapi message-to. Same script names (back-compat for CLAUDE.md instructions) but internals migrate transparently.CTO is fanning the migration plan to cue-mac-app separately.
🤖 Generated with Claude Code