lark1115 · March 3, 2026 22:28
diff --git a/agent-handoff.sh b/agent-handoff.sh
 #!/usr/bin/env bash
 set -euo pipefail

 usage() {
  cat <<'EOF'
 Usage:
  agent-handoff.sh <target-surface> <json-file|- > [--from <surface>] [--cid <id>] [--prev <epoch_ms>] [--dry-run]

 Send a task request to another agent via cmux send (terminal input injection).
 The JSON payload is wrapped in an envelope with FROM/TO/TYPE=REQ.

 Examples:
  agent-handoff.sh surface:6 payload.json
  echo '{"task":"run tests","context":"repo=cmux"}' | \
    agent-handoff.sh surface:6 - --from surface:4
 EOF
 }

 if [[ $# -lt 2 ]]; then
  usage
  exit 2
 fi

 target_surface="$1"
 payload_src="$2"
 shift 2

 from_surface=""
 cid="hoff-$(date +%Y%m%d-%H%M%S)-$(printf '%03x' $((RANDOM % 4096)))"
 prev_ts=""
 dry_run=0

 while [[ $# -gt 0 ]]; do
  case "$1" in
    --from)
      from_surface="${2:-}"
      shift 2
      ;;
    --cid)
      cid="${2:-}"
      shift 2
      ;;
    --prev)
      prev_ts="${2:-}"
      shift 2
      ;;
    --dry-run)
      dry_run=1
      shift
      ;;
    *)
      echo "Unknown option: $1" >&2
      usage
      exit 2
      ;;
  esac
 done

 # Auto-detect sender surface if not specified
 if [[ -z "$from_surface" ]]; then
  from_surface="$(cmux identify --json | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("caller",{}).get("surface_ref") or d.get("focused",{}).get("surface_ref") or "")')"
 fi

 if [[ -z "$from_surface" ]]; then
  echo "Could not resolve --from surface from cmux identify" >&2
  exit 1
 fi

 # Read payload
 if [[ "$payload_src" == "-" ]]; then
  payload="$(cat)"
 else
  payload="$(cat "$payload_src")"
 fi

 # Validate JSON: must have task + context
 validated_payload="$(python3 - "$payload" <<'PY'
 import json
 import sys

 raw = sys.argv[1]
 data = json.loads(raw)
 missing = [k for k in ("task", "context") if not data.get(k)]
 if missing:
    raise SystemExit(f"missing required keys: {', '.join(missing)}")
 print(json.dumps(data, separators=(",", ":"), ensure_ascii=False))
 PY
 )"

 # Generate TS (epoch ms, macOS-compatible)
 ts="$(python3 -c 'import time;print(int(time.time()*1000))')"

 prev_part=""
 if [[ -n "$prev_ts" ]]; then
  prev_part=" PREV=${prev_ts}"
 fi

 envelope="[FROM=${from_surface} TO=${target_surface} TYPE=REQ CID=${cid} TS=${ts}${prev_part}] ${validated_payload}"

 if [[ "$dry_run" -eq 1 ]]; then
  printf 'DRY_RUN: %s\n' "$envelope"
  exit 0
 fi

 # Send via primary channel (terminal input injection)
 cmux send --surface "$target_surface" "$envelope"
 cmux send-key --surface "$target_surface" enter

 printf 'SENT from=%s to=%s cid=%s ts=%s\n' "$from_surface" "$target_surface" "$cid" "$ts"
