chattrs 0.6.0 → 0.7.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
@@ -25,8 +25,48 @@ over TCP, so a script in any language can join too.
25
25
 
26
26
  ## Get running
27
27
 
28
- chattrs never starts agents. You start them. `chattrs env` sets the
29
- address and the session in the launch line.
28
+ `chattrs exec claude` starts an agent on the swarm. It sets the address
29
+ and the session, then hands the process to the agent. chattrs never hosts
30
+ or supervises the agent. For other launchers (Herdr, tmux, scripts), use
31
+ `chattrs env`, which prints the same settings as `export` lines.
32
+
33
+ `exec` does not put the token in the agent's environment. Each chattrs
34
+ call in the agent reads the token from `config.toml`, as the hooks do. An
35
+ explicit `CHATTRS_TOKEN` in your shell passes through unchanged. If no
36
+ token is found, `exec` prints `chattrs: no token for ADDR; the broker may
37
+ refuse` and still starts the agent.
38
+
39
+ The broker refuses a second live session for the same address (ID-1). The
40
+ refusal shows when the agent's hooks or `watch` connect.
41
+
42
+ #### Start an agent on another host
43
+
44
+ `chattrs exec --host H [--cwd DIR] [--detach] [--session-name NAME] PROGRAM`
45
+ starts the agent on host `H`. It runs the system `ssh`, so `~/.ssh/config`
46
+ aliases work. The remote login shell runs `chattrs exec` there.
47
+
48
+ ```bash
49
+ chattrs exec --host bobox --cwd ~/repo --as w1@bobox --lead lead@mac codex
50
+ chattrs exec --host bobox --cwd ~/repo --detach --as w1@bobox --lead lead@mac codex
51
+ ```
52
+
53
+ - chattrs forwards only `--as`, `--lead`, the program, and its arguments.
54
+ It never sends the token, the server, the project, the tags, or any
55
+ `CHATTRS_*` variable. The remote host reads its own config and token.
56
+ - The remote host needs `chattrs` on its login-shell `PATH` and its own
57
+ config and token (`chattrs setup --join`).
58
+ - Without `--detach`, the worker lives only as long as the ssh connection.
59
+ If the launching machine sleeps, loses the network, or closes the
60
+ terminal, the worker stops.
61
+ - With `--detach`, the worker runs in a remote tmux session and chattrs
62
+ returns. The worker lives until it exits or someone kills the session.
63
+ chattrs prints the attach command (`ssh -t H tmux attach -t NAME`) and
64
+ the stop command (`ssh H tmux kill-session -t NAME`). `NAME` defaults to
65
+ the user part of the address, with unsafe characters turned into `-`.
66
+ - tmux is optional. Only `--detach` needs it. If tmux is missing, chattrs
67
+ exits 1 and says so. It never installs tmux, never falls back to a run
68
+ without `--detach`, and never attaches to or kills an existing session.
69
+ - chattrs never watches, kills, or restarts agents.
30
70
 
31
71
  ### Solo, one machine
32
72
 
@@ -49,12 +89,16 @@ Three steps.
49
89
 
50
90
  ```bash
51
91
  # Terminal 1
52
- eval "$(chattrs env --as lead@mac)" && claude
92
+ chattrs exec --as lead@mac claude
53
93
 
54
94
  # Terminal 2
55
- eval "$(chattrs env --as w1@mac --lead lead@mac)" && codex
95
+ chattrs exec --as w1@mac --lead lead@mac codex
56
96
  ```
57
97
 
98
+ Without `--as`, the address is `<program>@<host>`, for example
99
+ `claude@mac`. Arguments after the program go to the program:
100
+ `chattrs exec claude --resume ID`.
101
+
58
102
  The first command starts a loopback broker on its own. The session-start
59
103
  hook tells each agent its address and its lead, and to load the skill.
60
104
  Ask the lead to send w1 a task. Run `chattrs agents` to see both agents.
@@ -103,8 +147,8 @@ the solo path.
103
147
  5. Launch every agent with its own address:
104
148
 
105
149
  ```bash
106
- eval "$(chattrs env --as lead@mac)" && claude
107
- eval "$(chattrs env --as w1@bobox --lead lead@mac)" && codex
150
+ chattrs exec --as lead@mac claude
151
+ chattrs exec --as w1@bobox --lead lead@mac codex
108
152
  ```
109
153
 
110
154
  `env --as` exports the address, a new session id, and the server. It does
@@ -126,8 +170,10 @@ It writes `~/.config/chattrs/tokens.toml` (mode 0600) and a systemd user unit
126
170
  (`~/Library/LaunchAgents/com.chattrs.broker.plist`). It never overwrites
127
171
  either file. It prints the command that starts the service; `--enable` runs
128
172
  it. It issues one agent token per host (`*@<host>`), one lead token, and one
