@awebai/oats 0.64.0 → 0.66.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 (51) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +109 -11
  3. package/docs/desktop-cli-api.md +88 -5
  4. package/docs/desktop.md +14 -5
  5. package/docs/implementation.md +26 -3
  6. package/docs/integrations.md +1 -1
  7. package/docs/official-catalog.md +2 -2
  8. package/docs/packages.md +7 -7
  9. package/docs/release-notes/v0.65.0.md +187 -0
  10. package/docs/release-notes/v0.66.0.md +183 -0
  11. package/docs/servers.md +2 -2
  12. package/docs/tui.md +548 -249
  13. package/docs/upgrading.md +1 -1
  14. package/docs/workspaces.md +132 -1
  15. package/lib/core.mjs +14 -4
  16. package/lib/deployments.mjs +341 -0
  17. package/lib/resolved-deployment.mjs +37 -0
  18. package/lib/workspace.mjs +2 -0
  19. package/package-catalog.json +2 -2
  20. package/package.json +1 -1
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/deployment-label.mjs +2 -2
  23. package/packages/client/deployment-list-cli.mjs +98 -0
  24. package/packages/client/deployment-list.mjs +91 -0
  25. package/packages/client/keymap.mjs +133 -0
  26. package/packages/client/machine-contract.mjs +1 -5
  27. package/packages/client/own-codes.mjs +2 -0
  28. package/packages/client/panel-views.mjs +1 -1
  29. package/packages/client/workspace-admission.mjs +2 -1
  30. package/packages/record/bin/setup.mjs +10 -2
  31. package/packages/record/docs/capture-service.md +45 -6
  32. package/packages/record/lib/capture-service-install.mjs +6 -95
  33. package/packages/record/lib/capture-setup-write.mjs +233 -0
  34. package/packages/tui/README.md +10 -9
  35. package/packages/tui/lib/actions.mjs +89 -64
  36. package/packages/tui/lib/client.mjs +4 -1
  37. package/packages/tui/lib/config.mjs +184 -36
  38. package/packages/tui/lib/main.mjs +161 -40
  39. package/packages/tui/lib/model.mjs +73 -41
  40. package/packages/tui/lib/read.mjs +15 -45
  41. package/packages/tui/lib/store.mjs +174 -40
  42. package/packages/tui/lib/term/keys.mjs +135 -33
  43. package/packages/tui/lib/term/kitty.mjs +198 -0
  44. package/packages/tui/lib/term/through.mjs +160 -24
  45. package/packages/tui/lib/term/tty.mjs +43 -12
  46. package/packages/tui/lib/views/act.mjs +17 -13
  47. package/packages/tui/lib/views/frame.mjs +418 -421
  48. package/packages/tui/lib/views/help.mjs +90 -29
  49. package/packages/tui/lib/views/instances.mjs +38 -9
  50. package/packages/tui/lib/views/switcher.mjs +65 -21
  51. package/skills/oats-getting-started/SKILL.md +102 -32
@@ -63,14 +63,21 @@ 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
72
- folder works. Suggest `~/Agents/<workspace>`: the Desktop and the TUI find
73
- deployments directly inside `~/Agents` by themselves. Write `D` everywhere
77
+ folder but their home folder itself works: ask for it, and suggest none.
78
+ From OATS 0.65.0, `oats onboard` adds `D` to this computer's list of
79
+ deployments (`~/.oats/config/deployments.json`, which `oats deployments`
80
+ reads), so the Desktop and the TUI find it wherever it is. Write `D` everywhere
74
81
  below as an absolute path, with the home folder spelled out: never `~`,
75
82
  which the shell does not expand inside quotes.
76
83
  - **OATS Desktop:** installed and started unless they decline. **The TUI**
@@ -118,6 +125,13 @@ GitHub access. Check first:
118
125
  gh auth status
119
126
  ```
120
127
 
128
+ If it is logged in, let Git use it (without this, step 5's push and step 6
129
+ fail with "could not read Username"), then go to step 4:
130
+
131
+ ```bash
132
+ gh auth setup-git
133
+ ```
134
+
121
135
  If it is not logged in, start the login yourself, detached and without a
122
136
  terminal (use your harness's background mode if it has one). gh then prints
123
137
  a one-time code and a URL instead of opening a browser, and waits:
@@ -234,7 +248,7 @@ pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
234
248
  ## 5. The workspace
235
249
 
236
250
  **New workspace.** Create its repository, private, inside the deployment
237
- directory `D`, then write four files in it.
251
+ directory `D`, then write the files below in it.
238
252
  - **Private** is the safe default: the workspace file names every member, so
239
253
  whoever reads it sees the list.
240
254
  - **`D/<repo>` must not exist yet:** an existing folder's files would end up
@@ -244,10 +258,11 @@ directory `D`, then write four files in it.
244
258
  mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
245
259
  ```
246
260
 
