chattrs 0.3.0 → 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
@@ -113,7 +113,8 @@ only; it never acks.
113
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. |
114
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
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. |
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. |
117
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. |
118
119
  | `log` | Show the full message history, oldest first. With `--about ADDR`, keep only messages that ADDR sent or received. |
119
120
  | `skill` | Print the bundled agent skill (`skills/chattrs/SKILL.md`) to stdout. Opens no connection, needs no address. |
@@ -126,6 +127,14 @@ Common flags:
126
127
  address defaults to `<agent>@<hostname>` from `--agent`.
127
128
  - `--agent AGENT` — agent name for the default address (`CHATTRS_AGENT`).
128
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.
129
138
  - `--token TOKEN` — fleet token (`CHATTRS_TOKEN`). `serve` needs it for a
130
139
  non-loopback bind; every other command sends it in `hello`.
131
140
  - `--json` — print JSON lines; every line carries a `type`, and
@@ -179,7 +188,9 @@ coordinator, who puts `$(chattrs skill)` in the worker's prompt.
179
188
  Run one broker on an always-on machine. Other hosts connect to it over
180
189
  a private network (Tailscale or a LAN) with the shared token. The
181
190
  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.
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.
183
194
 
184
195
  Install the same binary on every host:
185
196
 
@@ -300,7 +311,31 @@ A loopback server that is down gets a second, auto-started broker
300
311
  Limits: there is no TLS, so the token and the messages travel as
301
312
  clear text inside the private network. One token covers the whole
302
313
  fleet. Addresses are self-asserted: the token proves fleet
303
- membership, not which address is yours.
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
319
+
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.
330
+
331
+ ```bash
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
335
+ ```
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`.
304
339
 
305
340
  ### Start a worker
306
341
 
@@ -314,6 +349,8 @@ ssh <host> 'tmux new -d -s worker1 \
314
349
  ". ~/.config/chattrs/env; \
315
350
  export CHATTRS_ADDRESS=worker1@<host> \
316
351
  CHATTRS_SERVER=<broker-ip>:4646 \
352
+ CHATTRS_PROJECT=<project> \
353
+ CHATTRS_LEAD=opus@mac \
317
354
  CHATTRS_TAGS=gpu; \
318
355
  mkdir -p ~/.claude/skills/chattrs && \
319
356
  chattrs skill > ~/.claude/skills/chattrs/SKILL.md; \
@@ -321,7 +358,8 @@ ssh <host> 'tmux new -d -s worker1 \
321
358
  Run chattrs watch under the Monitor tool now.\""'
322
359
  ```
323
360
 
324
- The prompt names the worker's address and its lead. It also starts
361
+ `CHATTRS_LEAD` survives `/clear`; the launch prompt does not. The prompt
362
+ names the worker's address and its lead. It also starts
325
363
  `chattrs watch` under Monitor, so a message wakes the worker. See the
326
364
  `chattrs-fleet` skill for the same wording. `CHATTRS_TAGS` is optional
327
365
  and shows in `agents`.
@@ -340,7 +378,8 @@ each host to check.
340
378
 
341
379
  ### Watch the swarm
342
380
 
343
- `chattrs watch --all` shows every message live. See
381
+ `chattrs watch --all` shows every message of the own project live. With
382
+ `CHATTRS_PROJECT='*'` it shows every project. See
344
383
  [Monitoring API (observer)](#monitoring-api-observer) for the wire
345
384
  form. `chattrs agents` shows who is online, with tags.
346
385
 
@@ -357,6 +396,8 @@ Run this checklist once on a new swarm.
357
396
  lost.
358
397
  5. `chattrs watch --all` shows every message live.
359
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.
360
401
 
361
402
  ## Hooks (Claude Code and Codex)
362
403
 
@@ -390,9 +431,16 @@ What each event does (`chattrs hook <event>`):
390
431
 
391
432
  | Event | Effect |
392
433
  | ----- | ------ |
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. |
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.
396
444
 
397
445
  The hooks live in the user-level config, so they fire in every session.
398
446
  `chattrs hook` does nothing, with no output, unless `CHATTRS_ADDRESS` is
@@ -400,6 +448,11 @@ set. It never starts a broker. It is best effort: connect plus exchange
400
448
  get about 300 ms, and any failure prints nothing and exits 0. A message
401
449
  that was not acked stays unread for the next command.
402
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
+
403
456
  ## Protocol
404
457
 
405
458
  One JSON object per line, `\n`-terminated. The `type` field disambiguates.
@@ -416,27 +469,32 @@ Client → broker:
416
469
  {"type":"watch", "topics":["release-26"]}
417
470
  {"type":"hello", "v":1, "address":"codex@box1", "state":"working"}
418
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"}
419
474
  {"type":"watch", "all":true}
420
475
  {"type":"wait", "reply_to":12}
421
476
  {"type":"agents"}
477
+ {"type":"agents", "all":true}
478
+ {"type":"agents", "projects":true}
422
479
  {"type":"log", "address":"codex@box1", "after":0, "limit":500}
423
480
  ```
424
481
 
425
482
  Broker → client:
426
483
 
427
484
  ```json
428
- {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1"}
485
+ {"type":"welcome", "server":"chattrs", "v":1, "address":"codex@box1", "project":"alpha"}
429
486
  {"type":"sent", "id":12} // optional "known":false: `to` never said hello
430
487
  {"type":"inbox", "messages":[
431
488
  {"id":12,"from":"codex@box1","to":"opus@mac",
432
- "body":"hi","ts":1763200000000,"reply_to":null,"topic":null}]}
489
+ "body":"hi","ts":1763200000000,"reply_to":null,"topic":null,"project":"alpha"}]}
433
490
  {"type":"message", "id":13,"from":"opus@mac","to":"codex@box1",
434
- "body":"hi","ts":1763200000001,"reply_to":12,"topic":null}
491
+ "body":"hi","ts":1763200000001,"reply_to":12,"topic":null,"project":"alpha"}
435
492
  {"type":"acked", "ids":[12, 13]}
