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 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 (arm64):
13
+ On any machine with Node (macOS, Linux, Windows):
14
14
 
15
15
  ```bash
16
- brew install bolu-atx/tap/chattrs
16
+ npm install -g chattrs
17
17
  ```
18
18
 
19
- On any machine with Node (macOS, Linux, Windows):
19
+ On macOS (arm64):
20
20
 
21
21
  ```bash
22
- npm install -g chattrs
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). `watch` prints each new message as one JSON line with
73
- `"untrusted":true` and acks it, reconnecting with backoff when the
74
- broker drops. It prints nothing else to stdout, so it works under a
75
- watcher like Claude Code's Monitor tool.
76
- `ask --to ADDR [--timeout SECS] [TEXT...]` posts a question, blocks for
77
- the reply, prints it, acks it, and exits 0. On a timeout it exits 2 and
78
- the late reply stays unread. `--timeout 0` waits with no limit.
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` reads only; it never acks.
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
- | `agents` | List known agent addresses and when each was last seen. |
109
- | `log` | Show the full message history, oldest first. |
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 Linux host, reachable over Tailscale.
171
- Clients on other hosts connect to it with the shared token.
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
- On the broker host, start the broker on its Tailscale IP:
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
- chattrs serve --listen <tailscale-ip>:4646 --token <token> --db <path>
217
+ sqlite3 <db> ".backup <file>"
185
218
  ```
186
219
 
187
- Keep it running with a `systemd --user` unit that restarts on
188
- failure. The token lives in an `EnvironmentFile` with mode 600,
189
- never in the unit file itself:
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 <tailscale-ip>:4646 --db <path>
200
- Restart=on-failure
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
- On every client host, set the same three values:
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 &lt;broker-ip&gt;: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
- export CHATTRS_SERVER=<tailscale-ip>:4646
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 tailnet. One token covers the whole fleet.
227
- Addresses are self-asserted: the token proves fleet membership,
228
- not which address is yours. Bind the Tailscale IP only, never a
229
- public address.
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
- A coordinator that starts a worker over ssh passes the same env
232
- on the ssh command line:
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 <worker> "CHATTRS_SERVER=<tailscale-ip>:4646 \
236
- CHATTRS_TOKEN=<token> CHATTRS_ADDRESS=<agent>@<host> chattrs inbox"
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. The `inbox` command prints each message, flushes stdout, then acks,
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
- On `watch`, the broker first registers the watcher, then sends every
307
- unread message in id order, then each new message when it arrives. It
308
- tracks the highest id sent on the connection and skips ids at or below it,
309
- so the hand-over does not duplicate. Two watchers on one address both get
310
- every message. The `watch` command prints each message as one JSON line,
311
- flushes stdout, then acks it — always JSON, nothing else on stdout — and
312
- never exits by itself. When the connection drops it reconnects with
313
- backoff from 1 s to 30 s, logging to stderr only.
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 sends the lowest-id message to the `hello` address
327
- with that `reply_to`, whether it is acked or not — at once when one
328
- exists, else when one arrives. One `wait` gets one message. The reply
329
- also reaches live `watch` connections, so an agent running both sees it
330
- twice. The `ask` command sends its question, parks a `wait`, and on the
331
- reply prints it wrapped as `<agent-message>` text (or one JSON `message`
332
- line with `"untrusted":true` when `--json`), flushes stdout, acks it,
333
- and exits 0. On a timeout it closes
334
- the connection, writes `timeout: no reply to <id>` to stderr, exits 2
335
- (and prints `{"type":"timeout","id":12}` with `--json`); the late reply
336
- stays unread. A dropped connection reconnects with the `watch` backoff
337
- and resends only the `wait`, never the question.
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
 
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.2.2"
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.2.2"
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.2.2"
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.2.2",
82
+ "version": "0.3.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"