247
- Then write the four files below in `D/<repo>`. They show a workspace named
248
- `acme`, in the repository `acme/acme-oats`, with Claude as the harness:
249
- write the person's own workspace name, repository and harness in their
250
- place.
261
+ Then write the files below in `D/<repo>`, all in this one first commit.
262
+ They show a workspace named `acme`, in the repository `acme/acme-oats`,
263
+ with Claude as the harness and messaging for the aweb username `acme-ana`:
264
+ write the person's own workspace name, repository, harness and username in
265
+ their place.
251
266
 
252
267
  `oats-workspace.yaml`:
253
268
 
@@ -257,17 +272,27 @@ name: acme
257
272
  members:
258
273
  - git:github.com/acme/acme-oats # the host is a member too
259
274
  packages:
260
- oats.framework: v1.13.3 # the installed CLI's catalog version (below)
275
+ oats.framework: v1.13.4 # the installed CLI's catalog versions (below)
276
+ oats.aweb: v1.30.0 # messaging: agent identities, mail and chat
261
277
  defaults:
262
278
  capabilities:
263
279
  oats.core: { from: package }
280
+ messaging: { oats.aweb: { from: package } }
281
+ teams:
282
+ acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
283
+ defaultTeam: acme # every soul starts in this team
264
284
  ```
265
285
 
266
- - **The `oats.framework` version** is the installed CLI's catalog's:
267
- `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`,
268
- for example `oats-framework/v1.13.3`. Write the part after the `/`.
269
- - **Add nothing else:** knowledge, messaging and teams come with the setup
270
- expert.
286
+ - **The versions** are the installed CLI's catalog's:
287
+ `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
288
+ (for example `oats-framework/v1.13.4`: write the part after the `/`) and
289
+ `packages."oats.aweb".ref` (for example `v1.30.0`).
290
+ - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
291
+ its label (here `acme`) is the workspace name.
292
+ - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
293
+ line, `teams` and `defaultTeam`.
294
+ - **Add nothing else:** knowledge and the person's own repositories come
295
+ with the setup expert.
271
296
 
272
297
  `oats-membership.yaml`:
273
298
 
@@ -282,7 +307,7 @@ workspace: git:github.com/acme/acme-oats
282
307
  schemaVersion: 2
283
308
  name: acme-oats-setup-expert
284
309
  description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
285
- work: worktree # it changes this repository by pull request, on its own branch
310
+ work: worktree # it changes this repository from its own worktree
286
311
  capabilities:
287
312
  oats.setup: { from: package }
288
313
  knowledge: none # so it spawns on a machine before knowledge is set up there
@@ -302,7 +327,30 @@ toolkit: its briefing says what the person types and what you run, and its
302
327
  skills hold every procedure. Start with `/oats-setup-model`. When your task
303
328
  is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
304
329
  or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
305
- Change shared files only by pull request; the person reviews and merges them.
330
+ ```
331
+
332
+ `souls/acme-developer/soul.yaml`, a first developer for the person's tasks:
333
+
334
+ ```yaml
335
+ schemaVersion: 2
336
+ name: acme-developer
337
+ description: A developer in the acme workspace — builds what its task asks.
338
+ work: directory # its own folder; the setup expert points it at the person's repositories later
339
+ knowledge: none
340
+ launch: { harness: claude }
341
+ ```
342
+
343
+ `souls/acme-developer/AGENTS.md`, and beside it the symlink
344
+ `CLAUDE.md -> AGENTS.md`:
345
+
346
+ ```markdown
347
+ # acme-developer
348
+
349
+ You are a developer in the acme workspace. You build what your task asks,
350
+ in your own `work/` directory: write the code, run it and test it. Keep the
351
+ solution small and simple. When you finish, say what you built, where it is
352
+ and how you checked it. If you are blocked on a decision, ask whoever gave
353
+ you the task.
306
354
  ```
307
355
 
308
356
  **Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
@@ -310,13 +358,17 @@ it improves when the workspace's `oats.framework` pin moves. It has no
310
358
  knowledge of its own, so it can be spawned on a machine before knowledge is
311
359
  set up there. It takes the workspace's messaging and doesn't empty that
312
360
  slot: a setup soul that empties the messaging slot the workspace fills is
313
- not the workspace's operator, and gets no mail. A new workspace has no
314
- messaging yet; the setup expert adds it.
361
+ not the workspace's operator, and gets no mail.
315
362
 
316
363
  **Commit and push.**
317
364
  - This first commit goes straight to the new repository's default branch: it
318
- is the person's own, just created. Every later change is a pull request
319
- from the setup expert.
365
+ is the person's own, just created. Later changes come from the setup
366
+ expert, by its briefing's rule for shared files (`oats.setup`'s
367
+ `/oats-workspace-config`, "Change a shared file"). From oats.setup 2.8.3
368
+ (oats.framework 1.13.4), it pushes straight to the default branch when its
369
+ checks show nobody else can push there and nothing guards that branch, and
370
+ for a member repository only on the person's yes; otherwise it opens a
371
+ pull request. An older `oats.setup` always opens one.
320
372
  - If `git config user.email` prints nothing, the person's Git identity is not
321
373
  set up yet. After they confirm their name, commit with
322
374
  `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