436
- {"type":"agents", "agents":[{"address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]}
493
+ {"type":"agents", "agents":[{"project":"alpha","address":"codex@box1","last_seen":1763200000000,"online":true,"tags":["os:linux","gpu"],"state":"working","state_at":1763200000000}]}
437
494
  {"type":"log", "messages":[
438
495
  {"id":12,"from":"codex@box1","to":"opus@mac",
439
- "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}]}
440
498
  {"type":"error", "code":"empty_body", "message":"body is empty"}
441
499
  ```
442
500
 
@@ -459,6 +517,25 @@ stored with no owning inbox, and a `send` with no `to` and no `topic` is
459
517
  rejected with `bad_address`. A direct message with a topic stays direct:
460
518
  its topic is only a label, and topic watchers never receive it.
461
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
+
462
539
  `inbox` returns every message for the `hello` address with no ack yet, in
463
540
  id order. `ack` marks the listed ids read when they belong to that address
464
541
  and are unread, and `acked` lists the ids that changed; other ids are
@@ -506,6 +583,8 @@ A monitor, such as a tray, uses only the wire protocol:
506
583
  announcements, as `message` frames. It sends no backlog and acks nothing.
507
584
  `all` on a connection that did not say `observer` gets `not_observer`.
508
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.
509
588
 
510
589
  An observer connection is read-only: `send`, `ack`, `wait`, and `inbox` get
511
590
  `observer_read_only`. A slow observer that falls behind is disconnected, so
@@ -524,9 +603,20 @@ stays CLI only, with no TUI or GUI. The swarm needs nothing from any viewer.
524
603
  `"all":true` first, then read `log` after the last id you hold, and drop
525
604
  duplicates by id. Use `agents` for presence, tags, and state. An observer
526
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.
527
609
  - An interactive viewer, a GUI or TUI that sends or replies, connects as a
528
610
  normal agent with its own address, such as `operator@mac`, and uses the
529
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.
530
620
  - A viewer ignores unknown fields and unknown frame types.
531
621
  - The observer frames and the `agents` JSON shape are stable. They change
532
622
  only by adding fields.
@@ -582,7 +672,7 @@ message it answers; an explicit `topic` always wins. An invalid slug is
582
672
  rejected with `bad_topic`.
583
673
 
584
674
  Error codes: `bad_frame`, `hello_required`, `bad_version` (v ≠ 1),
585
- `bad_address`, `bad_token`, `bad_tags`, `bad_topic`, `empty_body`, `too_large`,
675
+ `bad_address`, `bad_token`, `bad_tags`, `bad_project`, `bad_topic`, `empty_body`, `too_large`,
586
676
  `unknown_message`, `not_recipient`. After `hello`, an error does not
587
677
  close the connection, except `bad_token`, which always closes it.
588
678
 
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.3.0"
22
+ "version": "0.4.0"
23
23
  },
24
24
  "node_modules/detect-libc": {
25
25
  "engines": {
@@ -48,5 +48,5 @@
48
48
  }
49
49
  },
50
50
  "requires": true,
51
- "version": "0.3.0"
51
+ "version": "0.4.0"
52
52
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "artifactDownloadUrls": [
3
- "https://github.com/bolu-atx/chattrs/releases/download/v0.3.0"
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.3.0",
82
+ "version": "0.4.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"