@awebai/oats 0.65.0 → 0.67.1

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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -63,9 +63,14 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
63
63
  they can create repositories in) and the repository's name. Suggest
64
64
  `<workspace>-oats`. Refuse `agents`: OATS keeps instance homes in a
65
65
  folder of that name.
66
- - **Messaging between agents (aweb):** wanted or not. The setup expert sets it
67
- up later. An existing workspace that already has it needs it on this
68
- machine before the setup expert can spawn (step 7).
66
+ - **Messaging between agents (aweb):** wanted or not (recommended: agents
67
+ that can mail each other can coordinate).
68
+ - New workspace: a **username** `N` for a new hosted aweb account
69
+ (lowercase letters, digits and `-`), not a secret. Step 7 signs it up
70
+ with no API key, and its team is `default:N.aweb.ai`. Also a name `A`
71
+ for this machine's messaging root, such as `<workspace>-root`.
72
+ - Existing workspace that already has it: this machine needs it before the
73
+ setup expert can spawn (step 7).
69
74
  - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
70
75
  the one you are, if it is one of these.
71
76
  - **The deployment directory `D`:** where OATS lives on this machine. Any
@@ -106,9 +111,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
106
111
  unless `sudo -n true` succeeds.
107
112
  - **npm's global folder** (`npm prefix -g`) must be writable for step 4's
108
113
  install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
109
- under `/usr`), either they run that install with `sudo` in their own
110
- terminal, or set a per-user prefix (`npm config set prefix ~/.local`, with
111
- `~/.local/bin` on their PATH).
114
+ under `/usr`, as NodeSource installs it), either they run that install with
115
+ `sudo` in their own terminal, or set a per-user prefix:
116
+ `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
117
+ 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.
112
120
  - **Windows** is not supported.
113
121
 
114
122
  ## 3. Log in to GitHub
@@ -120,6 +128,13 @@ GitHub access. Check first:
120
128
  gh auth status
121
129
  ```
122
130
 
131
+ If it is logged in, let Git use it (without this, step 5's push and step 6
132
+ fail with "could not read Username"), then go to step 4:
133
+
134
+ ```bash
135
+ gh auth setup-git
136
+ ```
137
+
123
138
  If it is not logged in, start the login yourself, detached and without a