@@ -325,7 +377,7 @@ messaging yet; the setup expert adds it.
325
377
  setup expert sets up their identity properly later.
326
378
 
327
379
  ```bash
328
- cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, membership, setup expert" && git push -u origin HEAD
380
+ cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, team, setup expert, developer" && git push -u origin HEAD
329
381
  ```
330
382
 
331
383
  The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
@@ -380,8 +432,25 @@ can't spawn on this machine until it has messaging too. Set it up now:
380
432
  ```
381
433
 
382
434
  Its `aw.status` must be `ok` or `done`; stop on `failed` and tell the
383
- person why. Its `defaultTeam.label` is `L`, the setup expert's team.
384
- 2. **The person gets an invite token** from a member of `L`, who runs
435
+ 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.
436
+ 2. **New workspace: sign up its aweb account and team,** with `N` and `A`
437
+ from step 1. No API key, no token and nothing for the person to type.
438
+ Preview first, then run it:
439
+
440
+ ```bash
441
+ cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
442
+ cd "D" && oats aweb setup --soul S --username N --name A --label L --json
443
+ ```
444
+
445
+ The preview does not contact aweb, so it can't tell whether `N` is free.
446
+ If the run fails with `E_SETUP_NATIVE` (most likely the username is
447
+ taken; aw's output is withheld), don't rerun yet: run
448
+ `test -e "D/.aw" && echo HAS_AW`. If it prints `HAS_AW`, stop and tell the
449
+ person what you saw. Otherwise ask the person for another `N`, then in
450
+ `D/<repo>` change the team id in `oats-workspace.yaml` to
451
+ `default:N.aweb.ai`, commit and push it, run `oats sync --dir D`, and run
452
+ both lines again. Then skip items 3 and 4 and go to the check (item 5).
453
+ 3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
385
454
  `oats aweb invite --soul <their soul> --label L --json` in their own
386
455
  deployment and passes the token to the person privately, never by
387
456
  ordinary mail. They also give the aweb service URL `U`. Choose with the
@@ -389,14 +458,14 @@ can't spawn on this machine until it has messaging too. Set it up now:
389
458
  `<workspace>-<their machine>`. This works for a hosted team only: if the
390
459
  invite is refused, or the join says the team is not hosted, stop, and
391
460
  the workspace's owner decides.
392
- 3. **The person joins in their own terminal,** typing the token at the
461
+ 4. **Existing workspace: the person joins in their own terminal,** typing the token at the
393
462
  hidden prompt. Give them the line with `D`, `S`, `L`, `A` and `U` filled
394
463
  in:
395
464
 
396
465
  ```text
397
466
  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'
398
467
  ```
399
- 4. **Check,** and expect `"member": true`:
468
+ 5. **Check,** and expect `"member": true`:
400
469
 
401
470
  ```bash
402
471
  cd "D" && oats aweb setup --soul S --check-only --json
@@ -421,7 +490,7 @@ are cloned, knowledge tools, messaging wanted or not>
421
490
  - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
422
491
  - GitHub: gh logged in over https as <login>; no SSH key or signing set up
423
492
  - New workspace only: repository <owner>/<repo> created, first commit pushed
424
- - Messaging: this machine joined L as root A (aw <version>, <harness>
493
+ - Messaging: new account N signed up, or joined L by invite; root A (aw <version>, <harness>
425
494
  channel installed) | not set up (the setup expert has no messaging)
426
495
 
427
496
  ## Left to you
@@ -465,8 +534,8 @@ oats spawn S --dir D --task-file D/.oats-handover.md
465
534
  already running, the new launch hands `--dir` to it and exits.
466
535
  - **Linux:** the person opens **OATS Desktop** from their app launcher, so it
467
536
  starts with their own session's environment, not yours. Then they pick `D`
468
- in its switcher (**Add local workspace… → Browse**), unless `D` is
469
- directly inside `~/Agents`.
537
+ in its switcher (listed there from OATS 0.65.0). If it isn't listed, they
538
+ add it with **Add local workspace… → Browse**.
470
539
  - **Never start it with an emptied environment** (`env -i`): it then loses
471
540
  HOME, and Git loses the person's login.
472
541
 
@@ -493,6 +562,7 @@ its own window when they need to type a secret. You are done.
493
562
  person did not create in step 5.
494
563
  - **The Desktop:** never download it through a browser, skip a verification
495
564
  step, strip quarantine without asking, or start it with `env -i`.
496
- - **Put an absolute path, an account or a credential** in
497
- `oats-workspace.yaml`, `oats-membership.yaml` or a soul.
565
+ - **Put an absolute path or a credential** in `oats-workspace.yaml`,
566
+ `oats-membership.yaml` or a soul (the aweb username in the team id is not
567
+ a secret).
498
568
  - **Spawn** before `oats onboard` confirmed the host.