@awebai/oats 0.66.0 → 0.68.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/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
|
@@ -29,9 +29,9 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
|
|
|
29
29
|
steps yourself and read back what each did.
|
|
30
30
|
- **Secrets.** The person types only what you must never hold: passwords,
|
|
31
31
|
tokens and logins. Before the spawn there are two ways for that: a browser
|
|
32
|
-
device flow you start (the GitHub login, step 3), and the exact command
|
|
33
|
-
|
|
34
|
-
|
|
32
|
+
device flow you start (the GitHub login, step 3), and the exact command in
|
|
33
|
+
their own terminal (a `sudo` or Homebrew password, an aweb invite token),
|
|
34
|
+
which you open for them (below).
|
|
35
35
|
- Never ask for a secret in the conversation, and never write one to a file.
|
|
36
36
|
- Never suggest Claude Code's `! <command>` for one: its command and output
|
|
37
37
|
enter your context.
|
|
@@ -42,6 +42,26 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
|
|
|
42
42
|
path), write that value in literally.
|
|
43
43
|
- **Sandboxes.** If your harness sandboxes commands, these steps need network
|
|
44
44
|
access and writes in the home folder: ask the person to approve them.
|
|
45
|
+
Starting the Desktop and opening a terminal also run outside the sandbox.
|
|
46
|
+
- **Their own terminal, opened by you.** When a command must run in the
|
|
47
|
+
person's terminal, write it to a file (`mktemp`; it holds no secret) after
|
|
48
|
+
a first line `export PATH="<node dir>:<oats dir>:<harness dir>:$HOME/.local/bin:$PATH"`,
|
|
49
|
+
with the folders `command -v node`, `command -v oats` and `command -v
|
|
50
|
+
<harness>` print written in (a window may load no shell startup file, so a
|
|
51
|
+
version manager's node would be missing), and a last line
|
|
52
|
+
`printf '\nDone: close this window.\n'; read -r _`. Then open a window
|
|
53
|
+
that runs it, with `F` the file's path written in:
|
|
54
|
+
- **macOS:** `osascript -e 'tell application "Terminal" to do script "sh F"'`.
|
|
55
|
+
The first time, macOS may ask the person to let you control Terminal.
|
|
56
|
+
- **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
|
|
57
|
+
or `x-terminal-emulator -e sh "F"` in place of `xdg-terminal-exec` where
|
|
58
|
+
only that exists. Through `systemd-run` the window gets their desktop
|
|
59
|
+
session's environment, not yours.
|
|
60
|
+
|
|
61
|
+
Tell them what to type there, and ask whether the window opened: a
|
|
62
|
+
command that started is no proof of a window. Check the result with a
|
|
63
|
+
read-only command, never by reading the window, then delete the file.
|
|
64
|
+
Only when no window opens do you give them the command to run themselves.
|
|
45
65
|
- **Touch nothing you were not asked to.** Don't edit an existing
|
|
46
66
|
deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
|
|
47
67
|
don't push to a repository the person did not create in step 5.
|
|
@@ -94,9 +114,11 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
94
114
|
- **The harness** they chose must be installed and logged in (`claude
|
|
95
115
|
--version`, `codex --version` or `pi --version`).
|
|
96
116
|
- **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
|
|
97
|
-
- **Without Homebrew,**
|
|
98
|
-
for
|
|
99
|
-
|
|
117
|
+
- **Without Homebrew,** it installs in their own Terminal, which you open
|
|
118
|
+
for them ("How to work") with the command under “Install Homebrew” on
|
|
119
|
+
<https://brew.sh>, since it asks for their password. Then add its
|
|
120
|
+
`brew shellenv` line to their `~/.zprofile` yourself, as its “Next
|
|
121
|
+
steps” say.
|
|
100
122
|
- Your running process does not see their new PATH. Start each later
|
|
101
123
|
command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
|
|
102
124
|
(`/usr/local/bin/brew` on Intel), or ask them to restart you.
|
|
@@ -111,9 +133,18 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
111
133
|
unless `sudo -n true` succeeds.
|
|
112
134
|
- **npm's global folder** (`npm prefix -g`) must be writable for step 4's
|
|
113
135
|
install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
|
|
114
|
-
under `/usr
|
|
115
|
-
terminal, or set a per-user prefix
|
|
116
|
-
`~/.local/bin` on
|
|
136
|
+
under `/usr`, as NodeSource installs it), either they run that install with
|
|
137
|
+
`sudo` in their own terminal, or set a per-user prefix:
|
|
138
|
+
`npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
|
|
139
|
+
each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
|
|
140
|
+
(your shell does not reread their profile). Add that line to their shell's
|
|
141
|
+
startup file yourself, so their own terminal finds `oats` too, and tell
|
|
142
|
+
them you did: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc`
|
|
143
|
+
(for fish, `fish -c 'fish_add_path ~/.local/bin'` instead).
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
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"
|
|
147
|
+
```
|
|
117
148
|
- **Windows** is not supported.
|
|
118
149
|
|
|
119
150
|
## 3. Log in to GitHub
|
|
@@ -146,9 +177,10 @@ In a separate command, a few seconds later, read the code and the URL:
|
|
|
146
177
|
cat "$HOME/.oats-gh-login.txt"
|
|
147
178
|
```
|
|
148
179
|
|
|
149
|
-
- **Give the person the code and the URL**
|
|
150
|
-
|
|
151
|
-
|
|
180
|
+
- **Give the person the code, and open the URL** in their browser
|
|
181
|
+
(`open https://github.com/login/device` on macOS, `xdg-open …` on Linux;
|
|
182
|
+
give them the URL if that fails). The code is not a secret: only their own
|
|
183
|
+
signed-in browser can use it. They enter the code and approve. A code expires after about 15
|
|
152
184
|
minutes; then start again.
|
|
153
185
|
- **Once they say they approved,** check the login and let Git use it:
|
|
154
186
|
|
|
@@ -194,8 +226,10 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
|
194
226
|
- **Download with `gh`, never through a browser.** `gh` sets no quarantine
|
|
195
227
|
on what it downloads, and that copy starts from Finder. A browser download
|
|
196
228
|
would be quarantined.
|
|
197
|
-
- **Install it.** If the Desktop is running,
|
|
198
|
-
|
|
229
|
+
- **Install it.** If the Desktop is running, tell the person and quit it;
|
|
230
|
+
its agents keep running:
|
|
231
|
+
`osascript -e 'quit app "OATS Desktop"'; for i in $(seq 20); do pgrep -xq "OATS Desktop" || break; sleep 1; done`.
|
|
232
|
+
Then, with the folder `pwd` printed:
|
|
199
233
|
|
|
200
234
|
```bash
|
|
201
235
|
cd "<that folder>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
@@ -207,7 +241,11 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
|
207
241
|
Desktop.app"`): never silently.
|
|
208
242
|
|
|
209
243
|
**Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
|
|
210
|
-
per user, without sudo, and shows in the app launcher
|
|
244
|
+
per user, without sudo, and shows in the app launcher. If the Desktop is
|
|
245
|
+
running, tell the person and quit it first; its agents keep running:
|
|
246
|
+
`pkill -o -u "$(id -u)" -x oats-desktop; for i in $(seq 20); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null || break; sleep 1; done; pgrep -u "$(id -u)" -x oats-desktop >/dev/null && echo STILL_RUNNING`
|
|
247
|
+
(the oldest process is the Desktop's main one). On `STILL_RUNNING`, ask the
|
|
248
|
+
person to quit it.
|
|
211
249
|
|
|
212
250
|
```bash
|
|
213
251
|
cd "$(mktemp -d)" &&
|
|
@@ -230,9 +268,10 @@ Terminal=false
|
|
|
230
268
|
Categories=Development;
|
|
231
269
|
```
|
|
232
270
|
|
|
233
|
-
- **Without FUSE** (
|
|
234
|
-
` --appimage-extract-and-run` after
|
|
235
|
-
|
|
271
|
+
- **Without FUSE** (step 8's start fails with a FUSE message; Ubuntu 22.04
|
|
272
|
+
and later ship without `libfuse2`), add ` --appimage-extract-and-run` after
|
|
273
|
+
the AppImage's path in `Exec=` and in step 8's start. That needs no
|
|
274
|
+
`sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
|
|
236
275
|
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
|
|
237
276
|
download, say so and go on.
|
|
238
277
|
|
|
@@ -272,12 +311,13 @@ name: acme
|
|
|
272
311
|
members:
|
|
273
312
|
- git:github.com/acme/acme-oats # the host is a member too
|
|
274
313
|
packages:
|
|
275
|
-
oats.framework: v1.
|
|
276
|
-
oats.aweb: v1.
|
|
314
|
+
oats.framework: v1.14.1 # the installed CLI's catalog versions (below)
|
|
315
|
+
oats.aweb: v1.31.0 # messaging, and tasks: agent identities, mail, chat and tasks
|
|
277
316
|
defaults:
|
|
278
317
|
capabilities:
|
|
279
318
|
oats.core: { from: package }
|
|
280
319
|
messaging: { oats.aweb: { from: package } }
|
|
320
|
+
tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
|
|
281
321
|
teams:
|
|
282
322
|
acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
|
|
283
323
|
defaultTeam: acme # every soul starts in this team
|
|
@@ -285,12 +325,19 @@ defaultTeam: acme # every soul starts in this team
|
|
|
285
325
|
|
|
286
326
|
- **The versions** are the installed CLI's catalog's:
|
|
287
327
|
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
|
|
288
|
-
(for example `oats-framework/v1.
|
|
289
|
-
`packages."oats.aweb".ref
|
|
328
|
+
(for example `oats-framework/v1.14.1`: write the part after the `/`) and
|
|
329
|
+
`packages."oats.aweb".ref`, but never below `v1.31.0`: that release
|
|
330
|
+
carries `oats.aweb-tasks`, and a bare version resolves through the
|
|
331
|
+
catalog's tag convention even when the installed catalog names an older
|
|
332
|
+
one.
|
|
290
333
|
- **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
|
|
291
334
|
its label (here `acme`) is the workspace name.
|
|
335
|
+
- **Tasks** use aweb, the same identities as messaging: agents assign,
|
|
336
|
+
claim and hand off work as aweb tasks the person sees on the aweb
|
|
337
|
+
dashboard. A workspace that uses Jira or Linear writes that provider in
|
|
338
|
+
`tasks:` instead (the setup expert sets it up).
|
|
292
339
|
- **Without messaging,** leave out the `oats.aweb` line, the `messaging`
|
|
293
|
-
line, `teams` and `defaultTeam`.
|
|
340
|
+
line, the `tasks` line, `teams` and `defaultTeam`.
|
|
294
341
|
- **Add nothing else:** knowledge and the person's own repositories come
|
|
295
342
|
with the setup expert.
|
|
296
343
|
|
|
@@ -458,9 +505,9 @@ can't spawn on this machine until it has messaging too. Set it up now:
|
|
|
458
505
|
`<workspace>-<their machine>`. This works for a hosted team only: if the
|
|
459
506
|
invite is refused, or the join says the team is not hosted, stop, and
|
|
460
507
|
the workspace's owner decides.
|
|
461
|
-
4. **Existing workspace: the person joins in their own terminal,**
|
|
462
|
-
|
|
463
|
-
in:
|
|
508
|
+
4. **Existing workspace: the person joins in their own terminal,** which you
|
|
509
|
+
open for them ("How to work"), typing the token at the hidden prompt. Its
|
|
510
|
+
command, with `D`, `S`, `L`, `A` and `U` filled in:
|
|
464
511
|
|
|
465
512
|
```text
|
|
466
513
|
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'
|
|
@@ -507,9 +554,9 @@ oats harness trust --dir D --harness claude
|
|
|
507
554
|
```
|
|
508
555
|
|
|
509
556
|
- **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
|
|
510
|
-
the writer refuses), don't edit the file or its attributes.
|
|
511
|
-
|
|
512
|
-
harness's folder-trust question and
|
|
557
|
+
the writer refuses), don't edit the file or its attributes. Open their
|
|
558
|
+
own terminal ("How to work") with `cd "D" && claude` (or `codex`); they
|
|
559
|
+
accept the harness's folder-trust question and exit.
|
|
513
560
|
- **Then check** that the `harness-trust` item of
|
|
514
561
|
`oats readiness --soul S --dir D --json` passes.
|
|
515
562
|
|
|
@@ -532,23 +579,30 @@ oats spawn S --dir D --task-file D/.oats-handover.md
|
|
|
532
579
|
**The Desktop**, if installed, starts on the new deployment:
|
|
533
580
|
- **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
|
|
534
581
|
already running, the new launch hands `--dir` to it and exits.
|
|
535
|
-
- **Linux:**
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
582
|
+
- **Linux:** start it yourself through their session manager, so it gets
|
|
583
|
+
their desktop session's environment, not yours (yours may carry your
|
|
584
|
+
harness's variables and sandbox, and the Desktop passes its environment to
|
|
585
|
+
every agent it starts):
|
|
586
|
+
|
|
587
|
+
```bash
|
|
588
|
+
U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
- **`STARTED`:** it shows `D`.
|
|
592
|
+
- **A FUSE message:** see step 4, then start it again.
|
|
593
|
+
- **Anything else,** or no `systemd-run`: tell the person what it printed.
|
|
594
|
+
They open **OATS Desktop** from their app launcher, and it lists `D` in
|
|
595
|
+
its switcher (from OATS 0.65.0).
|
|
539
596
|
- **Never start it with an emptied environment** (`env -i`): it then loses
|
|
540
597
|
HOME, and Git loses the person's login.
|
|
541
598
|
|
|
542
|
-
**The TUI**, if they wanted it, runs in a terminal of its own:
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
- **Linux:** give them `oats tui --dir D` for their terminal.
|
|
599
|
+
**The TUI**, if they wanted it, runs in a terminal of its own: open it in
|
|
600
|
+
their own terminal, as "How to work" says, with the command
|
|
601
|
+
`oats tui --dir "D"`.
|
|
546
602
|
|
|
547
|
-
**Tell the person
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
- `oats tui --dir D`;
|
|
551
|
-
- `oats session attach --home H` in a terminal.
|
|
603
|
+
**Tell the person where the setup expert is**, and that it continues from
|
|
604
|
+
here: in the Desktop or the TUI you started. Without either, they reach it
|
|
605
|
+
with `oats session attach --home H` in a terminal.
|
|
552
606
|
|
|
553
607
|
It will ask them only what the hand-over leaves open, and it opens a pane in
|
|
554
608
|
its own window when they need to type a secret. You are done.
|