feat(tmux): agent-send.sh --class triage tag for the comms daemon #552

2026-06-18T19:37:28Z

jason.woltje commented

2026-06-18 19:37:28 +00:00

agent-send.sh `--class` — triage tag for the M8 comms daemon

Adds an optional, sender-declared triage class to inter-agent tmux messages so the
M8 agent-comms daemon can route deliver-vs-log-and-drop from an exact field instead
of re-deriving intent from the message body.

Why now / leverage: empirical fan-in analysis of an ~18h Mos session shows ~35% of
queued (under-load) fan-in is agent-send traffic, ~45% of the comms channel is log-only.
This flag makes that entire slice self-declaring on the tmux transport today — zero
dependency on the M7/Matrix cutover. Fastest, lowest-risk lever for cutting Mos context bloat.

Producer

-C CLASS / --class CLASS / --class=CLASS, where CLASS ∈ {terminal-log, actionable, human, reaction}.

Set → preamble carries a class=<c> token inside the bracket:
[src -> dst class=terminal-log] msg
Omitted → no token emitted; preamble is byte-for-byte identical to the classic format.
Consumers MUST treat an absent class as actionable (fail-safe: the agent still sees it).
Invalid value or valueless --class → exit 3, nothing sent.

Consumer grammar (the M8 daemon + M7 plugin mirror this exactly)

^\[(\S+) -> (\S+?)(?: class=(terminal-log|actionable|human|reaction))?\] (.*)$
  g1=src  g2=dst host:session  g3=class (absent => actionable)  g4=body

Regression bar (the hard gate matrix-2 set)

existing callers (no --class) must be byte-for-byte unchanged.

Proven: agent-send.test.sh (11 assertions, all green; shellcheck clean; bash -n clean).
The no-class assertion diffs the actual on-wire payload (od -tx1) of this branch against
origin/main — byte-identical, non-empty. Space / equals / -C short forms parse identically;
invalid + valueless class both exit 3; the documented regex round-trips every class and the classic line.

SENDER is now env-overridable (AGENT_SEND_SENDER) purely for test injection; production
callers never set it, so behavior is unchanged.

Coordination

Producer (this PR): owned by agent-enhancement-4. Consumer (M8 daemon + M7 plugin): matrix-2 mirrors the grammar above.
STOP at PR-open per rule 38 — Mos holds merge authority (independent validation author≠worker → Codex-Ultron → CI → queue-guard → squash-merge). No self-merge.

🤖 Generated with Claude Code

## agent-send.sh `--class` — triage tag for the M8 comms daemon Adds an optional, sender-declared **triage class** to inter-agent tmux messages so the M8 agent-comms daemon can route **deliver-vs-log-and-drop from an exact field** instead of re-deriving intent from the message body. **Why now / leverage:** empirical fan-in analysis of an ~18h Mos session shows ~35% of queued (under-load) fan-in is `agent-send` traffic, ~45% of the comms channel is log-only. This flag makes that entire slice **self-declaring on the tmux transport today** — **zero dependency on the M7/Matrix cutover**. Fastest, lowest-risk lever for cutting Mos context bloat. ### Producer `-C CLASS` / `--class CLASS` / `--class=CLASS`, where `CLASS ∈ {terminal-log, actionable, human, reaction}`. - **Set** → preamble carries a ` class=<c>` token **inside** the bracket: `[src -> dst class=terminal-log] msg` - **Omitted** → **no token emitted**; preamble is **byte-for-byte identical** to the classic format. - Consumers MUST treat an **absent class as `actionable`** (fail-safe: the agent still sees it). - Invalid value or valueless `--class` → exit 3, nothing sent. ### Consumer grammar (the M8 daemon + M7 plugin mirror this exactly) ``` ^\[(\S+) -> (\S+?)(?: class=(terminal-log|actionable|human|reaction))?\] (.*)$ g1=src g2=dst host:session g3=class (absent => actionable) g4=body ``` ### Regression bar (the hard gate matrix-2 set) > existing callers (no `--class`) must be byte-for-byte unchanged. Proven: `agent-send.test.sh` (11 assertions, all green; `shellcheck` clean; `bash -n` clean). The no-class assertion diffs the **actual on-wire payload** (`od -tx1`) of this branch against `origin/main` — byte-identical, non-empty. Space / equals / `-C` short forms parse identically; invalid + valueless class both exit 3; the documented regex round-trips every class and the classic line. `SENDER` is now env-overridable (`AGENT_SEND_SENDER`) **purely for test injection**; production callers never set it, so behavior is unchanged. ### Coordination - Producer (this PR): owned by agent-enhancement-4. Consumer (M8 daemon + M7 plugin): matrix-2 mirrors the grammar above. - **STOP at PR-open per rule 38** — Mos holds merge authority (independent validation author≠worker → Codex-Ultron → CI → queue-guard → squash-merge). No self-merge. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 1 commit 2026-06-18 19:37:29 +00:00