diff --git a/agent-ping.sh b/agent-ping.sh
 #!/usr/bin/env bash
 set -euo pipefail

 usage() {
  cat <<'EOF'
 Usage:
  agent-ping.sh <target-surface> [--timeout <seconds>] [--from-surface <surface-ref>] [--prefix <name>]

 Examples:
  agent-ping.sh surface:1
  agent-ping.sh surface:1 --timeout 8 --prefix CODEX
 EOF
 }

 if [[ $# -lt 1 ]]; then
  usage
  exit 2
 fi

 target_surface="$1"
 shift

 timeout_s=5
 from_surface=""
 prefix="AGENT"

 while [[ $# -gt 0 ]]; do
  case "$1" in
    --timeout)
      timeout_s="${2:-}"
      shift 2
      ;;
    --from-surface)
      from_surface="${2:-}"
      shift 2
      ;;
    --prefix)
      prefix="${2:-}"
      shift 2
      ;;
    *)
      echo "Unknown option: $1" >&2
      usage
      exit 2
      ;;
  esac
 done

 if [[ -z "$from_surface" ]]; then
  from_surface="$(cmux identify --json | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("caller",{}).get("surface_ref") or d.get("focused",{}).get("surface_ref") or "")')"
 fi

 if [[ -z "$from_surface" ]]; then
  echo "Could not resolve from-surface from cmux identify" >&2
  exit 1
 fi

 nonce="$(date +%s%N)"
 ping_title="${prefix}_PING_${nonce}"
 pong_title="${prefix}_PONG_${nonce}"

 body="from=${from_surface};nonce=${nonce};reply_with=cmux notify --title ${pong_title} --body ack:${nonce} --surface ${from_surface}"

 cmux notify --title "$ping_title" --body "$body" --surface "$target_surface"

 start="$(date +%s)"
 while true; do
  if cmux list-notifications --json | awk -F'|' -v t="$pong_title" '$5 == t { found=1 } END { exit(found ? 0 : 1) }'; then
    echo "OK $pong_title"
    exit 0
  fi
  now="$(date +%s)"
  if (( now - start >= timeout_s )); then
    echo "TIMEOUT waiting for $pong_title" >&2
    exit 1
  fi
  sleep 1
 done
