@awebai/oats 0.68.0 → 0.69.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/bin/oats.mjs +102 -22
- package/docs/capabilities.md +49 -5
- package/docs/configuration.md +68 -2
- package/docs/desktop-cli-api.md +355 -12
- package/docs/desktop-instance-start.md +88 -3
- package/docs/desktop.md +147 -13
- package/docs/execution-targets.md +514 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +28 -11
- package/docs/integrations.md +1 -1
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/servers.md +44 -5
- package/docs/souls-and-instances.md +11 -7
- package/docs/tui.md +114 -31
- package/docs/upgrading.md +14 -5
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +345 -89
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +117 -23
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +32 -0
- package/lib/session-resume.mjs +310 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +2 -1
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +38 -4
- package/package-catalog.json +10 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -0
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +7 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/README.md +1 -1
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/main.mjs +5 -3
- package/packages/tui/lib/model.mjs +57 -15
- package/packages/tui/lib/store.mjs +8 -7
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +72 -7
- package/packages/tui/lib/views/help.mjs +9 -4
- package/packages/tui/lib/views/instances.mjs +46 -29
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/skills/oats-getting-started/SKILL.md +117 -4
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# OATS 0.69.1
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
0.69.0 was tagged but never published: its release run failed on a macOS-only
|
|
6
|
+
test before anything was released. 0.69.1 is the first 0.69 release, and it
|
|
7
|
+
carries everything in [0.69.0's notes](v0.69.0.md): session resume, the agent's
|
|
8
|
+
pane in a split window, the scroll keys, the waiting row, oats.aweb 1.32.0,
|
|
9
|
+
oats.engineering 1.15.0 and oats.framework 1.15.1.
|
|
10
|
+
|
|
11
|
+
## Upgrade
|
|
12
|
+
|
|
13
|
+
- **Follow [0.69.0's Upgrade section](v0.69.0.md#upgrade)**: install the
|
|
14
|
+
Desktop first and the CLI second (a 0.68 Desktop refuses a 0.69 CLI). The
|
|
15
|
+
0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`. Every host that shares
|
|
16
|
+
a workspace runs OATS 0.68.0 or later before any of them syncs to
|
|
17
|
+
oats.aweb 1.32.0. Then run `oats status` once before you restart, so the
|
|
18
|
+
session resume sweep knows what was running.
|
|
19
|
+
|
|
20
|
+
## Fixed
|
|
21
|
+
|
|
22
|
+
- **The Desktop's tests pass on macOS.** A test of the session resume
|
|
23
|
+
runner compared a working directory without resolving macOS's `/var` →
|
|
24
|
+
`/private/var` link, which failed both macOS Desktop builds of 0.69.0
|
|
25
|
+
(#1590). No behaviour changes.
|
package/docs/servers.md
CHANGED
|
@@ -71,7 +71,7 @@ which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
|
|
|
71
71
|
## Connect a machine
|
|
72
72
|
|
|
73
73
|
```bash
|
|
74
|
-
oats server connect altair-aweb --ssh altair --dir '~/acme' --
|
|
74
|
+
oats server connect altair-aweb --ssh altair --dir '~/acme' --install-oats
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
Run from a deployment, `server connect` puts that deployment's workspace on
|
|
@@ -83,7 +83,7 @@ missing, so after a human step you run the same command again.
|
|
|
83
83
|
|---|---|
|
|
84
84
|
| `--dir <path>` | none, inside a deployment too: the folder on the host for this deployment, absolute or `~/…` (resolved by the host). Without it: `E_BAD_ARGS` "--dir <path on the host> is required: the folder on `<host>` for this deployment (absolute, or ~/… resolved there)". A registration made before it was required is unchanged |
|
|
85
85
|
| `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
|
|
86
|
-
| `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses |
|
|
86
|
+
| `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses. Without it, connect uses the PATH of the host user's [login shell](#the-hosts-login-shell-path) |
|
|
87
87
|
| `--install-oats` | off: a missing or older OATS is a human step |
|
|
88
88
|
| `--replace` | off: an id registered for another host or directory is refused |
|
|
89
89
|
|
|
@@ -91,8 +91,8 @@ The steps, in order:
|
|
|
91
91
|
|
|
92
92
|
| Step | Checks | When something is missing |
|
|
93
93
|
|---|---|---|
|
|
94
|
-
| `ssh` | the host answers a non-interactive ssh | `failed` `E_SSH` |
|
|
95
|
-
| `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it
|
|
94
|
+
| `ssh` | the host answers a non-interactive ssh; without `--path`, the PATH of the host user's [login shell](#the-hosts-login-shell-path) is read (its `detail` says whether) | `failed` `E_SSH` |
|
|
95
|
+
| `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it: `needs-human` with the command to run. With no `npm` on the PATH it searched (named in `detail`): `needs-human` to install Node.js there, with a command that checks the login shell finds `npm`, then check again |
|
|
96
96
|
| `git` | the host's Git reads the workspace remote | `needs-human` with the remedy (and the [keychain hint](#git-on-a-macos-host)) |
|
|
97
97
|
| `deployment` | `--dir` holds a deployment of this workspace | an absent or empty directory is onboarded there (`done`); a deployment of another workspace is `failed` `E_SERVER_WORKSPACE_MISMATCH`; a non-empty directory without `oats-local.yaml` is `failed` `E_DIR_NOT_EMPTY` and nothing is written into it |
|
|
98
98
|
| `register` | the registration exists, with its `workspaceKey` | written (`done`); an id registered for another target is `failed` `E_SERVER_EXISTS` unless `--replace` (checked before anything else, so a requested id never reports ready while it routes elsewhere); a new id whose host and directory are already registered under another id is reported (`ok`, naming that id; the text result then names that id to spawn with) and not registered twice |
|
|
@@ -105,6 +105,37 @@ human. Connect never handles credentials: what Git on the host cannot read
|
|
|
105
105
|
is always a human step there. The `--json` shape is in
|
|
106
106
|
[desktop-cli-api.md](desktop-cli-api.md#oats-server-connect).
|
|
107
107
|
|
|
108
|
+
### The host's login-shell PATH
|
|
109
|
+
|
|
110
|
+
A non-interactive ssh command does not read the user's login files, so on a
|
|
111
|
+
host whose PATH comes from `~/.zprofile`, `~/.bash_profile` or `~/.profile`
|
|
112
|
+
(a Homebrew or version-manager directory, say) it finds neither `npm` nor
|
|
113
|
+
`oats`. Without `--path`, connect therefore asks the host user's own login
|
|
114
|
+
shell for its PATH once, in the `ssh` step, by the rules OATS uses for the
|
|
115
|
+
local login environment ([execution-targets.md](execution-targets.md)):
|
|
116
|
+
|
|
117
|
+
- The shell is the host's `$SHELL`, which sshd sets from the host's password
|
|
118
|
+
database. Only bash, zsh or fish at an absolute path is run; it runs
|
|
119
|
+
`-l -i -c` (login and interactive, so both its profile and its rc files are
|
|
120
|
+
read) and prints its PATH between two delimiters that carry a random nonce,
|
|
121
|
+
within 15 s and 1 MiB.
|
|
122
|
+
- The PATH's absolute directories (each once, in order) become the
|
|
123
|
+
registration's `path`, the field `--path` sets, so every later step and
|
|
124
|
+
every later `--server` command runs with them. `oats` found on that PATH is
|
|
125
|
+
recorded as `oatsPath` by its absolute path.
|
|
126
|
+
- Another shell, no answer in time, or an answer that is not one PATH: the
|
|
127
|
+
`ssh` step stays `ok`, its `detail` says why the PATH could not be read, and
|
|
128
|
+
connect goes on with ssh's own PATH.
|
|
129
|
+
- An explicit `--path` always wins: the login shell is not asked. An explicit
|
|
130
|
+
`--oats` is kept as given.
|
|
131
|
+
- A registration of the same host and directory made before keeps the `path`
|
|
132
|
+
and `oatsPath` it has; connect only fills in the ones it lacks (`register`
|
|
133
|
+
`done`, "recorded …"), and `--replace` rewrites them with what it found.
|
|
134
|
+
- The recorded `path` and `oatsPath` are a snapshot of the login shell at
|
|
135
|
+
connect time. On a host whose Node comes from a version manager (nvm,
|
|
136
|
+
asdf), a later Node upgrade can leave `oatsPath` pointing at a directory
|
|
137
|
+
that is gone; `oats server connect … --replace` reads them again.
|
|
138
|
+
|
|
108
139
|
### What connect runs on the host
|
|
109
140
|
|
|
110
141
|
Besides `version --json`, `status --json`, `souls --json` and `readiness
|
|
@@ -238,7 +269,7 @@ sent as text or on stdin, never as paths.
|
|
|
238
269
|
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply |
|
|
239
270
|
| `status` | registered workspace | |
|
|
240
271
|
| `retire` | the instance's home | `retire-home` to retire by exact home |
|
|
241
|
-
| `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
|
|
272
|
+
| `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
|
|
242
273
|
| `session start`, `session restart` | the instance's home | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
|
|
243
274
|
| `session upload` | the instance's home | `session-upload` |
|
|
244
275
|
| `okf harvest --instance <name>` | the saved home | `harvest` |
|
|
@@ -331,6 +362,11 @@ nothing was sent`. Under `--json` the envelope's `error.details` is
|
|
|
331
362
|
under `--print`, which otherwise skips it: a printed command must not carry
|
|
332
363
|
a flag its host would ignore.
|
|
333
364
|
|
|
365
|
+
`--no-status-line` travels as it is, with no probe of its own: a host that
|
|
366
|
+
does not advertise `session-attach-no-status-line` ignores it and shows the
|
|
367
|
+
viewer's status line, which loses nothing
|
|
368
|
+
([execution-targets.md](execution-targets.md#inspect-input-and-attach)).
|
|
369
|
+
|
|
334
370
|
**Not routed.** `session input` runs on the execution host, where schedules
|
|
335
371
|
and messaging capabilities call it. `session restart --stop-grace` is refused
|
|
336
372
|
with `--server`; the remote default applies. `session attach --print` shows
|
|
@@ -389,6 +425,9 @@ answer, never a separate `version --json`, kept only when it is a valid list
|
|
|
389
425
|
of feature names and otherwise `null` (unknown, as from a host before
|
|
390
426
|
0.49.0); a failed probe has no `features` key
|
|
391
427
|
([the field](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
|
|
428
|
+
It relays the host's viewer fact the same way, `probe.sessionViewer`
|
|
429
|
+
(`{prefixScroll}`, feature `session-attach-prefix-scroll`): whether that
|
|
430
|
+
host's viewer takes `C-b [`, or `null` when unknown.
|
|
392
431
|
|
|
393
432
|
**Harvest** runs the knowledge capability's `okf harvest --json` in the
|
|
394
433
|
instance's saved home on the server and relays its envelope.
|
|
@@ -982,8 +982,10 @@ A worktree that cannot be proven unchanged is copied without the read, so
|
|
|
982
982
|
there the refusal comes from the copy, as `E_WORK_PRESERVATION_FAILED`.
|
|
983
983
|
|
|
984
984
|
**A file in the worktree that cannot be read.** The same read refuses a file
|
|
985
|
-
it cannot read: one without read permission, or one
|
|
986
|
-
|
|
985
|
+
it cannot read: one without read permission, or one that ends before the
|
|
986
|
+
size it had when it was opened, because it shrank while it was read. A
|
|
987
|
+
file of any size is read in pieces of 1 MiB, so a file over 2 GiB is read
|
|
988
|
+
like any other. Two kinds of file are read although they are nothing
|
|
987
989
|
to preserve: a tracked file that is unchanged, and a file under a work root
|
|
988
990
|
that a capability declared disposable (`retirement.disposable.work`). So a
|
|
989
991
|
retire that has only the home to preserve refuses for such a file, with
|
|
@@ -992,10 +994,9 @@ retire that has only the home to preserve refuses for such a file, with
|
|
|
992
994
|
or a FIFO refused before the hooks, the retire has already stopped the
|
|
993
995
|
session of a launched instance by then, the instance is not retired, and its
|
|
994
996
|
home is kept. The message is `could not read the worktree at <work>:
|
|
995
|
-
<reason>`.
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
or make it readable, then run `oats retire <instance>` again. With nothing to
|
|
997
|
+
<reason>`. The reason names the file. To continue, make the file readable,
|
|
998
|
+
move it out of the worktree, or stop what writes to it, then run
|
|
999
|
+
`oats retire <instance>` again. With nothing to
|
|
999
1000
|
preserve, the files are not read and the retire goes through.
|
|
1000
1001
|
|
|
1001
1002
|
**A home whose `instance.json` cannot be read.** The record is what
|
|
@@ -1053,7 +1054,10 @@ of the whole home.
|
|
|
1053
1054
|
untracked and ignored files, have anything to preserve is decided against
|
|
1054
1055
|
two digests the spawn baseline stores: one of the home (without `work/`, the
|
|
1055
1056
|
provider-owned entries declared at spawn, the kernel's records above, and
|
|
1056
|
-
the fields the kernel writes into `instance.json` after spawn
|
|
1057
|
+
the fields the kernel writes into `instance.json` after spawn, for an
|
|
1058
|
+
`instance.json` of at most 16 MiB: a larger one is taken as its bytes, so a
|
|
1059
|
+
baseline that took it without those fields reads the home as changed and
|
|
1060
|
+
the retire copies the home to the recovery), and one of
|
|
1057
1061
|
the worktree's untracked and ignored paths outside the roots a capability
|
|
1058
1062
|
declared disposable. A spawn by 0.49.0 or later records `digestVersion: 2`
|
|
1059
1063
|
in the baseline, and its digests order entries by the bytes of their names,
|
package/docs/tui.md
CHANGED
|
@@ -98,10 +98,10 @@ runs.
|
|
|
98
98
|
acme-platform │ dev
|
|
99
99
|
│ soul dev
|
|
100
100
|
Instances 1 │ state running
|
|
101
|
-
> ●
|
|
101
|
+
> ● Dev │ harness claude, claude-opus-5-5 (so…
|
|
102
102
|
│ work worktree, agents/dev
|
|
103
|
-
|
|
104
|
-
○
|
|
103
|
+
! Reviewer │ team eng
|
|
104
|
+
○ Helper │ started 11:00
|
|
105
105
|
──────────────────────────────────────│ home …oy/agents/dev/instances/dev
|
|
106
106
|
Souls 2 │
|
|
107
107
|
Capabilities 3 │
|
|
@@ -132,7 +132,7 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
132
132
|
`since …` and its reason on rows of its own; the note of a view of one
|
|
133
133
|
deployment; and the line that says what happened after an open, an act or
|
|
134
134
|
a spawn. Then an empty row. A line that goes at the next key and fits one
|
|
135
|
-
row (`No workspace
|
|
135
|
+
row (`No other workspace to show.`) stands in that empty row instead, so
|
|
136
136
|
nothing under it moves.
|
|
137
137
|
- **The views** follow as an accordion, always in this order: `Instances`,
|
|
138
138
|
`Souls`, `Capabilities`, each with its key dim at the right edge. The open
|
|
@@ -183,21 +183,32 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
183
183
|
indent alone says which instance is under which: no mark is drawn for
|
|
184
184
|
it. A row whose instances are folded away (`h`) says how many after its
|
|
185
185
|
name: `+1`.
|
|
186
|
-
- **Each row** is the mark of its state and the name
|
|
187
|
-
input
|
|
186
|
+
- **Each row** is the mark of its state and the name. A row that needs
|
|
187
|
+
input has the needs-input mark in place of its state mark: `!`, bold,
|
|
188
|
+
in reverse video in the waiting colour, a yellow cell with the `!` cut
|
|
189
|
+
out (the Desktop's mark in one cell), whatever the row's state and its
|
|
190
|
+
instance colour. On the selected row, which is in reverse video already,
|
|
191
|
+
it is the waiting colour not reversed, a gap in the selection's bar;
|
|
192
|
+
under `NO_COLOR` the reverse video and the `!` carry it, and in ASCII it
|
|
193
|
+
is the same `!`. The detail says it in words (its `needs` line, the
|
|
194
|
+
reason and how long it has waited), and so does the help. The row shows the name as words, as the Desktop's sidebar does: each `-`
|
|
195
|
+
a space and the first letter upper-case, so `oats-expert-lead` reads
|
|
196
|
+
`Oats expert lead`. Only the row does: the detail, the filter (`/` with
|
|
197
|
+
`oats-expert` still finds the row), the palette, the tabs, the
|
|
198
|
+
confirmations and everything sent to OATS keep the instance's name. A
|
|
188
199
|
folded row with waiting instances among those it folds away says how
|
|
189
|
-
many
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
video in the waiting colour, and on the
|
|
193
|
-
|
|
200
|
+
many in a tag at its right edge, in the Desktop's words: `3 below`, and
|
|
201
|
+
`99+ below` past 99, whether or not the row needs input itself: its mark
|
|
202
|
+
says its own claim, the tag the rest, and the detail's `below` line names
|
|
203
|
+
them. The tag is in reverse video in the waiting colour, and on the
|
|
204
|
+
selected row it is the waiting colour not reversed, a gap in the
|
|
194
205
|
selection's bar; under `NO_COLOR` the reverse video alone carries it. On
|
|
195
206
|
a narrow row the tag gives way first: it says its words only where the
|
|
196
207
|
whole name, its `+1` and the row's word in its column all fit beside them,
|
|
197
|
-
and else shrinks to
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
208
|
+
and else shrinks to the count alone (`3`, `99+`), still in reverse video,
|
|
209
|
+
in the cells every row keeps at its right edge. So the tag never cuts a
|
|
210
|
+
name, a word or a mark: those give way as on a row whose instances do
|
|
211
|
+
not wait. The harness and the state in words are in
|
|
201
212
|
the detail. A row has a word, dim, only where its mark cannot say it: the
|
|
202
213
|
state of a home a spawn or a retire holds (`Retire didn't finish`), or
|
|
203
214
|
the shared words for why an instance cannot be reached or opened:
|
|
@@ -291,20 +302,23 @@ in its workspace for the rest of the run, also while it is not reached.
|
|
|
291
302
|
| `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
|
|
292
303
|
| `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
|
|
293
304
|
| `+n` | `+n` | after a name: n instances folded away below it |
|
|
294
|
-
|
|
|
295
|
-
| `N below` | `N below` | N instances folded away below it need input, `N` where the whole name does not fit beside the words |
|
|
305
|
+
| `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row); with its terminal shown, the [waiting row](#tabs) under the tab bar says what it waits on |
|
|
306
|
+
| `N below` | `N below` | N instances folded away below it need input: a tag in reverse video at the row's right edge, `N` where the whole name does not fit beside the words |
|
|
296
307
|
| `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
|
|
297
308
|
| `*` | `*` | in the switcher: the workspace that is open |
|
|
298
309
|
|
|
299
|
-
Every state has a mark of its own shape, so
|
|
310
|
+
Every state has a mark of its own shape, and so does needs input, so
|
|
311
|
+
nothing is told by colour alone.
|
|
300
312
|
|
|
301
313
|
**An instance's colour** (feature `instance-color`; set with
|
|
302
314
|
`oats instance color <instance> <colour>`, [desktop-cli-api.md](desktop-cli-api.md#an-instances-colour-oats-instance-color))
|
|
303
315
|
colours its mark, in the list and in a soul's detail: a running mark in it, a
|
|
304
316
|
stopped one and one with a shell left in it dim in it. `?` and `◆` keep their
|
|
305
317
|
own look whatever the colour, and an instance with no colour looks as above.
|
|
306
|
-
The six colours are the terminal's: `sand`
|
|
307
|
-
`mauve` magenta, `clay` red, `olive` cyan, the souls' own
|
|
318
|
+
The six colours are the terminal's: `sand` its own foreground colour, `sage`
|
|
319
|
+
green, `slate` blue, `mauve` magenta, `clay` red, `olive` cyan, the souls' own
|
|
320
|
+
map. `sand` is not yellow, which says needs input and nothing else, and in the
|
|
321
|
+
foreground colour it is seen on a light theme as on a dark one. Which colour a
|
|
308
322
|
row shows is the Desktop's rule (`instanceColor` in `packages/client`); an
|
|
309
323
|
older kernel reports none. Setting a colour from the TUI is not in this
|
|
310
324
|
version.
|
|
@@ -459,9 +473,39 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
459
473
|
reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
|
|
460
474
|
can be opened (`Esc` gives that up); a machine whose OATS cannot open its
|
|
461
475
|
sessions is said then.
|
|
462
|
-
- **
|
|
463
|
-
|
|
464
|
-
|
|
476
|
+
- **The viewer's scroll keys, and no mouse.** The panel shows what the
|
|
477
|
+
agent's window shows now. What has scrolled away is reached through the
|
|
478
|
+
viewer's own keys, as in `oats session attach`: `Shift+PageUp`, or
|
|
479
|
+
`Ctrl+B` then `[`, put it in tmux's copy mode. Then `PageUp`, `PageDown`,
|
|
480
|
+
the arrows, `Ctrl+U` and `Ctrl+D` move, and `q` or `Esc` leaves. The TUI
|
|
481
|
+
adds no key of its own: they reach the viewer as a terminal without the
|
|
482
|
+
kitty keyboard protocol sends them (re-encoded under it), and the viewer
|
|
483
|
+
shows no status line of its own (`--no-status-line`, where the kernel has
|
|
484
|
+
it).
|
|
485
|
+
- **The cheat sheet names them** while a terminal has the focus, and so
|
|
486
|
+
does a zoomed terminal's title row where it has room: `Shift+PageUp or
|
|
487
|
+
Ctrl+B [`, then `scroll back`. Where the row holds one key, `Ctrl+B [`.
|
|
488
|
+
The title row gives them up first: in the Alt family, whose chords lead
|
|
489
|
+
that row, a zoomed terminal 120 columns wide or less does not name
|
|
490
|
+
them. The help does.
|
|
491
|
+
- **As the tab's host says.** Each tab runs its host's viewer, so the
|
|
492
|
+
keys named are the ones that host's kernel says its viewer takes: this
|
|
493
|
+
machine's `oats version --json` for a tab of this machine, the roster's
|
|
494
|
+
probe of its server for another's
|
|
495
|
+
([`session-attach-prefix-scroll`](desktop-cli-api.md#features)).
|
|
496
|
+
`Shift+PageUp` where the host's kernel lists the feature, and
|
|
497
|
+
`Ctrl+B [` too where its `sessionViewer.prefixScroll` is true (a tmux of
|
|
498
|
+
3.3 or later, see
|
|
499
|
+
[Inspect, input and attach](execution-targets.md#inspect-input-and-attach)).
|
|
500
|
+
A host whose kernel does not list it, or one the roster did not reach,
|
|
501
|
+
gets no scroll keys named at all: an older viewer may hand
|
|
502
|
+
`Shift+PageUp` to the agent.
|
|
503
|
+
- **A leader of `Ctrl+B`** (`open.detachKey: "C-b"` in
|
|
504
|
+
[`tui.json`](#change-the-keys-tuijson)) takes `Ctrl+B` before the
|
|
505
|
+
viewer reads it, so `Ctrl+B [` cannot be typed there. The sheet and the
|
|
506
|
+
help name `Shift+PageUp` alone.
|
|
507
|
+
- Copy mode is the agent's pane's: while a tab is scrolled back, every
|
|
508
|
+
other viewer of that agent shows the same frozen screen.
|
|
465
509
|
- **How it works.** The terminal is the kernel's own viewer,
|
|
466
510
|
`oats session attach`, run in a pane of a tmux server private to this run
|
|
467
511
|
of `oats tui`: its socket is in a directory of the run's own (mode 0700,
|
|
@@ -537,6 +581,37 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
537
581
|
of the row with their dividers (they stay open). The shown tab's name
|
|
538
582
|
stays whole while the row can hold it, and is cut last.
|
|
539
583
|
- The TUI takes no mouse input: a tab is shown with the keys below.
|
|
584
|
+
- **The waiting row.** While the shown tab's agent waits on you (a live
|
|
585
|
+
`waitingOnYou` claim, as the list's `!` mark shows it), a row
|
|
586
|
+
stands under its group's tab bar, and the agent's screen starts under it:
|
|
587
|
+
|
|
588
|
+
```
|
|
589
|
+
│[steward 1]│ backend-lead 2
|
|
590
|
+
│ Needs input · 12 min Survey done: yes/no on bumping Claude Code
|
|
591
|
+
│ 2.1.309 + Codex 0.164.0 and removing their old mise installs
|
|
592
|
+
│>
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
- It reads `Needs input` in the list's needs-input look (reverse video in
|
|
596
|
+
the waiting colour), then how long the agent has waited, dim, after ` · `
|
|
597
|
+
(` - ` in ASCII), then the claim's message, the agent's own text. The
|
|
598
|
+
age comes first, so a cut never removes it.
|
|
599
|
+
- **A claim with no message** says what it waits on in the TUI's words:
|
|
600
|
+
`waiting on a permission prompt`, `asked you a question`,
|
|
601
|
+
`asked for your attention`, or `waiting for your input` when the
|
|
602
|
+
reason is not one of those.
|
|
603
|
+
- **A long message wraps** to at most 3 rows, and to no more than a
|
|
604
|
+
quarter of the group's height; when more is left, the last row ends in
|
|
605
|
+
`…` (`...` in ASCII). The whole message is in the agent's
|
|
606
|
+
[detail](#what-it-shows), and in `oats status`.
|
|
607
|
+
- **The agent's screen loses those rows** while the row stands, so its
|
|
608
|
+
pane is resized when the claim starts, clears or its text changes, and
|
|
609
|
+
never as the age grows: the rows are counted as if the age were its
|
|
610
|
+
longest, `under a minute`.
|
|
611
|
+
- In a [split](#splits) each group has its own row for its own shown tab.
|
|
612
|
+
A hidden tab's claim adds no row: the list's `!` mark shows it.
|
|
613
|
+
- Under `NO_COLOR` the words carry it: `Needs input` stays in reverse
|
|
614
|
+
video.
|
|
540
615
|
- **Opening.** `Enter` on a row, an instance in
|
|
541
616
|
[the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
|
|
542
617
|
[spawn](#spawning-an-agent)'s new agent open a terminal the same way:
|
|
@@ -918,10 +993,12 @@ workspace the list is its row.
|
|
|
918
993
|
- **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
|
|
919
994
|
`Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
|
|
920
995
|
families leave them to the programs, and the leader does it), opens the
|
|
921
|
-
workspace before or after the open one, as the list draws them. It
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
to
|
|
996
|
+
workspace before or after the open one, as the list draws them. It wraps,
|
|
997
|
+
as the [OATS Desktop](desktop.md#workspaces)'s do: `Down` on the last row
|
|
998
|
+
opens the first, and `Up` on the first opens the last. With no other row
|
|
999
|
+
to open, nothing moves, and the line under the list says `No other
|
|
1000
|
+
workspace to show.` until the next key, of any kind (one typed to an agent
|
|
1001
|
+
too), or a resize. The line stands in the empty row under the
|
|
925
1002
|
list, so the list of instances does not move while it shows; only when
|
|
926
1003
|
that list fills the sidebar, which then has no such row, does the line
|
|
927
1004
|
take a row, the list giving up its last. With the list's focus (`w`) the
|
|
@@ -941,7 +1018,8 @@ workspace the list is its row.
|
|
|
941
1018
|
workspace's name is underlined until `Enter` opens another; the list of
|
|
942
1019
|
instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
|
|
943
1020
|
`Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
|
|
944
|
-
open
|
|
1021
|
+
open, and stop at the list's ends (they do not wrap, as the Desktop
|
|
1022
|
+
list's own do not); `Enter` opens its row and gives the list of instances the focus;
|
|
945
1023
|
`Esc` gives that focus back with nothing opened; `w` again opens the
|
|
946
1024
|
switcher, for what the list does not hold. Any other key gives the list
|
|
947
1025
|
of instances the focus, then does what it does there. The cheat sheet
|
|
@@ -1605,7 +1683,7 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
|
|
|
1605
1683
|
|---|---|
|
|
1606
1684
|
| `k` or `Space` | opens [the palette](#the-palette) |
|
|
1607
1685
|
| `1`, `2`, `3` | the Instances, Souls and Capabilities views |
|
|
1608
|
-
| `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the
|
|
1686
|
+
| `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the moves wrap: past the last row, the first, and before the first, the last. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
|
|
1609
1687
|
| `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
|
|
1610
1688
|
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
|
|
1611
1689
|
| `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
@@ -2442,7 +2520,8 @@ version:
|
|
|
2442
2520
|
- The Souls and Capabilities views list a workspace of this machine's
|
|
2443
2521
|
souls and capabilities: both are this machine's.
|
|
2444
2522
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
2445
|
-
folded. An open terminal
|
|
2523
|
+
folded. An open terminal scrolls back with the viewer's own keys,
|
|
2524
|
+
`Shift+PageUp` and `Ctrl+B [`, and no other.
|
|
2446
2525
|
- Up to four terminals are open at a time, as tabs, in at most two
|
|
2447
2526
|
groups. The split cannot be resized or nested, a tab moves only between
|
|
2448
2527
|
the two groups, and no tab or split is kept from one run to the next, or
|
|
@@ -2546,7 +2625,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
2546
2625
|
included) and attributes: those are the agent's. With `NO_COLOR` set and
|
|
2547
2626
|
not empty it uses no colour at all, the agent's included; the agent's
|
|
2548
2627
|
bold, underline, reverse and the like stay. Nothing is told by colour
|
|
2549
|
-
alone.
|
|
2628
|
+
alone. **Yellow says needs input, and only that:** the `!` in place of a
|
|
2629
|
+
row's state mark and the dot in the list of workspaces. A state unknown,
|
|
2630
|
+
`?`, is dim in your terminal's foreground, and a warning (a failed read,
|
|
2631
|
+
`Can't spawn here`, `· 1 on an older version`) is bold red, and a soul's
|
|
2632
|
+
`sand` is in your terminal's foreground ([What it shows](#what-it-shows)).
|
|
2550
2633
|
- It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
|
|
2551
2634
|
`LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
|
|
2552
2635
|
no emoji. When the locale is not UTF-8, a character outside ASCII in text
|
package/docs/upgrading.md
CHANGED
|
@@ -6,11 +6,11 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.
|
|
10
|
-
The 0.
|
|
9
|
+
The latest version is **OATS 0.69.1** ([release notes](release-notes/v0.69.1.md)).
|
|
10
|
+
The 0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
|
|
11
11
|
|
|
12
12
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
13
|
-
0.
|
|
13
|
+
0.69.1,** in the [release notes](release-notes/): it says what to do before
|
|
14
14
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
15
15
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
16
16
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -19,8 +19,8 @@ prints the version you have.
|
|
|
19
19
|
Then, on each host:
|
|
20
20
|
|
|
21
21
|
```sh
|
|
22
|
-
# 0. where the Desktop is installed: Desktop 0.
|
|
23
|
-
npm install -g @awebai/oats@0.
|
|
22
|
+
# 0. where the Desktop is installed: Desktop 0.69.1 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.1 # 1. the CLI
|
|
24
24
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
25
25
|
oats doctor # 3. in the same deployment
|
|
26
26
|
```
|
|
@@ -166,6 +166,15 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
166
166
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
167
167
|
here.
|
|
168
168
|
|
|
169
|
+
- **[0.69.1](release-notes/v0.69.1.md#upgrade):** 0.69.0 was tagged but never
|
|
170
|
+
published; 0.69.1 carries all of it, so follow
|
|
171
|
+
[0.69.0's Upgrade section](release-notes/v0.69.0.md#upgrade): the Desktop
|
|
172
|
+
first, then the CLI: a 0.68 Desktop refuses a 0.69 CLI. Every host that shares a workspace
|
|
173
|
+
runs OATS 0.68.0 or later before any of them syncs to oats.aweb 1.32.0.
|
|
174
|
+
- **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the
|
|
175
|
+
CLI: a 0.67 Desktop refuses a 0.68 CLI. The catalog pins new package versions; after `oats sync`, a stopped
|
|
176
|
+
home can move to them with `oats instance upgrade` instead of a respawn
|
|
177
|
+
([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
|
|
169
178
|
- **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
|
|
170
179
|
0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
|
|
171
180
|
platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.15.1 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.3.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|