@awebai/oats 0.68.1 → 0.69.2
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 +180 -36
- package/docs/capabilities.md +73 -10
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/configuration.md +68 -2
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +600 -25
- package/docs/desktop-instance-start.md +59 -3
- package/docs/desktop.md +175 -10
- package/docs/execution-targets.md +536 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +33 -15
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +25 -16
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +51 -7
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +46 -9
- package/docs/tui.md +177 -21
- package/docs/upgrading.md +16 -7
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +496 -127
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- 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/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +136 -27
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +33 -0
- package/lib/session-resume.mjs +337 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +15 -11
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +41 -6
- package/package-catalog.json +11 -5
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +39 -8
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +16 -0
- package/packages/client/deployment-panel.mjs +7 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -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/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -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 +2 -2
- package/packages/tui/lib/client.mjs +7 -3
- package/packages/tui/lib/main.mjs +49 -14
- package/packages/tui/lib/model.mjs +146 -55
- package/packages/tui/lib/store.mjs +84 -27
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/frame.mjs +74 -7
- package/packages/tui/lib/views/help.mjs +10 -3
- package/packages/tui/lib/views/instances.mjs +41 -3
- package/skills/oats-getting-started/SKILL.md +117 -4
package/docs/tui.md
CHANGED
|
@@ -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
|
|
@@ -178,7 +178,10 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
178
178
|
order, from the same code. It is in name order, by each group's top
|
|
179
179
|
instance, so starting or stopping an instance moves nothing. An instance
|
|
180
180
|
that others were spawned from has them indented under it, and keeps its
|
|
181
|
-
place when it gains or loses one.
|
|
181
|
+
place when it gains or loses one. Under one parent, the instances that do
|
|
182
|
+
its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
|
|
183
|
+
come first, then the others, each part in name order, as the Desktop lists
|
|
184
|
+
them. An empty row stands between each run
|
|
182
185
|
of instances related to no other and the group before or after it. The
|
|
183
186
|
indent alone says which instance is under which: no mark is drawn for
|
|
184
187
|
it. A row whose instances are folded away (`h`) says how many after its
|
|
@@ -237,6 +240,27 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
237
240
|
own deployment, and a name that is no instance there, or two of them, is
|
|
238
241
|
not shown. From 80 columns up it stands beside the sidebar; on a narrower
|
|
239
242
|
terminal `Tab` opens it as a page over the whole screen.
|
|
243
|
+
- **Background instances** ([#1579](https://github.com/awebai/oats/issues/1579))
|
|
244
|
+
are listed apart, as in the Desktop's sidebar. An instance whose
|
|
245
|
+
`background` is on (`oats instance background`, or its soul's default at
|
|
246
|
+
spawn) leaves the list, and so do the instances below it, whatever their
|
|
247
|
+
own setting. They stand under one heading at the very end of the list:
|
|
248
|
+
`▸ Background 3` (`>` in ASCII), the word in bold and the count dim. The
|
|
249
|
+
heading starts closed in every run, and stays as you leave it for each
|
|
250
|
+
workspace while the TUI runs. It can be selected: `Enter` or `Space`
|
|
251
|
+
opens or closes it, `Right` opens it (on an open one, goes to its first
|
|
252
|
+
row) and `Left` closes it. Open (`▾`), its rows form their own tree, with
|
|
253
|
+
the deployments' headings in a view of two or more; a background instance
|
|
254
|
+
whose parent is in the list above is a top row there. While one of its
|
|
255
|
+
instances needs input, open or closed, the heading carries `Needs input`
|
|
256
|
+
at its right edge in the roll-up's look (only the `!` on a narrow row),
|
|
257
|
+
and the help's count of instances that need input counts it. A filter
|
|
258
|
+
shows the matching background rows with the section open, without
|
|
259
|
+
changing whether it is kept open, and the heading then counts the
|
|
260
|
+
matches. The movement keys pass over the rows of a closed section, and
|
|
261
|
+
showing a background instance's terminal from the palette leaves the
|
|
262
|
+
section as it was. The palette lists every instance. Without OATS's
|
|
263
|
+
`instance-background` feature every instance stays in the list.
|
|
240
264
|
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
241
265
|
beside the sidebar, where the detail was, as a tab: see
|
|
242
266
|
[Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
|
|
@@ -302,7 +326,7 @@ in its workspace for the rest of the run, also while it is not reached.
|
|
|
302
326
|
| `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
|
|
303
327
|
| `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
|
|
304
328
|
| `+n` | `+n` | after a name: n instances folded away below it |
|
|
305
|
-
| `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row) |
|
|
329
|
+
| `!` | `!` | 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
330
|
| `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 |
|
|
307
331
|
| `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
|
|
308
332
|
| `*` | `*` | in the switcher: the workspace that is open |
|
|
@@ -473,9 +497,39 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
473
497
|
reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
|
|
474
498
|
can be opened (`Esc` gives that up); a machine whose OATS cannot open its
|
|
475
499
|
sessions is said then.
|
|
476
|
-
- **
|
|
477
|
-
|
|
478
|
-
|
|
500
|
+
- **The viewer's scroll keys, and no mouse.** The panel shows what the
|
|
501
|
+
agent's window shows now. What has scrolled away is reached through the
|
|
502
|
+
viewer's own keys, as in `oats session attach`: `Shift+PageUp`, or
|
|
503
|
+
`Ctrl+B` then `[`, put it in tmux's copy mode. Then `PageUp`, `PageDown`,
|
|
504
|
+
the arrows, `Ctrl+U` and `Ctrl+D` move, and `q` or `Esc` leaves. The TUI
|
|
505
|
+
adds no key of its own: they reach the viewer as a terminal without the
|
|
506
|
+
kitty keyboard protocol sends them (re-encoded under it), and the viewer
|
|
507
|
+
shows no status line of its own (`--no-status-line`, where the kernel has
|
|
508
|
+
it).
|
|
509
|
+
- **The cheat sheet names them** while a terminal has the focus, and so
|
|
510
|
+
does a zoomed terminal's title row where it has room: `Shift+PageUp or
|
|
511
|
+
Ctrl+B [`, then `scroll back`. Where the row holds one key, `Ctrl+B [`.
|
|
512
|
+
The title row gives them up first: in the Alt family, whose chords lead
|
|
513
|
+
that row, a zoomed terminal 120 columns wide or less does not name
|
|
514
|
+
them. The help does.
|
|
515
|
+
- **As the tab's host says.** Each tab runs its host's viewer, so the
|
|
516
|
+
keys named are the ones that host's kernel says its viewer takes: this
|
|
517
|
+
machine's `oats version --json` for a tab of this machine, the roster's
|
|
518
|
+
probe of its server for another's
|
|
519
|
+
([`session-attach-prefix-scroll`](desktop-cli-api.md#features)).
|
|
520
|
+
`Shift+PageUp` where the host's kernel lists the feature, and
|
|
521
|
+
`Ctrl+B [` too where its `sessionViewer.prefixScroll` is true (a tmux of
|
|
522
|
+
3.3 or later, see
|
|
523
|
+
[Inspect, input and attach](execution-targets.md#inspect-input-and-attach)).
|
|
524
|
+
A host whose kernel does not list it, or one the roster did not reach,
|
|
525
|
+
gets no scroll keys named at all: an older viewer may hand
|
|
526
|
+
`Shift+PageUp` to the agent.
|
|
527
|
+
- **A leader of `Ctrl+B`** (`open.detachKey: "C-b"` in
|
|
528
|
+
[`tui.json`](#change-the-keys-tuijson)) takes `Ctrl+B` before the
|
|
529
|
+
viewer reads it, so `Ctrl+B [` cannot be typed there. The sheet and the
|
|
530
|
+
help name `Shift+PageUp` alone.
|
|
531
|
+
- Copy mode is the agent's pane's: while a tab is scrolled back, every
|
|
532
|
+
other viewer of that agent shows the same frozen screen.
|
|
479
533
|
- **How it works.** The terminal is the kernel's own viewer,
|
|
480
534
|
`oats session attach`, run in a pane of a tmux server private to this run
|
|
481
535
|
of `oats tui`: its socket is in a directory of the run's own (mode 0700,
|
|
@@ -551,6 +605,37 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
551
605
|
of the row with their dividers (they stay open). The shown tab's name
|
|
552
606
|
stays whole while the row can hold it, and is cut last.
|
|
553
607
|
- The TUI takes no mouse input: a tab is shown with the keys below.
|
|
608
|
+
- **The waiting row.** While the shown tab's agent waits on you (a live
|
|
609
|
+
`waitingOnYou` claim, as the list's `!` mark shows it), a row
|
|
610
|
+
stands under its group's tab bar, and the agent's screen starts under it:
|
|
611
|
+
|
|
612
|
+
```
|
|
613
|
+
│[steward 1]│ backend-lead 2
|
|
614
|
+
│ Needs input · 12 min Survey done: yes/no on bumping Claude Code
|
|
615
|
+
│ 2.1.309 + Codex 0.164.0 and removing their old mise installs
|
|
616
|
+
│>
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
- It reads `Needs input` in the list's needs-input look (reverse video in
|
|
620
|
+
the waiting colour), then how long the agent has waited, dim, after ` · `
|
|
621
|
+
(` - ` in ASCII), then the claim's message, the agent's own text. The
|
|
622
|
+
age comes first, so a cut never removes it.
|
|
623
|
+
- **A claim with no message** says what it waits on in the TUI's words:
|
|
624
|
+
`waiting on a permission prompt`, `asked you a question`,
|
|
625
|
+
`asked for your attention`, or `waiting for your input` when the
|
|
626
|
+
reason is not one of those.
|
|
627
|
+
- **A long message wraps** to at most 3 rows, and to no more than a
|
|
628
|
+
quarter of the group's height; when more is left, the last row ends in
|
|
629
|
+
`…` (`...` in ASCII). The whole message is in the agent's
|
|
630
|
+
[detail](#what-it-shows), and in `oats status`.
|
|
631
|
+
- **The agent's screen loses those rows** while the row stands, so its
|
|
632
|
+
pane is resized when the claim starts, clears or its text changes, and
|
|
633
|
+
never as the age grows: the rows are counted as if the age were its
|
|
634
|
+
longest, `under a minute`.
|
|
635
|
+
- In a [split](#splits) each group has its own row for its own shown tab.
|
|
636
|
+
A hidden tab's claim adds no row: the list's `!` mark shows it.
|
|
637
|
+
- Under `NO_COLOR` the words carry it: `Needs input` stays in reverse
|
|
638
|
+
video.
|
|
554
639
|
- **Opening.** `Enter` on a row, an instance in
|
|
555
640
|
[the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
|
|
556
641
|
[spawn](#spawning-an-agent)'s new agent open a terminal the same way:
|
|
@@ -932,10 +1017,12 @@ workspace the list is its row.
|
|
|
932
1017
|
- **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
|
|
933
1018
|
`Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
|
|
934
1019
|
families leave them to the programs, and the leader does it), opens the
|
|
935
|
-
workspace before or after the open one, as the list draws them. It
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
to
|
|
1020
|
+
workspace before or after the open one, as the list draws them. It wraps,
|
|
1021
|
+
as the [OATS Desktop](desktop.md#workspaces)'s do: `Down` on the last row
|
|
1022
|
+
opens the first, and `Up` on the first opens the last. With no other row
|
|
1023
|
+
to open, nothing moves, and the line under the list says `No other
|
|
1024
|
+
workspace to show.` until the next key, of any kind (one typed to an agent
|
|
1025
|
+
too), or a resize. The line stands in the empty row under the
|
|
939
1026
|
list, so the list of instances does not move while it shows; only when
|
|
940
1027
|
that list fills the sidebar, which then has no such row, does the line
|
|
941
1028
|
take a row, the list giving up its last. With the list's focus (`w`) the
|
|
@@ -955,7 +1042,8 @@ workspace the list is its row.
|
|
|
955
1042
|
workspace's name is underlined until `Enter` opens another; the list of
|
|
956
1043
|
instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
|
|
957
1044
|
`Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
|
|
958
|
-
open
|
|
1045
|
+
open, and stop at the list's ends (they do not wrap, as the Desktop
|
|
1046
|
+
list's own do not); `Enter` opens its row and gives the list of instances the focus;
|
|
959
1047
|
`Esc` gives that focus back with nothing opened; `w` again opens the
|
|
960
1048
|
switcher, for what the list does not hold. Any other key gives the list
|
|
961
1049
|
of instances the focus, then does what it does there. The cheat sheet
|
|
@@ -1208,6 +1296,63 @@ The exit status never depends on it.
|
|
|
1208
1296
|
there can leave `.oats-stop-pending.json` in the agent's home, and then
|
|
1209
1297
|
the agent can be started but not stopped while that file exists.
|
|
1210
1298
|
|
|
1299
|
+
## Resuming lost sessions
|
|
1300
|
+
|
|
1301
|
+
After a shutdown, a reboot or a crash, the instances that were running have
|
|
1302
|
+
lost their sessions. When `oats tui` opens, it asks the kernel to resume
|
|
1303
|
+
them: it runs `oats session resume --json`, and the kernel does the rest.
|
|
1304
|
+
The kernel looks at every deployment on this computer's list (local
|
|
1305
|
+
deployments only, never another machine's) and resumes each lost session as
|
|
1306
|
+
it decides. What it does to a session, when it starts one fresh from its
|
|
1307
|
+
briefing instead, and when it stops trying for one that keeps losing its
|
|
1308
|
+
session, is the kernel's rule, written beside the command. A session lost
|
|
1309
|
+
long ago is not resumed automatically; `oats session start --resume` still
|
|
1310
|
+
brings it back by hand. `oats tui` owns no session: it runs the command, and
|
|
1311
|
+
says nothing about it.
|
|
1312
|
+
|
|
1313
|
+
**When it runs.** Once the run has started, whether it started in a
|
|
1314
|
+
deployment or in [the switcher](#the-switcher): after the deployment it
|
|
1315
|
+
started in has been added to this computer's list (the sweep reads that
|
|
1316
|
+
list), and without holding up the first frame or the first read. Then
|
|
1317
|
+
again whenever a read of a deployment open in the run shows an instance of
|
|
1318
|
+
this computer whose session was lost and that is not running (another
|
|
1319
|
+
machine's instances shown in the same workspace never count). Never two at
|
|
1320
|
+
a time, and never sooner than 30 seconds after the last one began. After a
|
|
1321
|
+
sweep that a read started, every instance it was started for waits until it
|
|
1322
|
+
changes (it runs, or it is no longer lost); so does an instance any sweep
|
|
1323
|
+
could not resume, found was not lost, or left because it was lost long ago.
|
|
1324
|
+
Such an instance sets off no sweep until a later read shows it running or no
|
|
1325
|
+
longer lost, or a sweep resumes it. There
|
|
1326
|
+
is no timer and no queue: a read that comes too soon starts nothing, and the
|
|
1327
|
+
next read asks again. The rule is the shared client's
|
|
1328
|
+
(`packages/client/session-resume-trigger.mjs`). It runs only when the kernel
|
|
1329
|
+
advertises the `session-resume` feature; without it, nothing runs.
|
|
1330
|
+
|
|
1331
|
+
**What it says.** Nothing. `oats tui` says nothing about a resume: no line
|
|
1332
|
+
when the sweep resumed an instance, started one fresh, left one waiting for
|
|
1333
|
+
you or could not resume one, none when the sweep failed or another sweep
|
|
1334
|
+
held the machine, and none after leaving. The list shows each instance as
|
|
1335
|
+
it is after the next read: after a sweep that ran, the list is read at
|
|
1336
|
+
once, so a resumed instance shows running, and one the sweep did not resume
|
|
1337
|
+
shows not running. To see what a sweep would do, run
|
|
1338
|
+
`oats session resume --plan --json`; `oats session resume` run by hand says
|
|
1339
|
+
what it did, and why it could not resume an instance.
|
|
1340
|
+
|
|
1341
|
+
**There is no setting to turn it off.** To keep an instance down, stop it
|
|
1342
|
+
with OATS (`X`, or `oats instance stop`): a stopped instance is not lost,
|
|
1343
|
+
and the sweep leaves it alone.
|
|
1344
|
+
|
|
1345
|
+
**Quitting does not stop a sweep.** It is a change, like an act you
|
|
1346
|
+
confirmed ([above](#stopping-starting-restarting-and-retiring)): it runs in
|
|
1347
|
+
a session of its own, writes its answer to files of its own, and is never
|
|
1348
|
+
signalled by `oats tui`. Quitting while it runs leaves it to finish, without
|
|
1349
|
+
a word: unlike an act, a sweep still running is not named after the screen
|
|
1350
|
+
is left.
|
|
1351
|
+
|
|
1352
|
+
`S` and `R` are unchanged: a start or restart from `oats tui` starts the
|
|
1353
|
+
instance as it was last launched, and never resumes a conversation. Only
|
|
1354
|
+
the sweep resumes.
|
|
1355
|
+
|
|
1211
1356
|
## Spawning an agent
|
|
1212
1357
|
|
|
1213
1358
|
`n` spawns an agent of a soul of the open workspace, on this machine, with
|
|
@@ -1550,8 +1695,9 @@ from every focus, an agent's terminal included: the agent never gets them.
|
|
|
1550
1695
|
| `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
|
|
1551
1696
|
| `g` `Home`, `G` `End` | first row, last row |
|
|
1552
1697
|
| `PageUp`, `PageDown` | one page |
|
|
1553
|
-
| `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent |
|
|
1554
|
-
| `Right` `l` | show them again; on a row already open, go to its first child |
|
|
1698
|
+
| `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent (from a top row of the Background section, its heading); on the Background heading, close it |
|
|
1699
|
+
| `Right` `l` | show them again; on a row already open, go to its first child; on the Background heading, open it, or go to its first row |
|
|
1700
|
+
| `Enter`, `Space` | on the Background heading, open or close it |
|
|
1555
1701
|
| `Tab` | move between the list and the detail; under 80 columns, open and close the detail page |
|
|
1556
1702
|
| `/` | filter |
|
|
1557
1703
|
| `r` | read now |
|
|
@@ -1580,8 +1726,8 @@ from every focus, an agent's terminal included: the agent never gets them.
|
|
|
1580
1726
|
| `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
|
|
1581
1727
|
| `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
|
|
1582
1728
|
|
|
1583
|
-
The selection stands on instances
|
|
1584
|
-
heading, a reason and a note are passed over. What stands above the first
|
|
1729
|
+
The selection stands on instances and the Background heading only, and in
|
|
1730
|
+
the switcher on its rows: any other heading, a reason and a note are passed over. What stands above the first
|
|
1585
1731
|
instance or under the last one comes into view with it. When a movement key
|
|
1586
1732
|
has no instance to go to (the selection is on the first or the last one, or
|
|
1587
1733
|
the list has none), it scrolls the list instead, so the rows after the last
|
|
@@ -1619,7 +1765,7 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
|
|
|
1619
1765
|
|---|---|
|
|
1620
1766
|
| `k` or `Space` | opens [the palette](#the-palette) |
|
|
1621
1767
|
| `1`, `2`, `3` | the Instances, Souls and Capabilities views |
|
|
1622
|
-
| `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
|
|
1768
|
+
| `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)) |
|
|
1623
1769
|
| `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
|
|
1624
1770
|
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
|
|
1625
1771
|
| `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
@@ -2276,6 +2422,11 @@ with the Desktop (`packages/client/`).
|
|
|
2276
2422
|
|
|
2277
2423
|
An add and a remove are changes: `oats tui` never ends one, and one still
|
|
2278
2424
|
running as it leaves is named in one line after the screen is left.
|
|
2425
|
+
- **The kernel's machine sweep**, `oats session resume --json`, by the same
|
|
2426
|
+
kernel, from `/`, with no time limit: when the run starts, and when a
|
|
2427
|
+
read shows a lost session ([Resuming lost sessions](#resuming-lost-sessions)).
|
|
2428
|
+
It is a change, as an add is, but one still running as `oats tui` leaves
|
|
2429
|
+
is not named.
|
|
2279
2430
|
- **The workspace of each row of that list the run has not opened** is
|
|
2280
2431
|
one more read, `oats status --dir <path> --json` with `--max-age 60`, by
|
|
2281
2432
|
the same kernel ([the switcher](#the-switcher)): at the start, when the
|
|
@@ -2428,6 +2579,7 @@ with the Desktop (`packages/client/`).
|
|
|
2428
2579
|
| To | Run |
|
|
2429
2580
|
|---|---|
|
|
2430
2581
|
| start an agent with another harness or model | `oats session start --home <home>` with its options |
|
|
2582
|
+
| move an instance into or out of the background | `oats instance background <name> on\|off` |
|
|
2431
2583
|
| spawn an agent on another machine | `oats spawn <soul> --server <id>` |
|
|
2432
2584
|
| spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
|
|
2433
2585
|
| see a capability's skills and files | `oats capabilities show <name>` |
|
|
@@ -2456,7 +2608,8 @@ version:
|
|
|
2456
2608
|
- The Souls and Capabilities views list a workspace of this machine's
|
|
2457
2609
|
souls and capabilities: both are this machine's.
|
|
2458
2610
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
2459
|
-
folded. An open terminal
|
|
2611
|
+
folded. An open terminal scrolls back with the viewer's own keys,
|
|
2612
|
+
`Shift+PageUp` and `Ctrl+B [`, and no other.
|
|
2460
2613
|
- Up to four terminals are open at a time, as tabs, in at most two
|
|
2461
2614
|
groups. The split cannot be resized or nested, a tab moves only between
|
|
2462
2615
|
the two groups, and no tab or split is kept from one run to the next, or
|
|
@@ -2584,7 +2737,9 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
2584
2737
|
server, session, window or pane. Its probe only lists panes. An agent's
|
|
2585
2738
|
own session is started, ended or restarted only by the kernel's commands
|
|
2586
2739
|
of an act you confirmed
|
|
2587
|
-
([above](#stopping-starting-restarting-and-retiring))
|
|
2740
|
+
([above](#stopping-starting-restarting-and-retiring)) and by the kernel's
|
|
2741
|
+
machine sweep, which resumes lost sessions
|
|
2742
|
+
([above](#resuming-lost-sessions)), and an agent's
|
|
2588
2743
|
terminal is opened by `oats session attach`, which makes its own viewer
|
|
2589
2744
|
session on the agents' tmux server and removes it. The one tmux server
|
|
2590
2745
|
`oats tui` runs is its own private one
|
|
@@ -2595,11 +2750,12 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
2595
2750
|
([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
|
|
2596
2751
|
([above](#what-it-reads-and-what-it-runs)). The processes it starts are
|
|
2597
2752
|
the reads above, when you open an agent its private tmux server and the
|
|
2598
|
-
viewers in it, one for each tab,
|
|
2753
|
+
viewers in it, one for each tab, the acts you confirm and the kernel's
|
|
2754
|
+
machine sweep. No read, server or viewer
|
|
2599
2755
|
outlives it on every way out a process can handle; after SIGKILL a read
|
|
2600
2756
|
in flight runs to its own end, and the private server and its viewers end
|
|
2601
|
-
by themselves. An act you confirmed
|
|
2602
|
-
to its own end. A spawn is ended only at its deadline, while `oats tui`
|
|
2757
|
+
by themselves. An act you confirmed, and the machine sweep, are never
|
|
2758
|
+
ended by `oats tui`: each runs to its own end. A spawn is ended only at its deadline, while `oats tui`
|
|
2603
2759
|
runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
|
|
2604
2760
|
and never after it.
|
|
2605
2761
|
- It **changes this computer's list of deployments only through the
|
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.2** ([release notes](release-notes/v0.69.2.md)).
|
|
10
|
+
The 0.69.2 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.2,** 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.2 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.2 # 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,8 +166,17 @@ 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.
|
|
170
|
-
|
|
169
|
+
- **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
|
|
170
|
+
oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
|
|
171
|
+
instances on oats.okf 5.5.0 write proposals: an older harvester refuses
|
|
172
|
+
them. A soul's `background: true` waits until every deployment runs 0.69.2.
|
|
173
|
+
- **[0.69.1](release-notes/v0.69.1.md#upgrade):** 0.69.0 was tagged but never
|
|
174
|
+
published; 0.69.1 carries all of it, so follow
|
|
175
|
+
[0.69.0's Upgrade section](release-notes/v0.69.0.md#upgrade): the Desktop
|
|
176
|
+
first, then the CLI: a 0.68 Desktop refuses a 0.69 CLI. Every host that shares a workspace
|
|
177
|
+
runs OATS 0.68.0 or later before any of them syncs to oats.aweb 1.32.0.
|
|
178
|
+
- **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the
|
|
179
|
+
CLI: a 0.67 Desktop refuses a 0.68 CLI. The catalog pins new package versions; after `oats sync`, a stopped
|
|
171
180
|
home can move to them with `oats instance upgrade` instead of a respawn
|
|
172
181
|
([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
|
|
173
182
|
- **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ 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.
|
|
58
|
-
oats.okf: v5.
|
|
57
|
+
oats.framework: v1.16.1 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.5.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
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
|
@@ -1,42 +1,28 @@
|
|
|
1
1
|
## Your two directories
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
|
|
6
|
-
root, and not the work tree. Anything that says "your home" means this directory.
|
|
3
|
+
**IMPORTANT: ALWAYS FOLLOW THESE INSTRUCTIONS FOR WORKING**, here and in your
|
|
4
|
+
work-mode block below.
|
|
7
5
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
and from where), and whatever working state your role keeps — your knowledge
|
|
11
|
-
layer names those files, if you have one. They belong here, not in the work
|
|
12
|
-
tree.
|
|
13
|
-
- **Run OATS operational/lifecycle commands, and commands from active
|
|
14
|
-
capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
|
|
15
|
-
and whatever your own capabilities add; for example, when the
|
|
16
|
-
aweb messaging capability is active, run `aw` there too. They resolve their
|
|
17
|
-
scope from the directory you run them in, so running them from the work tree
|
|
18
|
-
points them at the wrong deployment. To act on a different package or config
|
|
19
|
-
scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
|
|
20
|
-
- **Soul work is repository work.** If your TASK is to change soul content that
|
|
21
|
-
lives in this repository, that is ordinary code work — do it on tracked paths
|
|
22
|
-
under `work/`, reviewed like the rest. How your own learnings reach your soul
|
|
23
|
-
is your knowledge capability's business, and its instructions below say so if you
|
|
24
|
-
have one.
|
|
6
|
+
**Your home is where this session starts** (`$OATS_INSTANCE_HOME`). It is not
|
|
7
|
+
your user home (`~`), not the repository root, and not the work tree.
|
|
25
8
|
|
|
26
|
-
|
|
27
|
-
|
|
9
|
+
- It holds your brain and state: `AGENTS.md`, `TASK.md`, `instance.json` and
|
|
10
|
+
your role's working state. Never put them in `./work`.
|
|
11
|
+
- **ALWAYS run OATS commands, and commands from active capabilities, from
|
|
12
|
+
instance home** (for example, when the aweb messaging capability is active,
|
|
13
|
+
`aw` too): they resolve their scope from where you run them. For another
|
|
14
|
+
scope on purpose: `oats <cmd> --dir <path>`.
|
|
15
|
+
|
|
16
|
+
**`<instance-home>/work` is your repository or workspace view**, as your work
|
|
17
|
+
mode grants it.
|
|
28
18
|
|
|
29
19
|
- **Repository work happens there, or in the extra trees your mode block
|
|
30
20
|
grants, and nowhere else**: reading, editing, building, testing, git and
|
|
31
21
|
commits, on repository content. Never from the main checkout or from your
|
|
32
22
|
home root, beyond what your mode block names.
|
|
33
|
-
- **What your mode permits is the mode block's call
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
script), go where your task and tooling direct.
|
|
40
|
-
|
|
41
|
-
Move between the two as the task needs — the boundary is what each directory is
|
|
42
|
-
*for*, not a place to settle in.
|
|
23
|
+
- **What your mode permits is the mode block's call**: your mode block, below,
|
|
24
|
+
is the authority.
|
|
25
|
+
- If your TASK is to change soul content that lives in this repository, that is
|
|
26
|
+
ordinary repository work. How your own learnings reach your soul is your
|
|
27
|
+
knowledge capability's business.
|
|
28
|
+
- Reports and scratch files go where your task and tooling direct.
|
package/injects/work-attached.md
CHANGED
|
@@ -1,16 +1,11 @@
|
|
|
1
1
|
## Work mode: attached
|
|
2
2
|
|
|
3
|
-
Your `./work` is
|
|
4
|
-
|
|
3
|
+
Your `./work` is **another instance's work tree**, its branch and uncommitted
|
|
4
|
+
state. You are a guest.
|
|
5
5
|
|
|
6
|
-
- **
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
- Retiring you never removes the shared tree — cleanup of the tree is the
|
|
13
|
-
owner's concern, not yours.
|
|
14
|
-
|
|
15
|
-
This mode fits service agents (harvesters, reviewers, fixers) that operate
|
|
16
|
-
on a live instance's work in flight.
|
|
6
|
+
- **NEVER switch branches, rebase or reset.** Make focused additions on top of
|
|
7
|
+
the owner's current state; keep changes and commits small, and name yourself
|
|
8
|
+
in commit messages where authorship could be unclear.
|
|
9
|
+
- Leave files the owner is editing alone unless your task says otherwise; when
|
|
10
|
+
unsure, ask through your messaging capability or your spawner.
|
|
11
|
+
- The tree's cleanup is its owner's; retiring you never removes it.
|
package/injects/work-checkout.md
CHANGED
|
@@ -1,40 +1,26 @@
|
|
|
1
1
|
## Work mode: checkout
|
|
2
2
|
|
|
3
|
-
Your `./work` is
|
|
4
|
-
in the same tree
|
|
3
|
+
Your `./work` is the repository's **shared checkout**: the human and other
|
|
4
|
+
agents work in the same tree.
|
|
5
5
|
|
|
6
|
-
- **
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
of another branch) without an explicit human instruction.
|
|
6
|
+
- **Stay on the checked-out branch; never switch unless explicitly asked.**
|
|
7
|
+
- **NO destructive git** (reset --hard, rebase, force-push, checking out
|
|
8
|
+
another branch) without an explicit human instruction.
|
|
10
9
|
- Work that needs its own branch goes in an extra tree, not in `work/`.
|
|
11
10
|
|
|
12
11
|
### Extra trees
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
existing one):
|
|
13
|
+
For another branch or repository, from your home (`--preview` first; `--repo
|
|
14
|
+
<member key|clone path>` for another repository; `<base>`: the remote branch
|
|
15
|
+
to start from, or the one you rework):
|
|
18
16
|
|
|
19
17
|
oats worktree add --purpose <purpose> --branch <branch> --base <base>
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Never `-C`/`-B`, which reset a branch someone else may own.
|
|
30
|
-
- If a capability of yours sets up new trees, `add` runs that setup, which
|
|
31
|
-
may take minutes: give it a long timeout, or run it in the background and
|
|
32
|
-
wait for it to exit. A killed `add` rolls back; run it again. Once it has
|
|
33
|
-
finished, running it again with the same arguments does nothing.
|
|
34
|
-
- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
|
|
35
|
-
(`<base>` when you rework an existing branch).
|
|
36
|
-
- Before your task closes, merge each extra tree into your PR branch, or push its
|
|
37
|
-
branch and name it in your hand-back; then
|
|
38
|
-
`oats worktree remove --purpose <purpose>`, which keeps the branch and
|
|
39
|
-
refuses a tree with uncommitted work.
|
|
40
|
-
Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
|
|
19
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
20
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
21
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
22
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
23
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
24
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
25
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
26
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
|
@@ -1,18 +1,12 @@
|
|
|
1
1
|
## Work mode: directory
|
|
2
2
|
|
|
3
|
-
Your `./work` is an **instance-owned execution directory
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
to edit that directory.
|
|
3
|
+
Your `./work` is an **instance-owned execution directory**, not a Git worktree,
|
|
4
|
+
checkout or link. The `repo` recorded for you supplies configuration only; it
|
|
5
|
+
grants no permission to edit the `repo` directory.
|
|
7
6
|
|
|
8
|
-
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- Keep canonical instructions in the instance's `AGENTS.md`; `CLAUDE.md` is its
|
|
15
|
-
compatibility symlink. Run OATS lifecycle/capability commands from home.
|
|
16
|
-
- Retirement removes the execution directory only after nonempty work has a
|
|
17
|
-
verified copy in the reported recovery storage beside the home. Recovery is
|
|
18
|
-
not publication: deliver your results through the task's own protocol first.
|
|
7
|
+
- Work inside `./work`. **Never initialize a fake repository**; a containing
|
|
8
|
+
repository Git discovers is not yours.
|
|
9
|
+
- Use external inputs and destinations only as your task and capabilities
|
|
10
|
+
explicitly authorize.
|
|
11
|
+
- Deliver results through your task's own protocol before you finish: the
|
|
12
|
+
recovery copy kept at retirement is not publication.
|
|
@@ -1,22 +1,11 @@
|
|
|
1
1
|
## Work mode: workspace
|
|
2
2
|
|
|
3
|
-
Your `./work` is the **whole workspace
|
|
4
|
-
|
|
5
|
-
cross-repo coordinator: your product is routing, analysis, and coordination —
|
|
6
|
-
not code changes.
|
|
3
|
+
Your `./work` is the **whole workspace**, not one repository. You route,
|
|
4
|
+
analyse and coordinate; you do not change code.
|
|
7
5
|
|
|
8
|
-
- **Read freely across
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
and needs no git ceremony.
|
|
15
|
-
- If one of your capabilities delivers durable updates into a repo, its own
|
|
16
|
-
instructions define where and how — including whether anything is committed at
|
|
17
|
-
all, and by whom. That is its business, not an exception you take into a
|
|
18
|
-
member repo yourself.
|
|
19
|
-
|
|
20
|
-
This mode fits coordinators, dispatchers, architects, and analysts whose
|
|
21
|
-
scope is the workspace itself; if a task needs actual edits in one repo, ask
|
|
22
|
-
for (or route to) a worktree-mode instance of that repo's agent instead.
|
|
6
|
+
- **Read freely across member repositories; never edit or commit inside them,
|
|
7
|
+
and NEVER change their Git state** (no branch switches, resets, pulls,
|
|
8
|
+
stashes or worktrees). Route a repository change to that repository's agents
|
|
9
|
+
or to your human.
|
|
10
|
+
- A capability that delivers updates into a repository follows its own
|
|
11
|
+
instructions; that is not an exception you take yourself.
|