send_message via the inbox socket #158
Labels
No labels
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
lz/agent-nexus#158
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
"Tell session 2 to look at the auth bug." The highest-value tool and the one with the most measured detail behind it.
Depends on #154. Scope:
nexus:write.Use the inbox socket, not
sendNudgeEvery session exports
CLAUDE_CODE_MESSAGING_SOCKETandCLAUDE_CODE_MESSAGING_TOKEN. Measured inside one worker:A message delivered there arrives as a cross-session message, which never counts as consent and so cannot answer a pending permission prompt on the recipient's behalf.
sendNudgetypes raw text into the PTY and has no such guarantee — the hazard its own comment innexus/src/lib/server/artifacts/tmux-nudge.tsalready describes.That gap is tolerable today because the only sender is the operator approving their own artifact feedback. It becomes a hole the moment a second principal exists, which is the direction this milestone is heading: one principal's
send_messagecould answer a permission dialog in another's session. The socket is the option that survives.Integration details, each pinned by a test
docker exec, so it is not an "own-child" sender; the message goes through the receiving session'scrossSessionInboundcontrols.defaultMode: auto, which counts as prompting, so messages are delivered. A session runningbypassPermissionsholds them for approval instead. Pin this rather than discovering it later — it is the difference between a tool that works and one that silently queues.{"type":"auth","token":"<CLAUDE_CODE_MESSAGING_TOKEN>"}as the first line. Optional on Linux, required on Windows; send it always.Resolving the socket
Each session's socket is named for its claude pid. Resolution has to go from a
sessionsrow to that pid. Noteprocpsis not installed in the worker image (AGENTS.md fact #5) — walk/proc/[0-9]*/cmdlinedirectly, ascheckSessionHealthalready does, and reuse itskind-dispatching match:kind='session'matches the full--remote-control "<workspace> · <name>"argv precisely so one Remote Control process does not satisfy every session's probe.Out of scope
sendNudgestays where it is. Artifact feedback submission is not in scope; whether it should also migrate is a follow-up.Do not build a mailbox or session-to-session messaging. Claude Code already does it, and Nexus made its own fleet addressable without meaning to —
ListAgentsfrom inside a worker returned 28 peers, sibling sessions over a Unix socket plus sessions in other Nexus workers via Remote Control. A Nexus mailbox would be a worse copy of something with inbound controls, loop throttling, burst caps, a 100-message hold queue, and the no-consent guarantee above.Done when
A message sent through the tool appears in the target session as a cross-session message; a
bypassPermissionssession is observed to hold rather than deliver it; and the auth line, the 30s idle close and the pid resolution each have a test proven able to fail.#174 put the tool surface on a contract. This becomes
nexus_send_message— and this is the name the prefix rule exists for:send_messageis a name almost any chat integration Claude has connected would also claim, and a collision does not error, it leaves the model choosing between indistinguishable names.The contract (AGENTS.md fact #40; worked example
mcp/tools/sessions.ts):mcp/tools/, which may not importregistry.ts— the cycle is aReferenceErrorunder Rollup and silentlyundefinedunder esbuild, and neither build warns.annotations, all four required:readOnly: false, destructive: false, idempotent: false, openWorld: false. Not idempotent — sending twice sends twice.outputSchemamandatory, and the SDK validatesstructuredContentagainst it on every call. A mismatch isisError: truecontent on a 200, not a JSON-RPC error, so assertisErrorexplicitly.Two places the contract helps this issue specifically.
Delivered vs held is an output field, not an error. A
bypassPermissionssession holds the message for approval instead of delivering it, and that is a success the caller has to be able to see. Put it in theoutputSchemaas something likedelivered: booleanplus areason, and it is then validated rather than described in prose. A refusal — no such session, socket unreachable, pid unresolvable — shouldthrowa sentence; the registry wrapper logs and rethrows, the SDK turns that intoisErrorcontent, andisErrorresults skip output validation.The description is where the no-consent guarantee goes. A message delivered through the inbox socket arrives as a cross-session message and can never answer a pending permission prompt on the recipient's behalf. That is the property that makes this tool safe for a second principal, and the model should be told it rather than inferring it.