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 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,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` 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 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 Linux host, reachable over Tailscale.
171
- Clients on other hosts connect to it with the shared token.
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
- On the broker host, start the broker on its Tailscale IP:
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
- chattrs serve --listen <tailscale-ip>:4646 --token <token> --db <path>
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 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:
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 <tailscale-ip>:4646 --db <path>
200
- Restart=on-failure
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 &lt;broker-ip&gt;: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
- On every client host, set the same three values:
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=<tailscale-ip>:4646
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 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.
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 coordinator that starts a worker over ssh passes the same env
232
- on the ssh command line:
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
- ssh <worker> "CHATTRS_SERVER=<tailscale-ip>:4646 \
236
- CHATTRS_TOKEN=<token> CHATTRS_ADDRESS=<agent>@<host> chattrs inbox"
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. The `inbox` command prints each message, flushes stdout, then acks,
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
- 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.
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 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.
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
 
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.2.2"
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.2.2"
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.2.2"
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.2.2",
82
+ "version": "0.4.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"