124
139
  terminal (use your harness's background mode if it has one). gh then prints
125
140
  a one-time code and a URL instead of opening a browser, and waits:
@@ -218,9 +233,11 @@ Terminal=false
218
233
  Categories=Development;
219
234
  ```
220
235
 
221
- - **Without FUSE** (the AppImage fails with a FUSE message), add
222
- ` --appimage-extract-and-run` after the AppImage's path in `Exec=` and
223
- wherever you start it.
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.
224
241
  - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
225
242
  download, say so and go on.
226
243
 
@@ -236,7 +253,7 @@ pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
236
253
  ## 5. The workspace
237
254
 
238
255
  **New workspace.** Create its repository, private, inside the deployment
239
- directory `D`, then write four files in it.
256
+ directory `D`, then write the files below in it.
240
257
  - **Private** is the safe default: the workspace file names every member, so
241
258
  whoever reads it sees the list.
242
259
  - **`D/<repo>` must not exist yet:** an existing folder's files would end up
@@ -246,10 +263,11 @@ directory `D`, then write four files in it.
246
263
  mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
247
264
  ```
248
265
 
249
- Then write the four files below in `D/<repo>`. They show a workspace named
250
- `acme`, in the repository `acme/acme-oats`, with Claude as the harness:
251
- write the person's own workspace name, repository and harness in their
252
- place.
266
+ Then write the files below in `D/<repo>`, all in this one first commit.
267
+ They show a workspace named `acme`, in the repository `acme/acme-oats`,
268
+ with Claude as the harness and messaging for the aweb username `acme-ana`:
269
+ write the person's own workspace name, repository, harness and username in
270
+ their place.
253
271
 
254
272
  `oats-workspace.yaml`:
255
273
 
@@ -259,17 +277,27 @@ name: acme
259
277
  members:
260
278
  - git:github.com/acme/acme-oats # the host is a member too
261
279
  packages:
262
- oats.framework: v1.13.3 # the installed CLI's catalog version (below)
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
263
282
  defaults:
264
283
  capabilities:
265
284
  oats.core: { from: package }
285
+ messaging: { oats.aweb: { from: package } }
286
+ teams:
287
+ acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
288
+ defaultTeam: acme # every soul starts in this team
266
289
  ```
267
290
 
268
- - **The `oats.framework` version** is the installed CLI's catalog's:
269
- `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`,
270
- for example `oats-framework/v1.13.3`. Write the part after the `/`.
271
- - **Add nothing else:** knowledge, messaging and teams come with the setup
272
- expert.
291
+ - **The versions** are the installed CLI's catalog's:
292
+ `"$(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`).
295
+ - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
296
+ its label (here `acme`) is the workspace name.
297
+ - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
298
+ line, `teams` and `defaultTeam`.
299
+ - **Add nothing else:** knowledge and the person's own repositories come
300
+ with the setup expert.
273
301
 
274
302
  `oats-membership.yaml`:
275
303
 
@@ -284,7 +312,7 @@ workspace: git:github.com/acme/acme-oats
284
312
  schemaVersion: 2
285
313
  name: acme-oats-setup-expert
286
314
  description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
287
- work: worktree # it changes this repository by pull request, on its own branch
315
+ work: worktree # it changes this repository from its own worktree
288
316
  capabilities:
289
317
  oats.setup: { from: package }
290
318
  knowledge: none # so it spawns on a machine before knowledge is set up there
@@ -304,7 +332,30 @@ toolkit: its briefing says what the person types and what you run, and its
304
332
  skills hold every procedure. Start with `/oats-setup-model`. When your task
305
333
  is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
306
334
  or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
307
- Change shared files only by pull request; the person reviews and merges them.
335
+ ```
336
+
337
+ `souls/acme-developer/soul.yaml`, a first developer for the person's tasks:
338
+
339
+ ```yaml
340
+ schemaVersion: 2
341
+ name: acme-developer
342
+ description: A developer in the acme workspace — builds what its task asks.
343
+ work: directory # its own folder; the setup expert points it at the person's repositories later
344
+ knowledge: none
345
+ launch: { harness: claude }
346
+ ```
347
+
348
+ `souls/acme-developer/AGENTS.md`, and beside it the symlink
349
+ `CLAUDE.md -> AGENTS.md`:
350
+
351
+ ```markdown
352
+ # acme-developer
353
+
354
+ You are a developer in the acme workspace. You build what your task asks,
355
+ in your own `work/` directory: write the code, run it and test it. Keep the
356
+ solution small and simple. When you finish, say what you built, where it is
357
+ and how you checked it. If you are blocked on a decision, ask whoever gave
358
+ you the task.
308
359
  ```
309
360
 
310
361
  **Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
@@ -312,13 +363,17 @@ it improves when the workspace's `oats.framework` pin moves. It has no
312
363
  knowledge of its own, so it can be spawned on a machine before knowledge is
313
364
  set up there. It takes the workspace's messaging and doesn't empty that
314
365
  slot: a setup soul that empties the messaging slot the workspace fills is
315
- not the workspace's operator, and gets no mail. A new workspace has no
316
- messaging yet; the setup expert adds it.
366
+ not the workspace's operator, and gets no mail.
317
367
 
318
368
  **Commit and push.**
319
369
  - This first commit goes straight to the new repository's default branch: it
320
- is the person's own, just created. Every later change is a pull request
321
- from the setup expert.
370
+ is the person's own, just created. Later changes come from the setup
371
+ expert, by its briefing's rule for shared files (`oats.setup`'s
372
+ `/oats-workspace-config`, "Change a shared file"). From oats.setup 2.8.3
373
+ (oats.framework 1.13.4), it pushes straight to the default branch when its
374
+ checks show nobody else can push there and nothing guards that branch, and
375
+ for a member repository only on the person's yes; otherwise it opens a
376
+ pull request. An older `oats.setup` always opens one.
322
377
  - If `git config user.email` prints nothing, the person's Git identity is not
323
378
  set up yet. After they confirm their name, commit with
324
379
  `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
@@ -327,7 +382,7 @@ messaging yet; the setup expert adds it.
327
382
  setup expert sets up their identity properly later.
328
383
 
329
384
  ```bash
330
- cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, membership, setup expert" && git push -u origin HEAD
385
+ cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, team, setup expert, developer" && git push -u origin HEAD
331
386
  ```
332
387
 
333
388
  The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
@@ -382,8 +437,25 @@ can't spawn on this machine until it has messaging too. Set it up now:
382
437
  ```
383
438
 
384
439
  Its `aw.status` must be `ok` or `done`; stop on `failed` and tell the
385
- person why. Its `defaultTeam.label` is `L`, the setup expert's team.
386
- 2. **The person gets an invite token** from a member of `L`, who runs
440
+ person why. Its `defaultTeam.label` is `L`, the setup expert's team. For a new workspace it must equal the label you wrote under `teams:` (the workspace name, not the username `N`); if it differs, stop and tell the person.
441
+ 2. **New workspace: sign up its aweb account and team,** with `N` and `A`
442
+ from step 1. No API key, no token and nothing for the person to type.
443
+ Preview first, then run it:
444
+
445
+ ```bash
446
+ cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
447
+ cd "D" && oats aweb setup --soul S --username N --name A --label L --json
448
+ ```
449
+
450
+ The preview does not contact aweb, so it can't tell whether `N` is free.
451
+ If the run fails with `E_SETUP_NATIVE` (most likely the username is
452
+ taken; aw's output is withheld), don't rerun yet: run
453
+ `test -e "D/.aw" && echo HAS_AW`. If it prints `HAS_AW`, stop and tell the
454
+ person what you saw. Otherwise ask the person for another `N`, then in
455
+ `D/<repo>` change the team id in `oats-workspace.yaml` to
456
+ `default:N.aweb.ai`, commit and push it, run `oats sync --dir D`, and run
457
+ both lines again. Then skip items 3 and 4 and go to the check (item 5).
458
+ 3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
387
459
  `oats aweb invite --soul <their soul> --label L --json` in their own
388
460
  deployment and passes the token to the person privately, never by
389
461
  ordinary mail. They also give the aweb service URL `U`. Choose with the
@@ -391,14 +463,14 @@ can't spawn on this machine until it has messaging too. Set it up now:
391
463
  `<workspace>-<their machine>`. This works for a hosted team only: if the
392
464
  invite is refused, or the join says the team is not hosted, stop, and
393
465
  the workspace's owner decides.
394
- 3. **The person joins in their own terminal,** typing the token at the
466
+ 4. **Existing workspace: the person joins in their own terminal,** typing the token at the
395
467
  hidden prompt. Give them the line with `D`, `S`, `L`, `A` and `U` filled
396
468
  in:
397
469
 
398
470
  ```text
399
471
  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'
400
472
  ```
401
- 4. **Check,** and expect `"member": true`:
473
+ 5. **Check,** and expect `"member": true`:
402
474
 
403
475
  ```bash
404
476
  cd "D" && oats aweb setup --soul S --check-only --json
@@ -423,7 +495,7 @@ are cloned, knowledge tools, messaging wanted or not>
423
495
  - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
424
496
  - GitHub: gh logged in over https as <login>; no SSH key or signing set up
425
497
  - New workspace only: repository <owner>/<repo> created, first commit pushed
426
- - Messaging: this machine joined L as root A (aw <version>, <harness>
498
+ - Messaging: new account N signed up, or joined L by invite; root A (aw <version>, <harness>
427
499
  channel installed) | not set up (the setup expert has no messaging)
428
500
 
429
501
  ## Left to you
@@ -495,6 +567,7 @@ its own window when they need to type a secret. You are done.
495
567
  person did not create in step 5.
496
568
  - **The Desktop:** never download it through a browser, skip a verification
497
569
  step, strip quarantine without asking, or start it with `env -i`.
498
- - **Put an absolute path, an account or a credential** in
499
- `oats-workspace.yaml`, `oats-membership.yaml` or a soul.
570
+ - **Put an absolute path or a credential** in `oats-workspace.yaml`,
571
+ `oats-membership.yaml` or a soul (the aweb username in the team id is not
572
+ a secret).
500
573
  - **Spawn** before `oats onboard` confirmed the host.