@awebai/oats 0.67.1 → 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.
Files changed (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -0,0 +1,55 @@
1
+ // The list of workspaces at the top of the sidebar (docs/tui.md, "The list of workspaces"): (the
2
+ // model's `workspaces`, a width) -> rows of spans. Pure: no IO, no clock, no escape byte.
3
+ // A row is one line, a workspace's name, which is the shared home's and goes through shown(); `>`,
4
+ // the dot and `+N` are the TUI's. The open workspace's row is in reverse video; while the list has
5
+ // the focus the cursor's row is, with `>`, and the open workspace's name is underlined. A workspace
6
+ // where an instance needs input has a dot after its name, `●` in yellow, `!` without colour or in
7
+ // ASCII, and `+N` has it when one of the workspaces it counts does.
8
+ import { lit, shown } from "../term/text.mjs";
9
+ import { style } from "../term/style.mjs";
10
+ import { measured } from "./instances.mjs";
11
+
12
+ /** The dot of a workspace where an instance needs input: in yellow, or, with no colour to say it
13
+ * (NO_COLOR) or in ASCII, the needs-input mark of the rows. */
14
+ export const WAITING_DOT = Object.freeze({ utf8: "●", ascii: "!" });
15
+ const CURSOR = 0, NAME = 2, MARGIN = 1;
16
+ const PLAIN = style(), BOLD = style({ bold: true }), BAR = style({ bold: true, reverse: true });
17
+ const OPEN = style({ bold: true, underline: true });
18
+ const YELLOW = style({ fg: "yellow", bold: true });
19
+
20
+ /** One row of the list, `cols` wide: `>` under the cursor, the name, cut with an ellipsis where it
21
+ * does not fit, and one cell after the name as drawn the dot (the screen draws it `after` the
22
+ * name: a name cut, or drawn in `?` without UTF-8, leaves no gap before it). The open workspace's
23
+ * row is in reverse video across the row while the list does not have the focus, the cursor's
24
+ * while it has, and then the open workspace's name is underlined, so it stays told apart until
25
+ * Enter opens the cursor's row. The dot's cell is a gap in the reverse video, on the normal
26
+ * background (a yellow cell with a dark dot in it would read as something else). */
27
+ function row(line, cols, { focused, cursor, ascii, colour }) {
28
+ const under = focused && line.key === cursor, barred = under || (!focused && line.current);
29
+ const spans = barred ? [{ col: 0, width: cols, style: BAR }] : [];
30
+ if (under) spans.push({ col: CURSOR, text: lit(">"), style: BAR, width: 1 });
31
+ // The name keeps the row less the margin, and less the dot and the cell before it when there is one.
32
+ const room = Math.max(0, cols - MARGIN - NAME - (line.waiting ? 2 : 0));
33
+ const width = Math.min(room, measured(line.label).width);
34
+ const look = barred ? BAR : focused && line.current ? OPEN : PLAIN;
35
+ if (width > 0) spans.push({ col: NAME, text: shown(line.label), style: look, width });
36
+ if (line.waiting) spans.push(dot(NAME + width + 1, width > 0, { ascii, colour }));
37
+ return spans;
38
+ }
39
+ /** The dot at `col`, drawn `after` what stands before it when `after`. */
40
+ function dot(col, after, { ascii, colour }) {
41
+ const yellow = colour && !ascii;
42
+ return { col, text: lit(yellow ? WAITING_DOT.utf8 : WAITING_DOT.ascii), style: yellow ? YELLOW : BOLD, width: 1, after };
43
+ }
44
+
45
+ /** The list's rows: `w` the model's `workspaces` (`lines` windowed, `more`, `moreWaiting`, `focused`,
46
+ * `cursor`), in `cols`; `+N` last when N workspaces are not shown, the dot one cell after it when
47
+ * an instance of one of them needs input. */
48
+ export function workspaceRows(w, cols, { ascii = false, colour = true } = {}) {
49
+ const rows = w.lines.map((line) => row(line, cols, { focused: w.focused, cursor: w.cursor, ascii, colour }));
50
+ if (w.more > 0) {
51
+ const width = String(w.more).length + 1;
52
+ rows.push([{ col: NAME, text: lit(`+${w.more}`), style: style({ dim: true }), width }, ...(w.moreWaiting ? [dot(NAME + width + 1, false, { ascii, colour })] : [])]);
53
+ }
54
+ return rows;
55
+ }
@@ -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
- for their own terminal (a `sudo` or Homebrew password, an aweb invite
34
- token).
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,** they install it in their own Terminal, since it asks
98
- for their password: from <https://brew.sh>, the command under “Install
99
- Homebrew”, then the “Next steps” lines it prints.
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.
@@ -115,8 +137,14 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
115
137
  `sudo` in their own terminal, or set a per-user prefix:
116
138
  `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
117
139
  each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
118
- (your shell does not reread their profile), and ask them to add that line
119
- to their shell's startup file so their own terminal finds `oats` too.
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
+ ```
120
148
  - **Windows** is not supported.
121
149
 
122
150
  ## 3. Log in to GitHub
@@ -149,9 +177,10 @@ In a separate command, a few seconds later, read the code and the URL:
149
177
  cat "$HOME/.oats-gh-login.txt"
150
178
  ```
151
179
 
152
- - **Give the person the code and the URL** (`https://github.com/login/device`).
153
- The code is not a secret: only their own signed-in browser can use it. They
154
- open the URL, enter the code and approve. A code expires after about 15
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
155
184
  minutes; then start again.
156
185
  - **Once they say they approved,** check the login and let Git use it:
157
186
 
@@ -197,8 +226,10 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
197
226
  - **Download with `gh`, never through a browser.** `gh` sets no quarantine
198
227
  on what it downloads, and that copy starts from Finder. A browser download
199
228
  would be quarantined.
200
- - **Install it.** If the Desktop is running, ask the person to quit it. Then,
201
- with the folder `pwd` printed:
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:
202
233
 
203
234
  ```bash
204
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
@@ -210,7 +241,11 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
210
241
  Desktop.app"`): never silently.
