@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.
- package/README.md +11 -5
- package/bin/oats.mjs +74 -20
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +222 -10
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +16 -6
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.66.0.md +183 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +5 -4
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +658 -143
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +9 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/deployments.mjs +21 -5
- package/lib/instance-color.mjs +58 -0
- 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 +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- 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 +3 -1
- 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 +99 -11
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/machine-contract.mjs +1 -5
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +9 -8
- package/packages/tui/lib/actions.mjs +108 -64
- package/packages/tui/lib/client.mjs +8 -3
- package/packages/tui/lib/config.mjs +208 -26
- package/packages/tui/lib/main.mjs +91 -20
- package/packages/tui/lib/model.mjs +167 -61
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +156 -47
- package/packages/tui/lib/term/keys.mjs +150 -34
- package/packages/tui/lib/term/kitty.mjs +223 -0
- package/packages/tui/lib/term/through.mjs +174 -27
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +143 -21
- package/packages/tui/lib/views/instances.mjs +59 -20
- 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/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
|
|
67
|
-
|
|
68
|
-
|
|
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
|
|
110
|
-
terminal, or set a per-user prefix
|
|
111
|
-
`~/.local/bin` on
|
|
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
|
|
222
|
-
|
|
223
|
-
|
|
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
|
|
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
|
|
250
|
-
`acme`, in the repository `acme/acme-oats`,
|
|
251
|
-
|
|
252
|
-
|
|
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.
|
|
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
|
|
269
|
-
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref
|
|
270
|
-
for example `oats-framework/v1.13.
|
|
271
|
-
|
|
272
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
321
|
-
|
|
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,
|
|
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. **
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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
|
|
499
|
-
`oats-
|
|
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.
|