129
- observer token (`tray@*`, all projects). Then it prints one join string for
130
- each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
173
+ observer token (`tray@*`). The tokens have no `project` line, so they work in
174
+ every project. With `--projects`, it writes one entry per project instead,
175
+ and each token stays inside those projects (the observer still sees all).
176
+ Then it prints one join string for each, `chattrs://<token>@<ip>:<port>?as=<pattern>`. The pattern is
131
177
  percent-encoded.
132
178
 
133
179
  `setup --join` also takes a string as an argument. Quote it, but it then
@@ -239,6 +285,7 @@ acks them (MSG-5). Announcements never reach an inbox.
239
285
  | `agents [--all] [--json]` | List the agents of the project: online or last seen, state, health, tags. Hides agents offline over 7 days with no traffic since. `--all` shows them. |
240
286
  | `projects [--json]` | List every project with its agent and message counts. Read-only. |
241
287
  | `status working\|idle\|waiting` | Report the own state. Best effort: it never starts a broker, gives up after about 2 s, and always exits 0. |
288
+ | `exec [--as ADDR] [--project P] [--lead ADDR] [--server S] [--tags T] [--host H [--cwd DIR] [--detach [--session-name N]]] [--] PROGRAM [ARGS...]` | Run PROGRAM with the session env that `env` prints. On Unix it replaces the chattrs process. The default address is `<program>@<host>`. It never adds the token to the environment. With `--host` it runs the same command on H over `ssh`, see [Start an agent on another host](#start-an-agent-on-another-host). |
242
289
  | `env --as ADDR [--project P] [--lead ADDR] [--server S] [--tags T] [--token T] [--with-token]` | Print `export` lines for one session: `eval "$(chattrs env --as a@h)"`. It makes a new `CHATTRS_SESSION` on every run. It omits the token unless `--with-token`. |
243
290
  | `setup` | Install the hooks and the skill for each agent found (Claude Code, Codex). Write a starter `config.toml` only if missing. Safe to run again. `setup --broker --hosts a,b [...]` prepares a broker host; `setup --join STRING\|-` stores join-string tokens. See [Several hosts](#several-hosts-setup---broker-and-setup---join-setup-2). |
244
291
  | `doctor [--as ADDR] [--server S]` | Check config, token files, broker, token, protocol, hooks, and skill. One `ok` or `FAIL` line each; exit 1 on any failure. Read-only. See [Check a host](#check-a-host-doctor-setup-3). |
@@ -451,17 +498,28 @@ second, auto-started broker, and that agent then joins a different swarm.
451
498
 
452
499
  ### Start a worker
453
500
 
454
- The lead starts each worker over ssh in a detached tmux session. The worker
455
- needs no flags. The host config has the server and token file. The repo's
456
- `.chattrs.toml` has the project and lead. The address, session, project,
457
- and lead exist only in the launch line:
501
+ The lead starts each worker with `chattrs exec --host`. The worker needs no
502
+ flags. The host config has the server and token file. The project is the
503
+ repo name, and the repo's `.chattrs.toml` can set the lead:
458
504
 
459
505
  ```bash
460
- ssh <host> 'tmux new -d -s w1 '"'"'eval "$(chattrs env --as worker1@<host>)"; exec claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."'"'"''
506
+ chattrs exec --host <host> --cwd ~/repo --detach --as worker1@<host> --lead opus@mac claude "Your address is worker1@<host>. Your lead is opus@mac. Run chattrs watch under the Monitor tool now."
461
507
  ```
462
508
 
509
+ `--detach` starts the worker in a tmux session on the host and prints how
510
+ to attach and stop it. Without `--detach`, the worker lives only as long as
511
+ the ssh connection: if the launching machine sleeps, loses network, or
512
+ closes the terminal, the worker stops.
513
+
463
514
  On the host itself:
464
515
 
516
+ ```bash
517
+ chattrs exec --as worker1@box claude "..."
518
+ ```
519
+
520
+ For other launchers (Herdr, tmux, scripts), `chattrs env` prints the same
521
+ settings as shell exports:
522
+
465
523
  ```bash
466
524
  tmux new -d -s w1 'eval "$(chattrs env --as worker1@box)"; exec claude "..."'
467
525
  ```
@@ -506,43 +564,50 @@ Run this once on a new swarm.
506
564
 
507
565
  ### Token table
508
566
 
509
- Meets SEC-4. A token table gives each token a project, an address pattern,
510
- and a role. Start the broker with `serve --tokens <path>` or
567
+ Meets SEC-4. A token table gives each token an address pattern and a role.
568
+ A token works in every project. An optional `project` line limits it to one
569
+ project. Start the broker with `serve --tokens <path>` or
511
570
  `CHATTRS_TOKENS`. The file is TOML. The broker refuses to start when its
512
571
  mode is wider than 0600 (unix). Make each token with `openssl rand -hex 32`.
513
572
 
514
573
  ```toml
515
- # The lead of project alpha. Only a lead token can claim this address.
574
+ # The lead. Only a lead token can claim this address, in any project.
516
575
  [[token]]
517
576
  token = "<64 hex characters>"
518
- project = "alpha"
519
577
  addr = "lead@box1"
520
578
  role = "lead"
521
579
 
522
- # Any worker on box1, in alpha only.
580
+ # Any worker on box1, in every project.
523
581
  [[token]]
524
582
  token = "<64 hex characters>"
525
- project = "alpha"
526
583
  addr = "*@box1"
527
584
  role = "agent"
528
585
 
586
+ # A worker on box2, walled into project alpha.
587
+ [[token]]
588
+ token = "<64 hex characters>"
589
+ project = "alpha"
590
+ addr = "*@box2"
591
+ role = "agent"
592
+
529
593
  # A read-only viewer that sees every project.
530
594
  [[token]]
531
595
  token = "<64 hex characters>"
532
- project = "*"
533
596
  addr = "tray@mac"
534
597
  role = "observer"
535
598
  ```
536
599
 
537
600
  The parser reads a small subset of TOML: blank lines, `#` comments,
538
601
  `[[token]]` headers, and `key = "value"` lines (double quotes, no escapes).
539
- The keys `token`, `project`, `addr`, and `role` are required, once each.
540
- Any other line, an unknown key, a bad value, or a repeated token stops the
541
- broker with an error that names the line. A lead who leads several projects
542
- uses one token and lists it once per project. One token twice in one
543
- project is refused.
544
-
545
- - `project` is a project name, or `"*"` for `observer` entries only.
602
+ The keys `token`, `addr`, and `role` are required. `project` is optional.
603
+ Each key appears once per entry. Any other line, an unknown key, or a bad
604
+ value stops the broker with an error that names the line. A repeated token
605
+ stops it too, unless every copy names a different project. A lead who
606
+ leads several projects can use one entry with no `project`, or one token
607
+ listed once per project.
608
+
609
+ - `project` is a project name. With no `project`, the token works in every
610
+ project. `"*"` means the same, for `observer` entries only (the old form).
546
611
  - `addr` is an exact address, or a pattern where `*` matches any run of
547
612
  characters, such as `*@box1`.
548
613
  - `role` is `lead`, `agent`, or `observer`.
@@ -552,9 +617,10 @@ time, then checks the hello:
552
617
 
553
618
  - No entry matches: `bad_token`. The broker closes the connection.
554
619
  - The project or address does not fit the entry, or a role rule fails:
555
- `forbidden`.
620
+ `forbidden`. The project check applies only to an entry with a `project`.
556
621
  - Lead rule: only a `lead` entry can claim an address that a `lead` entry
557
- names exactly in that project.
622
+ names exactly. This holds in every project, whether or not that entry
623
+ has a `project`.
558
624
  - Observer rule: an `observer` entry works only with an observer hello. An
559
625
  `agent` entry cannot send an observer hello.
560
626
 
@@ -612,9 +678,23 @@ another project lands in the sender's project, with `known:false`. The same
612
678
  address in two projects is two agents (NS-1). A client with no project uses
613
679
  `default`.
614
680
 
615
- Set `CHATTRS_PROJECT` in the launch environment, with an explicit name.
616
- Never derive it from the directory name: a renamed or second checkout would
617
- split or merge swarms.
681
+ A client picks its project in this order. The first match wins:
682
+
683
+ 1. `CHATTRS_PROJECT` or `--project`.
684
+ 2. `project` in `.chattrs.toml` or `~/.config/chattrs/config.toml`.
685
+ 3. The repo name, when the directory is inside a git repo.
686
+ 4. `default`.
687
+
688
+ The repo name is the last part of the `origin` URL, without `.git`. With no
689
+ `origin`, it is the name of the directory that holds the repo. A worktree
690
+ has the same name as its main repo. The name is lowercase, and every
691
+ character outside `a-z` and `0-9` becomes `-`. `chattrs doctor` and
692
+ `chattrs env` print the project and its source.
693
+
694
+ Upgrade note: a session inside a repo now joins the repo project, not
695
+ `default`. A token table that allows only `default` rejects it. Add the repo
696
+ project to `tokens.toml`, or pin `project` in `.chattrs.toml`. Doctor then
697
+ says `token not valid for project <name> (derived from git)`.
618
698
 
619
699
  ```bash
620
700
  export CHATTRS_PROJECT=alpha
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "chattrs",
22
- "version": "0.6.0"
22
+ "version": "0.7.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.6.0"
51
+ "version": "0.7.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.6.0"
3
+ "https://github.com/bolu-atx/chattrs/releases/download/v0.7.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.6.0",
82
+ "version": "0.7.0",
83
83
  "volta": {
84
84
  "node": "18.14.1",
85
85
  "npm": "9.5.0"