feat(framework/tools): inter-agent tmux comms — agent-send.sh + addressing standard (#533)

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -0,0 +1,100 @@
+#!/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).
+#
+# 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
+#   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
+#   -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
+#
+# 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"
+
+DST_SESSION=""; SSH_TARGET=""; DST_HOST=""; MSG=""; FILE=""
+SRC_LABEL=""; RETRIES=2; VERBOSE=0
+usage() { sed -n '2,44p' "$0"; exit "${1:-3}"; }
+
+while getopts "s:H:n:m:f:S:r: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 ;;
+    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; }
+
+# 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}]"
+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