@awebai/oats 0.69.12 → 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 +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- 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 +24 -5
- package/docs/workspaces.md +31 -5
- 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 +1 -1
- 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 +92 -25
- 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
|
|
@@ -399,18 +400,26 @@ for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -
|
|
|
399
400
|
whole-tree fetches, and go on.
|
|
400
401
|
- **npm's global folder** must be writable for step 4's installs
|
|
401
402
|
(`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
|
|
402
|
-
`/usr`, as NodeSource installs it),
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
startup file yourself, so their own terminal finds `oats` too, and tell
|
|
408
|
-
them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
|
|
409
|
-
`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`):
|
|
410
408
|
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
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"`.
|
|
414
423
|
- **Windows** is not supported.
|
|
415
424
|
|
|
416
425
|
## 3. Log in to GitHub
|
|
@@ -489,9 +498,21 @@ file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
|
|
|
489
498
|
checksum and the release's attestation all pass:
|
|
490
499
|
|
|
491
500
|
```bash
|
|
492
|
-
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 & }
|
|
493
502
|
```
|
|
494
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
|
+
|
|
495
516
|
Write the folder it prints in as `<W>` in step 4.
|
|
496
517
|
|
|
497
518
|
## 4. Install OATS Desktop, the CLI and the messaging CLI
|
|
@@ -512,7 +533,7 @@ installed CLI's catalog:
|
|
|
512
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"
|
|
513
534
|
```
|
|
514
535
|
|
|
515
|
-
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
|
|
516
537
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
517
538
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
518
539
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -744,7 +765,7 @@ name: acme
|
|
|
744
765
|
members:
|
|
745
766
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
746
767
|
packages:
|
|
747
|
-
oats.framework: v1.
|
|
768
|
+
oats.framework: v1.23.0 # the installed CLI's catalog versions (below)
|
|
748
769
|
oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
|
|
749
770
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
750
771
|
defaults:
|
|
@@ -811,6 +832,14 @@ oats onboard D --workspace W --json
|
|
|
811
832
|
- **The host must be `confirmed`;** a host that can't be read is a GitHub
|
|
812
833
|
access problem (step 3). Another member with `cannot-read` is an access
|
|
813
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.
|
|
814
843
|
- **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
|
|
815
844
|
person whether to use it as it is or to choose another directory.
|
|
816
845
|
|
|
@@ -865,6 +894,15 @@ oats soul launch set <key> --harness <its harness> --model <its model> --dir D -
|
|
|
865
894
|
oats soul launch set <key> --harness <its harness> --model <its model> --dir D
|
|
866
895
|
```
|
|
867
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
|
+
|
|
868
906
|
`S` is the exception: it always keeps `<harness>`, the person's choice in
|
|
869
907
|
step 1. When `S` declares another harness, give it its own entry with
|
|
870
908
|
`<harness>` instead:
|
|
@@ -950,25 +988,54 @@ readiness still reports a problem.
|
|
|
950
988
|
whose own agent runs
|
|
951
989
|
`oats aweb invite --soul <their soul> --label L --json` in their
|
|
952
990
|
deployment. The answer's `result.token` is the invite token,
|
|
953
|
-
passed to the person privately, never by ordinary mail.
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
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
|
|
958
1001
|
`A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
|
|
959
1002
|
name from step 8: don't ask. Only a hosted team works: if the invite is
|
|
960
1003
|
refused, or the join says the team is not hosted, stop; the workspace's
|
|
961
1004
|
owner decides.
|
|
962
1005
|
4. **Existing workspace: the person joins in their own terminal,** which you
|
|
963
|
-
open for them ("How to work"),
|
|
964
|
-
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:
|
|
965
1024
|
|
|
966
1025
|
```text
|
|
967
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'
|
|
968
1027
|
```
|
|
969
1028
|
|
|
970
1029
|
5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
|
|
971
|
-
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
|
|
972
1039
|
left this machine's root outside `L`, with what the check shows, and
|
|
973
1040
|
don't rerun the signup or the join (you can't see the join's output).
|
|
974
1041
|
When another machine of the same name may already be in the team, say
|
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
|
-
}
|