bus-live-test
Skill22 starsChanged 45 days agoMITView on GitHub
Test gravityd's cross-session bot communication against a live daemon, in two modes — synthetic (double runtime, drive the MCP bus directly as the bots, free and deterministic) and real (pty runtime spawning billed Claude Code sessions, observing genuine bot behavior). Use when changing send_message/complete_task, the bus guardrails (reply caps, fan-out, hop limits, terminal kinds, deadlines/expiry), delivery, the system prompt's bus sections, or the artifacts flow — or when someone asks to demo, smoke-test, or observe bot-to-bot traffic on a dev daemon.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- marketing-screenshotSkill
- releaseSkill
- terminal-perf-testSkill
- visual-regressionSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
billed against the user's account: Use only with explicit user consent, and only to observe *behavior*: do real bots obey the prompt …
- Very specific: line 42
Wait for the published $BUS_HOME/gravityd.port, verify it is 49666, and check curl --fail http://127.0.0.1:49666/health.
- Distinctive: line 50
Create a project and bots with the bundled driver (Node 22+, no deps):
- Very specific: line 106
Wait for boot (active_bots in /health, turn complete per bot in the log), then speak as the user:
- Distinctive: line 158
Stop only the daemon started in this live shell:
- Distinctive: line 165
If the shell/session was lost, verify process ownership again before signalling.
- Distinctive: line 166
Never use broad process-name matching.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Live bus / cross-session communication test
Runs a real gravityd on a throwaway home and exercises bot-to-bot traffic
end to end. Two modes, cheapest first:
- Synthetic (
runtime = "double"): no Claude sessions; you act as the bots by calling the MCP bus with their bearer tokens. Deterministic, free, and the only mode where you can force every refusal on demand. Use for verifying daemon rules. - Real (
runtime = "pty"): the daemon spawns actualclaudesessions — billed against the user's account. Use only with explicit user consent, and only to observe behavior: do real bots obey the prompt contracts, brief delegations well, use artifacts, stay silent after adone.
Shared setup
cargo build -p gravityd
umask 077
BUS_HOME=$(mktemp -d "${TMPDIR:-/tmp}/gravity-bus.XXXXXX")
BUS_HOME=$(cd "$BUS_HOME" && pwd -P)
cat > "$BUS_HOME/gravityd.toml" <<EOF
home = "$BUS_HOME"
bind = ["127.0.0.1"]
port = 49666 # verify this test port is free first
negotiate_port = false
runtime = "double" # or "pty" for real mode
supervision_interval_ms = 1000
[scheduler]
tick_interval_ms = 2000 # fast expiry sweeps; default is 30s
EOF
./target/debug/gravityd --config "$BUS_HOME/gravityd.toml" > "$BUS_HOME/gravityd.log" 2>&1 &
BUS_DAEMON_PID=$!Wait for the published $BUS_HOME/gravityd.port, verify it is 49666, and
check curl --fail http://127.0.0.1:49666/health. Confirm the recorded PID
is still running; stop on startup failure. Never reuse the installed daemon
or stop another process to free this port.
For real mode add claude_bin = "$(command -v claude)" (absolute path — the
daemon's PATH may not include ~/.local/bin) and set runtime = "pty".
Create a project and bots with the bundled driver (Node 22+, no deps):
node .claude/skills/bus-live-test/scripts/bus.mjs setup "$BUS_HOME" 49666 \
"lead:You coordinate work." "worker:You do small jobs."
# prints {"project":..., "bots":{"lead":"<id>","worker":"<id>"}}Credentials on disk: client token at $BUS_HOME/secrets/client.token, per-bot MCP
tokens at $BUS_HOME/secrets/bot-<id>.token.
Synthetic mode: act as the bots
Set LEAD and WORKER to the IDs printed by setup. Call bus tools with
tokens loaded from disk; do not paste token values into tool calls, terminal
arguments, logs, issues, or chat. Review responses before sharing them:
mcp() { # mcp <bot-id> <tool> <json-args>; token is read only inside Node
node .claude/skills/bus-live-test/scripts/bus.mjs mcp "$BUS_HOME" 49666 "$@"
}
mcp $LEAD send_message '{"to":"worker","body":"do X","kind":"task"}'
mcp $WORKER complete_task '{"task_id":"...","result":"done","artifacts":["/path"]}'Guardrail checklist — force each refusal and read its hint text:
- Reply cap: task, then 7 replies alternating direction → 7th refused
with
reply limit reached … complete_task;complete_taskstill succeeds past the cap. - Terminal kinds: reply after the task is done →
no open task; reply withrefpointing at a done message id →is a task result; kindschat/done/unknown → each refused with its hint. - Fan-out: 4th open delegation from one origin → refused; allowed again
after one
complete_task. - Depth: chain tasks A→B→C→D→E (needs 6 bots); the send past
MAX_TASK_HOPSis refused and the target's inbox stays empty. - Expiry: backdate a deadline and watch the sweep flip it and notify
both ends exactly once:
sqlite3 "$BUS_HOME/bus.sqlite" "UPDATE task SET deadline_at='2020-01-01T00:00:00Z' WHERE id='<id>';" # within ~2 ticks: state='expired', WARN "task exceeded its deadline" in the log, # one system note per live end (assignee: stop work; requester: re-delegate)
The constants live in crates/bus/src/types/entities.rs
(MAX_TASK_REPLIES, MAX_TASK_FANOUT, MAX_TASK_HOPS,
DEFAULT_TASK_DEADLINE_HOURS).
Real mode: observe billed sessions
Get explicit user consent first — every bot turn is a real Claude Code session on the user's account. Keep runs small: each bot burns one turn on its creation intro before you send anything, and a 4-bot research-synthesize-review pipeline costs roughly 8–10 turns total.
Wait for boot (active_bots in /health, turn complete per bot in the
log), then speak as the user:
node .claude/skills/bus-live-test/scripts/bus.mjs chat "$BUS_HOME" 49666 <lead-bot-id> \
"Delegate this to worker: ... When you get the result, read the artifact and tell me ..."Good scenario shapes (each verified to exercise the guardrails):
- Minimal: delegate one artifact-producing job; instruct lead to thank
the worker afterwards — the reply channel is closed after
done, so a compliant lead uses anoteand the worker stays silent. - Pipeline: split a research question between two bots, synthesize their artifacts, and have a third bot review the synthesis ("you must not approve your own work") — exercises fan-out pacing, artifacts, author ≠ reviewer.
Observation channels
- Bus ledger — the ground truth for chatter:
sqlite3 "$BUS_HOME/bus.sqlite" "SELECT num,sender_name,kind,substr(replace(body,char(10),' '),1,100) FROM message ORDER BY num;" sqlite3 "$BUS_HOME/bus.sqlite" "SELECT substr(id,1,8),state,hop_count,reply_count,deadline_at IS NOT NULL FROM task;" - Daemon log — bot state transitions, delivery, expiry warns.
- Session transcripts — tool-by-tool behavior including refusals the bot
hit (
is_errortool results). Workspaces under/tmpland in~/.claude/projects/-private-tmp-…-workspace/*.jsonl(note the-private-prefix: macOS/tmpis/private/tmp). Extract tool calls and errors from the newest.jsonl; a bot's answer to the user is its last assistanttextblock there.
Pitfalls learned the hard way
- Bot replies to the user never hit the bus. They go to the terminal, so
don't wait on
sender_kind='bot'message rows to detect that intros finished — watchturn completein the daemon log instead. - Delivery lags ~1s (
delivery.poll_interval_ms): acheck_inboximmediately after a send misses the message. Sleep ≥2s or poll. - The
donefromcomplete_taskgoes into the origin conversation and is delivered to the requester — it will not appear in the assignee's inbox. - Expiry notes name only live bots; a task whose ends were archived
expires silently.
deadline_at IS NULLnever expires (legacy escape hatch). - In synthetic mode nothing consumes inboxes, so
check_inboxas a bot is also your read channel — remember every fresh bot has onesystemintro note to filter out. - Real mode writes residue outside the throwaway home: transcript dirs in
~/.claude/projects/and trust entries in~/.claude.jsonfor the workspaces. Tell the user; do not remove it without approval.
Cleanup
Stop only the daemon started in this live shell:
kill "$BUS_DAEMON_PID"
wait "$BUS_DAEMON_PID"If the shell/session was lost, verify process ownership again before signalling. Never use broad process-name matching. Retain the run directory and logs for review; ask before deleting its exact path. In real mode, identify any remaining child sessions narrowly, and obtain approval before removing their exact transcript directories or trust entries from the user's real home.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

