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 +104 -14
- package/npm-shrinkwrap.json +2 -2
- package/package.json +2 -2
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
|
-
|
|
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.
|
|
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
|
|
394
|
-
| `user-prompt-submit`, `post-tool-use` | Adds unread messages as `additionalContext`, in the `<agent-message>` wrapper.
|
|
395
|
-
| `stop` | Sets the state to idle. When messages are unread, blocks the stop with them as the reason,
|
|
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
|
|
package/npm-shrinkwrap.json
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"hasInstallScript": true,
|
|
20
20
|
"license": "MIT",
|
|
21
21
|
"name": "chattrs",
|
|
22
|
-
"version": "0.
|
|
22
|
+
"version": "0.4.0"
|
|
23
23
|
},
|
|
24
24
|
"node_modules/detect-libc": {
|
|
25
25
|
"engines": {
|
|
@@ -48,5 +48,5 @@
|
|
|
48
48
|
}
|
|
49
49
|
},
|
|
50
50
|
"requires": true,
|
|
51
|
-
"version": "0.
|
|
51
|
+
"version": "0.4.0"
|
|
52
52
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"artifactDownloadUrls": [
|
|
3
|
-
"https://github.com/bolu-atx/chattrs/releases/download/v0.
|
|
3
|
+
"https://github.com/bolu-atx/chattrs/releases/download/v0.4.0"
|
|
4
4
|
],
|
|
5
5
|
"bin": {
|
|
6
6
|
"chattrs": "run-chattrs.js"
|
|
@@ -79,7 +79,7 @@
|
|
|
79
79
|
"zipExt": ".tar.xz"
|
|
80
80
|
}
|
|
81
81
|
},
|
|
82
|
-
"version": "0.
|
|
82
|
+
"version": "0.4.0",
|
|
83
83
|
"volta": {
|
|
84
84
|
"node": "18.14.1",
|
|
85
85
|
"npm": "9.5.0"
|