be35001695
Add an optional triage class to inter-agent messages so a comms daemon (M8)
can route deliver-vs-log-and-drop from an exact field instead of re-deriving
intent from the message body. ~35% of Mos's queued fan-in is agent-send
traffic; this makes that slice self-declaring on the tmux transport today,
with zero dependency on the M7/Matrix cutover.
Producer:
-C CLASS / --class CLASS / --class=CLASS, c in
{terminal-log, actionable, human, reaction}.
When SET, the preamble carries a ` class=<c>` token INSIDE the bracket:
[src -> dst class=terminal-log] msg
When OMITTED, NO token is emitted — the preamble is byte-for-byte identical
to the classic format (regression bar). Consumers treat an absent class as
'actionable' (fail-safe: the agent still sees it). Invalid/empty class => exit 3.
Consumer grammar (daemon mirrors this exactly):
^\[(\S+) -> (\S+?)(?: class=(terminal-log|actionable|human|reaction))?\] (.*)$
Tests (agent-send.test.sh, 11 assertions, all green; shellcheck clean):
- REGRESSION: no --class is byte-identical to origin/main (proven via od -tx1
diff of the on-wire payload, not just an expected string).
- space / equals / -C short forms all parse identically.
- invalid class and valueless --class both exit 3 with nothing sent.
- the documented consumer regex round-trips every class + the classic line.
SENDER is now env-overridable (AGENT_SEND_SENDER) purely for test injection;
production callers never set it, so behavior is unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Kt2D8TsnDwhtzEAPijsNmR
151 lines
7.0 KiB
Bash
Executable File
151 lines
7.0 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# agent-send.sh — standard inter-agent tmux messaging for the Mosaic stack.
|
|
#
|
|
# WHAT IT DOES
|
|
# Sends a message to another agent's tmux pane (local or on a remote host)
|
|
# with the canonical addressing preamble prepended:
|
|
#
|
|
# [<src_host>:<src_session> -> <dst_host>:<dst_session>] <message>
|
|
#
|
|
# The preamble makes every inter-agent message self-identifying, so a fresh
|
|
# or context-wiped agent always knows who sent a message and to whom — no
|
|
# ambiguity about lanes or origin. Recipients replying should FLIP the
|
|
# preamble: [<dst> -> <src>] ... (this tool sends; it does not auto-reply).
|
|
#
|
|
# Optionally tags the message with a TRIAGE CLASS (see -C / --class) so a
|
|
# comms daemon can route it (deliver-to-agent vs log-and-drop) from an exact
|
|
# field instead of re-deriving intent from the body.
|
|
#
|
|
# WHY A WRAPPER
|
|
# Reliable submission into an interactive REPL (Claude Code / Codex) is fiddly:
|
|
# a trailing Enter is often swallowed and the message sits as an unsubmitted
|
|
# DRAFT. tools/tmux/send-message.sh already solves that for a LOCAL pane via
|
|
# bracketed-paste + Enter-flush + draft-detection. For REMOTE targets this
|
|
# wrapper SHIPS send-message.sh over ssh (stdin) and runs it there, so the
|
|
# reliable send-keys happens local to the target pane — sidestepping the
|
|
# ssh->nested-tmux Enter/C-m swallow entirely. No mosaic install needed on
|
|
# the remote host; only bash + tmux + base64 (standard).
|
|
#
|
|
# USAGE
|
|
# agent-send.sh -s <dst_session> -m "message" # local target
|
|
# agent-send.sh -H user@host -s <dst_session> -m "message" # remote target
|
|
# agent-send.sh -H user@host -n <dst_hostname> -s <sess> -f msg.txt
|
|
# agent-send.sh -s mos-claude --class terminal-log -m "ACK — received"
|
|
# echo "msg" | agent-send.sh -H user@host -s <dst_session>
|
|
#
|
|
# OPTIONS
|
|
# -s DST_SESSION target tmux session (or session:window.pane) [required]
|
|
# -H SSH_TARGET ssh target (user@host) for a remote pane; omit for local
|
|
# -n DST_HOST hostname to show in the preamble for the target.
|
|
# Default: local hostname, or (remote) resolved via one ssh.
|
|
# -m MESSAGE message text (single- or multi-line)
|
|
# -f FILE read message from FILE instead of -m
|
|
# -C CLASS triage class for a comms daemon. One of:
|
|
# terminal-log log-only; never needs the agent's attention
|
|
# actionable carries a decision/blocker/gate — deliver
|
|
# human from a human operator — deliver
|
|
# reaction an emoji/ack reaction
|
|
# Long form: --class CLASS (or --class=CLASS). When SET, the
|
|
# preamble carries a ` class=<CLASS>` token INSIDE the bracket:
|
|
# [<src> -> <dst> class=terminal-log] <message>
|
|
# When OMITTED, NO token is emitted and the preamble is
|
|
# byte-for-byte identical to the classic format. Consumers MUST
|
|
# treat an absent class as 'actionable' (fail-safe: agent sees it).
|
|
# -S SRC_LABEL override source label "<host>:<session>" (default: auto)
|
|
# -r N Enter-flush attempts passed through (default 2)
|
|
# -v verbose: print pane tail after delivery
|
|
# -h help
|
|
#
|
|
# PREAMBLE GRAMMAR (for consumers / daemons mirroring this producer)
|
|
# ^\[(\S+) -> (\S+?)(?: class=(terminal-log|actionable|human|reaction))?\] (.*)$
|
|
# group 1 = src label group 2 = dst host:session
|
|
# group 3 = class (absent => actionable) group 4 = message body
|
|
#
|
|
# EXIT CODES (passed through from send-message.sh)
|
|
# 0 delivered/queued · 1 target not found · 2 still draft · 3 usage error
|
|
set -uo pipefail
|
|
|
|
SELF_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
|
|
# Sender is overridable via env purely for testing (inject a capture stub). The
|
|
# default is the canonical send-message.sh beside this script; production callers
|
|
# never set AGENT_SEND_SENDER, so behavior is unchanged.
|
|
SENDER="${AGENT_SEND_SENDER:-$SELF_DIR/send-message.sh}"
|
|
|
|
# Translate the long option --class[=value] into "-C value" so getopts (which is
|
|
# short-option-only) can parse it. Every other argument passes through untouched,
|
|
# so callers that never use --class hit the exact original getopts path.
|
|
args=()
|
|
while [ $# -gt 0 ]; do
|
|
case "$1" in
|
|
--class) [ $# -ge 2 ] || { echo "ERROR: --class requires a value" >&2; exit 3; }
|
|
args+=(-C "$2"); shift 2 ;;
|
|
--class=*) args+=(-C "${1#*=}"); shift ;;
|
|
*) args+=("$1"); shift ;;
|
|
esac
|
|
done
|
|
set -- ${args[@]+"${args[@]}"}
|
|
|
|
DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""
|
|
SRC_LABEL=""; RETRIES=2; VERBOSE=0; CLASS=""
|
|
usage() { sed -n '2,/^set -uo pipefail/{/^set -uo pipefail/d;p}' "$0"; exit "${1:-3}"; }
|
|
|
|
while getopts "s:H:n:m:f:S:r:C:vh" o; do
|
|
case "$o" in
|
|
s) DST_SESSION=$OPTARG ;; H) SSH_TARGET=$OPTARG ;; n) DST_HOST=$OPTARG ;;
|
|
m) MSG=$OPTARG ;; f) FILE=$OPTARG ;; S) SRC_LABEL=$OPTARG ;;
|
|
C) CLASS=$OPTARG ;;
|
|
r) RETRIES=$OPTARG ;; v) VERBOSE=1 ;; h) usage 0 ;; *) usage 3 ;;
|
|
esac
|
|
done
|
|
|
|
[ -n "$DST_SESSION" ] || { echo "ERROR: -s DST_SESSION is required" >&2; usage 3; }
|
|
[ -x "$SENDER" ] || { echo "ERROR: send-message.sh not found beside this script" >&2; exit 3; }
|
|
|
|
# Validate the triage class only when one was given. An absent class emits NO
|
|
# token (preamble byte-identical to the classic format); the consumer defaults
|
|
# absent => actionable.
|
|
CLASS_TOKEN=""
|
|
if [ -n "$CLASS" ]; then
|
|
case "$CLASS" in
|
|
terminal-log|actionable|human|reaction) CLASS_TOKEN=" class=${CLASS}" ;;
|
|
*) echo "ERROR: invalid --class '$CLASS' (allowed: terminal-log, actionable, human, reaction)" >&2; exit 3 ;;
|
|
esac
|
|
fi
|
|
|
|
# Message body from -f / -m / stdin.
|
|
if [ -n "$FILE" ]; then [ -r "$FILE" ] || { echo "ERROR: cannot read $FILE" >&2; exit 3; }; MSG=$(cat -- "$FILE")
|
|
elif [ -z "$MSG" ] && [ ! -t 0 ]; then MSG=$(cat)
|
|
fi
|
|
[ -n "$MSG" ] || { echo "ERROR: empty message (use -m, -f, or stdin)" >&2; exit 3; }
|
|
|
|
# Source label: this agent's host:session (auto-detected, overridable).
|
|
if [ -z "$SRC_LABEL" ]; then
|
|
src_host=$(hostname -s 2>/dev/null || echo "?")
|
|
src_sess=$(tmux display-message -p '#S' 2>/dev/null || echo "?")
|
|
SRC_LABEL="${src_host}:${src_sess}"
|
|
fi
|
|
|
|
# Destination host label for the preamble.
|
|
if [ -z "$DST_HOST" ]; then
|
|
if [ -n "$SSH_TARGET" ]; then
|
|
DST_HOST=$(ssh -o ConnectTimeout=8 -o BatchMode=yes "$SSH_TARGET" 'hostname -s' 2>/dev/null || echo "${SSH_TARGET#*@}")
|
|
else
|
|
DST_HOST=$(hostname -s 2>/dev/null || echo "local")
|
|
fi
|
|
fi
|
|
|
|
PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}${CLASS_TOKEN}]"
|
|
FULL="${PREAMBLE} ${MSG}"
|
|
B64=$(printf '%s' "$FULL" | base64 -w0)
|
|
|
|
vflag=""; [ "$VERBOSE" = 1 ] && vflag="-v"
|
|
|
|
if [ -z "$SSH_TARGET" ]; then
|
|
# Local pane: call the canonical sender directly.
|
|
exec "$SENDER" -t "$DST_SESSION" -b "$B64" -r "$RETRIES" $vflag
|
|
else
|
|
# Remote pane: ship the sender over ssh and run it local to the target.
|
|
ssh -o ConnectTimeout=10 "$SSH_TARGET" \
|
|
"bash -s -- -t '$DST_SESSION' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
|
|
fi
|