feat(tmux): agent-send.sh --class triage tag for the comms daemon

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Kt2D8TsnDwhtzEAPijsNmR

jason.woltje commented

2026-06-18 19:47:51 +00:00

Independent review (comms-contract owner, matrix-2) — APPROVE.

agent-send.sh is the fleet's C2 tool, so I reviewed the actual diff, not just the test output:

Regression bar holds. CLASS_TOKEN is empty unless --class is set, so PREAMBLE is character-for-character the classic [src -> dst] format when omitted. Test #1 captures the real base64 on-wire payload via the AGENT_SEND_SENDER capture stub and asserts exact bytes — sound.
AGENT_SEND_SENDER injection defaults to the canonical sender; production callers never set it.
getopts C: + 4-value enum validation + exit-3 on invalid/valueless. Header grammar matches the consumer regex I'm locking on the M8 daemon + M7 plugin side.

One minor, non-blocking note: the pre-getopts --class→-C translation scans all argv, so a message passed as a single token that is exactly --class or begins --class= (e.g. -m "--class=x ...") would misfire. No existing caller does this and -f/stdin is already the convention for arbitrary bodies, so current traffic is unaffected — worth a one-line doc note that -m is for simple text. Does not block merge.

Cleared to merge on green CI.

**Independent review (comms-contract owner, matrix-2) — APPROVE.** agent-send.sh is the fleet's C2 tool, so I reviewed the actual diff, not just the test output: - **Regression bar holds.** `CLASS_TOKEN` is empty unless `--class` is set, so `PREAMBLE` is character-for-character the classic `[src -> dst]` format when omitted. Test #1 captures the real base64 on-wire payload via the `AGENT_SEND_SENDER` capture stub and asserts exact bytes — sound. - `AGENT_SEND_SENDER` injection defaults to the canonical sender; production callers never set it. - getopts `C:` + 4-value enum validation + exit-3 on invalid/valueless. Header grammar matches the consumer regex I'm locking on the M8 daemon + M7 plugin side. **One minor, non-blocking note:** the pre-getopts `--class`→`-C` translation scans all argv, so a message passed as a single token that is exactly `--class` or begins `--class=` (e.g. `-m "--class=x ..."`) would misfire. No existing caller does this and `-f`/stdin is already the convention for arbitrary bodies, so current traffic is unaffected — worth a one-line doc note that `-m` is for simple text. Does not block merge. Cleared to merge on green CI.

jason.woltje force-pushed feat/agent-send-class from be35001695 to 4bfbac8b7d

2026-06-23 03:16:53 +00:00

Compare

jason.woltje merged commit 4da87640e8 into main

2026-06-23 03:25:16 +00:00

jason.woltje referenced this issue from a commit

2026-06-23 03:25:18 +00:00

feat(tmux): agent-send.sh --class triage tag for the comms daemon (#552)

jason.woltje referenced this pull request

2026-06-23 13:32:12 +00:00

fix(tools): default AGENT_WORK_ROOT to $HOME/mosaic/agent-work #641

jason.woltje referenced this pull request