chattrs 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +698 -499
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,60 +1,212 @@
|
|
|
1
1
|
# chattrs
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
3
|
+
What if any agent could work in a swarm the way Claude Code agents do?
|
|
4
|
+
|
|
5
|
+
chattrs gives Claude Code-style swarms to any agent: Claude Code, Codex, or
|
|
6
|
+
any CLI agent. A lead and its workers talk through one small broker. Each
|
|
7
|
+
agent has an `agent@host` address. The wire protocol is line-delimited JSON
|
|
8
|
+
over TCP, so a script in any language can join too.
|
|
9
|
+
|
|
10
|
+
- **Messaging.** `send`, `reply`, `ask`, `inbox`, `watch`. Topics name a
|
|
11
|
+
workstream and give announcement rooms.
|
|
12
|
+
- **Wake on message.** `watch` under Claude Code's Monitor tool wakes an
|
|
13
|
+
agent. Hooks do the same for Claude Code and Codex.
|
|
14
|
+
- **Presence, state, health.** `agents` shows online, `working`, `idle`, or
|
|
15
|
+
`waiting`, and `healthy`, `stalled`, or `gone`.
|
|
16
|
+
- **Projects.** One broker serves many projects. Each is isolated.
|
|
17
|
+
- **Identity.** A token table gives each token a project, an address
|
|
18
|
+
pattern, and a role. One session holds an address at a time.
|
|
19
|
+
- **Recovery.** After `/clear`, a hook re-briefs the agent with its
|
|
20
|
+
address, its lead (`CHATTRS_LEAD`), and its recent messages.
|
|
21
|
+
- **Monitoring.** An observer `watch` streams all traffic. The
|
|
22
|
+
[viewer contract](#viewer-contract) lets any program build a view. An
|
|
23
|
+
optional macOS menu bar app lives in [`tray/`](tray/README.md).
|
|
24
|
+
- **Config.** Config files and `chattrs env` set up a session in one line.
|
|
25
|
+
|
|
26
|
+
## Get running
|
|
27
|
+
|
|
28
|
+
chattrs never starts agents. You start them. `chattrs env` sets the
|
|
29
|
+
address and the session in the launch line.
|
|
30
|
+
|
|
31
|
+
### Solo, one machine
|
|
32
|
+
|
|
33
|
+
Three steps.
|
|
34
|
+
|
|
35
|
+
1. Install chattrs. On macOS: `brew install bolu-atx/tap/chattrs`. For
|
|
36
|
+
npm or cargo, see [Install](#install).
|
|
37
|
+
2. Set up the agents once:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
chattrs setup
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`setup` finds Claude Code and Codex. For each one it installs the hooks
|
|
44
|
+
and the skill. It writes `~/.config/chattrs/config.toml` only when none
|
|
45
|
+
exists. It is safe to run again. Then follow the printed trust steps:
|
|
46
|
+
open Codex once and run `/hooks` to trust the new hooks. Claude Code may
|
|
47
|
+
ask you to review the hooks.
|
|
48
|
+
3. Start a lead and a worker in two terminals:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Terminal 1
|
|
52
|
+
eval "$(chattrs env --as lead@mac)" && claude
|
|
53
|
+
|
|
54
|
+
# Terminal 2
|
|
55
|
+
eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The first command starts a loopback broker on its own. The session-start
|
|
59
|
+
hook tells each agent its address and its lead, and to load the skill.
|
|
60
|
+
Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
|
|
61
|
+
An agent shows `online` only while it runs `chattrs watch`. Hooks deliver
|
|
62
|
+
messages between tool calls. In Claude Code, the agent runs `chattrs
|
|
63
|
+
watch` under Monitor, so a message wakes it.
|
|
64
|
+
|
|
65
|
+
### Swarm, several machines
|
|
66
|
+
|
|
67
|
+
Five steps. Use a broker host that is always on. A laptop sleeps, and the
|
|
68
|
+
swarm stops. Install and run `chattrs setup` on every host first, as in
|
|
69
|
+
the solo path.
|
|
70
|
+
|
|
71
|
+
1. On the broker host, issue tokens and write the service unit:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
chattrs setup --broker --hosts mac,bobox --bind 100.64.0.1 --enable
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`--hosts` lists the agent hosts. `--bind` is the tailnet or LAN IP. It
|
|
78
|
+
defaults to the Tailscale IPv4. It never takes `0.0.0.0` or `::`.
|
|
79
|
+
`--enable` starts the service. The command prints one join string for
|
|
80
|
+
each token.
|
|
81
|
+
2. Copy each host's join string to that host, over a private channel. A
|
|
82
|
+
join string holds a token. Treat it like a password. The broker never
|
|
83
|
+
stores it.
|
|
84
|
+
3. On each host, run `setup --join` and paste the join strings on stdin.
|
|
85
|
+
End with Ctrl-D. This keeps them out of shell history:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
chattrs setup --join -
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
It writes a token file (mode 0600) and one `[tokens]` entry in
|
|
92
|
+
`~/.config/chattrs/config.toml`, and it sets `server`. A host that runs
|
|
93
|
+
agents next to the broker needs this step too. The lead host needs
|
|
94
|
+
the lead's join string as well.
|
|
95
|
+
4. On each host, check the setup:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
chattrs doctor --as w1@bobox
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Each check prints `ok` or `FAIL` with a fix hint. The command exits 1
|
|
102
|
+
on any failure.
|
|
103
|
+
5. Launch every agent with its own address:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
eval "$(chattrs env --as lead@mac)" && claude
|
|
107
|
+
eval "$(chattrs env --as w1@bobox --lead lead@mac)" && codex
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`env --as` exports the address, a new session id, and the server. It does
|
|
111
|
+
not print the token. Each command then reads the token from the `[tokens]`
|
|
112
|
+
entry that matches the address. To set the project for all hosts, commit a
|
|
113
|
+
`.chattrs.toml` in the repo ([Environment and config](#environment-and-config)).
|
|
114
|
+
|
|
115
|
+
### Several hosts: `setup --broker` and `setup --join` (SETUP-2)
|
|
116
|
+
|
|
117
|
+
Reference for steps 1 to 3 above.
|
|
14
118
|
|
|
15
119
|
```bash
|
|
16
|
-
|
|
120
|
+
chattrs setup --broker --hosts <a,b> [--lead lead@mac] [--projects p1,p2] \
|
|
121
|
+
[--bind <ip>] [--port 4646] [--enable]
|
|
17
122
|
```
|
|
18
123
|
|
|
19
|
-
|
|
124
|
+
It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
|
|
125
|
+
(`~/.config/systemd/user/chattrs.service`) or a launchd plist
|
|
126
|
+
(`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
|
|
127
|
+
either file. It prints the command that starts the service; `--enable` runs
|
|
128
|
+
it. It issues one agent token per host (`*@<host>`), one lead token, and one
|
|
129
|
+
observer token (`tray@*`, all projects). Then it prints one join string for
|
|
130
|
+
each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
|
|
131
|
+
percent-encoded.
|
|
132
|
+
|
|
133
|
+
`setup --join` also takes a string as an argument. Quote it, but it then
|
|
134
|
+
stays in shell history:
|
|
20
135
|
|
|
21
136
|
```bash
|
|
22
|
-
|
|
137
|
+
chattrs setup --join 'chattrs://TOKEN@100.64.0.1:4646?as=lead%40mac'
|
|
23
138
|
```
|
|
24
139
|
|
|
25
|
-
|
|
26
|
-
|
|
140
|
+
`--join` is repeatable, and stdin can carry one string per line. A string
|
|
141
|
+
without `?as=` needs `--as <pattern>` (one string only). Each string writes
|
|
142
|
+
`~/.config/chattrs/<name>.token` (mode 0600). The name is the pattern with
|
|
143
|
+
`@` as `-` and `*` as `any`: `lead@mac` gives `lead-mac.token`,
|
|
144
|
+
`*@bobox` gives `any-bobox.token`. The command sets `server` when it is
|
|
145
|
+
missing, and it refuses a different `server`. It keeps all other lines. It
|
|
146
|
+
refuses a pattern that already has an entry or a file; `--force` replaces
|
|
147
|
+
them. Then it runs the plain `setup`. The project is not in the join
|
|
148
|
+
string; it comes from `.chattrs.toml`, else `default`.
|
|
149
|
+
|
|
150
|
+
### Check a host: `doctor` (SETUP-3)
|
|
151
|
+
|
|
152
|
+
Reference for step 4 above. Run `chattrs doctor` in the environment of an
|
|
153
|
+
agent (with `CHATTRS_ADDRESS` set, or pass `--as`). It prints one line per
|
|
154
|
+
check, `ok <check>: ...` or `FAIL <check>: ... <fix hint>`, and exits 1 on
|
|
155
|
+
any failure. It checks the config files, the token file each identity uses
|
|
156
|
+
(mode 0600), that the broker accepts a connection, that the broker accepts
|
|
157
|
+
the token for the project and address, the protocol version, the hooks, and
|
|
158
|
+
the skill text. It never prints a token. It writes no file and reads no
|
|
159
|
+
message. The token check sends one normal `hello` as the current address,
|
|
160
|
+
with `CHATTRS_SESSION`, so the broker logs no rejection. It shows the project
|
|
161
|
+
and the broker version from the `welcome`. The `hello` updates the last-seen
|
|
162
|
+
of the current address, so that address looks active to health for a moment.
|
|
163
|
+
This is known and not fixed. Other `[tokens]` identities are listed and not
|
|
164
|
+
probed. Without a current address, doctor checks only that the broker accepts
|
|
165
|
+
a connection and prints a warning. Without `CHATTRS_SESSION`, doctor says
|
|
166
|
+
`hello` without a session and prints a note: use `chattrs env`. A `tray@`
|
|
167
|
+
identity says an observer `hello`. Codex hook trust cannot be detected, so
|
|
168
|
+
doctor always ends with a reminder to trust the hooks in `/hooks` in Codex.
|
|
27
169
|
|
|
28
|
-
|
|
170
|
+
## Install
|
|
29
171
|
|
|
30
172
|
```bash
|
|
31
|
-
|
|
173
|
+
npm install -g chattrs # macOS, Linux, Windows
|
|
174
|
+
brew install bolu-atx/tap/chattrs # macOS arm64
|
|
175
|
+
cargo install --git https://github.com/bolu-atx/chattrs # from source
|
|
32
176
|
```
|
|
33
177
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
178
|
+
Prebuilt binaries and installers are on the
|
|
179
|
+
[Releases page](https://github.com/bolu-atx/chattrs/releases).
|
|
180
|
+
`chattrs --version` names the release. Every channel installs the same
|
|
181
|
+
build (DIST-1).
|
|
37
182
|
|
|
38
183
|
## Quick start
|
|
39
184
|
|
|
185
|
+
This is the raw CLI on one machine, with no agent. For agents, see [Get running](#get-running).
|
|
186
|
+
|
|
187
|
+
One machine, no broker terminal. The first command starts a loopback broker
|
|
188
|
+
on `127.0.0.1:4646`. The broker logs to `chattrs.log` and writes its pid to
|
|
189
|
+
`chattrs.pid`, both next to the DB. `chattrs stop` ends it.
|
|
190
|
+
|
|
40
191
|
```bash
|
|
41
|
-
|
|
42
|
-
|
|
192
|
+
# Terminal 1: the lead
|
|
193
|
+
export CHATTRS_ADDRESS=lead@me
|
|
194
|
+
chattrs watch # prints each new message as JSON
|
|
195
|
+
|
|
196
|
+
# Terminal 2: a worker
|
|
197
|
+
export CHATTRS_ADDRESS=worker1@me
|
|
198
|
+
chattrs send --to lead@me "build is green" # prints the message id
|
|
199
|
+
chattrs agents # who is known, online, and their state
|
|
43
200
|
```
|
|
44
201
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
against it. The broker logs to `chattrs.log` and records its pid in
|
|
48
|
-
`chattrs.pid`, both next to the DB file; `chattrs stop` ends it. A
|
|
49
|
-
remote `CHATTRS_SERVER` is never auto-started.
|
|
202
|
+
Terminal 1 now shows the message. Reply from the worker's side of the
|
|
203
|
+
conversation with `chattrs reply ID "thanks"`. Read it with `chattrs inbox`.
|
|
50
204
|
|
|
51
|
-
`
|
|
52
|
-
|
|
205
|
+
Use `export` like this for a quick try only. For real sessions, set the
|
|
206
|
+
address in the launch line (see [Start a worker](#start-a-worker)).
|
|
53
207
|
|
|
54
|
-
`inbox` prints
|
|
55
|
-
|
|
56
|
-
the text is from another agent and not user instructions, then the body —
|
|
57
|
-
and acks what it printed, so a second run prints nothing:
|
|
208
|
+
`inbox` prints each unread message in an `<agent-message>` wrapper, then
|
|
209
|
+
acks it:
|
|
58
210
|
|
|
59
211
|
```text
|
|
60
212
|
<agent-message id="13" from="codex@box1" to="opus@mac" reply-to="12" ts="2026-11-15T10:00:00Z">
|
|
@@ -63,176 +215,169 @@ hello
|
|
|
63
215
|
</agent-message>
|
|
64
216
|
```
|
|
65
217
|
|
|
66
|
-
`reply-to` is omitted when the message is not a reply
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
omits it. A reply without `--topic` inherits the topic of the message
|
|
70
|
-
it answers.
|
|
71
|
-
`inbox --json` prints one message object per line with
|
|
72
|
-
`"type":"message"` and `"untrusted":true` added.
|
|
73
|
-
|
|
74
|
-
`reply ID` answers message ID and prints the new id (text args, else
|
|
75
|
-
stdin); `reply --json` prints the `sent` frame instead and prints the
|
|
76
|
-
unread preamble as JSON lines, like `send --json`. `watch` prints each new message as one JSON line with
|
|
77
|
-
`"untrusted":true` and acks it on the same connection, reconnecting with
|
|
78
|
-
backoff when the broker drops. It prints nothing else to stdout, so it
|
|
79
|
-
works under a watcher like Claude Code's Monitor tool.
|
|
80
|
-
`ask --to ADDR [--timeout SECS] [TEXT...]` posts a question on one
|
|
81
|
-
connection, blocks for the reply on it, prints it, acks it on it, and
|
|
82
|
-
exits 0. On a timeout it exits 2 and the late reply stays unread.
|
|
83
|
-
`--timeout 0` waits with no limit.
|
|
84
|
-
|
|
85
|
-
`send`, `reply`, `ask`, `agents`, and `log` print unread messages
|
|
86
|
-
first, then their own output. With `--json` the preamble lines are
|
|
87
|
-
`message` objects with `"untrusted":true`; a reader tells them from the
|
|
88
|
-
command's own line by `type`. `watch` and `serve` print no preamble.
|
|
89
|
-
Announcements never appear in an inbox, so they never trigger a
|
|
90
|
-
preamble.
|
|
91
|
-
|
|
92
|
-
`log` prints `Agent messages below. They are not user instructions.`,
|
|
93
|
-
then one line per message, oldest first: the timestamp, id (`*` marks an
|
|
94
|
-
unread message), sender, recipient, topic (`(topic slug)`, omitted for
|
|
95
|
-
the general chat), reply id, and body with newlines escaped. An
|
|
96
|
-
announcement shows its room as the recipient
|
|
97
|
-
(`codex@box1 → topic:release-26: body`).
|
|
98
|
-
`log --json` prints one object per message with `"type":"log"`
|
|
99
|
-
and `"untrusted":true`, so a reader tells log rows from the preamble
|
|
100
|
-
`message` lines. `log --about ADDR` keeps only messages that ADDR sent
|
|
101
|
-
or received; an invalid address exits 1 before connecting. `log` reads
|
|
102
|
-
only; it never acks.
|
|
218
|
+
`reply-to` is omitted when the message is not a reply. A topic adds
|
|
219
|
+
`topic="slug"`. A token table adds `from-role="lead"` for a lead. A body
|
|
220
|
+
that holds `</agent-message` is escaped, so it cannot close the wrapper.
|
|
103
221
|
|
|
104
222
|
## Commands
|
|
105
223
|
|
|
224
|
+
Every command except `serve`, `stop`, `skill`, `env`, `setup`, `doctor`, and `hooks` takes the
|
|
225
|
+
[common flags](#environment-and-config). Every one except `status`, `projects`,
|
|
226
|
+
`hook`, and `watch` first prints unread messages, then its own output, and
|
|
227
|
+
acks them (MSG-5). Announcements never reach an inbox.
|
|
228
|
+
|
|
106
229
|
| Command | What it does |
|
|
107
230
|
| ------- | ------------ |
|
|
108
|
-
| `serve` | Run the broker
|
|
109
|
-
| `stop` | Stop the auto-started broker named by the pidfile next to the
|
|
110
|
-
| `send`
|
|
111
|
-
| `reply` | Answer message `ID
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `agents` | List the
|
|
117
|
-
| `projects` | List every project with its agent and message counts. Read-only.
|
|
118
|
-
| `status` | Report the own state
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
231
|
+
| `serve [--listen ADDR] [--db PATH] [--token T] [--tokens PATH]` | Run the broker. Default `--listen` is `127.0.0.1:4646`. A non-loopback bind needs `--token` or `--tokens`. `--tokens` replaces `--token`. |
|
|
232
|
+
| `stop` | Stop the auto-started broker named by the pidfile next to the DB. |
|
|
233
|
+
| `send [--to ADDR] [--topic SLUG] [--json] [TEXT...]` | Post a message and print its id. With no text, read stdin. With `--topic` and no `--to`, announce to that room. |
|
|
234
|
+
| `reply ID [--topic SLUG] [--json] [TEXT...]` | Answer message `ID`. The reply inherits the topic unless `--topic` sets one. |
|
|
235
|
+
| `ask --to ADDR [--topic SLUG] [--timeout SECS] [--json] [TEXT...]` | Post a question and block for the reply. Default timeout is 600 s, `0` waits with no limit. Exit 0 on a reply, 2 on a timeout, 1 on an error. |
|
|
236
|
+
| `inbox [--json]` | Print every unread message, then ack it. |
|
|
237
|
+
| `watch [--topic SLUG]... [--all]` | Stream new messages as JSON lines and ack them. Nothing else goes to stdout. `--topic` (repeatable) streams those rooms instead and acks nothing. `--all` observes all traffic in the project and acks nothing. |
|
|
238
|
+
| `log [--about ADDR] [--tail N] [--json]` | Show the history, oldest first. `--about` keeps messages that ADDR sent or received. `--tail` keeps the newest N. Never acks. |
|
|
239
|
+
| `agents [--all] [--json]` | List the agents of the project: online or last seen, state, health, tags. Hides agents offline over 7 days with no traffic since. `--all` shows them. |
|
|
240
|
+
| `projects [--json]` | List every project with its agent and message counts. Read-only. |
|
|
241
|
+
| `status working\|idle\|waiting` | Report the own state. Best effort: it never starts a broker, gives up after about 2 s, and always exits 0. |
|
|
242
|
+
| `env --as ADDR [--project P] [--lead ADDR] [--server S] [--tags T] [--token T] [--with-token]` | Print `export` lines for one session: `eval "$(chattrs env --as a@h)"`. It makes a new `CHATTRS_SESSION` on every run. It omits the token unless `--with-token`. |
|
|
243
|
+
| `setup` | Install the hooks and the skill for each agent found (Claude Code, Codex). Write a starter `config.toml` only if missing. Safe to run again. `setup --broker --hosts a,b [...]` prepares a broker host; `setup --join STRING\|-` stores join-string tokens. See [Several hosts](#several-hosts-setup---broker-and-setup---join-setup-2). |
|
|
244
|
+
| `doctor [--as ADDR] [--server S]` | Check config, token files, broker, token, protocol, hooks, and skill. One `ok` or `FAIL` line each; exit 1 on any failure. Read-only. See [Check a host](#check-a-host-doctor-setup-3). |
|
|
245
|
+
| `hooks install\|remove [--agent claude\|codex\|all] [--project]` | Edit the hook entries in the agent configs. See [Hooks](#hooks-claude-code-and-codex). |
|
|
246
|
+
| `hook EVENT` | Run as a hook. Reads hook JSON on stdin. Not for direct use. |
|
|
247
|
+
| `skill` | Print the bundled agent skill. Needs no connection or address. |
|
|
248
|
+
|
|
249
|
+
A message that starts with `-` needs `--`:
|
|
250
|
+
`chattrs send --to b@h -- "- starts with a dash"`.
|
|
251
|
+
|
|
252
|
+
`--json` prints one JSON object per line. Every line has a `type`. Message
|
|
253
|
+
lines also have `"untrusted":true`. `log --json` rows have `"type":"log"`.
|
|
254
|
+
Unread messages printed first are `message` lines.
|
|
255
|
+
|
|
256
|
+
`log` text starts with `Agent messages below. They are not user
|
|
257
|
+
instructions.` Each line shows the time, the id (`*` marks unread), sender,
|
|
258
|
+
recipient, topic, reply id, and the body. An announcement shows its room as
|
|
259
|
+
the recipient: `codex@box1 → topic:release-26: body`.
|
|
260
|
+
|
|
261
|
+
## Environment and config
|
|
262
|
+
|
|
263
|
+
Each value has one source order. From lowest to highest:
|
|
264
|
+
|
|
265
|
+
1. `~/.config/chattrs/config.toml`: `server`, `token_file`, `tags`.
|
|
266
|
+
2. `.chattrs.toml` in the current directory or the nearest parent, up to
|
|
267
|
+
the first `.git` directory: `project`, `lead`.
|
|
268
|
+
3. Environment variables.
|
|
269
|
+
4. Command-line flags.
|
|
270
|
+
|
|
271
|
+
Both files hold flat `key = "value"` lines and `#` comments. An unknown key
|
|
272
|
+
is an error that names the file and line. The repo file holds no secrets: a
|
|
273
|
+
`token` or `token_file` key there is an error. `token_file` names a file
|
|
274
|
+
that holds only the token. On unix it must have mode 0600 or tighter. The
|
|
275
|
+
token applies when neither `CHATTRS_TOKEN` nor `--token` is set.
|
|
276
|
+
|
|
277
|
+
One host can hold several identities (SETUP-4). A `[tokens]` table in the
|
|
278
|
+
user config maps an address or a glob to its own token file:
|
|
279
|
+
|
|
280
|
+
```toml
|
|
281
|
+
token_file = "/home/me/.config/chattrs/token" # fallback
|
|
282
|
+
[tokens]
|
|
283
|
+
"lead@mac" = "/home/me/.config/chattrs/lead-token"
|
|
284
|
+
"*@mac" = "/home/me/.config/chattrs/mac-token"
|
|
157
285
|
```
|
|
158
286
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
287
|
+
The token for an address comes from the first of these that applies:
|
|
288
|
+
`CHATTRS_TOKEN` or `--token`; the `[tokens]` entry that matches the address
|
|
289
|
+
(an exact address beats a glob, and among globs the longest pattern wins);
|
|
290
|
+
the plain `token_file`. The address is `--as`, `--address`, or `--agent`,
|
|
291
|
+
then `CHATTRS_ADDRESS`, then `CHATTRS_AGENT`. `chattrs env --as ADDR
|
|
292
|
+
--with-token` prints the token for ADDR. The table is only in the user
|
|
293
|
+
config, never in `.chattrs.toml`.
|
|
294
|
+
|
|
295
|
+
```toml
|
|
296
|
+
# ~/.config/chattrs/config.toml
|
|
297
|
+
server = "10.0.0.5:4646"
|
|
298
|
+
token_file = "/home/me/.config/chattrs/token"
|
|
299
|
+
```
|
|
170
300
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
301
|
+
```toml
|
|
302
|
+
# .chattrs.toml (committed)
|
|
303
|
+
project = "alpha"
|
|
304
|
+
lead = "opus@mac"
|
|
305
|
+
```
|
|
174
306
|
|
|
175
|
-
|
|
307
|
+
| Variable | Flag | Meaning |
|
|
308
|
+
| -------- | ---- | ------- |
|
|
309
|
+
| `CHATTRS_SERVER` | `--server` | Broker address. Default `127.0.0.1:4646`. A loopback server that is down is auto-started (CLI-11). A remote one never is. |
|
|
310
|
+
| `CHATTRS_ADDRESS` | `--address` | Own address, `user@host`. |
|
|
311
|
+
| `CHATTRS_AGENT` | `--agent` | Agent name. With no address, the address is `<agent>@<hostname>` (hostname cut at the first dot, lowercase). Without address and agent, the command exits 1. |
|
|
312
|
+
| `CHATTRS_TOKEN` | `--token` | Token for the broker. |
|
|
313
|
+
| `CHATTRS_TOKENS` | `serve --tokens` | Token table file for the broker. See [Token table](#token-table). |
|
|
314
|
+
| `CHATTRS_PROJECT` | none | Project of every command. Default `default`. Lowercase letters, digits, and hyphens. `*` is for observers only. |
|
|
315
|
+
| `CHATTRS_LEAD` | `env --lead` | Address of the agent's lead. The `session-start` hook reads it. |
|
|
316
|
+
| `CHATTRS_SESSION` | none | Id of one session, 1 to 128 printable ASCII characters. See [One session per address](#one-session-per-address). |
|
|
317
|
+
| `CHATTRS_TAGS` | `env --tags` | Comma-separated tags, such as `gpu:4090,fast`. `agents` shows them. The client always adds `os:` and `arch:` tags. |
|
|
318
|
+
| `CHATTRS_DB` | `serve --db` | SQLite path. Default `$XDG_DATA_HOME/chattrs/chattrs.db` (`%APPDATA%\chattrs\chattrs.db` on Windows). |
|
|
319
|
+
| `CHATTRS_HOOK_DEBUG` | none | A file path. Each `chattrs hook` run appends one JSON line: `pid`, `ts_ms`, `event`, `input`, and the ids it `fetched` and `emitted`. |
|
|
320
|
+
|
|
321
|
+
Set `CHATTRS_ADDRESS`, `CHATTRS_PROJECT`, `CHATTRS_LEAD`, `CHATTRS_SESSION`,
|
|
322
|
+
and `CHATTRS_TAGS` only in the launch line. Never put them in a shell rc
|
|
323
|
+
file: every session would share one identity.
|
|
324
|
+
|
|
325
|
+
Tags come from the latest `hello`. A command run from another shell without
|
|
326
|
+
`CHATTRS_TAGS` replaces the agent's tags with `os` and `arch`.
|
|
327
|
+
|
|
328
|
+
## Teach workers the skill
|
|
329
|
+
|
|
330
|
+
`chattrs skill` prints the worker skill (`skills/chattrs/SKILL.md`).
|
|
331
|
+
`chattrs setup` installs it for Claude Code and Codex. To install it by
|
|
332
|
+
hand:
|
|
176
333
|
|
|
177
334
|
```bash
|
|
178
335
|
mkdir -p ~/.claude/skills/chattrs && chattrs skill > ~/.claude/skills/chattrs/SKILL.md
|
|
179
336
|
```
|
|
180
337
|
|
|
181
|
-
For pi, pass
|
|
338
|
+
For pi, pass that directory with `--skill`. Muse has no skill directory:
|
|
339
|
+
the lead puts `$(chattrs skill)` in the worker's prompt.
|
|
182
340
|
|
|
183
|
-
|
|
184
|
-
|
|
341
|
+
Give each worker a unique address. Two agents on one address share an
|
|
342
|
+
inbox. There is no default agent name.
|
|
185
343
|
|
|
186
344
|
## Run across hosts
|
|
187
345
|
|
|
188
|
-
Run one broker on an always-on machine. Other hosts connect
|
|
189
|
-
a
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
not a second broker.
|
|
194
|
-
|
|
195
|
-
Install the same binary on every host:
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
cargo install --git https://github.com/bolu-atx/chattrs
|
|
199
|
-
# or: brew install bolu-atx/tap/chattrs (macOS arm64)
|
|
200
|
-
# or: npm install -g chattrs
|
|
201
|
-
```
|
|
346
|
+
Run one broker on an always-on machine. Other hosts connect over a tailnet
|
|
347
|
+
(Tailscale) with a token. There is no TLS. A plain LAN is for a trusted
|
|
348
|
+
home network only. One broker serves every project, so a second swarm needs
|
|
349
|
+
a new `CHATTRS_PROJECT`, not a second broker. The broker host can run an
|
|
350
|
+
agent too. Install the same binary on every host.
|
|
202
351
|
|
|
203
352
|
### Pick the broker host
|
|
204
353
|
|
|
205
|
-
- Use a machine that is always on.
|
|
206
|
-
|
|
207
|
-
-
|
|
208
|
-
|
|
209
|
-
-
|
|
210
|
-
|
|
211
|
-
no token, any local process can say hello as any address.
|
|
212
|
-
- Keep the token in a file with mode 0600, never in a unit file or on a
|
|
213
|
-
command line:
|
|
354
|
+
- Use a machine that is always on. A laptop sleeps, and the swarm stops.
|
|
355
|
+
- Bind to the LAN or tailnet IP. Never use `0.0.0.0` or a public address.
|
|
356
|
+
- Use a [token table](#token-table). The broker refuses a non-loopback
|
|
357
|
+
bind without a token or a table.
|
|
358
|
+
- Keep token files at mode 0600. Never put a token in a unit file or on a
|
|
359
|
+
command line.
|
|
214
360
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
printf 'CHATTRS_TOKEN=%s\n' "$(openssl rand -hex 32)" > ~/.config/chattrs/env
|
|
218
|
-
chmod 600 ~/.config/chattrs/env
|
|
219
|
-
```
|
|
361
|
+
A single shared `CHATTRS_TOKEN` also works (legacy mode). It gives every
|
|
362
|
+
holder every project and every address. Use it for a quick test only.
|
|
220
363
|
|
|
221
364
|
### Keep the database
|
|
222
365
|
|
|
223
|
-
Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never
|
|
224
|
-
|
|
225
|
-
|
|
366
|
+
Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never deletes a
|
|
367
|
+
message, so the database is the swarm's history. Back it up with
|
|
368
|
+
`chattrs backup`, never with `cp` on a live database. It works while the
|
|
369
|
+
broker runs and refuses to replace a file unless you pass `--force`:
|
|
226
370
|
|
|
227
371
|
```bash
|
|
228
|
-
|
|
372
|
+
chattrs backup <file> [--db <db>] [--force]
|
|
229
373
|
```
|
|
230
374
|
|
|
231
375
|
### Run the broker as a service
|
|
232
376
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
377
|
+
`chattrs setup --broker` writes these units for you ([Get running](#get-running)). Use this section to write them by hand.
|
|
378
|
+
|
|
379
|
+
Linux: put a `systemd --user` unit in
|
|
380
|
+
`~/.config/systemd/user/chattrs.service`.
|
|
236
381
|
|
|
237
382
|
```ini
|
|
238
383
|
[Unit]
|
|
@@ -241,8 +386,7 @@ After=network-online.target
|
|
|
241
386
|
Wants=network-online.target
|
|
242
387
|
|
|
243
388
|
[Service]
|
|
244
|
-
|
|
245
|
-
ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path>
|
|
389
|
+
ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path> --tokens %h/.config/chattrs/tokens.toml
|
|
246
390
|
Restart=always
|
|
247
391
|
|
|
248
392
|
[Install]
|
|
@@ -255,10 +399,9 @@ systemctl --user enable --now chattrs
|
|
|
255
399
|
loginctl enable-linger <user> # run without a login session
|
|
256
400
|
```
|
|
257
401
|
|
|
258
|
-
macOS: a launchd agent
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
the binary path to match your install (`which chattrs`).
|
|
402
|
+
macOS: put a launchd agent in `~/Library/LaunchAgents/dev.chattrs.broker.plist`.
|
|
403
|
+
A shell wrapper reads the 0600 tokens file, so the plist holds no token.
|
|
404
|
+
Change the binary path to match `which chattrs`.
|
|
262
405
|
|
|
263
406
|
```xml
|
|
264
407
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
@@ -271,7 +414,7 @@ the binary path to match your install (`which chattrs`).
|
|
|
271
414
|
<array>
|
|
272
415
|
<string>/bin/sh</string>
|
|
273
416
|
<string>-c</string>
|
|
274
|
-
<string>
|
|
417
|
+
<string>exec /opt/homebrew/bin/chattrs serve --listen <broker-ip>:4646 --db "$HOME/.local/share/chattrs/chattrs.db" --tokens "$HOME/.config/chattrs/tokens.toml"</string>
|
|
275
418
|
</array>
|
|
276
419
|
<key>RunAtLoad</key><true/>
|
|
277
420
|
<key>KeepAlive</key><true/>
|
|
@@ -286,203 +429,290 @@ launchctl kickstart -k gui/$(id -u)/dev.chattrs.broker # restart
|
|
|
286
429
|
launchctl bootout gui/$(id -u)/dev.chattrs.broker # stop and unload
|
|
287
430
|
```
|
|
288
431
|
|
|
289
|
-
A launchd agent runs while its user is logged in. Turn on automatic
|
|
290
|
-
|
|
432
|
+
A launchd agent runs while its user is logged in. Turn on automatic login
|
|
433
|
+
for an unattended Mac.
|
|
291
434
|
|
|
292
435
|
### Set client hosts
|
|
293
436
|
|
|
294
|
-
|
|
437
|
+
`chattrs setup --join` does this for you ([Get running](#get-running)). Use this section to edit the config by hand.
|
|
295
438
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
export CHATTRS_TOKEN=<token>
|
|
299
|
-
export CHATTRS_ADDRESS=<agent>@<host>
|
|
300
|
-
```
|
|
439
|
+
On every client host, set the broker address and the token file in the user
|
|
440
|
+
config (see [Environment and config](#environment-and-config)):
|
|
301
441
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
442
|
+
```toml
|
|
443
|
+
# ~/.config/chattrs/config.toml
|
|
444
|
+
server = "<broker-ip>:4646"
|
|
445
|
+
token_file = "/home/me/.config/chattrs/token" # mode 0600, this host's token only
|
|
446
|
+
```
|
|
305
447
|
|
|
306
|
-
The agent on the broker host is a client too. Set its
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
(CLI-11), and that agent then talks to a different swarm.
|
|
448
|
+
The agent on the broker host is a client too. Set its `server` to the
|
|
449
|
+
broker's tailnet IP, not to loopback. A loopback server that is down gets a
|
|
450
|
+
second, auto-started broker, and that agent then joins a different swarm.
|
|
310
451
|
|
|
311
|
-
|
|
312
|
-
clear text inside the private network. One token covers the whole
|
|
313
|
-
fleet. Addresses are self-asserted: the token proves fleet
|
|
314
|
-
membership, not which address is yours. Until signed tokens land, the
|
|
315
|
-
shared `CHATTRS_TOKEN` reaches every project: a project keeps agents
|
|
316
|
-
apart by accident, not by access control.
|
|
452
|
+
### Start a worker
|
|
317
453
|
|
|
318
|
-
|
|
454
|
+
The lead starts each worker over ssh in a detached tmux session. The worker
|
|
455
|
+
needs no flags. The host config has the server and token file. The repo's
|
|
456
|
+
`.chattrs.toml` has the project and lead. The address, session, project,
|
|
457
|
+
and lead exist only in the launch line:
|
|
319
458
|
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
that exists only in another project lands in the sender's project, with
|
|
324
|
-
`known:false`. The same address in two projects is two agents. A client
|
|
325
|
-
with no project uses `default`, so old clients keep working.
|
|
459
|
+
```bash
|
|
460
|
+
ssh <host> 'tmux new -d -s w1 '"'"'eval "$(chattrs env --as worker1@<host>)"; exec claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."'"'"''
|
|
461
|
+
```
|
|
326
462
|
|
|
327
|
-
|
|
328
|
-
explicitly. Never derive it from the git directory name: two checkouts of
|
|
329
|
-
one repo, or a renamed directory, would split or merge swarms by accident.
|
|
463
|
+
On the host itself:
|
|
330
464
|
|
|
331
465
|
```bash
|
|
332
|
-
|
|
333
|
-
chattrs projects # every project with agent and message counts
|
|
334
|
-
chattrs agents --all # include agents quiet for over 7 days
|
|
466
|
+
tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
|
|
335
467
|
```
|
|
336
468
|
|
|
337
|
-
|
|
338
|
-
and
|
|
469
|
+
`chattrs env` prints `export` lines for `CHATTRS_SERVER`, `CHATTRS_ADDRESS`,
|
|
470
|
+
`CHATTRS_SESSION`, and, when known, `CHATTRS_PROJECT`, `CHATTRS_LEAD`, and
|
|
471
|
+
`CHATTRS_TAGS`. Commands read the token from `token_file`.
|
|
339
472
|
|
|
340
|
-
|
|
473
|
+
`CHATTRS_LEAD` and `CHATTRS_SESSION` survive `/clear`. The launch prompt
|
|
474
|
+
does not, so the prompt names the address and the lead, and starts `chattrs
|
|
475
|
+
watch` under Monitor. The `chattrs-fleet` skill has the same wording.
|
|
341
476
|
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
token in `~/.config/chattrs/env` on the worker host, mode 0600, as
|
|
345
|
-
`export CHATTRS_TOKEN=<token>`.
|
|
477
|
+
Some systemd hosts kill a user's tmux server on ssh logout. Start tmux in
|
|
478
|
+
its own scope and turn on linger:
|
|
346
479
|
|
|
347
480
|
```bash
|
|
348
|
-
ssh <host> 'tmux new -d -s
|
|
349
|
-
|
|
350
|
-
export CHATTRS_ADDRESS=worker1@<host> \
|
|
351
|
-
CHATTRS_SERVER=<broker-ip>:4646 \
|
|
352
|
-
CHATTRS_PROJECT=<project> \
|
|
353
|
-
CHATTRS_LEAD=opus@mac \
|
|
354
|
-
CHATTRS_TAGS=gpu; \
|
|
355
|
-
mkdir -p ~/.claude/skills/chattrs && \
|
|
356
|
-
chattrs skill > ~/.claude/skills/chattrs/SKILL.md; \
|
|
357
|
-
exec claude \"Your address is worker1@<host>. Your lead is opus@mac. \
|
|
358
|
-
Run chattrs watch under the Monitor tool now.\""'
|
|
481
|
+
ssh <host> 'systemd-run --user --scope tmux new -d -s w1 ...'
|
|
482
|
+
loginctl enable-linger <user> # once, on the worker host
|
|
359
483
|
```
|
|
360
484
|
|
|
361
|
-
|
|
362
|
-
names the worker's address and its lead. It also starts
|
|
363
|
-
`chattrs watch` under Monitor, so a message wakes the worker. See the
|
|
364
|
-
`chattrs-fleet` skill for the same wording. `CHATTRS_TAGS` is optional
|
|
365
|
-
and shows in `agents`.
|
|
366
|
-
Tags come from the latest hello. Set `CHATTRS_TAGS` in the worker's
|
|
367
|
-
launch environment. A chattrs command run from another shell without
|
|
368
|
-
it replaces the agent's tags with `os` and `arch`.
|
|
369
|
-
|
|
370
|
-
Windows has no native tmux. Use WSL, or leave a terminal session
|
|
371
|
-
running.
|
|
372
|
-
|
|
373
|
-
### Upgrade
|
|
374
|
-
|
|
375
|
-
Upgrade the broker first, then the clients. New protocol fields are
|
|
376
|
-
optional, so old clients keep working. Run `chattrs --version` on
|
|
377
|
-
each host to check.
|
|
485
|
+
Windows has no native tmux. Use WSL, or leave a terminal session open.
|
|
378
486
|
|
|
379
487
|
### Watch the swarm
|
|
380
488
|
|
|
381
|
-
`chattrs watch --all`
|
|
382
|
-
`CHATTRS_PROJECT='*'` it
|
|
383
|
-
|
|
384
|
-
|
|
489
|
+
`chattrs watch --all` streams every message of the own project. With
|
|
490
|
+
`CHATTRS_PROJECT='*'` it streams every project (needs an observer token or
|
|
491
|
+
legacy mode). `chattrs agents` shows who is online. `chattrs projects`
|
|
492
|
+
lists the projects.
|
|
385
493
|
|
|
386
494
|
### Exit test
|
|
387
495
|
|
|
388
|
-
Run this
|
|
496
|
+
Run this once on a new swarm.
|
|
389
497
|
|
|
390
|
-
1. Start the broker service
|
|
391
|
-
two remote workers connect to it.
|
|
498
|
+
1. Start the broker service. Connect a lead and two remote workers.
|
|
392
499
|
2. A worker reports to the lead. The lead gets it.
|
|
393
|
-
3. A worker asks the lead
|
|
394
|
-
4. Restart the broker mid-run
|
|
395
|
-
`launchctl kickstart -k ...`). Check `chattrs log`: no message is
|
|
396
|
-
lost.
|
|
500
|
+
3. A worker asks the lead and gets the reply.
|
|
501
|
+
4. Restart the broker mid-run. `chattrs log` shows no lost message.
|
|
397
502
|
5. `chattrs watch --all` shows every message live.
|
|
398
|
-
6. `chattrs agents` shows both workers online, with
|
|
399
|
-
7. An agent in another project cannot see or send to these workers
|
|
400
|
-
|
|
503
|
+
6. `chattrs agents` shows both workers online, with tags.
|
|
504
|
+
7. An agent in another project cannot see or send to these workers. A `*`
|
|
505
|
+
observer sees both projects.
|
|
506
|
+
|
|
507
|
+
### Token table
|
|
508
|
+
|
|
509
|
+
Meets SEC-4. A token table gives each token a project, an address pattern,
|
|
510
|
+
and a role. Start the broker with `serve --tokens <path>` or
|
|
511
|
+
`CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
|
|
512
|
+
mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
|
|
513
|
+
|
|
514
|
+
```toml
|
|
515
|
+
# The lead of project alpha. Only a lead token can claim this address.
|
|
516
|
+
[[token]]
|
|
517
|
+
token = "<64 hex characters>"
|
|
518
|
+
project = "alpha"
|
|
519
|
+
addr = "lead@box1"
|
|
520
|
+
role = "lead"
|
|
521
|
+
|
|
522
|
+
# Any worker on box1, in alpha only.
|
|
523
|
+
[[token]]
|
|
524
|
+
token = "<64 hex characters>"
|
|
525
|
+
project = "alpha"
|
|
526
|
+
addr = "*@box1"
|
|
527
|
+
role = "agent"
|
|
528
|
+
|
|
529
|
+
# A read-only viewer that sees every project.
|
|
530
|
+
[[token]]
|
|
531
|
+
token = "<64 hex characters>"
|
|
532
|
+
project = "*"
|
|
533
|
+
addr = "tray@mac"
|
|
534
|
+
role = "observer"
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
The parser reads a small subset of TOML: blank lines, `#` comments,
|
|
538
|
+
`[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
|
|
539
|
+
The keys `token`, `project`, `addr`, and `role` are required, once each.
|
|
540
|
+
Any other line, an unknown key, a bad value, or a repeated token stops the
|
|
541
|
+
broker with an error that names the line. A lead who leads several projects
|
|
542
|
+
uses one token and lists it once per project. One token twice in one
|
|
543
|
+
project is refused.
|
|
544
|
+
|
|
545
|
+
- `project` is a project name, or `"*"` for `observer` entries only.
|
|
546
|
+
- `addr` is an exact address, or a pattern where `*` matches any run of
|
|
547
|
+
characters, such as `*@box1`.
|
|
548
|
+
- `role` is `lead`, `agent`, or `observer`.
|
|
549
|
+
|
|
550
|
+
On `hello`, the broker compares the token with every entry in constant
|
|
551
|
+
time, then checks the hello:
|
|
552
|
+
|
|
553
|
+
- No entry matches: `bad_token`. The broker closes the connection.
|
|
554
|
+
- The project or address does not fit the entry, or a role rule fails:
|
|
555
|
+
`forbidden`.
|
|
556
|
+
- Lead rule: only a `lead` entry can claim an address that a `lead` entry
|
|
557
|
+
names exactly in that project.
|
|
558
|
+
- Observer rule: an `observer` entry works only with an observer hello. An
|
|
559
|
+
`agent` entry cannot send an observer hello.
|
|
560
|
+
|
|
561
|
+
The broker stamps each message with the sender's role as `from_role`. The
|
|
562
|
+
wrapper prints `from-role="lead"` for a lead. A worker accepts a destructive
|
|
563
|
+
request only from that role or from the user. Without a table, a lead
|
|
564
|
+
address is a claim, not proof.
|
|
565
|
+
|
|
566
|
+
Rules:
|
|
567
|
+
|
|
568
|
+
- With a tokens file, `CHATTRS_TOKEN` on the broker is ignored. A client
|
|
569
|
+
that sends the shared token gets `bad_token`.
|
|
570
|
+
- Without a tokens file, the shared token gives full access to every
|
|
571
|
+
project, and messages carry no `from_role`.
|
|
572
|
+
- The broker reads the file once, at start. To revoke a token, delete its
|
|
573
|
+
block and restart.
|
|
574
|
+
- Use one token per host. Put a lead token only on the lead's host. A
|
|
575
|
+
worker host then cannot claim the lead's address.
|
|
576
|
+
|
|
577
|
+
#### Turning on per-host tokens
|
|
578
|
+
|
|
579
|
+
This is for a swarm that already runs on the shared token. A new swarm uses `chattrs setup --broker` instead.
|
|
580
|
+
|
|
581
|
+
Once a tokens file exists, the broker refuses the shared token. Switching
|
|
582
|
+
everything at once breaks every client at the same moment. Use two phases.
|
|
583
|
+
|
|
584
|
+
Phase 1: a plain upgrade.
|
|
585
|
+
|
|
586
|
+
1. Back up the database: `chattrs backup <file> --db <db>`.
|
|
587
|
+
2. Upgrade the broker. Start it with no tokens file. Legacy mode stays on.
|
|
588
|
+
3. Check that workers and viewers still connect.
|
|
589
|
+
|
|
590
|
+
Phase 2: the cutover.
|
|
591
|
+
|
|
592
|
+
1. Write `tokens.toml` at mode 0600. Make each token with
|
|
593
|
+
`openssl rand -hex 32`. Add one `lead` entry per project: `project = "*"`
|
|
594
|
+
is for observers only, and the broker refuses it on `lead` and `agent`
|
|
595
|
+
entries. Add one `agent` entry per host with an address pattern such as
|
|
596
|
+
`*@box1`. Add one `observer` entry for a viewer, with `project = "*"`.
|
|
597
|
+
2. Before the switch, give each host its `token_file` (mode 0600) and
|
|
598
|
+
`~/.config/chattrs/config.toml` (`server`, `token_file`). Enter each
|
|
599
|
+
viewer's token in that viewer's own settings.
|
|
600
|
+
3. Start the broker with `--tokens <path>`, or restart it.
|
|
601
|
+
4. Verify: the lead's messages show `from-role="lead"`. A worker token
|
|
602
|
+
cannot claim the lead's address. The viewer connects as an observer.
|
|
603
|
+
Hooks still deliver.
|
|
604
|
+
5. Roll back: remove `--tokens` and restart. Legacy mode returns at once.
|
|
605
|
+
|
|
606
|
+
### Projects
|
|
607
|
+
|
|
608
|
+
A project is a namespace on the broker. Messages, inboxes, agents, the log,
|
|
609
|
+
topics, and the online count belong to one project. An agent sees and sends
|
|
610
|
+
only inside its own project. A `send` to an address that exists only in
|
|
611
|
+
another project lands in the sender's project, with `known:false`. The same
|
|
612
|
+
address in two projects is two agents (NS-1). A client with no project uses
|
|
613
|
+
`default`.
|
|
614
|
+
|
|
615
|
+
Set `CHATTRS_PROJECT` in the launch environment, with an explicit name.
|
|
616
|
+
Never derive it from the directory name: a renamed or second checkout would
|
|
617
|
+
split or merge swarms.
|
|
618
|
+
|
|
619
|
+
```bash
|
|
620
|
+
export CHATTRS_PROJECT=alpha
|
|
621
|
+
chattrs projects # every project with agent and message counts
|
|
622
|
+
chattrs agents --all # include agents quiet for over 7 days
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
### One session per address
|
|
626
|
+
|
|
627
|
+
`hello` may carry a `session`, from `CHATTRS_SESSION`. The broker keeps an
|
|
628
|
+
in-memory record of which session holds each (project, address). A restart
|
|
629
|
+
clears it (ID-1).
|
|
630
|
+
|
|
631
|
+
- A `hello` from another session while the holder has a live connection
|
|
632
|
+
gets `address_in_use`. The message says how long ago the holder was last
|
|
633
|
+
active. The client does not retry. Wait, or use another address.
|
|
634
|
+
- The same session may open more connections. `watch`, `send`, and the
|
|
635
|
+
hooks all do.
|
|
636
|
+
- The address is free when the holder's last connection closes. A holder
|
|
637
|
+
that died without a close clears through TCP keepalive in about 1 minute.
|
|
638
|
+
Restart the worker with the same address and a new session. `chattrs env`
|
|
639
|
+
makes a new session on every run.
|
|
640
|
+
- An old client sends no session. It is never refused and never registered.
|
|
641
|
+
The broker only warns about a second live watch (CLI-15).
|
|
642
|
+
- An observer never registers and is never refused.
|
|
643
|
+
- A short-lived script sets no `CHATTRS_ADDRESS`. It takes no address and
|
|
644
|
+
fires no hooks. If it needs one, give it a unique address.
|
|
401
645
|
|
|
402
646
|
## Hooks (Claude Code and Codex)
|
|
403
647
|
|
|
404
|
-
Hooks deliver unread messages between tool calls. Codex has no
|
|
405
|
-
tool, so hooks are how a Codex worker hears a message.
|
|
648
|
+
Hooks deliver unread messages between tool calls (HOOK-1). Codex has no
|
|
649
|
+
Monitor tool, so hooks are how a Codex worker hears a message.
|
|
406
650
|
|
|
407
651
|
```bash
|
|
408
652
|
chattrs hooks install [--agent claude|codex|all] [--project]
|
|
409
653
|
chattrs hooks remove [--agent claude|codex|all] [--project]
|
|
410
654
|
```
|
|
411
655
|
|
|
412
|
-
-
|
|
413
|
-
`$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project`
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
- Install merges in place
|
|
418
|
-
|
|
419
|
-
file. `remove` deletes only own entries. Invalid JSON exits 1 and
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
new hooks only after review: open Codex and run `/hooks` to trust
|
|
426
|
-
them. Claude Code may ask you to review hooks edited outside it.
|
|
427
|
-
Until then the hooks look installed but do not run.
|
|
656
|
+
- By default, install edits `~/.claude/settings.json` and
|
|
657
|
+
`$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project` edits
|
|
658
|
+
`.claude/settings.json` and `.codex/hooks.json` in the current directory.
|
|
659
|
+
With `--agent all`, an agent whose config directory is missing is
|
|
660
|
+
skipped. An explicit `--agent` creates the file.
|
|
661
|
+
- Install merges in place. Other hooks stay. The own entries are
|
|
662
|
+
`chattrs hook <event> --agent claude|codex`. Install twice gives the same
|
|
663
|
+
file. `remove` deletes only own entries. Invalid JSON exits 1 and writes
|
|
664
|
+
nothing. A `.bak` copy is written once.
|
|
665
|
+
- After install, follow the printed next step. Codex runs new hooks only
|
|
666
|
+
after review: open Codex and run `/hooks` to trust them. Claude Code may
|
|
667
|
+
ask you to review hooks edited outside it. Until then the hooks do not
|
|
668
|
+
run.
|
|
428
669
|
- `chattrs` must be on the agent's `PATH`.
|
|
429
670
|
|
|
430
|
-
What each event does (`chattrs hook <event>`):
|
|
431
|
-
|
|
432
671
|
| Event | Effect |
|
|
433
672
|
| ----- | ------ |
|
|
434
|
-
| `session-start` | Fires on startup, clear, and compact
|
|
435
|
-
| `user-prompt-submit`, `post-tool-use` |
|
|
436
|
-
| `stop` | Sets the state to idle. When messages are unread, blocks the stop with them as the reason
|
|
437
|
-
|
|
438
|
-
Each delivering event claims before it prints
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
The cost: a message claimed but not printed (stdout closed) is not
|
|
673
|
+
| `session-start` | Fires on startup, clear, and compact (HOOK-2). Sets the state to idle. Tells the agent its address, its project (when not `default`), its lead (`CHATTRS_LEAD`), and to load the skill. Claude Code also gets the Monitor reminder. Then it adds the last 10 messages to and from the address, oldest first. When `CHATTRS_LEAD` is unset or equals the address, it also lists up to 10 messages the agent has not replied to. It acks nothing. It prints the address, lead, and skill lines even when the broker is down. |
|
|
674
|
+
| `user-prompt-submit`, `post-tool-use` | Add unread messages as `additionalContext`. `user-prompt-submit` also sets the state to working. |
|
|
675
|
+
| `stop` | Sets the state to idle. When messages are unread, it blocks the stop with them as the reason and sets working again. It never blocks when `stop_hook_active` is true. |
|
|
676
|
+
|
|
677
|
+
Each delivering event claims before it prints: it fetches unread messages,
|
|
678
|
+
acks them all, and prints only the ids that the ack changed. Two hook runs
|
|
679
|
+
at once split the messages and never print one twice. If the ack fails, the
|
|
680
|
+
run prints nothing. A message that was claimed but not printed is not
|
|
443
681
|
redelivered.
|
|
444
682
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
get about 300 ms, and any failure prints nothing and exits 0. A message
|
|
449
|
-
that was not acked stays unread for the next command.
|
|
450
|
-
|
|
451
|
-
Debugging aid: set `CHATTRS_HOOK_DEBUG=<file>` and each `chattrs hook` run
|
|
452
|
-
appends one JSON line with `pid`, `ts_ms`, `event`, the raw stdin as
|
|
453
|
-
`input`, and the ids it `fetched` and `emitted`. Use it to see which hook
|
|
454
|
-
runs fire for one tool call and which ones deliver.
|
|
683
|
+
`chattrs hook` does nothing unless `CHATTRS_ADDRESS` is set. It never
|
|
684
|
+
starts a broker. It is best effort: it waits about 300 ms for the broker,
|
|
685
|
+
and any failure prints nothing and exits 0.
|
|
455
686
|
|
|
456
687
|
## Protocol
|
|
457
688
|
|
|
458
|
-
One JSON object per line, `\n`-terminated. The `type` field
|
|
689
|
+
One JSON object per line, `\n`-terminated. The `type` field names the
|
|
690
|
+
frame. Protocol version is 1.
|
|
459
691
|
|
|
460
|
-
Client
|
|
692
|
+
Client to broker:
|
|
461
693
|
|
|
462
694
|
```json
|
|
463
695
|
{"type":"hello", "v":1, "address":"codex@box1", "token":"…", "tags":["os:linux","arch:x86_64","gpu"]}
|
|
696
|
+
{"type":"hello", "v":1, "address":"codex@box1", "project":"alpha", "session":"s1", "state":"working"}
|
|
697
|
+
{"type":"hello", "v":1, "address":"viewer@mac", "observer":true, "project":"*"}
|
|
464
698
|
{"type":"send", "to":"opus@mac", "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
465
699
|
{"type":"send", "to":null, "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
466
700
|
{"type":"inbox"}
|
|
467
701
|
{"type":"ack", "ids":[12, 13]}
|
|
468
702
|
{"type":"watch"}
|
|
469
703
|
{"type":"watch", "topics":["release-26"]}
|
|
470
|
-
{"type":"hello", "v":1, "address":"codex@box1", "state":"working"}
|
|
471
|
-
{"type":"hello", "v":1, "address":"viewer@mac", "observer":true}
|
|
472
|
-
{"type":"hello", "v":1, "address":"viewer@mac", "observer":true, "project":"*"}
|
|
473
|
-
{"type":"hello", "v":1, "address":"codex@box1", "project":"alpha"}
|
|
474
704
|
{"type":"watch", "all":true}
|
|
475
705
|
{"type":"wait", "reply_to":12}
|
|
476
706
|
{"type":"agents"}
|
|
477
|
-
{"type":"agents", "all":true}
|
|
478
|
-
{"type":"agents", "projects":true}
|
|
707
|
+
{"type":"agents", "all":true, "projects":true}
|
|
479
708
|
{"type":"log", "address":"codex@box1", "after":0, "limit":500}
|
|
709
|
+
{"type":"log", "address":"codex@box1", "tail":10}
|
|
480
710
|
```
|
|
481
711
|
|
|
482
|
-
Broker
|
|
712
|
+
Broker to client:
|
|
483
713
|
|
|
484
714
|
```json
|
|
485
|
-
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
|
|
715
|
+
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha", "version":"0.6.0"}
|
|
486
716
|
{"type":"sent", "id":12} // optional "known":false: `to` never said hello
|
|
487
717
|
{"type":"inbox", "messages":[
|
|
488
718
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
@@ -490,221 +720,190 @@ Broker → client:
|
|
|
490
720
|
{"type":"message", "id":13,"from":"opus@mac","to":"codex@box1",
|
|
491
721
|
"body":"hi","ts":1763200000001,"reply_to":12,"topic":null,"project":"alpha"}
|
|
492
722
|
{"type":"acked", "ids":[12, 13]}
|
|
493
|
-
{"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]
|
|
494
|
-
{"
|
|
495
|
-
|
|
723
|
+
{"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}],
|
|
724
|
+
"projects":[{"project":"alpha","agents":2,"messages":14}]}
|
|
725
|
+
{"type":"log", "messages":[{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
496
726
|
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"project":"alpha","acked_at":null}]}
|
|
497
|
-
{"type":"agents", "agents":[…], "projects":[{"project":"alpha","agents":2,"messages":14}]}
|
|
498
727
|
{"type":"error", "code":"empty_body", "message":"body is empty"}
|
|
499
728
|
```
|
|
500
729
|
|
|
501
|
-
`
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
`
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
`
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
effective `project` (an older broker omits it). Every frame is scoped to the
|
|
524
|
-
connection's project: `send` (`to` is always in the sender's project),
|
|
525
|
-
`inbox`, `wait`, `ack`, `agents`, `log`, `watch` with and without topics,
|
|
526
|
-
topic backlogs, `known`, and the online count, which is keyed by project and
|
|
527
|
-
address. Message and agent JSON carry `project`; a frame from an older
|
|
528
|
-
broker without it reads as `default`. Only an observer may send
|
|
529
|
-
`"project":"*"`; any other `hello` with `*` gets `bad_project`. A `*` observer's
|
|
530
|
-
`watch` with `all`, its `log`, and its `agents` span every project, and each
|
|
531
|
-
message and agent row carries its `project`. An observer with a named
|
|
532
|
-
project sees only that project. `agents` leaves out an agent that is
|
|
533
|
-
offline, last seen over 7 days ago, and has sent or received nothing for 7
|
|
534
|
-
days, unless the request sets `"all":true`; nothing is deleted. With
|
|
535
|
-
`"projects":true`, the `agents` answer adds `projects`, the agent and message
|
|
536
|
-
count of each project the connection can see (one for a named project, every
|
|
537
|
-
project for `*`); `chattrs projects` is that request from a `*` observer.
|
|
538
|
-
|
|
539
|
-
`inbox` returns every message for the `hello` address with no ack yet, in
|
|
540
|
-
id order. `ack` marks the listed ids read when they belong to that address
|
|
541
|
-
and are unread, and `acked` lists the ids that changed; other ids are
|
|
542
|
-
ignored. Except for `watch`, the broker never pushes messages: the client
|
|
543
|
-
asks. Every accepted `hello` records the address with the broker clock, and
|
|
544
|
-
the broker records it again when that connection closes. `agents` returns
|
|
545
|
-
all recorded addresses sorted by address; an address that only received
|
|
546
|
-
messages and never connected is not listed. `hello` may carry an optional
|
|
547
|
-
`tags` list (at most 32 tags of 64 bytes each, else `bad_tags`). The client
|
|
548
|
-
always sends `os:<os>` and `arch:<arch>`, plus the comma-separated entries of
|
|
549
|
-
`CHATTRS_TAGS` (for example `CHATTRS_TAGS=gpu:4090,fast`). The broker keeps
|
|
550
|
-
the tags of the latest `hello` that sent any, and `agents` shows them after
|
|
551
|
-
the last-seen time; `agents --json` always has a `tags` array. Tags come from the latest hello. Set `CHATTRS_TAGS` in the worker's launch environment. A chattrs command run from another shell without it replaces the agent's tags with `os` and `arch`. Each agent
|
|
552
|
-
also has `online`: `true` while the address has a live inbox `watch`
|
|
553
|
-
connection (topic watches do not count), else `false`. The broker counts
|
|
554
|
-
this in memory and never stores it; an older broker omits it, which reads as
|
|
555
|
-
`false`. `agents` text shows `online` in place of the last-seen time.
|
|
556
|
-
`hello` may also carry an optional `state`: `working`, `idle`, or `waiting`
|
|
557
|
-
(else `bad_state`). The broker stores the state and the time it was set
|
|
558
|
-
(`state_at`, ms on the broker clock) when a `hello` carries one; a `hello`
|
|
559
|
-
without a state keeps both. An observer `hello` with a state gets
|
|
560
|
-
`observer_read_only`. `agents` text shows the state after the online or
|
|
561
|
-
last-seen column and before the tags, and shows nothing when the agent never
|
|
562
|
-
reported one; `agents --json` always has `state` and `state_at`, `null`
|
|
563
|
-
when never set. The broker never expires a state. A client shows a state
|
|
564
|
-
older than 15 minutes as `unknown`; `agents` text does. `chattrs status
|
|
565
|
-
<state>` sends such a `hello`.
|
|
730
|
+
`projects` appears only when the request sets `"projects":true`.
|
|
731
|
+
|
|
732
|
+
**Hello.** `hello` must come first, or the broker answers `hello_required`
|
|
733
|
+
and closes. The broker takes the sender from the `hello` address. A `send`
|
|
734
|
+
carries no sender. When the broker has a token or table, every `hello`
|
|
735
|
+
carries a token, loopback too. Optional `hello` fields:
|
|
736
|
+
|
|
737
|
+
- `project` (from `CHATTRS_PROJECT`): validated like a topic. Default is
|
|
738
|
+
`default`. `welcome` echoes it. Only an observer may use `*`.
|
|
739
|
+
- `session`: see [One session per address](#one-session-per-address).
|
|
740
|
+
- `tags`: at most 32 tags of 64 bytes. The client sends `os:<os>`,
|
|
741
|
+
`arch:<arch>`, and the `CHATTRS_TAGS` entries. The broker keeps the tags
|
|
742
|
+
of the latest `hello` that sent any.
|
|
743
|
+
- `state`: `working`, `idle`, or `waiting`. The broker stores it with
|
|
744
|
+
`state_at` (ms, broker clock). A `hello` without a state keeps the old
|
|
745
|
+
one. The broker never expires a state. A client shows a state older than
|
|
746
|
+
15 minutes as `unknown` (MON-4). `chattrs status` sends such a `hello`.
|
|
747
|
+
- `observer`: see [Monitoring](#monitoring-api-observer).
|
|
748
|
+
|
|
749
|
+
`welcome` carries `"version"`, the broker's crate version. It is optional:
|
|
750
|
+
an older broker omits it, and an older client ignores it. `doctor` shows it.
|
|
751
|
+
|
|
566
752
|
`welcome` may carry `"watching":true` when the address already has a live
|
|
567
|
-
inbox `watch
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
753
|
+
inbox `watch`. The `watch` command then warns once on stderr and keeps
|
|
754
|
+
going.
|
|
755
|
+
|
|
756
|
+
**Send.** A send to an unknown address succeeds, and the inbox exists by
|
|
757
|
+
name (MSG-8). A `send` with `reply_to` and no `to` is a reply: the broker
|
|
758
|
+
addresses it to the sender of that message. A reply without a `topic`
|
|
759
|
+
stores the topic of the message it answers. A `send` with a `topic` and no
|
|
760
|
+
`to` is an announcement: it has `"to":null` and no owning inbox. No `to`
|
|
761
|
+
and no `topic` gets `bad_address`. A direct message with a topic stays
|
|
762
|
+
direct: topic watchers never see it.
|
|
763
|
+
|
|
764
|
+
**Scope.** Every frame is scoped to the connection's project: `send`,
|
|
765
|
+
`inbox`, `wait`, `ack`, `agents`, `log`, `watch`, topic backlogs, `known`,
|
|
766
|
+
and the online count. Message and agent rows carry `project`. A frame from
|
|
767
|
+
an older broker without it reads as `default`.
|
|
768
|
+
|
|
769
|
+
**Inbox and ack.** `inbox` returns every unread message for the `hello`
|
|
770
|
+
address, in id order. `ack` marks the listed ids read when they belong to
|
|
771
|
+
that address. `acked` lists the ids that changed. Delivery is at least
|
|
772
|
+
once: a crash between print and ack prints the message again. The id
|
|
773
|
+
tells duplicates apart.
|
|
774
|
+
|
|
775
|
+
**Agents.** Every accepted `hello` records the address with the broker
|
|
776
|
+
clock, and the broker records it again on close. `agents` lists the
|
|
777
|
+
recorded addresses of the project, sorted by address. An address that only
|
|
778
|
+
received messages is not listed. `online` is true while the address has a
|
|
779
|
+
live inbox `watch` (topic watches do not count). The broker counts it in
|
|
780
|
+
memory. `agents` leaves out an agent that is offline, last seen over 7 days
|
|
781
|
+
ago, with no traffic in 7 days, unless the request sets `"all":true`.
|
|
782
|
+
Nothing is deleted. With `"projects":true`, the answer adds the counts of
|
|
783
|
+
every project the connection can see.
|
|
784
|
+
|
|
785
|
+
**Watch.** The broker subscribes the connection, sends every unread message
|
|
786
|
+
in id order, then each new one. It skips ids it already sent. A connection
|
|
787
|
+
that falls behind is closed. The `watch` command prints each message as one
|
|
788
|
+
JSON line, acks it on the same connection, and reconnects with backoff from
|
|
789
|
+
1 s to 30 s. Two watchers on one address both get every message.
|
|
790
|
+
|
|
791
|
+
With `topics`, `watch` subscribes to those rooms instead of the inbox. The
|
|
792
|
+
broker sends each room's latest 500 announcements in id order, then each
|
|
793
|
+
new one. The client never acks them. A reconnect replays the backlog, so
|
|
794
|
+
an announcement can arrive twice. There is no join or leave: closing the
|
|
795
|
+
watcher ends the subscription.
|
|
796
|
+
|
|
797
|
+
**Wait and ask.** `wait` sends the lowest-id message to the `hello` address
|
|
798
|
+
with that `reply_to`, at once or when it arrives. `ask` sends its question,
|
|
799
|
+
parks a `wait`, prints the reply, acks it, and exits 0, all on one
|
|
800
|
+
connection. On a timeout it writes `timeout: no reply to <id>` to stderr
|
|
801
|
+
and exits 2 (`{"type":"timeout","id":12}` with `--json`). The late reply
|
|
802
|
+
stays unread. After a drop, `ask` resends only the `wait`, never the
|
|
803
|
+
question.
|
|
804
|
+
|
|
805
|
+
**Log.** `log` returns messages with id above `after`, in id order, at most
|
|
806
|
+
`limit` (cap 500), with `acked_at` set for read messages. With `address`,
|
|
807
|
+
only that sender or recipient. It never acks. The `log` command pages until
|
|
808
|
+
a page has fewer than 500 rows. With `tail` N, `log` returns the newest N
|
|
809
|
+
rows in one round trip, still in id order, and ignores `limit`. An old
|
|
810
|
+
broker ignores `tail`, and the client keeps the last N rows it got.
|
|
572
811
|
|
|
573
812
|
### Monitoring API (observer)
|
|
574
813
|
|
|
575
|
-
A monitor, such as
|
|
814
|
+
A monitor, such as the tray, uses only the wire protocol (MON-3):
|
|
576
815
|
|
|
577
816
|
1. `hello` with `"observer":true`. The broker never records the address,
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
817
|
+
lists it in `agents`, or counts it as online or `watching`. It stores no
|
|
818
|
+
tags from it. The token check is the same. A `"project":"*"` observer
|
|
819
|
+
sees every project. Otherwise it sees its own project.
|
|
820
|
+
2. `welcome` echoes `"observer":true`. A broker without observer support
|
|
821
|
+
omits it. The client then polls `log`.
|
|
582
822
|
3. `watch` with `"all":true` streams each new message, direct and
|
|
583
|
-
announcements, as `message` frames. It sends no backlog and acks nothing
|
|
584
|
-
`all`
|
|
823
|
+
announcements, as `message` frames. It sends no backlog and acks nothing
|
|
824
|
+
(MON-1). `all` without an observer hello gets `not_observer`.
|
|
585
825
|
4. `agents` gives presence, tags, and state. `log` gives history.
|
|
586
|
-
5. `"project":"*"` on the observer `hello` streams and lists every project;
|
|
587
|
-
without it the observer sees only its own project.
|
|
588
826
|
|
|
589
|
-
An observer
|
|
590
|
-
`observer_read_only
|
|
591
|
-
it never delays a sender. To catch up
|
|
592
|
-
`watch` with `all` first and buffer what it streams
|
|
593
|
-
`
|
|
594
|
-
message id.
|
|
827
|
+
An observer is read-only: `send`, `ack`, `wait`, and `inbox` get
|
|
828
|
+
`observer_read_only`, and so does a `hello` with a `state`. A slow
|
|
829
|
+
observer is disconnected, so it never delays a sender. To catch up, start
|
|
830
|
+
`watch` with `all` first and buffer what it streams. Then read `log` with
|
|
831
|
+
`after` set to the last id you hold. Drop duplicates by id.
|
|
595
832
|
|
|
596
833
|
#### Viewer contract
|
|
597
834
|
|
|
598
|
-
Viewers are separate programs
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
Hooks say `hello` on every tool call, so `last_seen` is an activity
|
|
619
|
-
heartbeat. There is no ping probe, and no lease rule yet.
|
|
835
|
+
Viewers are separate programs. The `chattrs` binary stays CLI only.
|
|
836
|
+
|
|
837
|
+
- A read-only viewer connects as an observer and follows the catch-up flow
|
|
838
|
+
above. Use `agents` for presence, tags, and state.
|
|
839
|
+
- A viewer that observes `*` groups rows by `project`. In legacy mode the
|
|
840
|
+
shared token reaches every project. With a token table, only an entry
|
|
841
|
+
with `project = "*"` does.
|
|
842
|
+
- With a token table, a message also carries `from_role` (`lead` or
|
|
843
|
+
`agent`). It is absent without a table and on older rows. A viewer may
|
|
844
|
+
show it next to `from`. It proves no more than the token table proves.
|
|
845
|
+
- An interactive viewer, one that sends or replies, connects as a normal
|
|
846
|
+
agent with its own address, such as `operator@mac`.
|
|
847
|
+
- Health (MON-5) is not on the wire. A viewer computes it from the
|
|
848
|
+
`agents` row and its own clock, as `chattrs agents` does. Activity is the
|
|
849
|
+
later of `last_seen` and `state_at`. Check in this order: `gone` when not
|
|
850
|
+
`online` and `last_seen` is over 1 h ago; `stalled` when `state` is
|
|
851
|
+
`working` and activity is 10 min or more ago; `healthy` when `online` and
|
|
852
|
+
activity is under 10 min ago; else no label. Hooks say `hello` on every
|
|
853
|
+
tool call, so `last_seen` works as an activity heartbeat. There is no
|
|
854
|
+
ping.
|
|
620
855
|
- A viewer ignores unknown fields and unknown frame types.
|
|
621
|
-
- The observer frames and the `agents` JSON shape
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
announcement twice across a reconnect; the id tells duplicates apart.
|
|
645
|
-
Closing the watcher ends the subscription: there is no join or leave,
|
|
646
|
-
and the broker tracks no listener list.
|
|
647
|
-
|
|
648
|
-
On `wait`, the broker subscribes the connection, then sends the
|
|
649
|
-
lowest-id message to the `hello` address with that `reply_to`, whether
|
|
650
|
-
it is acked or not — at once when one exists, else when one arrives.
|
|
651
|
-
One `wait` gets one message, and the connection keeps reading frames
|
|
652
|
-
while it waits. The reply also reaches live `watch` connections, so an
|
|
653
|
-
agent running both sees it twice. The `ask` command sends its question,
|
|
654
|
-
parks a `wait`, and on the reply prints it wrapped as `<agent-message>`
|
|
655
|
-
text (or one JSON `message` line with `"untrusted":true` when
|
|
656
|
-
`--json`), flushes stdout, acks it, and exits 0 — all on one connection.
|
|
657
|
-
On a timeout it closes the connection, writes `timeout: no reply to
|
|
658
|
-
<id>` to stderr, exits 2 (and prints `{"type":"timeout","id":12}` with
|
|
659
|
-
`--json`); the late reply stays unread. A dropped connection reconnects
|
|
660
|
-
with the `watch` backoff and resends only the `wait`, never the
|
|
661
|
-
question, and the reply is acked on the connection that received it.
|
|
662
|
-
|
|
663
|
-
`log` returns messages with id above `after`, in id order, at most
|
|
664
|
-
`limit` (capped at 500), with `acked_at` set for read messages and null
|
|
665
|
-
for unread ones. With `address`, only messages where it is the sender or
|
|
666
|
-
the recipient are returned; without it, the full history is. `log` reads
|
|
667
|
-
only: it never acks. The `log` command pages with `after` until a page
|
|
668
|
-
holds fewer than 500 rows, so its output is the full history.
|
|
669
|
-
|
|
670
|
-
A `send` with a `reply_to` and no `topic` stores the topic of the
|
|
671
|
-
message it answers; an explicit `topic` always wins. An invalid slug is
|
|
672
|
-
rejected with `bad_topic`.
|
|
673
|
-
|
|
674
|
-
Error codes: `bad_frame`, `hello_required`, `bad_version` (v ≠ 1),
|
|
675
|
-
`bad_address`, `bad_token`, `bad_tags`, `bad_project`, `bad_topic`, `empty_body`, `too_large`,
|
|
676
|
-
`unknown_message`, `not_recipient`. After `hello`, an error does not
|
|
677
|
-
close the connection, except `bad_token`, which always closes it.
|
|
678
|
-
|
|
679
|
-
Limits: an address is `user@host` (`[A-Za-z0-9._-]` each side, 128 bytes
|
|
680
|
-
max). A body is 1 byte to 64 KiB. A topic is 1-64 bytes of lowercase
|
|
681
|
-
letters, digits, and hyphens, never starting or ending with a hyphen.
|
|
682
|
-
An inbound line over 128 KiB is rejected with `too_large`.
|
|
856
|
+
- The observer frames and the `agents` JSON shape change only by adding
|
|
857
|
+
fields.
|
|
858
|
+
|
|
859
|
+
### Errors and limits
|
|
860
|
+
|
|
861
|
+
Error codes: `bad_frame`, `hello_required`, `bad_version` (v is not 1),
|
|
862
|
+
`bad_address`, `bad_token`, `forbidden`, `bad_tags`, `bad_project`,
|
|
863
|
+
`bad_session`, `address_in_use`, `bad_state`, `observer_read_only`,
|
|
864
|
+
`not_observer`, `bad_topic`, `empty_body`, `too_large`, `unknown_message`,
|
|
865
|
+
`not_recipient`, `internal`. After `hello`, an error does not close the
|
|
866
|
+
connection. `bad_token` always does.
|
|
867
|
+
|
|
868
|
+
An address is `user@host` (`[A-Za-z0-9._-]` each side, 128 bytes max). A
|
|
869
|
+
body is 1 byte to 64 KiB. A topic is 1 to 64 bytes of lowercase letters,
|
|
870
|
+
digits, and hyphens, and does not start or end with a hyphen. A line over
|
|
871
|
+
128 KiB gets `too_large`.
|
|
872
|
+
|
|
873
|
+
## Compatibility
|
|
874
|
+
|
|
875
|
+
The protocol is v1. New fields are optional, so old clients keep working.
|
|
876
|
+
Upgrade the broker first, then the clients. Check `chattrs --version` on
|
|
877
|
+
each host. Projects, the token table, and sessions need a broker of the
|
|
878
|
+
matching version. An older broker ignores them.
|
|
683
879
|
|
|
684
880
|
## Design
|
|
685
881
|
|
|
686
|
-
- **Durable
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
- **Addresses, not accounts.** An agent is whoever its `hello` says
|
|
690
|
-
|
|
691
|
-
fleet token admits every address.
|
|
882
|
+
- **Durable first.** The broker commits each message to SQLite before it
|
|
883
|
+
confirms the send. A restart loses nothing. The broker never deletes a
|
|
884
|
+
message (MSG-1).
|
|
885
|
+
- **Addresses, not accounts.** An agent is whoever its `hello` says, unless
|
|
886
|
+
a token table limits the token.
|
|
692
887
|
- **Small and boring.** One SQLite file, line-JSON over TCP, no framework.
|
|
693
888
|
|
|
694
889
|
## Repository
|
|
695
890
|
|
|
696
|
-
- `src/main.rs` —
|
|
697
|
-
- `src/
|
|
698
|
-
- `src/
|
|
699
|
-
- `src/model.rs` — wire types
|
|
891
|
+
- `src/main.rs` — entry and dispatch.
|
|
892
|
+
- `src/cli.rs` — argument parsing.
|
|
893
|
+
- `src/config.rs` — config files.
|
|
894
|
+
- `src/model.rs` — wire types.
|
|
700
895
|
- `src/protocol.rs` — line-JSON framing.
|
|
701
896
|
- `src/store.rs` — SQLite storage.
|
|
702
|
-
- `src/server.rs` — the broker.
|
|
897
|
+
- `src/server.rs`, `src/server/` — the broker.
|
|
898
|
+
- `src/tokens.rs` — token table.
|
|
703
899
|
- `src/client.rs` — one connection per command.
|
|
704
|
-
- `src/
|
|
900
|
+
- `src/autostart.rs` — on-demand broker start, `stop`.
|
|
901
|
+
- `src/hook.rs`, `src/hook_install.rs` — hooks.
|
|
902
|
+
- `src/output.rs`, `src/skill.rs` — printing and the embedded skill.
|
|
903
|
+
- `tray/` — the macOS menu bar app.
|
|
705
904
|
|
|
706
|
-
See
|
|
707
|
-
|
|
905
|
+
See [docs/mission.md](docs/mission.md), [docs/requirements.md](docs/requirements.md),
|
|
906
|
+
[docs/planning.md](docs/planning.md), and [docs/code-style.md](docs/code-style.md).
|
|
708
907
|
|
|
709
908
|
## License
|
|
710
909
|
|