chattrs 0.2.2 → 0.3.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 +297 -63
- 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,25 @@ 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 known agent addresses, `online` while an agent has a live inbox `watch`, else when it was last seen, then the reported state and the tags. |
|
|
117
|
+
| `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. |
|
|
118
|
+
| `log` | Show the full message history, oldest first. With `--about ADDR`, keep only messages that ADDR sent or received. |
|
|
110
119
|
| `skill` | Print the bundled agent skill (`skills/chattrs/SKILL.md`) to stdout. Opens no connection, needs no address. |
|
|
111
120
|
|
|
112
121
|
Common flags:
|
|
@@ -167,8 +176,10 @@ coordinator, who puts `$(chattrs skill)` in the worker's prompt.
|
|
|
167
176
|
|
|
168
177
|
## Run across hosts
|
|
169
178
|
|
|
170
|
-
Run one broker on an always-on
|
|
171
|
-
|
|
179
|
+
Run one broker on an always-on machine. Other hosts connect to it over
|
|
180
|
+
a private network (Tailscale or a LAN) with the shared token. The
|
|
181
|
+
broker host can run an agent too. This is "Claude Code-style swarms
|
|
182
|
+
for any agent": a lead and its workers share one broker.
|
|
172
183
|
|
|
173
184
|
Install the same binary on every host:
|
|
174
185
|
|
|
@@ -178,15 +189,39 @@ cargo install --git https://github.com/bolu-atx/chattrs
|
|
|
178
189
|
# or: npm install -g chattrs
|
|
179
190
|
```
|
|
180
191
|
|
|
181
|
-
|
|
192
|
+
### Pick the broker host
|
|
193
|
+
|
|
194
|
+
- Use a machine that is always on. Do not use the lead's Mac: it
|
|
195
|
+
sleeps, and the swarm stops with it.
|
|
196
|
+
- Bind to the LAN or tailnet IP, never `0.0.0.0` and never a public
|
|
197
|
+
address. There is no TLS.
|
|
198
|
+
- Set `CHATTRS_TOKEN`. The broker refuses a non-loopback bind without
|
|
199
|
+
it. The `from` of a message is only as trustworthy as the token: with
|
|
200
|
+
no token, any local process can say hello as any address.
|
|
201
|
+
- Keep the token in a file with mode 0600, never in a unit file or on a
|
|
202
|
+
command line:
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
mkdir -p ~/.config/chattrs
|
|
206
|
+
printf 'CHATTRS_TOKEN=%s\n' "$(openssl rand -hex 32)" > ~/.config/chattrs/env
|
|
207
|
+
chmod 600 ~/.config/chattrs/env
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Keep the database
|
|
211
|
+
|
|
212
|
+
Put `CHATTRS_DB` (or `--db`) on persistent disk. The broker never
|
|
213
|
+
deletes a message, so the database is the swarm's history. Back it up
|
|
214
|
+
with SQLite, never with `cp` on a live database:
|
|
182
215
|
|
|
183
216
|
```bash
|
|
184
|
-
|
|
217
|
+
sqlite3 <db> ".backup <file>"
|
|
185
218
|
```
|
|
186
219
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
220
|
+
### Run the broker as a service
|
|
221
|
+
|
|
222
|
+
Linux: a `systemd --user` unit. Put it in
|
|
223
|
+
`~/.config/systemd/user/chattrs.service`. The token comes from the
|
|
224
|
+
0600 file through `EnvironmentFile`.
|
|
190
225
|
|
|
191
226
|
```ini
|
|
192
227
|
[Unit]
|
|
@@ -196,24 +231,59 @@ Wants=network-online.target
|
|
|
196
231
|
|
|
197
232
|
[Service]
|
|
198
233
|
EnvironmentFile=%h/.config/chattrs/env
|
|
199
|
-
ExecStart=%h/.cargo/bin/chattrs serve --listen <
|
|
200
|
-
Restart=
|
|
234
|
+
ExecStart=%h/.cargo/bin/chattrs serve --listen <broker-ip>:4646 --db <path>
|
|
235
|
+
Restart=always
|
|
201
236
|
|
|
202
237
|
[Install]
|
|
203
238
|
WantedBy=default.target
|
|
204
239
|
```
|
|
205
240
|
|
|
206
241
|
```bash
|
|
207
|
-
# the env file holds one line: CHATTRS_TOKEN=<token>
|
|
208
|
-
chmod 600 ~/.config/chattrs/env
|
|
209
242
|
systemctl --user daemon-reload
|
|
210
243
|
systemctl --user enable --now chattrs
|
|
244
|
+
loginctl enable-linger <user> # run without a login session
|
|
211
245
|
```
|
|
212
246
|
|
|
213
|
-
|
|
247
|
+
macOS: a launchd agent. Put it in
|
|
248
|
+
`~/Library/LaunchAgents/dev.chattrs.broker.plist`. A shell wrapper
|
|
249
|
+
reads the same 0600 file, so the token stays out of the plist. Change
|
|
250
|
+
the binary path to match your install (`which chattrs`).
|
|
251
|
+
|
|
252
|
+
```xml
|
|
253
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
254
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
|
255
|
+
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
256
|
+
<plist version="1.0">
|
|
257
|
+
<dict>
|
|
258
|
+
<key>Label</key><string>dev.chattrs.broker</string>
|
|
259
|
+
<key>ProgramArguments</key>
|
|
260
|
+
<array>
|
|
261
|
+
<string>/bin/sh</string>
|
|
262
|
+
<string>-c</string>
|
|
263
|
+
<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>
|
|
264
|
+
</array>
|
|
265
|
+
<key>RunAtLoad</key><true/>
|
|
266
|
+
<key>KeepAlive</key><true/>
|
|
267
|
+
<key>StandardErrorPath</key><string>/tmp/chattrs-broker.log</string>
|
|
268
|
+
</dict>
|
|
269
|
+
</plist>
|
|
270
|
+
```
|
|
214
271
|
|
|
215
272
|
```bash
|
|
216
|
-
|
|
273
|
+
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.chattrs.broker.plist
|
|
274
|
+
launchctl kickstart -k gui/$(id -u)/dev.chattrs.broker # restart
|
|
275
|
+
launchctl bootout gui/$(id -u)/dev.chattrs.broker # stop and unload
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
A launchd agent runs while its user is logged in. Turn on automatic
|
|
279
|
+
login for an unattended Mac.
|
|
280
|
+
|
|
281
|
+
### Set client hosts
|
|
282
|
+
|
|
283
|
+
On every client host, set the same values:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
export CHATTRS_SERVER=<broker-ip>:4646
|
|
217
287
|
export CHATTRS_TOKEN=<token>
|
|
218
288
|
export CHATTRS_ADDRESS=<agent>@<host>
|
|
219
289
|
```
|
|
@@ -222,20 +292,114 @@ export CHATTRS_ADDRESS=<agent>@<host>
|
|
|
222
292
|
address per host, or set `CHATTRS_AGENT` and let the binary use
|
|
223
293
|
`<agent>@<hostname>`.
|
|
224
294
|
|
|
295
|
+
The agent on the broker host is a client too. Set its
|
|
296
|
+
`CHATTRS_SERVER` to the broker's LAN or tailnet IP, not to loopback.
|
|
297
|
+
A loopback server that is down gets a second, auto-started broker
|
|
298
|
+
(CLI-11), and that agent then talks to a different swarm.
|
|
299
|
+
|
|
225
300
|
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
|
-
|
|
301
|
+
clear text inside the private network. One token covers the whole
|
|
302
|
+
fleet. Addresses are self-asserted: the token proves fleet
|
|
303
|
+
membership, not which address is yours.
|
|
304
|
+
|
|
305
|
+
### Start a worker
|
|
230
306
|
|
|
231
|
-
|
|
232
|
-
|
|
307
|
+
The lead starts each worker over ssh, in a detached tmux session. The
|
|
308
|
+
worker needs no flags: the env sets everything (CLI-6). First put the
|
|
309
|
+
token in `~/.config/chattrs/env` on the worker host, mode 0600, as
|
|
310
|
+
`export CHATTRS_TOKEN=<token>`.
|
|
233
311
|
|
|
234
312
|
```bash
|
|
235
|
-
ssh <
|
|
236
|
-
|
|
313
|
+
ssh <host> 'tmux new -d -s worker1 \
|
|
314
|
+
". ~/.config/chattrs/env; \
|
|
315
|
+
export CHATTRS_ADDRESS=worker1@<host> \
|
|
316
|
+
CHATTRS_SERVER=<broker-ip>:4646 \
|
|
317
|
+
CHATTRS_TAGS=gpu; \
|
|
318
|
+
mkdir -p ~/.claude/skills/chattrs && \
|
|
319
|
+
chattrs skill > ~/.claude/skills/chattrs/SKILL.md; \
|
|
320
|
+
exec claude \"Your address is worker1@<host>. Your lead is opus@mac. \
|
|
321
|
+
Run chattrs watch under the Monitor tool now.\""'
|
|
237
322
|
```
|
|
238
323
|
|
|
324
|
+
The prompt names the worker's address and its lead. It also starts
|
|
325
|
+
`chattrs watch` under Monitor, so a message wakes the worker. See the
|
|
326
|
+
`chattrs-fleet` skill for the same wording. `CHATTRS_TAGS` is optional
|
|
327
|
+
and shows in `agents`.
|
|
328
|
+
Tags come from the latest hello. Set `CHATTRS_TAGS` in the worker's
|
|
329
|
+
launch environment. A chattrs command run from another shell without
|
|
330
|
+
it replaces the agent's tags with `os` and `arch`.
|
|
331
|
+
|
|
332
|
+
Windows has no native tmux. Use WSL, or leave a terminal session
|
|
333
|
+
running.
|
|
334
|
+
|
|
335
|
+
### Upgrade
|
|
336
|
+
|
|
337
|
+
Upgrade the broker first, then the clients. New protocol fields are
|
|
338
|
+
optional, so old clients keep working. Run `chattrs --version` on
|
|
339
|
+
each host to check.
|
|
340
|
+
|
|
341
|
+
### Watch the swarm
|
|
342
|
+
|
|
343
|
+
`chattrs watch --all` shows every message live. See
|
|
344
|
+
[Monitoring API (observer)](#monitoring-api-observer) for the wire
|
|
345
|
+
form. `chattrs agents` shows who is online, with tags.
|
|
346
|
+
|
|
347
|
+
### Exit test
|
|
348
|
+
|
|
349
|
+
Run this checklist once on a new swarm.
|
|
350
|
+
|
|
351
|
+
1. Start the broker service on the swarm machine. A lead on the Mac and
|
|
352
|
+
two remote workers connect to it.
|
|
353
|
+
2. A worker reports to the lead. The lead gets it.
|
|
354
|
+
3. A worker asks the lead a question and gets the reply.
|
|
355
|
+
4. Restart the broker mid-run (`systemctl --user restart chattrs`, or
|
|
356
|
+
`launchctl kickstart -k ...`). Check `chattrs log`: no message is
|
|
357
|
+
lost.
|
|
358
|
+
5. `chattrs watch --all` shows every message live.
|
|
359
|
+
6. `chattrs agents` shows both workers online, with their tags.
|
|
360
|
+
|
|
361
|
+
## Hooks (Claude Code and Codex)
|
|
362
|
+
|
|
363
|
+
Hooks deliver unread messages between tool calls. Codex has no Monitor
|
|
364
|
+
tool, so hooks are how a Codex worker hears a message. Meets HOOK-1.
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
chattrs hooks install [--agent claude|codex|all] [--project]
|
|
368
|
+
chattrs hooks remove [--agent claude|codex|all] [--project]
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
- User level (default): `~/.claude/settings.json` and
|
|
372
|
+
`$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`). `--project`
|
|
373
|
+
edits `.claude/settings.json` and `.codex/hooks.json` in the current
|
|
374
|
+
directory. With `--agent all`, an agent whose config directory is
|
|
375
|
+
missing is skipped; an explicit `--agent` creates the file.
|
|
376
|
+
- Install merges in place: other hooks and key order stay. Own entries
|
|
377
|
+
are the commands `chattrs hook <event> --agent claude|codex`. Install twice gives the same
|
|
378
|
+
file. `remove` deletes only own entries. Invalid JSON exits 1 and
|
|
379
|
+
writes nothing. A `.bak` copy is written once, when none exists. The
|
|
380
|
+
file is written as 2-space pretty JSON with a trailing newline, so a
|
|
381
|
+
file in that format is restored byte for byte by install then remove;
|
|
382
|
+
another format keeps its content, not its layout.
|
|
383
|
+
- After install, take the printed next step for each agent. Codex runs
|
|
384
|
+
new hooks only after review: open Codex and run `/hooks` to trust
|
|
385
|
+
them. Claude Code may ask you to review hooks edited outside it.
|
|
386
|
+
Until then the hooks look installed but do not run.
|
|
387
|
+
- `chattrs` must be on the agent's `PATH`.
|
|
388
|
+
|
|
389
|
+
What each event does (`chattrs hook <event>`):
|
|
390
|
+
|
|
391
|
+
| Event | Effect |
|
|
392
|
+
| ----- | ------ |
|
|
393
|
+
| `session-start` | Sets the state to idle, tells the agent its address 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). Prints even when the broker is unreachable. |
|
|
394
|
+
| `user-prompt-submit`, `post-tool-use` | Adds unread messages as `additionalContext`, in the `<agent-message>` wrapper. Acks them after stdout is flushed. `user-prompt-submit` also sets the state to working. |
|
|
395
|
+
| `stop` | Sets the state to idle. When messages are unread, blocks the stop with them as the reason, then acks, and sets working again. Never blocks when `stop_hook_active` is true. |
|
|
396
|
+
|
|
397
|
+
The hooks live in the user-level config, so they fire in every session.
|
|
398
|
+
`chattrs hook` does nothing, with no output, unless `CHATTRS_ADDRESS` is
|
|
399
|
+
set. It never starts a broker. It is best effort: connect plus exchange
|
|
400
|
+
get about 300 ms, and any failure prints nothing and exits 0. A message
|
|
401
|
+
that was not acked stays unread for the next command.
|
|
402
|
+
|
|
239
403
|
## Protocol
|
|
240
404
|
|
|
241
405
|
One JSON object per line, `\n`-terminated. The `type` field disambiguates.
|
|
@@ -243,13 +407,16 @@ One JSON object per line, `\n`-terminated. The `type` field disambiguates.
|
|
|
243
407
|
Client → broker:
|
|
244
408
|
|
|
245
409
|
```json
|
|
246
|
-
{"type":"hello", "v":1, "address":"codex@box1", "token":"…"}
|
|
410
|
+
{"type":"hello", "v":1, "address":"codex@box1", "token":"…", "tags":["os:linux","arch:x86_64","gpu"]}
|
|
247
411
|
{"type":"send", "to":"opus@mac", "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
248
412
|
{"type":"send", "to":null, "body":"hi", "reply_to":null, "topic":"release-26"}
|
|
249
413
|
{"type":"inbox"}
|
|
250
414
|
{"type":"ack", "ids":[12, 13]}
|
|
251
415
|
{"type":"watch"}
|
|
252
416
|
{"type":"watch", "topics":["release-26"]}
|
|
417
|
+
{"type":"hello", "v":1, "address":"codex@box1", "state":"working"}
|
|
418
|
+
{"type":"hello", "v":1, "address":"viewer@mac", "observer":true}
|
|
419
|
+
{"type":"watch", "all":true}
|
|
253
420
|
{"type":"wait", "reply_to":12}
|
|
254
421
|
{"type":"agents"}
|
|
255
422
|
{"type":"log", "address":"codex@box1", "after":0, "limit":500}
|
|
@@ -259,14 +426,14 @@ Broker → client:
|
|
|
259
426
|
|
|
260
427
|
```json
|
|
261
428
|
{"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1"}
|
|
262
|
-
{"type":"sent", "id":12}
|
|
429
|
+
{"type":"sent", "id":12} // optional "known":false: `to` never said hello
|
|
263
430
|
{"type":"inbox", "messages":[
|
|
264
431
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
265
432
|
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null}]}
|
|
266
433
|
{"type":"message", "id":13,"from":"opus@mac","to":"codex@box1",
|
|
267
434
|
"body":"hi","ts":1763200000001,"reply_to":12,"topic":null}
|
|
268
435
|
{"type":"acked", "ids":[12, 13]}
|
|
269
|
-
{"type":"agents", "agents":[{"address":"codex@box1","last_seen":1763200000000}]}
|
|
436
|
+
{"type":"agents", "agents":[{"address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]}
|
|
270
437
|
{"type":"log", "messages":[
|
|
271
438
|
{"id":12,"from":"codex@box1","to":"opus@mac",
|
|
272
439
|
"body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"acked_at":null}]}
|
|
@@ -299,18 +466,83 @@ ignored. Except for `watch`, the broker never pushes messages: the client
|
|
|
299
466
|
asks. Every accepted `hello` records the address with the broker clock, and
|
|
300
467
|
the broker records it again when that connection closes. `agents` returns
|
|
301
468
|
all recorded addresses sorted by address; an address that only received
|
|
302
|
-
messages and never connected is not listed.
|
|
469
|
+
messages and never connected is not listed. `hello` may carry an optional
|
|
470
|
+
`tags` list (at most 32 tags of 64 bytes each, else `bad_tags`). The client
|
|
471
|
+
always sends `os:<os>` and `arch:<arch>`, plus the comma-separated entries of
|
|
472
|
+
`CHATTRS_TAGS` (for example `CHATTRS_TAGS=gpu:4090,fast`). The broker keeps
|
|
473
|
+
the tags of the latest `hello` that sent any, and `agents` shows them after
|
|
474
|
+
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
|
|
475
|
+
also has `online`: `true` while the address has a live inbox `watch`
|
|
476
|
+
connection (topic watches do not count), else `false`. The broker counts
|
|
477
|
+
this in memory and never stores it; an older broker omits it, which reads as
|
|
478
|
+
`false`. `agents` text shows `online` in place of the last-seen time.
|
|
479
|
+
`hello` may also carry an optional `state`: `working`, `idle`, or `waiting`
|
|
480
|
+
(else `bad_state`). The broker stores the state and the time it was set
|
|
481
|
+
(`state_at`, ms on the broker clock) when a `hello` carries one; a `hello`
|
|
482
|
+
without a state keeps both. An observer `hello` with a state gets
|
|
483
|
+
`observer_read_only`. `agents` text shows the state after the online or
|
|
484
|
+
last-seen column and before the tags, and shows nothing when the agent never
|
|
485
|
+
reported one; `agents --json` always has `state` and `state_at`, `null`
|
|
486
|
+
when never set. The broker never expires a state. A client shows a state
|
|
487
|
+
older than 15 minutes as `unknown`; `agents` text does. `chattrs status
|
|
488
|
+
<state>` sends such a `hello`.
|
|
489
|
+
`welcome` may carry `"watching":true` when the address already has a live
|
|
490
|
+
inbox `watch` at `hello` time; it is omitted otherwise, and from an older
|
|
491
|
+
broker. The `watch` command then warns once per connect on stderr and keeps
|
|
492
|
+
watching; other commands ignore it. The `inbox` command prints each message, flushes stdout, then acks,
|
|
303
493
|
so a crash between print and ack redelivers the message on the next run —
|
|
304
494
|
delivery is at least once, and the id tells duplicates apart.
|
|
305
495
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
496
|
+
### Monitoring API (observer)
|
|
497
|
+
|
|
498
|
+
A monitor, such as a tray, uses only the wire protocol:
|
|
499
|
+
|
|
500
|
+
1. `hello` with `"observer":true`. The broker never records the address,
|
|
501
|
+
never lists it in `agents`, and never counts it as online or `watching`.
|
|
502
|
+
It stores no tags from an observer `hello`. The token check is the same.
|
|
503
|
+
2. The `welcome` echoes `"observer":true`. A broker without observer support
|
|
504
|
+
omits it; the client must then fall back to polling `log`.
|
|
505
|
+
3. `watch` with `"all":true` streams each new message, direct and
|
|
506
|
+
announcements, as `message` frames. It sends no backlog and acks nothing.
|
|
507
|
+
`all` on a connection that did not say `observer` gets `not_observer`.
|
|
508
|
+
4. `agents` gives presence, tags, and state. `log` gives history.
|
|
509
|
+
|
|
510
|
+
An observer connection is read-only: `send`, `ack`, `wait`, and `inbox` get
|
|
511
|
+
`observer_read_only`. A slow observer that falls behind is disconnected, so
|
|
512
|
+
it never delays a sender. To catch up after a connect or a drop, start
|
|
513
|
+
`watch` with `all` first and buffer what it streams, then read
|
|
514
|
+
`log` with `after` set to the last id you hold, and drop duplicates by
|
|
515
|
+
message id.
|
|
516
|
+
|
|
517
|
+
#### Viewer contract
|
|
518
|
+
|
|
519
|
+
Viewers are separate programs that use this contract. The `chattrs` binary
|
|
520
|
+
stays CLI only, with no TUI or GUI. The swarm needs nothing from any viewer.
|
|
521
|
+
|
|
522
|
+
- A read-only viewer connects as an observer: `hello` with
|
|
523
|
+
`"observer":true`, then check the `welcome` echo. Start `watch` with
|
|
524
|
+
`"all":true` first, then read `log` after the last id you hold, and drop
|
|
525
|
+
duplicates by id. Use `agents` for presence, tags, and state. An observer
|
|
526
|
+
is read-only.
|
|
527
|
+
- An interactive viewer, a GUI or TUI that sends or replies, connects as a
|
|
528
|
+
normal agent with its own address, such as `operator@mac`, and uses the
|
|
529
|
+
normal frames.
|
|
530
|
+
- A viewer ignores unknown fields and unknown frame types.
|
|
531
|
+
- The observer frames and the `agents` JSON shape are stable. They change
|
|
532
|
+
only by adding fields.
|
|
533
|
+
|
|
534
|
+
On `watch`, the broker first subscribes the connection to its one
|
|
535
|
+
broadcast, then sends every unread message in id order, then each new
|
|
536
|
+
message the broadcast carries for that connection. It tracks the highest
|
|
537
|
+
id sent on the connection and skips ids at or below it, so the hand-over
|
|
538
|
+
does not duplicate. A connection that falls behind the broadcast is
|
|
539
|
+
closed; the client reconnects and the broker replays from the store.
|
|
540
|
+
Two watchers on one address both get every message. The `watch` command
|
|
541
|
+
prints each message as one JSON line, flushes stdout, then acks it on
|
|
542
|
+
the same connection — always JSON, nothing else on stdout — and never
|
|
543
|
+
exits by itself. A watching connection still answers other frames, so
|
|
544
|
+
its `ack` needs no second connection. When the connection drops it
|
|
545
|
+
reconnects with backoff from 1 s to 30 s, logging to stderr only.
|
|
314
546
|
|
|
315
547
|
With `topics`, `watch` subscribes to those rooms instead of the inbox:
|
|
316
548
|
on subscribe the broker sends each room's most recent 500 announcements
|
|
@@ -323,18 +555,20 @@ announcement twice across a reconnect; the id tells duplicates apart.
|
|
|
323
555
|
Closing the watcher ends the subscription: there is no join or leave,
|
|
324
556
|
and the broker tracks no listener list.
|
|
325
557
|
|
|
326
|
-
On `wait`, the broker
|
|
327
|
-
with that `reply_to`, whether
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
558
|
+
On `wait`, the broker subscribes the connection, then sends the
|
|
559
|
+
lowest-id message to the `hello` address with that `reply_to`, whether
|
|
560
|
+
it is acked or not — at once when one exists, else when one arrives.
|
|
561
|
+
One `wait` gets one message, and the connection keeps reading frames
|
|
562
|
+
while it waits. The reply also reaches live `watch` connections, so an
|
|
563
|
+
agent running both sees it twice. The `ask` command sends its question,
|
|
564
|
+
parks a `wait`, and on the reply prints it wrapped as `<agent-message>`
|
|
565
|
+
text (or one JSON `message` line with `"untrusted":true` when
|
|
566
|
+
`--json`), flushes stdout, acks it, and exits 0 — all on one connection.
|
|
567
|
+
On a timeout it closes the connection, writes `timeout: no reply to
|
|
568
|
+
<id>` to stderr, exits 2 (and prints `{"type":"timeout","id":12}` with
|
|
569
|
+
`--json`); the late reply stays unread. A dropped connection reconnects
|
|
570
|
+
with the `watch` backoff and resends only the `wait`, never the
|
|
571
|
+
question, and the reply is acked on the connection that received it.
|
|
338
572
|
|
|
339
573
|
`log` returns messages with id above `after`, in id order, at most
|
|
340
574
|
`limit` (capped at 500), with `acked_at` set for read messages and null
|
|
@@ -348,7 +582,7 @@ message it answers; an explicit `topic` always wins. An invalid slug is
|
|
|
348
582
|
rejected with `bad_topic`.
|
|
349
583
|
|
|
350
584
|
Error codes: `bad_frame`, `hello_required`, `bad_version` (v ≠ 1),
|
|
351
|
-
`bad_address`, `bad_token`, `bad_topic`, `empty_body`, `too_large`,
|
|
585
|
+
`bad_address`, `bad_token`, `bad_tags`, `bad_topic`, `empty_body`, `too_large`,
|
|
352
586
|
`unknown_message`, `not_recipient`. After `hello`, an error does not
|
|
353
587
|
close the connection, except `bad_token`, which always closes it.
|
|
354
588
|
|
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.3.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.3.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.3.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.3.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|