211
242
 
212
243
  **Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
213
- 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.
214
249
 
215
250
  ```bash
216
251
  cd "$(mktemp -d)" &&
@@ -233,11 +268,10 @@ Terminal=false
233
268
  Categories=Development;
234
269
  ```
235
270
 
236
- - **Without FUSE** (the AppImage fails with a FUSE message; Ubuntu 22.04
237
- and later ship without `libfuse2`), either they install it in their own
238
- terminal (`sudo apt install libfuse2`, or `libfuse2t64` on Ubuntu 24.04),
239
- or add ` --appimage-extract-and-run` after the AppImage's path in `Exec=`
240
- and wherever you start it.
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.
241
275
  - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
242
276
  download, say so and go on.
243
277
 
@@ -277,12 +311,13 @@ name: acme
277
311
  members:
278
312
  - git:github.com/acme/acme-oats # the host is a member too
279
313
  packages:
280
- oats.framework: v1.13.5 # the installed CLI's catalog versions (below)
281
- oats.aweb: v1.30.0 # messaging: agent identities, mail and chat
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
282
316
  defaults:
283
317
  capabilities:
284
318
  oats.core: { from: package }
285
319
  messaging: { oats.aweb: { from: package } }
320
+ tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
286
321
  teams:
287
322
  acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
288
323
  defaultTeam: acme # every soul starts in this team
@@ -290,12 +325,19 @@ defaultTeam: acme # every soul starts in this team
290
325
 
291
326
  - **The versions** are the installed CLI's catalog's:
292
327
  `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
293
- (for example `oats-framework/v1.13.5`: write the part after the `/`) and
294
- `packages."oats.aweb".ref` (for example `v1.30.0`).
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.
295
333
  - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
296
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).
297
339
  - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
298
- line, `teams` and `defaultTeam`.
340
+ line, the `tasks` line, `teams` and `defaultTeam`.
299
341
  - **Add nothing else:** knowledge and the person's own repositories come
300
342
  with the setup expert.
301
343
 
@@ -463,9 +505,9 @@ can't spawn on this machine until it has messaging too. Set it up now:
463
505
  `<workspace>-<their machine>`. This works for a hosted team only: if the
464
506
  invite is refused, or the join says the team is not hosted, stop, and
465
507
  the workspace's owner decides.
466
- 4. **Existing workspace: the person joins in their own terminal,** typing the token at the
467
- hidden prompt. Give them the line with `D`, `S`, `L`, `A` and `U` filled
468
- 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:
469
511
 
470
512
  ```text
471
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'
@@ -512,9 +554,9 @@ oats harness trust --dir D --harness claude
512
554
  ```
513
555
 
514
556
  - **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
515
- the writer refuses), don't edit the file or its attributes. The person
516
- runs `cd D && claude` (or `codex`) in their own terminal, accepts the
517
- harness's folder-trust question and exits.
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.
518
560
  - **Then check** that the `harness-trust` item of
519
561
  `oats readiness --soul S --dir D --json` passes.
520
562
 
@@ -537,23 +579,30 @@ oats spawn S --dir D --task-file D/.oats-handover.md
537
579
  **The Desktop**, if installed, starts on the new deployment:
538
580
  - **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
539
581
  already running, the new launch hands `--dir` to it and exits.
540
- - **Linux:** the person opens **OATS Desktop** from their app launcher, so it
541
- starts with their own session's environment, not yours. Then they pick `D`
542
- in its switcher (listed there from OATS 0.65.0). If it isn't listed, they
543
- add it with **Add local workspace… → Browse**.
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).
544
596
  - **Never start it with an emptied environment** (`env -i`): it then loses
545
597
  HOME, and Git loses the person's login.
546
598
 
547
- **The TUI**, if they wanted it, runs in a terminal of its own:
548
- - **macOS:** open a Terminal window with
549
- `osascript -e 'tell application "Terminal" to do script "oats tui --dir D"'`.
550
- - **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"`.
551
602
 
552
- **Tell the person how to reach the setup expert**, and that it continues
553
- from here:
554
- - the Desktop;
555
- - `oats tui --dir D`;
556
- - `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.
557
606
 
558
607
  It will ask them only what the hand-over leaves open, and it opens a pane in
559
608
  its own window when they need to type a secret. You are done.