diff --git a/packages/mosaic/framework/tools/tmux/agent-send.sh b/packages/mosaic/framework/tools/tmux/agent-send.sh index fe30d1b..6ecd84b 100755 --- a/packages/mosaic/framework/tools/tmux/agent-send.sh +++ b/packages/mosaic/framework/tools/tmux/agent-send.sh @@ -12,6 +12,10 @@ # ambiguity about lanes or origin. Recipients replying should FLIP the # preamble: [ -> ] ... (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 @@ -26,6 +30,7 @@ # agent-send.sh -s -m "message" # local target # agent-send.sh -H user@host -s -m "message" # remote target # agent-send.sh -H user@host -n -s -f msg.txt +# agent-send.sh -s mos-claude --class terminal-log -m "ACK — received" # echo "msg" | agent-send.sh -H user@host -s # # OPTIONS @@ -35,26 +40,60 @@ # 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=` token INSIDE the bracket: +# [ -> class=terminal-log] +# 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 ":" (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="$SELF_DIR/send-message.sh" +# 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 -usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; } +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:vh" o; do +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 @@ -62,6 +101,17 @@ 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) @@ -84,7 +134,7 @@ if [ -z "$DST_HOST" ]; then fi fi -PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}]" +PREAMBLE="[${SRC_LABEL} -> ${DST_HOST}:${DST_SESSION}${CLASS_TOKEN}]" FULL="${PREAMBLE} ${MSG}" B64=$(printf '%s' "$FULL" | base64 -w0) diff --git a/packages/mosaic/framework/tools/tmux/agent-send.test.sh b/packages/mosaic/framework/tools/tmux/agent-send.test.sh new file mode 100755 index 0000000..e02cbc9 --- /dev/null +++ b/packages/mosaic/framework/tools/tmux/agent-send.test.sh @@ -0,0 +1,97 @@ +#!/usr/bin/env bash +# agent-send.test.sh — regression + grammar lock for agent-send.sh --class. +# +# Strategy: inject a capture stub via AGENT_SEND_SENDER that decodes the -b +# base64 payload and prints the FULL message (preamble + body) so we can assert +# the exact bytes on the wire. Local path only (no ssh), -n pins the dst host so +# the preamble is deterministic across machines. +# +# Guarantees locked here: +# 1. REGRESSION BAR — no --class => preamble byte-for-byte identical to classic. +# 2. --class => ` class=` token emitted inside the bracket. +# 3. --class= (equals form) parses identically to the space form. +# 4. -C short form parses identically. +# 5. invalid class => exit 3, nothing sent. +# 6. --class with no value => exit 3. +# 7. the documented consumer regex parses producer output for every class. +set -uo pipefail + +HERE=$(cd -- "$(dirname -- "$0")" && pwd) +TOOL="$HERE/agent-send.sh" + +# Capture stub: stands in for send-message.sh. Decodes -b and prints the payload. +STUB=$(mktemp) +trap 'rm -f "$STUB"' EXIT +cat >"$STUB" <<'STUB_EOF' +#!/usr/bin/env bash +set -uo pipefail +b64="" +while getopts "t:b:r:v" o; do case "$o" in b) b64=$OPTARG ;; *) : ;; esac; done +printf '%s' "$b64" | base64 -d +STUB_EOF +chmod +x "$STUB" + +PASS=0; FAIL=0 +ok() { PASS=$((PASS+1)); printf 'ok %s\n' "$1"; } +no() { FAIL=$((FAIL+1)); printf 'FAIL %s\n %s\n' "$1" "$2"; } + +# Run the tool with the stub injected; echoes captured payload on stdout. +run() { AGENT_SEND_SENDER="$STUB" bash "$TOOL" -S a:src -n dsthost "$@"; } + +# Documented consumer grammar — the daemon will mirror exactly this. +GRAMMAR='^\[(\S+) -> (\S+) class=(terminal-log|actionable|human|reaction)\] (.*)$' +GRAMMAR_NOCLASS='^\[(\S+) -> (\S+)\] (.*)$' + +# 1. REGRESSION BAR: classic preamble, byte-for-byte. +got=$(run -s mos -m "hello world") +want='[a:src -> dsthost:mos] hello world' +[ "$got" = "$want" ] && ok "regression: no --class is byte-identical" \ + || no "regression: no --class is byte-identical" "got=[$got] want=[$want]" + +# 2. --class space form emits the token. +got=$(run -s mos --class terminal-log -m "ACK") +want='[a:src -> dsthost:mos class=terminal-log] ACK' +[ "$got" = "$want" ] && ok "--class terminal-log emits token" \ + || no "--class terminal-log emits token" "got=[$got] want=[$want]" + +# 3. --class=value equals form. +got=$(run -s mos --class=actionable -m "decide X") +want='[a:src -> dsthost:mos class=actionable] decide X' +[ "$got" = "$want" ] && ok "--class=actionable (equals form)" \ + || no "--class=actionable (equals form)" "got=[$got] want=[$want]" + +# 4. -C short form. +got=$(run -s mos -C human -m "from a person") +want='[a:src -> dsthost:mos class=human] from a person' +[ "$got" = "$want" ] && ok "-C human (short form)" \ + || no "-C human (short form)" "got=[$got] want=[$want]" + +# 5. invalid class => exit 3, no send. +if out=$(run -s mos --class bogus -m "x" 2>/dev/null); then + no "invalid class rejected" "expected non-zero exit, got 0 (out=[$out])" +else + rc=$? + [ "$rc" = 3 ] && [ -z "$out" ] && ok "invalid class => exit 3, nothing sent" \ + || no "invalid class => exit 3, nothing sent" "rc=$rc out=[$out]" +fi + +# 6. --class with no value => exit 3. +if run -s mos -m "x" --class 2>/dev/null; then + no "--class with no value rejected" "expected non-zero exit, got 0" +else + [ "$?" = 3 ] && ok "--class with no value => exit 3" || no "--class with no value => exit 3" "wrong rc" +fi + +# 7. consumer grammar parses every class + classic line. +for c in terminal-log actionable human reaction; do + line=$(run -s mos --class "$c" -m "body $c") + [[ "$line" =~ $GRAMMAR ]] && [ "${BASH_REMATCH[3]}" = "$c" ] && [ "${BASH_REMATCH[4]}" = "body $c" ] \ + && ok "grammar parses class=$c" || no "grammar parses class=$c" "line=[$line]" +done +classic=$(run -s mos -m "plain body") +[[ "$classic" =~ $GRAMMAR_NOCLASS ]] && [ "${BASH_REMATCH[3]}" = "plain body" ] \ + && ok "grammar (no-class) parses classic line" || no "grammar (no-class) parses classic line" "line=[$classic]" + +echo "---" +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" -eq 0 ]