chattrs 0.2.2 → 0.4.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 +391 -67
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -10,18 +10,21 @@ so any language with a socket and a JSON library can participate.
|
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
13
|
-
On macOS
|
|
13
|
+
On any machine with Node (macOS, Linux, Windows):
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
|
|
16
|
+
npm install -g chattrs
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
On
|
|
19
|
+
On macOS (arm64):
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
|
|
22
|
+
brew install bolu-atx/tap/chattrs
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
+
Prebuilt binaries and shell/powershell installers for every
|
|
26
|
+
release live on the [Releases page](https://github.com/bolu-atx/chattrs/releases).
|
|
27
|
+
|
|
25
28
|
From source (any target, including Intel Macs):
|
|
26
29
|
|
|
27
30
|
```bash
|
|
@@ -69,13 +72,15 @@ it answers.
|
|
|
69
72
|
`"type":"message"` and `"untrusted":true` added.
|
|
70
73
|
|
|
71
74
|
`reply ID` answers message ID and prints the new id (text args, else
|
|
72
|
-
stdin)
|
|
73
|
-
`
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
the
|
|
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.
|
|
79
84
|
|
|
80
85
|
`send`, `reply`, `ask`, `agents`, and `log` print unread messages
|
|
81
86
|
first, then their own output. With `--json` the preamble lines are
|
|
@@ -92,21 +97,26 @@ announcement shows its room as the recipient
|
|
|
92
97
|
(`codex@box1 → topic:release-26: body`).
|
|
93
98
|
`log --json` prints one object per message with `"type":"log"`
|
|
94
99
|
and `"untrusted":true`, so a reader tells log rows from the preamble
|
|
95
|
-
`message` lines. `log`
|
|
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.
|
|
96
103
|
|
|
97
104
|
## Commands
|
|
98
105
|
|
|
99
106
|
| Command | What it does |
|
|
100
107
|
| ------- | ------------ |
|
|
101
108
|
| `serve` | Run the broker on `--listen` (default `127.0.0.1:4646`), storing to `--db`. A non-loopback `--listen` needs `--token`. |
|
|
102
|
-
| `stop` | Stop the auto-started broker named by the pidfile next to the DB. |
|
|
109
|
+
| `stop` | Stop the auto-started broker named by the pidfile next to the default DB. A remote broker is never stopped. |
|
|
103
110
|
| `send` | Post to `--to ADDR` and print the id (text args, else stdin). Names the workstream with `--topic SLUG`. With `--topic` and no `--to`, announce to that room instead. |
|
|
104
|
-
| `reply` | Answer message `ID` (text args, else stdin) and print the new id. Overrides the inherited topic with `--topic SLUG`. |
|
|
111
|
+
| `reply` | Answer message `ID` (text args, else stdin) and print the new id. Overrides the inherited topic with `--topic SLUG`. With `--json`, print the `sent` frame instead. |
|
|
105
112
|
| `inbox` | Print every unread message for `--address`, then ack what was printed. Announcements never appear here. |
|
|
106
113
|
| `watch` | Stream new messages as JSON lines forever, acking what is printed. With `--topic SLUG` (repeatable), stream that room's announcements instead, without acking. |
|
|
107
|
-
| `ask` | Post to `--to ADDR` and block for the reply (`--timeout SECS`, default 600, `0` means no limit). Names the workstream with `--topic SLUG`. |
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
114
|
+
| `ask` | Post to `--to ADDR` and block for the reply (`--timeout SECS`, default 600, `0` means no limit). Names the workstream with `--topic SLUG`. Exits 0 on a reply, 2 on a timeout. |
|
|
115
|
+
| `watch --all` | Observe every message, direct and announcements, as JSON lines. Connects as an observer, never acks, and exits 1 on a broker without observer support. |
|
|
116
|
+
| `agents` | List the known agent addresses of the own project, `online` while an agent has a live inbox `watch`, else when it was last seen, then the reported state, the health (`healthy`, `stalled`, or `gone`; see the Viewer contract), and the tags. Hides agents offline for over 7 days with no messages in that time; `--all` shows them. Nothing is deleted. |
|
|
117
|
+
| `projects` | List every project with its agent and message counts. Read-only. Connects as a `*` observer, so it prints no unread messages first. |
|
|
118
|
+
| `status` | Report the own state (`working`, `idle`, or `waiting`) and exit 0. Never starts a broker, gives up after about 2 s, and on a failure prints one stderr line and still exits 0. |
|
|
119
|
+
| `log` | Show the full message history, oldest first. With `--about ADDR`, keep only messages that ADDR sent or received. |
|
|
110
120
|
| `skill` | Print the bundled agent skill (`skills/chattrs/SKILL.md`) to stdout. Opens no connection, needs no address. |
|
|
111
121
|
|
|
112
122
|
Common flags:
|
|
@@ -117,6 +127,14 @@ Common flags:
|
|
|
117
127
|
address defaults to `<agent>@<hostname>` from `--agent`.
|
|
118
128
|
- `--agent AGENT` — agent name for the default address (`CHATTRS_AGENT`).
|
|
119
129
|
Needs one of address or agent: with neither, the command exits 1.
|
|
130
|
+
- `CHATTRS_PROJECT` — the project of every command, such as `alpha`
|
|
131
|
+
(default `default`). It has no flag. Valid names follow the topic rule:
|
|
132
|
+
lowercase letters, digits, and hyphens. See [Projects](#projects).
|
|
133
|
+
- `CHATTRS_LEAD` — the address of the agent's lead. Only the
|
|
134
|
+
`session-start` hook reads it (see [Hooks](#hooks-claude-code-and-codex)).
|
|
135
|
+
Optional. Set it only in the launch environment, with `CHATTRS_ADDRESS`
|
|
136
|
+
and `CHATTRS_PROJECT`. Never set these in a shell rc file: every session
|
|
137
|
+
would share one identity.
|
|
120
138
|
- `--token TOKEN` — fleet token (`CHATTRS_TOKEN`). `serve` needs it for a
|
|
121
139
|
non-loopback bind; every other command sends it in `hello`.
|
|
122
140
|
- `--json` — print JSON lines; every line carries a `type`, and
|
|
@@ -167,8 +185,12 @@ coordinator, who puts `$(chattrs skill)` in the worker's prompt.
|
|
|
167
185
|
|
|
168
186
|
## Run across hosts
|
|
169
187
|
|
|
170
|
-
Run one broker on an always-on
|
|
171
|
-
|
|
188
|
+
Run one broker on an always-on machine. Other hosts connect to it over
|
|
189
|
+
a private network (Tailscale or a LAN) with the shared token. The
|
|
190
|
+
broker host can run an agent too. This is "Claude Code-style swarms
|
|
191
|
+
for any agent": a lead and its workers share one broker. One broker
|
|
192
|
+
serves every project, so a second swarm needs a new `CHATTRS_PROJECT`,
|
|
193
|
+
not a second broker.
|
|
172
194
|
|
|
173
195
|
Install the same binary on every host:
|
|
174
196
|
|
|
@@ -178,15 +200,39 @@ cargo install --git https://github.com/bolu-atx/chattrs
|
|
|
178
200
|
# or: npm install -g chattrs
|
|
179
201
|
```
|
|
180
202
|
|
|
181
|
-
|
|
203
|
+
### Pick the broker host
|
|
204
|
+
|
|
205
|
+
- Use a machine that is always on. Do not use the lead's Mac: it
|
|
206
|
+
sleeps, and the swarm stops with it.
|
|
207
|
+
- Bind to the LAN or tailnet IP, never `0.0.0.0` and never a public
|
|
208
|
+
address. There is no TLS.
|
|
209
|
+
- Set `CHATTRS_TOKEN`. The broker refuses a non-loopback bind without
|
|
210
|
+
it. The `from` of a message is only as trustworthy as the token: with
|
|
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:
|
|
182
214
|
|
|
183
215
|
```bash
|
|
184
|
-
|
|
216
|
+
mkdir -p ~/.config/chattrs
|
|
217
|
+
printf 'CHATTRS_TOKEN=%s\n' "$(openssl rand -hex 32)" > ~/.config/chattrs/env
|
|
218
|
+
chmod 600 ~/.config/chattrs/env
|
|
185
219
|
```
|
|
186
220
|
|
|
187
|
-
Keep
|
|
188
|
-
|
|
189
|
-
|
|
221
|
+
### Keep the database
|
|
222
|
+
|
|
223
|
+
Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never
|
|
224
|
+
deletes a message, so the database is the swarm's history. Back it up
|
|
225
|
+
with SQLite, never with `cp` on a live database:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
sqlite3 <db> ".backup <file>"
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Run the broker as a service
|
|
232
|
+
|
|
233
|
+
Linux: a `systemd --user` unit. Put it in
|
|
234
|
+
`~/.config/systemd/user/chattrs.service`. The token comes from the
|
|
235
|
+
0600 file through `EnvironmentFile`.
|
|
190
236
|
|
|
191
237
|
```ini
|
|
192
238
|
[Unit]
|
|
@@ -196,24 +242,59 @@ Wants=network-online.target
|
|
|
196
242
|
|
|
197
243
|
[Service]
|
|
198
244
|
EnvironmentFile=%h/.config/chattrs/env
|
|
199
|
-
ExecStart=%h/.cargo/bin/chattrs serve --listen <
|
|
200
|
-
Restart=
|
|
245
|
+
ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path>
|
|
246
|
+
Restart=always
|
|
201
247
|
|
|
202
248
|
[Install]
|
|
203
249
|
WantedBy=default.target
|
|
204
250
|
```
|
|
205
251
|
|
|
206
252
|
```bash
|
|
207
|
-
# the env file holds one line: CHATTRS_TOKEN=<token>
|
|
208
|
-
chmod 600 ~/.config/chattrs/env
|
|
209
253
|
systemctl --user daemon-reload
|
|
210
254
|
systemctl --user enable --now chattrs
|
|
255
|
+
loginctl enable-linger <user> # run without a login session
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
macOS: a launchd agent. Put it in
|
|
259
|
+
`~/Library/LaunchAgents/dev.chattrs.broker.plist`. A shell wrapper
|
|
260
|
+
reads the same 0600 file, so the token stays out of the plist. Change
|
|
261
|
+
the binary path to match your install (`which chattrs`).
|
|
262
|
+
|
|
263
|
+
```xml
|
|
264
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
265
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
|
266
|
+
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
267
|
+
<plist version="1.0">
|
|
268
|
+
<dict>
|
|
269
|
+
<key>Label</key><string>dev.chattrs.broker</string>
|
|
270
|
+
<key>ProgramArguments</key>
|
|
271
|
+
<array>
|
|
272
|
+
<string>/bin/sh</string>
|
|
273
|
+
<string>-c</string>
|
|
274
|
+
<string>set -a; . "$HOME/.config/chattrs/env"; exec /opt/homebrew/bin/chattrs serve --listen <broker-ip>:4646 --db "$HOME/.local/share/chattrs/chattrs.db"</string>
|
|
275
|
+
</array>
|
|
276
|
+
<key>RunAtLoad</key><true/>
|
|
277
|
+
<key>KeepAlive</key><true/>
|
|
278
|
+
<key>StandardErrorPath</key><string>/tmp/chattrs-broker.log</string>
|
|
279
|
+
</dict>
|
|
280
|
+
</plist>
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
```bash
|
|
284
|
+
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.chattrs.broker.plist
|
|
285
|
+
launchctl kickstart -k gui/$(id -u)/dev.chattrs.broker # restart
|
|
286
|
+
launchctl bootout gui/$(id -u)/dev.chattrs.broker # stop and unload
|
|
211
287
|
```
|
|
212
288
|
|
|
213
|
-
|
|
289
|
+
A launchd agent runs while its user is logged in. Turn on automatic
|
|
290
|
+
login for an unattended Mac.
|
|
291
|
+
|
|
292
|
+
### Set client hosts
|
|
293
|
+
|
|
294
|
+
On every client host, set the same values:
|
|
214
295
|
|
|
215
296
|
```bash
|
|
216
|
-
export CHATTRS_SERVER=<
|
|
297
|
+
export CHATTRS_SERVER=<broker-ip>:4646
|
|
217
298
|
export CHATTRS_TOKEN=<token>
|
|
218
299
|
export CHATTRS_ADDRESS=<agent>@<host>
|
|
219
300
|
```
|
|
@@ -222,20 +303,156 @@ export CHATTRS_ADDRESS=<agent>@<host>
|
|
|
222
303
|
address per host, or set `CHATTRS_AGENT` and let the binary use
|
|
223
304
|
`<agent>@<hostname>`.
|
|
224
305
|
|
|
306
|
+
The agent on the broker host is a client too. Set its
|
|
307
|
+
`CHATTRS_SERVER` to the broker's LAN or tailnet IP, not to loopback.
|
|
308
|
+
A loopback server that is down gets a second, auto-started broker
|
|
309
|
+
(CLI-11), and that agent then talks to a different swarm.
|
|
310
|
+
|
|
225
311
|
Limits: there is no TLS, so the token and the messages travel as
|
|
226
|
-
clear text inside the
|
|
227
|
-
Addresses are self-asserted: the token proves fleet
|
|
228
|
-
not which address is yours.
|
|
229
|
-
|
|
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.
|
|
317
|
+
|
|
318
|
+
### Projects
|
|
230
319
|
|
|
231
|
-
A
|
|
232
|
-
|
|
320
|
+
A project is a namespace on the broker. Messages, inboxes, agents, the
|
|
321
|
+
log, topics, and the online count all belong to one project. An agent
|
|
322
|
+
sees and sends only inside its own project, and a `send` to an address
|
|
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.
|
|
326
|
+
|
|
327
|
+
Set the project with `CHATTRS_PROJECT` in the launch environment. Name it
|
|
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.
|
|
233
330
|
|
|
234
331
|
```bash
|
|
235
|
-
|
|
236
|
-
|
|
332
|
+
export CHATTRS_PROJECT=alpha
|
|
333
|
+
chattrs projects # every project with agent and message counts
|
|
334
|
+
chattrs agents --all # include agents quiet for over 7 days
|
|
237
335
|
```
|
|
238
336
|
|
|
337
|
+
The hooks need no setup: they read `CHATTRS_PROJECT` like every command,
|
|
338
|
+
and the session-start context names the project when it is not `default`.
|
|
339
|
+
|
|
340
|
+
### Start a worker
|
|
341
|
+
|
|
342
|
+
The lead starts each worker over ssh, in a detached tmux session. The
|
|
343
|
+
worker needs no flags: the env sets everything (CLI-6). First put the
|
|
344
|
+
token in `~/.config/chattrs/env` on the worker host, mode 0600, as
|
|
345
|
+
`export CHATTRS_TOKEN=<token>`.
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
ssh <host> 'tmux new -d -s worker1 \
|
|
349
|
+
". ~/.config/chattrs/env; \
|
|
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.\""'
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
`CHATTRS_LEAD` survives `/clear`; the launch prompt does not. The prompt
|
|
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.
|
|
378
|
+
|
|
379
|
+
### Watch the swarm
|
|
380
|
+
|
|
381
|
+
`chattrs watch --all` shows every message of the own project live. With
|
|
382
|
+
`CHATTRS_PROJECT='*'` it shows every project. See
|
|
383
|
+
[Monitoring API (observer)](#monitoring-api-observer) for the wire
|
|
384
|
+
form. `chattrs agents` shows who is online, with tags.
|
|
385
|
+
|
|
386
|
+
### Exit test
|
|
387
|
+
|
|
388
|
+
Run this checklist once on a new swarm.
|
|
389
|
+
|
|
390
|
+
1. Start the broker service on the swarm machine. A lead on the Mac and
|
|
391
|
+
two remote workers connect to it.
|
|
392
|
+
2. A worker reports to the lead. The lead gets it.
|
|
393
|
+
3. A worker asks the lead a question and gets the reply.
|
|
394
|
+
4. Restart the broker mid-run (`systemctl --user restart chattrs`, or
|
|
395
|
+
`launchctl kickstart -k ...`). Check `chattrs log`: no message is
|
|
396
|
+
lost.
|
|
397
|
+
5. `chattrs watch --all` shows every message live.
|
|
398
|
+
6. `chattrs agents` shows both workers online, with their tags.
|
|
399
|
+
7. An agent in another project cannot see or send to these workers, and a
|
|
400
|
+
`*` observer sees both projects.
|
|
401
|
+
|
|
402
|
+
## Hooks (Claude Code and Codex)
|
|
403
|
+
|
|
404
|
+
Hooks deliver unread messages between tool calls. Codex has no Monitor
|
|
405
|
+
tool, so hooks are how a Codex worker hears a message. Meets HOOK-1.
|
|
406
|
+
|
|
407
|
+
```bash
|
|
408
|
+
chattrs hooks install [--agent claude|codex|all] [--project]
|
|
409
|
+
chattrs hooks remove [--agent claude|codex|all] [--project]
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
- User level (default): `~/.claude/settings.json` and
|
|
413
|
+
`$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project`
|
|
414
|
+
edits `.claude/settings.json` and `.codex/hooks.json` in the current
|
|
415
|
+
directory. With `--agent all`, an agent whose config directory is
|
|
416
|
+
missing is skipped; an explicit `--agent` creates the file.
|
|
417
|
+
- Install merges in place: other hooks and key order stay. Own entries
|
|
418
|
+
are the commands `chattrs hook <event> --agent claude|codex`. Install twice gives the same
|
|
419
|
+
file. `remove` deletes only own entries. Invalid JSON exits 1 and
|
|
420
|
+
writes nothing. A `.bak` copy is written once, when none exists. The
|
|
421
|
+
file is written as 2-space pretty JSON with a trailing newline, so a
|
|
422
|
+
file in that format is restored byte for byte by install then remove;
|
|
423
|
+
another format keeps its content, not its layout.
|
|
424
|
+
- After install, take the printed next step for each agent. Codex runs
|
|
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.
|
|
428
|
+
- `chattrs` must be on the agent's `PATH`.
|
|
429
|
+
|
|
430
|
+
What each event does (`chattrs hook <event>`):
|
|
431
|
+
|
|
432
|
+
| Event | Effect |
|
|
433
|
+
| ----- | ------ |
|
|
434
|
+
| `session-start` | Fires on startup, clear, and compact, and behaves the same for all three (HOOK-2). Sets the state to idle. Tells the agent its address, its project when not `default`, its lead (`CHATTRS_LEAD`, when set), and to load the skill. Claude Code also gets the Monitor reminder (Codex has none; the Codex config passes `--agent codex`, and no flag means Claude). Then it adds the last 10 messages to and from the address, oldest first, in the `<agent-message>` wrapper. When `CHATTRS_LEAD` is unset or equals the address, it also lists up to 10 messages to the address that it has not replied to, most recent first. It reads the log and acks nothing. It gets about 800 ms and prints the address, lead, and skill lines even when the broker is unreachable. |
|
|
435
|
+
| `user-prompt-submit`, `post-tool-use` | Adds unread messages as `additionalContext`, in the `<agent-message>` wrapper. `user-prompt-submit` also sets the state to working. |
|
|
436
|
+
| `stop` | Sets the state to idle. When messages are unread, blocks the stop with them as the reason, and sets working again. Never blocks when `stop_hook_active` is true. |
|
|
437
|
+
|
|
438
|
+
Each delivering event claims before it prints. It fetches the unread
|
|
439
|
+
messages, acks them all, and prints only the ids the ack changed to read.
|
|
440
|
+
Two hook runs that fire at once therefore split the messages and never
|
|
441
|
+
print one twice. If the ack fails or times out, the run prints nothing.
|
|
442
|
+
The cost: a message claimed but not printed (stdout closed) is not
|
|
443
|
+
redelivered.
|
|
444
|
+
|
|
445
|
+
The hooks live in the user-level config, so they fire in every session.
|
|
446
|
+
`chattrs hook` does nothing, with no output, unless `CHATTRS_ADDRESS` is
|
|
447
|
+
set. It never starts a broker. It is best effort: connect plus exchange
|
|
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.
|
|
455
|
+
|
|
239
456
|
## Protocol
|
|
240
457
|
|
|
241
458
|
One JSON object per line, `\n`-terminated. The `type` field disambiguates.
|
|
@@ -243,33 +460,41 @@ One JSON object per line, `\n`-terminated. The `type` field disambiguates.
|
|
|
243
460
|
Client → broker:
|
|
244
461
|
|
|
245
462
|
```json
|
|
246
|
-
{"type":"hello", "v":1, "address":"codex@box1", "token":"…"}
|
|
463
|
+
{"type":"hello", "v":1, "address":"codex@box1", "token":"…", "tags":["os:linux","arch:x86_64","gpu"]}
|
|
247
464
|
{"type":"send", "to":"opus@mac", "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
248
465
|
{"type":"send", "to":null, "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
249
466
|
{"type":"inbox"}
|
|
250
467
|
{"type":"ack", "ids":[12, 13]}
|
|
251
468
|
{"type":"watch"}
|
|
252
469
|
{"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
|
+
{"type":"watch", "all":true}
|
|
253
475
|
{"type":"wait", "reply_to":12}
|
|
254
476
|
{"type":"agents"}
|
|
477
|
+
{"type":"agents", "all":true}
|
|
478
|
+
{"type":"agents", "projects":true}
|
|
255
479
|
{"type":"log", "address":"codex@box1", "after":0, "limit":500}
|
|
256
480
|
```
|
|
257
481
|
|
|
258
482
|
Broker → client:
|
|
259
483
|
|
|
260
484
|
```json
|
|
261
|
-
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1"}
|
|
262
|
-
{"type":"sent", "id":12}
|
|
485
|
+
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
|
|
486
|
+
{"type":"sent", "id":12} // optional "known":false: `to` never said hello
|
|
263
487
|
{"type":"inbox", "messages":[
|
|
264
488
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
265
|
-
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null}]}
|
|
489
|
+
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"project":"alpha"}]}
|
|
266
490
|
{"type":"message", "id":13,"from":"opus@mac","to":"codex@box1",
|
|
267
|
-
"body":"hi","ts":1763200000001,"reply_to":12,"topic":null}
|
|
491
|
+
"body":"hi","ts":1763200000001,"reply_to":12,"topic":null,"project":"alpha"}
|
|
268
492
|
{"type":"acked", "ids":[12, 13]}
|
|
269
|
-
{"type":"agents", "agents":[{"address":"codex@box1","last_seen":1763200000000}]}
|
|
493
|
+
{"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]}
|
|
270
494
|
{"type":"log", "messages":[
|
|
271
495
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
272
|
-
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"acked_at":null}]}
|
|
496
|
+
"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}]}
|
|
273
498
|
{"type":"error", "code":"empty_body", "message":"body is empty"}
|
|
274
499
|
```
|
|
275
500
|
|
|
@@ -292,6 +517,25 @@ stored with no owning inbox, and a `send` with no `to` and no `topic` is
|
|
|
292
517
|
rejected with `bad_address`. A direct message with a topic stays direct:
|
|
293
518
|
its topic is only a label, and topic watchers never receive it.
|
|
294
519
|
|
|
520
|
+
`hello` may carry an optional `project`, which the client reads from
|
|
521
|
+
`CHATTRS_PROJECT`. It is validated like a topic name; an invalid name gets
|
|
522
|
+
`bad_project`. Without it the project is `default`, and `welcome` echoes the
|
|
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
|
+
|
|
295
539
|
`inbox` returns every message for the `hello` address with no ack yet, in
|
|
296
540
|
id order. `ack` marks the listed ids read when they belong to that address
|
|
297
541
|
and are unread, and `acked` lists the ids that changed; other ids are
|
|
@@ -299,18 +543,96 @@ ignored. Except for `watch`, the broker never pushes messages: the client
|
|
|
299
543
|
asks. Every accepted `hello` records the address with the broker clock, and
|
|
300
544
|
the broker records it again when that connection closes. `agents` returns
|
|
301
545
|
all recorded addresses sorted by address; an address that only received
|
|
302
|
-
messages and never connected is not listed.
|
|
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`.
|
|
566
|
+
`welcome` may carry `"watching":true` when the address already has a live
|
|
567
|
+
inbox `watch` at `hello` time; it is omitted otherwise, and from an older
|
|
568
|
+
broker. The `watch` command then warns once per connect on stderr and keeps
|
|
569
|
+
watching; other commands ignore it. The `inbox` command prints each message, flushes stdout, then acks,
|
|
303
570
|
so a crash between print and ack redelivers the message on the next run —
|
|
304
571
|
delivery is at least once, and the id tells duplicates apart.
|
|
305
572
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
573
|
+
### Monitoring API (observer)
|
|
574
|
+
|
|
575
|
+
A monitor, such as a tray, uses only the wire protocol:
|
|
576
|
+
|
|
577
|
+
1. `hello` with `"observer":true`. The broker never records the address,
|
|
578
|
+
never lists it in `agents`, and never counts it as online or `watching`.
|
|
579
|
+
It stores no tags from an observer `hello`. The token check is the same.
|
|
580
|
+
2. The `welcome` echoes `"observer":true`. A broker without observer support
|
|
581
|
+
omits it; the client must then fall back to polling `log`.
|
|
582
|
+
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` on a connection that did not say `observer` gets `not_observer`.
|
|
585
|
+
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
|
+
|
|
589
|
+
An observer connection is read-only: `send`, `ack`, `wait`, and `inbox` get
|
|
590
|
+
`observer_read_only`. A slow observer that falls behind is disconnected, so
|
|
591
|
+
it never delays a sender. To catch up after a connect or a drop, start
|
|
592
|
+
`watch` with `all` first and buffer what it streams, then read
|
|
593
|
+
`log` with `after` set to the last id you hold, and drop duplicates by
|
|
594
|
+
message id.
|
|
595
|
+
|
|
596
|
+
#### Viewer contract
|
|
597
|
+
|
|
598
|
+
Viewers are separate programs that use this contract. The `chattrs` binary
|
|
599
|
+
stays CLI only, with no TUI or GUI. The swarm needs nothing from any viewer.
|
|
600
|
+
|
|
601
|
+
- A read-only viewer connects as an observer: `hello` with
|
|
602
|
+
`"observer":true`, then check the `welcome` echo. Start `watch` with
|
|
603
|
+
`"all":true` first, then read `log` after the last id you hold, and drop
|
|
604
|
+
duplicates by id. Use `agents` for presence, tags, and state. An observer
|
|
605
|
+
is read-only.
|
|
606
|
+
- Messages and agent rows carry `project`. A viewer that observes `*`
|
|
607
|
+
groups by it. Until signed tokens land, the shared token reaches every
|
|
608
|
+
project.
|
|
609
|
+
- An interactive viewer, a GUI or TUI that sends or replies, connects as a
|
|
610
|
+
normal agent with its own address, such as `operator@mac`, and uses the
|
|
611
|
+
normal frames.
|
|
612
|
+
- Health (MON-5) is not on the wire. A viewer computes it from the `agents`
|
|
613
|
+
row and its own clock, the same way `chattrs agents` does. Activity is the
|
|
614
|
+
later of `last_seen` and `state_at`. Check in this order:
|
|
615
|
+
`gone` when not `online` and `last_seen` is more than 1 h ago;
|
|
616
|
+
`stalled` when `state` is `working` and activity is 10 min or more ago;
|
|
617
|
+
`healthy` when `online` and activity is under 10 min ago; else no label.
|
|
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.
|
|
620
|
+
- A viewer ignores unknown fields and unknown frame types.
|
|
621
|
+
- The observer frames and the `agents` JSON shape are stable. They change
|
|
622
|
+
only by adding fields.
|
|
623
|
+
|
|
624
|
+
On `watch`, the broker first subscribes the connection to its one
|
|
625
|
+
broadcast, then sends every unread message in id order, then each new
|
|
626
|
+
message the broadcast carries for that connection. It tracks the highest
|
|
627
|
+
id sent on the connection and skips ids at or below it, so the hand-over
|
|
628
|
+
does not duplicate. A connection that falls behind the broadcast is
|
|
629
|
+
closed; the client reconnects and the broker replays from the store.
|
|
630
|
+
Two watchers on one address both get every message. The `watch` command
|
|
631
|
+
prints each message as one JSON line, flushes stdout, then acks it on
|
|
632
|
+
the same connection — always JSON, nothing else on stdout — and never
|
|
633
|
+
exits by itself. A watching connection still answers other frames, so
|
|
634
|
+
its `ack` needs no second connection. When the connection drops it
|
|
635
|
+
reconnects with backoff from 1 s to 30 s, logging to stderr only.
|
|
314
636
|
|
|
315
637
|
With `topics`, `watch` subscribes to those rooms instead of the inbox:
|
|
316
638
|
on subscribe the broker sends each room's most recent 500 announcements
|
|
@@ -323,18 +645,20 @@ announcement twice across a reconnect; the id tells duplicates apart.
|
|
|
323
645
|
Closing the watcher ends the subscription: there is no join or leave,
|
|
324
646
|
and the broker tracks no listener list.
|
|
325
647
|
|
|
326
|
-
On `wait`, the broker
|
|
327
|
-
with that `reply_to`, whether
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
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.
|
|
338
662
|
|
|
339
663
|
`log` returns messages with id above `after`, in id order, at most
|
|
340
664
|
`limit` (capped at 500), with `acked_at` set for read messages and null
|
|
@@ -348,7 +672,7 @@ message it answers; an explicit `topic` always wins. An invalid slug is
|
|
|
348
672
|
rejected with `bad_topic`.
|
|
349
673
|
|
|
350
674
|
Error codes: `bad_frame`, `hello_required`, `bad_version` (v ≠ 1),
|
|
351
|
-
`bad_address`, `bad_token`, `bad_topic`, `empty_body`, `too_large`,
|
|
675
|
+
`bad_address`, `bad_token`, `bad_tags`, `bad_project`, `bad_topic`, `empty_body`, `too_large`,
|
|
352
676
|
`unknown_message`, `not_recipient`. After `hello`, an error does not
|
|
353
677
|
close the connection, except `bad_token`, which always closes it.
|
|
354
678
|
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"hasInstallScript": true,
|
|
20
20
|
"license": "MIT",
|
|
21
21
|
"name": "chattrs",
|
|
22
|
-
"version": "0.
|
|
22
|
+
"version": "0.4.0"
|
|
23
23
|
},
|
|
24
24
|
"node_modules/detect-libc": {
|
|
25
25
|
"engines": {
|
|
@@ -48,5 +48,5 @@
|
|
|
48
48
|
}
|
|
49
49
|
},
|
|
50
50
|
"requires": true,
|
|
51
|
-
"version": "0.
|
|
51
|
+
"version": "0.4.0"
|
|
52
52
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"artifactDownloadUrls": [
|
|
3
|
-
"https://github.com/bolu-atx/chattrs/releases/download/v0.
|
|
3
|
+
"https://github.com/bolu-atx/chattrs/releases/download/v0.4.0"
|
|
4
4
|
],
|
|
5
5
|
"bin": {
|
|
6
6
|
"chattrs": "run-chattrs.js"
|
|
@@ -79,7 +79,7 @@
|
|
|
79
79
|
"zipExt": ".tar.xz"
|
|
80
80
|
}
|
|
81
81
|
},
|
|
82
|
-
"version": "0.
|
|
82
|
+
"version": "0.4.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|