diff --git a/collaboration-ethics.md b/collaboration-ethics.md
diff --git a/gist-comment.sh b/gist-comment.sh
 #!/usr/bin/env bash
 set -euo pipefail

 usage() {
  cat <<'EOF'
 Usage:
  gist-comment.sh <gist-id> <message-file|- > [--prefix <text>]

 Examples:
  gist-comment.sh c524bf0d3ab446e6f2111b78c3d09abd notes.md --prefix "[Codex]"
  echo "Turn summary" | gist-comment.sh c524bf0d3ab446e6f2111b78c3d09abd -
 EOF
 }

 if [[ $# -lt 2 ]]; then
  usage
  exit 2
 fi

 gist_id="$1"
 message_src="$2"
 shift 2

 prefix=""
 while [[ $# -gt 0 ]]; do
  case "$1" in
    --prefix)
      prefix="${2:-}"
      shift 2
      ;;
    *)
      echo "Unknown option: $1" >&2
      usage
      exit 2
      ;;
  esac
 done

 if [[ "$message_src" == "-" ]]; then
  msg="$(cat)"
 else
  msg="$(cat "$message_src")"
 fi

 if [[ -n "$prefix" ]]; then
  body="${prefix} ${msg}"
 else
  body="${msg}"
 fi

 gh api -X POST "/gists/${gist_id}/comments" -f "body=${body}" >/dev/null
 echo "COMMENTED gist=${gist_id}"
diff --git a/handoff-schema.md b/handoff-schema.md
diff --git a/oss-policy.md b/oss-policy.md
diff --git a/protocol.md b/protocol.md
diff --git a/scripts.md b/scripts.md
diff --git a/SKILL.md b/SKILL.md
diff --git a/timing-log.md b/timing-log.md
diff --git a/validate-envelope.sh b/validate-envelope.sh
 #!/bin/bash
 # validate-envelope.sh — Validate cmux multi-agent envelope format
 # Usage: scripts/validate-envelope.sh "<envelope_message>"
 # Exit 0 = valid, Exit 1 = invalid (with error message on stderr)

 set -euo pipefail

 MSG="${1:-}"

 if [[ -z "$MSG" ]]; then
  echo "Usage: validate-envelope.sh '<envelope_message>'" >&2
  exit 1
 fi

 ERRORS=()

 # Check envelope bracket wrapper
 if ! [[ "$MSG" =~ ^\[.+\] ]]; then
  ERRORS+=("Missing envelope brackets [...]")
 fi

 # Check required fields
 if ! [[ "$MSG" =~ FROM=surface:[0-9]+ ]]; then
  ERRORS+=("Missing or invalid FROM=surface:N")
 fi

 if ! [[ "$MSG" =~ TO=surface:[0-9]+ ]]; then
  ERRORS+=("Missing or invalid TO=surface:N")
 fi

 if ! [[ "$MSG" =~ TYPE=(HELLO|HELLO_ACK|REQ|ACK|RES|ERR|INFO) ]]; then
  ERRORS+=("Missing or invalid TYPE (must be HELLO|HELLO_ACK|REQ|ACK|RES|ERR|INFO)")
 fi

 if ! [[ "$MSG" =~ TS=[0-9]+ ]]; then
  ERRORS+=("Missing TS=<epoch_ms>")
 fi

 # Check CID requirement for REQ/ACK/RES/ERR
 if [[ "$MSG" =~ TYPE=REQ ]] && ! [[ "$MSG" =~ CID= ]]; then
  ERRORS+=("TYPE=REQ requires CID=<id>")
 fi

 if [[ "$MSG" =~ TYPE=ACK ]] && ! [[ "$MSG" =~ CID= ]]; then
  ERRORS+=("TYPE=ACK requires CID=<id> (echo sender's CID)")
 fi

 if [[ "$MSG" =~ TYPE=RES ]] && ! [[ "$MSG" =~ CID= ]]; then
  ERRORS+=("TYPE=RES requires CID=<id> (echo sender's CID)")
 fi

 # Check PRIORITY value if present
 if [[ "$MSG" =~ PRIORITY= ]] && ! [[ "$MSG" =~ PRIORITY=(URGENT|NORMAL|LOW) ]]; then
  ERRORS+=("Invalid PRIORITY (must be URGENT|NORMAL|LOW)")
 fi

 # Check single-line constraint
 LINE_COUNT=$(echo "$MSG" | wc -l | tr -d ' ')
 if [[ "$LINE_COUNT" -gt 1 ]]; then
  ERRORS+=("Multi-line message detected ($LINE_COUNT lines). Must be single line.")
 fi

 # Report results
 if [[ ${#ERRORS[@]} -gt 0 ]]; then
  echo "INVALID envelope (${#ERRORS[@]} error(s)):" >&2
  for err in "${ERRORS[@]}"; do
    echo "  - $err" >&2
  done
  exit 1
 fi

 echo "OK"
 exit 0
	#!/usr/bin/env bash
	set -euo pipefail

	usage() {
	cat <<'EOF'
	Usage:
	agent-handoff.sh <target-surface> <json-file\|- > [--from <surface>] [--cid <id>] [--prev <epoch_ms>] [--dry-run]

	Send a task request to another agent via cmux send (terminal input injection).
	The JSON payload is wrapped in an envelope with FROM/TO/TYPE=REQ.

	Examples:
	agent-handoff.sh surface:6 payload.json
	echo '{"task":"run tests","context":"repo=cmux"}' \| \
	agent-handoff.sh surface:6 - --from surface:4
	EOF
	}

	if [[ $# -lt 2 ]]; then
	usage
	exit 2
	fi

	target_surface="$1"
	payload_src="$2"
	shift 2

	from_surface=""
	cid="hoff-$(date +%Y%m%d-%H%M%S)-$(printf '%03x' $((RANDOM % 4096)))"
	prev_ts=""
	dry_run=0

	while [[ $# -gt 0 ]]; do
	case "$1" in
	--from)
	from_surface="${2:-}"
	shift 2
	;;
	--cid)
	cid="${2:-}"
	shift 2
	;;
	--prev)
	prev_ts="${2:-}"
	shift 2
	;;
	--dry-run)
	dry_run=1
	shift
	;;
	*)
	echo "Unknown option: $1" >&2
	usage
	exit 2
	;;
	esac
	done

	# Auto-detect sender surface if not specified
	if [[ -z "$from_surface" ]]; then
	from_surface="$(cmux identify --json \| python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("caller",{}).get("surface_ref") or d.get("focused",{}).get("surface_ref") or "")')"
	fi

	if [[ -z "$from_surface" ]]; then
	echo "Could not resolve --from surface from cmux identify" >&2
	exit 1
	fi

	# Read payload
	if [[ "$payload_src" == "-" ]]; then
	payload="$(cat)"
	else
	payload="$(cat "$payload_src")"
	fi

	# Validate JSON: must have task + context
	validated_payload="$(python3 - "$payload" <<'PY'
	import json
	import sys

	raw = sys.argv[1]
	data = json.loads(raw)
	missing = [k for k in ("task", "context") if not data.get(k)]
	if missing:
	raise SystemExit(f"missing required keys: {', '.join(missing)}")
	print(json.dumps(data, separators=(",", ":"), ensure_ascii=False))
	PY
	)"

	# Generate TS (epoch ms, macOS-compatible)
	ts="$(python3 -c 'import time;print(int(time.time()*1000))')"

	prev_part=""
	if [[ -n "$prev_ts" ]]; then
	prev_part=" PREV=${prev_ts}"
	fi

	envelope="[FROM=${from_surface} TO=${target_surface} TYPE=REQ CID=${cid} TS=${ts}${prev_part}] ${validated_payload}"

	if [[ "$dry_run" -eq 1 ]]; then
	printf 'DRY_RUN: %s\n' "$envelope"
	exit 0
	fi

	# Send via primary channel (terminal input injection)
	cmux send --surface "$target_surface" "$envelope"
	cmux send-key --surface "$target_surface" enter

	printf 'SENT from=%s to=%s cid=%s ts=%s\n' "$from_surface" "$target_surface" "$cid" "$ts"
Type	Direction	Purpose
`HELLO`	initiator → peer	Announce identity at session start
`HELLO_ACK`	peer → initiator	Confirm identity
`REQ`	sender → receiver	Task request (include `size=S\|M\|L`)
`ACK`	receiver → sender	Acknowledge receipt (SHOULD within 30s, MUST before heavy work)
`RES`	receiver → sender	Task result
`ERR`	either → either	Error report
`INFO`	either → either	Informational: progress, BUSY notification, no response needed
name	cmux-multi-agent
description	Coordinate multi-agent workflows across cmux panes (Claude Code + Codex + Gemini) using envelope messaging over cmux send. Use when two or more agents must delegate work, exchange status, and keep task ownership unambiguous.
Priority	When to Use	Receiver Behavior
`URGENT`	User-initiated redirects, error escalations, cancellation requests	MUST interrupt current work. Finish current tool call, then process immediately.
`NORMAL`	Standard REQ/RES/INFO flow (default — can be omitted)	Process at next checkpoint or when idle.
`LOW`	Background updates, non-blocking informational	May defer until current task completes. Do not starve beyond 120s.
Size	Duration	Checkpoint Required?
S	0-30 sec	No mid-task check needed
M	30 sec - 2 min	Yes — check at each sub-task boundary
L	2+ min	MUST decompose into sub-tasks first
Time Elapsed	Action
30s	Wait (peer may be busy)
45-60s	Send one `INFO` ping with same CID
90s+	Escalate to user/operator
Script	Purpose	Usage
`scripts/agent-handoff.sh`	MANDATORY for REQ. Wraps payload in envelope, auto-detects surface, auto-generates CID	`scripts/agent-handoff.sh <surface> - < payload.json`
`scripts/validate-envelope.sh`	MANDATORY for non-REQ sends. Validates envelope format	`scripts/validate-envelope.sh "<envelope>"`
`scripts/agent-ping.sh`	Diagnostic liveness check only	Not for protocol messaging
`scripts/gist-comment.sh`	Append turn log to Gist	`scripts/gist-comment.sh <gist-id>`
Reference	Content
references/protocol.md	Full envelope protocol and lifecycle details
references/handoff-schema.md	Message and payload schema guidance
references/collaboration-ethics.md	Findings sharing, cross-validation, attribution
references/oss-policy.md	Guidelines for filing issues/PRs on external repos
references/timing-log.md	Latency logging format and analysis metrics
references/scripts.md	Available helper scripts and detailed usage
	#!/bin/bash
	# validate-envelope.sh — Validate cmux multi-agent envelope format
	# Usage: scripts/validate-envelope.sh "<envelope_message>"
	# Exit 0 = valid, Exit 1 = invalid (with error message on stderr)

	set -euo pipefail

	MSG="${1:-}"

	if [[ -z "$MSG" ]]; then
	echo "Usage: validate-envelope.sh '<envelope_message>'" >&2
	exit 1
	fi

	ERRORS=()

	# Check envelope bracket wrapper
	if ! [[ "$MSG" =~ ^\[.+\] ]]; then
	ERRORS+=("Missing envelope brackets [...]")
	fi

	# Check required fields
	if ! [[ "$MSG" =~ FROM=surface:[0-9]+ ]]; then
	ERRORS+=("Missing or invalid FROM=surface:N")
	fi

	if ! [[ "$MSG" =~ TO=surface:[0-9]+ ]]; then
	ERRORS+=("Missing or invalid TO=surface:N")
	fi

	if ! [[ "$MSG" =~ TYPE=(HELLO\|HELLO_ACK\|REQ\|ACK\|RES\|ERR\|INFO) ]]; then
	ERRORS+=("Missing or invalid TYPE (must be HELLO\|HELLO_ACK\|REQ\|ACK\|RES\|ERR\|INFO)")
	fi

	if ! [[ "$MSG" =~ TS=[0-9]+ ]]; then
	ERRORS+=("Missing TS=<epoch_ms>")
	fi

	# Check CID requirement for REQ/ACK/RES/ERR
	if [[ "$MSG" =~ TYPE=REQ ]] && ! [[ "$MSG" =~ CID= ]]; then
	ERRORS+=("TYPE=REQ requires CID=<id>")
	fi

	if [[ "$MSG" =~ TYPE=ACK ]] && ! [[ "$MSG" =~ CID= ]]; then
	ERRORS+=("TYPE=ACK requires CID=<id> (echo sender's CID)")
	fi

	if [[ "$MSG" =~ TYPE=RES ]] && ! [[ "$MSG" =~ CID= ]]; then
	ERRORS+=("TYPE=RES requires CID=<id> (echo sender's CID)")
	fi

	# Check PRIORITY value if present
	if [[ "$MSG" =~ PRIORITY= ]] && ! [[ "$MSG" =~ PRIORITY=(URGENT\|NORMAL\|LOW) ]]; then
	ERRORS+=("Invalid PRIORITY (must be URGENT\|NORMAL\|LOW)")
	fi

	# Check single-line constraint
	LINE_COUNT=$(echo "$MSG" \| wc -l \| tr -d ' ')
	if [[ "$LINE_COUNT" -gt 1 ]]; then
	ERRORS+=("Multi-line message detected ($LINE_COUNT lines). Must be single line.")
	fi

	# Report results
	if [[ ${#ERRORS[@]} -gt 0 ]]; then
	echo "INVALID envelope (${#ERRORS[@]} error(s)):" >&2
	for err in "${ERRORS[@]}"; do
	echo " - $err" >&2
	done
	exit 1
	fi

	echo "OK"
	exit 0