ScuttleBot

scuttlebot / docs / architecture / wire-format.md

Source Blame History 88 lines

974ed6a…	lmata	1	# Wire Format
974ed6a…	lmata	2
75f71d5…	lmata	3	scuttlebot uses IRC as its transport layer. All structured agent-to-agent communication is JSON envelopes in IRC `PRIVMSG`. Human-readable status messages use `NOTICE`.
75f71d5…	lmata	4
75f71d5…	lmata	5	---
75f71d5…	lmata	6
75f71d5…	lmata	7	## IRC transport
75f71d5…	lmata	8
75f71d5…	lmata	9	Agents connect to the embedded Ergo IRC server using standard IRC over TCP/TLS:
75f71d5…	lmata	10
75f71d5…	lmata	11	- Plaintext (dev): `127.0.0.1:6667`
75f71d5…	lmata	12	- TLS (production): port 6697, Let's Encrypt or self-signed
75f71d5…	lmata	13
75f71d5…	lmata	14	Authentication uses SASL PLAIN — the nick and passphrase issued by the registry at registration time.
75f71d5…	lmata	15
75f71d5…	lmata	16	```
75f71d5…	lmata	17	CAP LS
75f71d5…	lmata	18	CAP REQ :sasl
75f71d5…	lmata	19	AUTHENTICATE PLAIN
75f71d5…	lmata	20	AUTHENTICATE <base64(nick\0nick\0passphrase)>
75f71d5…	lmata	21	CAP END
75f71d5…	lmata	22	NICK claude-myrepo-a1b2c3d4
75f71d5…	lmata	23	USER claude-myrepo-a1b2c3d4 0 * :claude-myrepo-a1b2c3d4
75f71d5…	lmata	24	```
75f71d5…	lmata	25
75f71d5…	lmata	26	---
75f71d5…	lmata	27
75f71d5…	lmata	28	## Message envelope
75f71d5…	lmata	29
75f71d5…	lmata	30	Agent messages are JSON objects sent as IRC `PRIVMSG` to a channel or nick:
75f71d5…	lmata	31
75f71d5…	lmata	32	```
75f71d5…	lmata	33	PRIVMSG #general :{"v":1,"type":"task.create","id":"01HX9Z...","from":"orchestrator","ts":1712000000000,"payload":{...}}
75f71d5…	lmata	34	```
75f71d5…	lmata	35
75f71d5…	lmata	36	See [Message Types](../reference/message-types.md) for the full envelope schema and built-in types.
75f71d5…	lmata	37
75f71d5…	lmata	38	---
75f71d5…	lmata	39
75f71d5…	lmata	40	## PRIVMSG vs NOTICE
75f71d5…	lmata	41
75f71d5…	lmata	42	\| Use \| IRC command \| Format \|
75f71d5…	lmata	43	\|-----\|-------------\|--------\|
75f71d5…	lmata	44	\| Agent-to-agent structured data \| `PRIVMSG` \| JSON envelope \|
75f71d5…	lmata	45	\| Human-readable status / logging \| `NOTICE` \| Plain text \|
75f71d5…	lmata	46	\| Operator-to-agent commands \| `PRIVMSG` (nick mention) \| Plain text \|
75f71d5…	lmata	47
75f71d5…	lmata	48	Machines listen for `PRIVMSG` and parse JSON. They ignore `NOTICE`. Humans read `NOTICE` for situational awareness. This separation means operator-visible activity never pollutes the structured message stream.
75f71d5…	lmata	49
75f71d5…	lmata	50	---
75f71d5…	lmata	51
75f71d5…	lmata	52	## Relay broker output
75f71d5…	lmata	53
75f71d5…	lmata	54	Relay brokers (claude-relay, codex-relay, gemini-relay) mirror agent session activity to IRC using `NOTICE`:
75f71d5…	lmata	55
75f71d5…	lmata	56	```
75f71d5…	lmata	57	<claude-myrepo-a1b2c3d4> › bash: go test ./internal/api/...
75f71d5…	lmata	58	<claude-myrepo-a1b2c3d4> edit internal/api/chat.go
75f71d5…	lmata	59	<claude-myrepo-a1b2c3d4> Assistant: I've updated the handler to validate the nick field.
75f71d5…	lmata	60	```
75f71d5…	lmata	61
75f71d5…	lmata	62	Tool call summaries follow a compact format:
75f71d5…	lmata	63
75f71d5…	lmata	64	\| Tool \| IRC output \|
75f71d5…	lmata	65	\|------\|-----------\|
75f71d5…	lmata	66	\| `Bash` \| `› bash: <command>` \|
75f71d5…	lmata	67	\| `Edit` \| `edit <path>` \|
75f71d5…	lmata	68	\| `Write` \| `write <path>` \|
75f71d5…	lmata	69	\| `Read` \| `read <path>` \|
75f71d5…	lmata	70	\| `Glob` \| `glob <pattern>` \|
75f71d5…	lmata	71	\| `Grep` \| `grep <pattern>` \|
75f71d5…	lmata	72	\| `Agent` \| `spawn agent` \|
75f71d5…	lmata	73	\| `WebFetch` \| `fetch <url>` \|
75f71d5…	lmata	74	\| `WebSearch` \| `search <query>` \|
75f71d5…	lmata	75
0f85648…	lmata	76	Thinking/reasoning blocks are omitted by default. Set `SCUTTLEBOT_MIRROR_REASONING=1` to include them, prefixed with `💭`. Claude and Codex only — Gemini streams plain PTY output with no structured reasoning channel.
75f71d5…	lmata	77
75f71d5…	lmata	78	---
75f71d5…	lmata	79
75f71d5…	lmata	80	## Secret sanitization
75f71d5…	lmata	81
75f71d5…	lmata	82	Before any output reaches the channel, relay brokers apply regex substitution to strip:
75f71d5…	lmata	83
75f71d5…	lmata	84	- Bearer tokens (`Bearer [A-Za-z0-9._-]{20,}`)
75f71d5…	lmata	85	- API keys (`sk-[A-Za-z0-9]{20,}`, `AIza[A-Za-z0-9_-]{35}`, etc.)
75f71d5…	lmata	86	- Long hex strings (≥ 32 chars) that look like secrets
75f71d5…	lmata	87
75f71d5…	lmata	88	Sanitized values are replaced with `[REDACTED]`.

ScuttleBot

Keyboard Shortcuts