@awebai/oats 0.69.11 → 0.69.14
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 +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +9 -5
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/knowledge.md +10 -3
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +42 -8
- package/docs/packages.md +101 -22
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.12.md +97 -0
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +30 -5
- package/docs/workspaces.md +32 -6
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +180 -49
- package/lib/tmux-config.mjs +0 -35
|
@@ -11,13 +11,13 @@ description: >-
|
|
|
11
11
|
Use for "get started with OATS", "set up / install / adopt OATS", "set up
|
|
12
12
|
OATS for this project", "join our OATS workspace", or when someone gives
|
|
13
13
|
you this file or its URL. Download this file whole (`curl -fsSL
|
|
14
|
-
https://raw.githubusercontent.com/
|
|
14
|
+
https://raw.githubusercontent.com/oats-project/oats/main/skills/oats-getting-started/SKILL.md`)
|
|
15
15
|
and follow it as written: a summary of it is not the procedure.
|
|
16
16
|
---
|
|
17
17
|
|
|
18
18
|
**Read this whole file, never a summary of it.** If you only have a summary
|
|
19
19
|
(a web fetch that summarises, say), download it whole with
|
|
20
|
-
`curl -fsSL https://raw.githubusercontent.com/
|
|
20
|
+
`curl -fsSL https://raw.githubusercontent.com/oats-project/oats/main/skills/oats-getting-started/SKILL.md`
|
|
21
21
|
and follow it as written.
|
|
22
22
|
|
|
23
23
|
# Getting started with OATS
|
|
@@ -33,7 +33,8 @@ A **workspace** is one Git repository declaring which repositories belong to
|
|
|
33
33
|
an organisation and which packages it trusts. A **soul** is a durable agent
|
|
34
34
|
role defined in Git; an **instance** is a soul at work, in its own home and
|
|
35
35
|
terminal. A new workspace's setup expert is `oats.framework`'s soul
|
|
36
|
-
`oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding
|
|
36
|
+
`oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding`, and
|
|
37
|
+
`oats.coordination-setup` from oats.framework 1.23.0),
|
|
37
38
|
spawned as `<workspace>-oats-setup-expert`.
|
|
38
39
|
|
|
39
40
|
**A machine found-list** is a JSON file in your prompt whose
|
|
@@ -46,6 +47,12 @@ tell the person this machine already has its workspace and steward, and
|
|
|
46
47
|
stop. Wherever a later step says to ask the
|
|
47
48
|
person, on a machine found-list you tell them what happened, as it is, and
|
|
48
49
|
stop instead: the person answers nothing after step 1.
|
|
50
|
+
Step 1's machine round is always asked, even when the prompt that started
|
|
51
|
+
you says to ask for nothing more (an installer's "beyond starting this, ask
|
|
52
|
+
no other yes"). Its one yes, naming the changes, is the consent your
|
|
53
|
+
harness's permission check reads; without it, the check refuses each change
|
|
54
|
+
on its own (the repository, the aweb signup, the folder trust), and each
|
|
55
|
+
costs the person a round. After that yes, nothing more is asked.
|
|
49
56
|
|
|
50
57
|
**How to work.**
|
|
51
58
|
- **Ask first, then run.** Ask everything in one round (step 1), then run the
|
|
@@ -154,7 +161,15 @@ On a machine found-list, ask the machine's round below instead of this list.
|
|
|
154
161
|
|
|
155
162
|
**First, step 2's checks.** They only read, so run them before the message
|
|
156
163
|
(not its installs): the changes to their computer that the message lists
|
|
157
|
-
are what they found missing.
|
|
164
|
+
are what they found missing. On Linux x64 they include the Desktop's system
|
|
165
|
+
libraries: a missing one goes on the list as a system package, dropped if
|
|
166
|
+
they decline the Desktop, so the Desktop's install needs no second yes.
|
|
167
|
+
|
|
168
|
+
**No GitHub account.** Their agents' shared setup and their projects live
|
|
169
|
+
on GitHub. When gh is not logged in, ask in the same message whether they
|
|
170
|
+
have a GitHub account. Without one, they make one, free, in their browser
|
|
171
|
+
at step 3, and nothing else changes: gh goes on the list of changes like
|
|
172
|
+
any missing tool, and you install it.
|
|
158
173
|
|
|
159
174
|
**The message.** Ask three things, and in the same message propose
|
|
160
175
|
everything else as defaults they accept with "ok" or change:
|
|
@@ -263,9 +278,9 @@ the final values in one short message before you go on. The rules:
|
|
|
263
278
|
`PEP` and `GPT`.
|
|
264
279
|
|
|
265
280
|
With a tracker, the agents keep using it: the line says so ("your agents
|
|
266
|
-
use your GitHub issues; the setup assistant
|
|
267
|
-
writes `tasks: none`; the setup expert
|
|
268
|
-
person later. Without one, the line says "aweb's task list, shared by your
|
|
281
|
+
use your GitHub issues; the setup assistant offers to connect them") and
|
|
282
|
+
step 7 writes `tasks: none`; the setup expert offers to connect the
|
|
283
|
+
tracker with the person later. Without one, the line says "aweb's task list, shared by your
|
|
269
284
|
agents". Ask only when unsure, as the final-values message's one open
|
|
270
285
|
line, prefilled with the answer you'd pick: ticket keys the person didn't
|
|
271
286
|
name, a project kept somewhere other than GitHub (its issues can't be
|
|
@@ -275,8 +290,9 @@ the final values in one short message before you go on. The rules:
|
|
|
275
290
|
**The machine's round.** Read the found-list, then ask only these choices,
|
|
276
291
|
together, each with its default and one line on what it is. Enter, or
|
|
277
292
|
"yes", accepts every default. Nothing is asked after this round, and never
|
|
278
|
-
a key.
|
|
279
|
-
|
|
293
|
+
a key. Ask it even when your prompt says to ask nothing more (above). The
|
|
294
|
+
use case, repositories and knowledge tools are not asked: the steward takes
|
|
295
|
+
them up with the person later.
|
|
280
296
|
- **The workspace:** a new one, the machine's own. Its name defaults to the
|
|
281
297
|
hostname, lowercased, with every character outside `[a-z0-9-]` turned
|
|
282
298
|
into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
|
|
@@ -330,6 +346,13 @@ before the first line that needs `sudo`.
|
|
|
330
346
|
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g; { git config --global user.name && git config --global user.email; } >/dev/null || echo NO_GIT_IDENTITY
|
|
331
347
|
```
|
|
332
348
|
|
|
349
|
+
On Linux x64, also check the Desktop's system libraries, ALSA and FUSE 2
|
|
350
|
+
(what a missing one means is under "The Desktop's system libraries", below):
|
|
351
|
+
|
|
352
|
+
```bash
|
|
353
|
+
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
354
|
+
```
|
|
355
|
+
|
|
333
356
|
- **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
|
|
334
357
|
caches; older Git works with whole-tree fetches); `gh` 2.49 or later
|
|
335
358
|
(step 3 uses `gh attestation`).
|
|
@@ -360,15 +383,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
|
|
|
360
383
|
```bash
|
|
361
384
|
sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
|
|
362
385
|
```
|
|
363
|
-
- **The Desktop's system libraries** (x64)
|
|
364
|
-
|
|
365
|
-
```bash
|
|
366
|
-
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
367
|
-
```
|
|
368
|
-
|
|
386
|
+
- **The Desktop's system libraries** (x64), from the check above, run
|
|
387
|
+
before step 1's message:
|
|
369
388
|
- **ALSA missing:** the Desktop needs it, so step 1's list names its
|
|
370
|
-
package
|
|
371
|
-
before them, `alsa-lib` on
|
|
389
|
+
package, to install with the other system packages: `libasound2t64`
|
|
390
|
+
on Ubuntu 24.04 and Debian 13, `libasound2` before them, `alsa-lib` on
|
|
391
|
+
Fedora.
|
|
372
392
|
- **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
|
|
373
393
|
`--appimage-extract-and-run`, which needs no FUSE.
|
|
374
394
|
- **Passwords:** a line that needs `sudo` runs only after their yes in
|
|
@@ -380,18 +400,26 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
|
|
|
380
400
|
whole-tree fetches, and go on.
|
|
381
401
|
- **npm's global folder** must be writable for step 4's installs
|
|
382
402
|
(`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
|
|
383
|
-
`/usr`, as NodeSource installs it),
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
startup file yourself, so their own terminal finds `oats` too, and tell
|
|
389
|
-
them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
|
|
390
|
-
`fish -c 'fish_add_path ~/.local/bin'` instead).
|
|
403
|
+
`/usr`, as NodeSource installs it), make the two changes step 1's list
|
|
404
|
+
named for it (when Node will come from NodeSource, the list names the
|
|
405
|
+
per-user folder and its PATH line), each as its own command, never
|
|
406
|
+
joined into one:
|
|
407
|
+
- **npm's per-user folder** (in `~/.npmrc`):
|
|
391
408
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
409
|
+
```bash
|
|
410
|
+
npm config set prefix ~/.local
|
|
411
|
+
```
|
|
412
|
+
- **The line that puts it on their PATH** in their shell's startup file:
|
|
413
|
+
`~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
|
|
414
|
+
`fish -c 'fish_add_path ~/.local/bin'` instead), so their own terminal
|
|
415
|
+
finds `oats` too. Tell them which file.
|
|
416
|
+
|
|
417
|
+
```bash
|
|
418
|
+
RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Your own shell doesn't read their startup file, so start each later
|
|
422
|
+
command of yours with `export PATH="$HOME/.local/bin:$PATH"`.
|
|
395
423
|
- **Windows** is not supported.
|
|
396
424
|
|
|
397
425
|
## 3. Log in to GitHub
|
|
@@ -411,7 +439,15 @@ fail with "could not read Username"), then go on below:
|
|
|
411
439
|
gh auth setup-git
|
|
412
440
|
```
|
|
413
441
|
|
|
414
|
-
|
|
442
|
+
**When they have no GitHub account** (step 1), open GitHub's sign-up page
|
|
443
|
+
in their browser first: `open https://github.com/signup` on macOS,
|
|
444
|
+
`xdg-open https://github.com/signup` on Linux, or give them the URL if that
|
|
445
|
+
fails. Tell them it is free, and that they choose a username, an email and a
|
|
446
|
+
password there, in their browser, never in this conversation; GitHub emails
|
|
447
|
+
them a code to confirm the address. Wait until they say the account is
|
|
448
|
+
made, then start the login below.
|
|
449
|
+
|
|
450
|
+
If not logged in, start the login yourself, detached and without a terminal (your
|
|
415
451
|
harness's background mode if it has one); gh prints a one-time code and a
|
|
416
452
|
URL instead of opening a browser, and waits:
|
|
417
453
|
|
|
@@ -462,9 +498,21 @@ file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
|
|
|
462
498
|
checksum and the release's attestation all pass:
|
|
463
499
|
|
|
464
500
|
```bash
|
|
465
|
-
W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R
|
|
501
|
+
W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R oats-project/oats -p "F" -p SHA256SUMS.txt && L=$(grep " F\$" SHA256SUMS.txt) && printf "%s\n" "$L" | sha256sum -c - && { gh attestation verify "F" --repo oats-project/oats --signer-workflow oats-project/oats/.github/workflows/release.yml --source-ref refs/tags/vV || case vV in v0.[0-9].*|v0.[1-5][0-9].*|v0.6[0-8].*|v0.69.[0-9]|v0.69.1[0-2]) gh attestation verify "F" --owner awebai --signer-workflow awebai/oats/.github/workflows/release.yml --source-ref refs/tags/vV;; *) false;; esac; } && echo VERIFIED; echo DONE' sh "$W" </dev/null >"$W.log" 2>&1 & }
|
|
466
502
|
```
|
|
467
503
|
|
|
504
|
+
The attestation has two forms because the repository moved:
|
|
505
|
+
- **Releases after 0.69.12** are attested in `oats-project/oats`.
|
|
506
|
+
- **Releases up to 0.69.12** were signed in `awebai/oats`, and their
|
|
507
|
+
attestations stayed with the `awebai` organisation. The `case` tries this
|
|
508
|
+
second form only for those versions.
|
|
509
|
+
|
|
510
|
+
Each form accepts only its own repository's release workflow, run for the
|
|
511
|
+
tag `vV`. On an older release the log shows the first form's `HTTP 404`
|
|
512
|
+
before the second passes; that is not a failure. The checksum counts only
|
|
513
|
+
when `SHA256SUMS.txt` has a line for `F`, because on macOS `sha256sum` passes
|
|
514
|
+
empty or malformed input; the attestation checks the file itself.
|
|
515
|
+
|
|
468
516
|
Write the folder it prints in as `<W>` in step 4.
|
|
469
517
|
|
|
470
518
|
## 4. Install OATS Desktop, the CLI and the messaging CLI
|
|
@@ -485,7 +533,7 @@ installed CLI's catalog:
|
|
|
485
533
|
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
486
534
|
```
|
|
487
535
|
|
|
488
|
-
It prints the two refs, for example `oats-framework/v1.
|
|
536
|
+
It prints the two refs, for example `oats-framework/v1.23.0 v1.37.0`. If the
|
|
489
537
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
490
538
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
491
539
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -717,8 +765,8 @@ name: acme
|
|
|
717
765
|
members:
|
|
718
766
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
719
767
|
packages:
|
|
720
|
-
oats.framework: v1.
|
|
721
|
-
oats.aweb: v1.
|
|
768
|
+
oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
|
|
769
|
+
oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
|
|
722
770
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
723
771
|
defaults:
|
|
724
772
|
capabilities:
|
|
@@ -759,9 +807,11 @@ workspace: git:github.com/acme/acme-oats
|
|
|
759
807
|
which named it, without asking again; show the person the files only if
|
|
760
808
|
they ask. When others can push to the repository (`gh api
|
|
761
809
|
repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
|
|
762
|
-
fails), its default branch is protected
|
|
763
|
-
branch
|
|
764
|
-
|
|
810
|
+
fails), its default branch `<branch>` is protected (`gh api
|
|
811
|
+
repos/<owner>/<repo>/branches/<branch> --jq .protected` prints `true`,
|
|
812
|
+
`gh api repos/<owner>/<repo>/rules/branches/<branch> --jq length` prints
|
|
813
|
+
more than 0, or either fails), or the push is refused: push a branch
|
|
814
|
+
instead, open a pull request, tell them, and stop until it is merged.
|
|
765
815
|
- If `git config user.name` or `git config user.email` prints nothing in
|
|
766
816
|
`D/<repo>`, commit with the name step 1's yes covered:
|
|
767
817
|
`-c user.name="<their name>" -c user.email="<their noreply address>"`,
|
|
@@ -782,6 +832,14 @@ oats onboard D --workspace W --json
|
|
|
782
832
|
- **The host must be `confirmed`;** a host that can't be read is a GitHub
|
|
783
833
|
access problem (step 3). Another member with `cannot-read` is an access
|
|
784
834
|
question for the setup expert, not a reason to stop.
|
|
835
|
+
- **On Git under 2.45** (step 2; Ubuntu 24.04 ships 2.43), a warning
|
|
836
|
+
that this Git can't keep a partial cache, so OATS fetches whole trees, is
|
|
837
|
+
expected. A recent OATS prints it at most once per command that starts or
|
|
838
|
+
rebuilds caches; an older one prints it once for each repository it
|
|
839
|
+
starts a cache for. Either form is harmless. Don't show it to the person
|
|
840
|
+
as an error, and don't try to fix it now: a Git of 2.45 or later,
|
|
841
|
+
installed later, removes it, and caches already made with whole trees
|
|
842
|
+
stay that way.
|
|
785
843
|
- **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
|
|
786
844
|
person whether to use it as it is or to choose another directory.
|
|
787
845
|
|
|
@@ -806,9 +864,48 @@ needs a clone of its repository at `D/<repo name>`: for an existing
|
|
|
806
864
|
workspace whose setup soul is its own, run the `git clone` line
|
|
807
865
|
`oats onboard` printed for it, if it says it is missing.
|
|
808
866
|
|
|
809
|
-
**Record the
|
|
810
|
-
none, and without this every later check (readiness, harness trust) and
|
|
811
|
-
spawn would use the default, pi
|
|
867
|
+
**Record the harness for every soul** on this machine: a package soul names
|
|
868
|
+
none, and without this every later check (readiness, harness trust) and
|
|
869
|
+
every spawn would use the default, pi, for `S` and for each soul the setup
|
|
870
|
+
expert or the steward spawns later. `'*'` is every soul without an entry of
|
|
871
|
+
its own, `S` among them, and souls added later that name no harness of
|
|
872
|
+
their own:
|
|
873
|
+
|
|
874
|
+
```bash
|
|
875
|
+
oats soul launch set '*' --harness <harness> --dir D --plan
|
|
876
|
+
oats soul launch set '*' --harness <harness> --dir D
|
|
877
|
+
```
|
|
878
|
+
|
|
879
|
+
`'*'` wins over a soul's own `launch:` on this machine. So read
|
|
880
|
+
`oats souls --dir D --json` first, in a new workspace too (a package soul
|
|
881
|
+
may name its harness). For each row whose `launch.declared.harness`
|
|
882
|
+
differs from `<harness>` and whose declared harness is installed and
|
|
883
|
+
logged in here (`claude --version`, `codex --version` or `pi --version`,
|
|
884
|
+
as in step 2), give that soul its own entry with its declared harness, so
|
|
885
|
+
it keeps its choice. A declared harness that isn't installed here stays
|
|
886
|
+
under `'*'`, so the soul can run; name it in the hand-over ("For the
|
|
887
|
+
person, later"). Use the row's `key` (`<package>/<soul>`
|
|
888
|
+
for a package's soul, so the name is never ambiguous), add
|
|
889
|
+
`--model <its model>` only when `launch.declared.model` names one, and plan
|
|
890
|
+
first:
|
|
891
|
+
|
|
892
|
+
```bash
|
|
893
|
+
oats soul launch set <key> --harness <its harness> --model <its model> --dir D --plan
|
|
894
|
+
oats soul launch set <key> --harness <its harness> --model <its model> --dir D
|
|
895
|
+
```
|
|
896
|
+
|
|
897
|
+
Check a reviewer soul by its model too, since `'*'` replaces the model as
|
|
898
|
+
well as the harness: where it declares `<harness>` but another model, give
|
|
899
|
+
it its own entry the same way, with `--harness <its harness> --model <its
|
|
900
|
+
model>`. Then its `oats spawn <key> --preview --json --dir D` must show a
|
|
901
|
+
`launch.effective` model from a family other than the developers'. Where
|
|
902
|
+
its declared model can't run here, set one that can, from another family;
|
|
903
|
+
with none, name it in the hand-over ("For the person, later"): its reviews
|
|
904
|
+
share the developers' model.
|
|
905
|
+
|
|
906
|
+
`S` is the exception: it always keeps `<harness>`, the person's choice in
|
|
907
|
+
step 1. When `S` declares another harness, give it its own entry with
|
|
908
|
+
`<harness>` instead:
|
|
812
909
|
|
|
813
910
|
```bash
|
|
814
911
|
oats soul launch set S --harness <harness> --dir D --plan
|
|
@@ -891,25 +988,54 @@ readiness still reports a problem.
|
|
|
891
988
|
whose own agent runs
|
|
892
989
|
`oats aweb invite --soul <their soul> --label L --json` in their
|
|
893
990
|
deployment. The answer's `result.token` is the invite token,
|
|
894
|
-
passed to the person privately, never by ordinary mail.
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
991
|
+
passed to the person privately, never by ordinary mail. **The token is
|
|
992
|
+
all they pass** when this machine has oats.aweb 1.36.0 or later (the
|
|
993
|
+
`version` of the `oats.aweb` row in the `oats inspect` answer's
|
|
994
|
+
`result.capabilities`, above) and aw 1.36.53 or later (`aw.version` in
|
|
995
|
+
item 1's check): the join reads the team and the service from the
|
|
996
|
+
invite itself. Otherwise the member passes the service URL `U` too:
|
|
997
|
+
from oats.aweb 1.33.1 the answer's `result.awebUrl`, no secret. When it
|
|
998
|
+
is `null` or absent, leave `--service U` out of item 4's labelled form:
|
|
999
|
+
the join then takes the service from the invite, or fails and item 5
|
|
1000
|
+
stops. This machine's messaging root is
|
|
899
1001
|
`A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
|
|
900
1002
|
name from step 8: don't ask. Only a hosted team works: if the invite is
|
|
901
1003
|
refused, or the join says the team is not hosted, stop; the workspace's
|
|
902
1004
|
owner decides.
|
|
903
1005
|
4. **Existing workspace: the person joins in their own terminal,** which you
|
|
904
|
-
open for them ("How to work"),
|
|
905
|
-
with `D`, `S
|
|
1006
|
+
open for them ("How to work"), pasting the token at the hidden prompt,
|
|
1007
|
+
with `D`, `S` and `A` filled in:
|
|
1008
|
+
|
|
1009
|
+
```text
|
|
1010
|
+
cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --invite-stdin --name A'
|
|
1011
|
+
```
|
|
1012
|
+
|
|
1013
|
+
Before redeeming anything, it refuses an invite it can't use here: one
|
|
1014
|
+
expired, used up or revoked, one for a team this workspace doesn't name
|
|
1015
|
+
(unless the workspace allows local teams and this machine's own
|
|
1016
|
+
`oats-local.yaml` sets its default team), one whose team's label is
|
|
1017
|
+
already another team here, one for a global identity, or one for a team
|
|
1018
|
+
this machine is already in. The person sees why in the window, and
|
|
1019
|
+
item 5 stops. In that exception, an invite for a team the workspace
|
|
1020
|
+
doesn't name is redeemed instead: this machine joins that team under a
|
|
1021
|
+
label of its own, and item 5 catches it. With an older
|
|
1022
|
+
oats.aweb or aw (item 3), open the labelled form instead, with `L` and
|
|
1023
|
+
`U` filled in too:
|
|
906
1024
|
|
|
907
1025
|
```text
|
|
908
1026
|
cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
|
|
909
1027
|
```
|
|
910
1028
|
|
|
911
1029
|
5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
|
|
912
|
-
On `"member": false`, stop and spawn nothing
|
|
1030
|
+
On `"member": false`, stop and spawn nothing. With `"root": null` after
|
|
1031
|
+
item 4's invite-only form, look first, read-only:
|
|
1032
|
+
`ls -d "D"/.aweb-roots/*/.aw 2>/dev/null`. Nothing printed: the join
|
|
1033
|
+
refused before redeeming anything: ask the person for the `E_SETUP_`
|
|
1034
|
+
code their window shows (a code, no secret), tell them in plain words
|
|
1035
|
+
what it means, and that a new invite is the inviter's to send. A path
|
|
1036
|
+
printed for a label other than `L`: the invite was for that team, and
|
|
1037
|
+
this machine joined it instead: tell them so, and that an invite for
|
|
1038
|
+
`L` is the inviter's to send. Otherwise tell the person the run
|
|
913
1039
|
left this machine's root outside `L`, with what the check shows, and
|
|
914
1040
|
don't rerun the signup or the join (you can't see the join's output).
|
|
915
1041
|
When another machine of the same name may already be in the team, say
|
|
@@ -970,7 +1096,8 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
|
|
|
970
1096
|
|
|
971
1097
|
- Workspace: <workspace> (W), new | existing; deployment directory: D
|
|
972
1098
|
- Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
|
|
973
|
-
- Setup expert: S, instance <name>, harness <harness>
|
|
1099
|
+
- Setup expert: S, instance <name>, harness <harness> (this machine's
|
|
1100
|
+
harness for every soul without its own)
|
|
974
1101
|
- Machine found-list only: steward R, address N.aweb.ai/R | local team
|
|
975
1102
|
identity (<the fallback's reason>)
|
|
976
1103
|
|
|
@@ -1127,7 +1254,7 @@ and say yes to it in the hand-over below.
|
|
|
1127
1254
|
line, with how to change it: "Your agents share aweb's task list; to use
|
|
1128
1255
|
another tracker later, ask the setup assistant to switch." With a
|
|
1129
1256
|
tracker: "Your agents use your <GitHub issues | tracker>; the setup
|
|
1130
|
-
assistant
|
|
1257
|
+
assistant offers to connect them. Leave aweb's task list empty: one task there
|
|
1131
1258
|
opts your whole group in to it. To use aweb's task list instead, ask the
|
|
1132
1259
|
setup assistant."
|
|
1133
1260
|
|
|
@@ -1140,6 +1267,10 @@ the setup expert, not in this message. You are done.
|
|
|
1140
1267
|
|
|
1141
1268
|
## Never
|
|
1142
1269
|
|
|
1270
|
+
- **Run `aw team ensure` when joining an existing workspace.** It is only
|
|
1271
|
+
step 5's, for a new workspace. On a join it doesn't find the teammate's
|
|
1272
|
+
team: it makes a new team of the person's own for the same repository,
|
|
1273
|
+
silently. A join goes through step 9's invite.
|
|
1143
1274
|
- **Ask for, read, print or store a secret,** or suggest Claude Code's
|
|
1144
1275
|
`! <command>` for one: its command and output enter your context. If the
|
|
1145
1276
|
person pastes one anyway, don't repeat it, and tell them to rotate it.
|
package/lib/tmux-config.mjs
DELETED
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
|
|
2
|
-
import { spawnSync } from "node:child_process";
|
|
3
|
-
import { homedir } from "node:os";
|
|
4
|
-
import { dirname, join } from "node:path";
|
|
5
|
-
|
|
6
|
-
const OATS_MOUSE_BLOCK = `# OATS: scroll agent windows normally with a mouse or trackpad.\nset -g mouse on\n`;
|
|
7
|
-
|
|
8
|
-
/** Choose the tmux user config without creating a second competing config. */
|
|
9
|
-
export function tmuxConfigPath(home = homedir(), env = process.env) {
|
|
10
|
-
const legacy = join(home, ".tmux.conf");
|
|
11
|
-
const xdg = join(env.XDG_CONFIG_HOME || join(home, ".config"), "tmux", "tmux.conf");
|
|
12
|
-
return existsSync(legacy) || !existsSync(xdg) ? legacy : xdg;
|
|
13
|
-
}
|
|
14
|
-
|
|
15
|
-
/** Whether the selected config explicitly enables tmux mouse support. */
|
|
16
|
-
export function tmuxMouseEnabled(text) {
|
|
17
|
-
return text.split("\n").some((line) => {
|
|
18
|
-
const active = line.replace(/\s+#.*$/, "").trim();
|
|
19
|
-
return /^(?:set|set-option)(?:\s+-[a-zA-Z]+)*\s+mouse\s+(?:on|1)\s*$/.test(active);
|
|
20
|
-
});
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
/** Add the setting once and reload a running tmux server when possible. */
|
|
24
|
-
export function enableTmuxMouse(configPath = tmuxConfigPath()) {
|
|
25
|
-
const before = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
|
|
26
|
-
if (tmuxMouseEnabled(before)) return { changed: false, configPath, reloaded: false };
|
|
27
|
-
|
|
28
|
-
mkdirSync(dirname(configPath), { recursive: true });
|
|
29
|
-
const separator = before.length === 0 || before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
|
|
30
|
-
appendFileSync(configPath, separator + OATS_MOUSE_BLOCK);
|
|
31
|
-
|
|
32
|
-
const server = spawnSync("tmux", ["has-session"], { stdio: "ignore" });
|
|
33
|
-
const reloaded = server.status === 0 && spawnSync("tmux", ["source-file", configPath], { stdio: "ignore" }).status === 0;
|
|
34
|
-
return { changed: true, configPath, reloaded };
|
|
35
|
-
}
|