@awebai/oats 0.55.1 → 0.57.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/tui.md
CHANGED
|
@@ -12,11 +12,12 @@ install.
|
|
|
12
12
|
`oats tui` is marked **preview**. That means:
|
|
13
13
|
|
|
14
14
|
- **This version shows a workspace's instances, on this machine and on the
|
|
15
|
-
other machines registered on this machine, in one list,
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
15
|
+
other machines registered on this machine, in one list, opens an agent's
|
|
16
|
+
terminal, and stops, starts, restarts and retires an agent after a
|
|
17
|
+
confirmation.** The registered machines are the ones `oats server list`
|
|
18
|
+
names. It follows the instances as they start, stop and wait for you. It
|
|
19
|
+
cannot spawn an agent, start one with another harness or model, or add,
|
|
20
|
+
check or remove a machine: [what it does not do
|
|
20
21
|
yet](#what-this-version-does-not-do) names the `oats` command for each.
|
|
21
22
|
- **Its screens and its configuration file may change without notice** while
|
|
22
23
|
it is a preview.
|
|
@@ -126,6 +127,29 @@ runs.
|
|
|
126
127
|
branch, team, parent, when it last started, and its home. From 80
|
|
127
128
|
columns up it stands beside the list; on a narrower terminal `Tab` opens
|
|
128
129
|
it as a page.
|
|
130
|
+
- **Opening an agent.** `Enter` on an instance that runs gives your terminal
|
|
131
|
+
to that agent's own terminal, through `oats session attach`: you see what
|
|
132
|
+
the agent shows, and what you type goes to it. `Ctrl+\` brings `oats tui`
|
|
133
|
+
back, and the agent keeps running. The key is yours to change
|
|
134
|
+
([`tui.json`](#change-the-keys-tuijson)), and the footer names it whenever
|
|
135
|
+
`Enter` would open.
|
|
136
|
+
- Inside tmux the agent opens in the same pane. `oats tui` makes no window
|
|
137
|
+
and no split.
|
|
138
|
+
- After the return the instances are read again at once, and one line
|
|
139
|
+
says what happened: that you left and the agent keeps running, that it
|
|
140
|
+
could not be opened, or that the connection to its machine ended. When
|
|
141
|
+
the agent's own terminal ended while you were in it, you are back with
|
|
142
|
+
no line: the list shows the agent as it now is.
|
|
143
|
+
- What `oats session attach` printed when it failed stands under that line
|
|
144
|
+
in quotation marks. It is not said who printed it: OATS, tmux and ssh
|
|
145
|
+
all can.
|
|
146
|
+
- `Enter` on an instance that cannot be opened opens nothing and says why:
|
|
147
|
+
it does not run, whether it runs is not known, the detail's reason holds
|
|
148
|
+
it, or its machine's OATS is older than 0.51.0 and has no key to leave a
|
|
149
|
+
viewer.
|
|
150
|
+
- For each time you open an agent, one line of tmux's own stays on your
|
|
151
|
+
screen and is there after you quit: `[detached (from session …)]`, or
|
|
152
|
+
`[exited]`.
|
|
129
153
|
|
|
130
154
|
**A view of more than one deployment** (this machine and another, or two
|
|
131
155
|
deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
@@ -281,6 +305,94 @@ view to go back to, and `Esc` and `1` do not close the switcher. The same
|
|
|
281
305
|
holds after a start outside every deployment, which opens the switcher with
|
|
282
306
|
nothing open.
|
|
283
307
|
|
|
308
|
+
## Stopping, starting, restarting and retiring
|
|
309
|
+
|
|
310
|
+
With an instance selected, a capital letter acts on it, always after a
|
|
311
|
+
confirmation:
|
|
312
|
+
|
|
313
|
+
| Key | Does |
|
|
314
|
+
|---|---|
|
|
315
|
+
| `X` | stops it: its session ends, and its home, work and launch are kept |
|
|
316
|
+
| `D` | retires it |
|
|
317
|
+
| `S` | starts a stopped instance as it was last launched |
|
|
318
|
+
| `R` | restarts a running instance as it was last launched |
|
|
319
|
+
|
|
320
|
+
The rules are the Desktop's, from the readers both clients share: an
|
|
321
|
+
instance offers what the Desktop offers for it, and nothing else. One that
|
|
322
|
+
is still being spawned, and one its machine reports it cannot reach, offers
|
|
323
|
+
none; one whose spawn stopped half way offers only to be retired; a running
|
|
324
|
+
one offers restart and not start, a stopped one start and not restart. The
|
|
325
|
+
footer names the keys the selected instance offers now, after `Enter`, and
|
|
326
|
+
on a narrow terminal they are the first hints it gives up. A key for an act
|
|
327
|
+
the instance does not offer opens nothing, and the line above the panes
|
|
328
|
+
says why. The keys are yours to change in
|
|
329
|
+
[`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
|
|
330
|
+
`start` and `restart`.
|
|
331
|
+
|
|
332
|
+
**The confirmation** opens over the list, with the focus on `Cancel`.
|
|
333
|
+
`Left`/`Right` and `Tab`/`Shift+Tab` move between its buttons and `Enter`
|
|
334
|
+
presses one. No letter moves the focus, and an `Enter` that arrives in the
|
|
335
|
+
same read of input as the move onto the act's button is ignored, so pasted
|
|
336
|
+
text can open a confirmation but never act in it. `Esc` closes it. `q` and
|
|
337
|
+
`Ctrl+C` still quit. The help (`?`) is not shown over a confirmation.
|
|
338
|
+
|
|
339
|
+
- **Stop and retire read the kernel's plan first** (`oats instance stop
|
|
340
|
+
<instance> --plan`, `oats retire <instance> --plan`) and show what the act
|
|
341
|
+
will do, in the Desktop's words. `Space` switches the plan's choice (for a
|
|
342
|
+
stop: whether the instances spawned from it stop too), which reads a new
|
|
343
|
+
plan. The act's button applies exactly the plan on the screen: when the
|
|
344
|
+
instance changed since, the kernel refuses it and the confirmation shows
|
|
345
|
+
the new plan. For an agent on another machine the plan is read through
|
|
346
|
+
that machine's kernel, and a machine that does not answer gives no plan:
|
|
347
|
+
the confirmation says so.
|
|
348
|
+
- **`Review again`** reads the plan again. **`Check again`** asks what
|
|
349
|
+
became of an apply whose answer did not come, or came in a form
|
|
350
|
+
`oats tui` cannot read: it never applies a second time.
|
|
351
|
+
- **Start and restart have no plan.** The confirmation says what will
|
|
352
|
+
happen and shows the agent's home (and its machine). A restart ends the
|
|
353
|
+
agent's session and starts it again: what it is doing is interrupted.
|
|
354
|
+
Both run `oats session start --home <home>` (or `restart`) with the launch
|
|
355
|
+
recorded for the instance and no choice of harness, model or
|
|
356
|
+
configuration: for those, run `oats session start --home <home>` with
|
|
357
|
+
its options yourself.
|
|
358
|
+
- Once an act has answered, the confirmation shows the answer, and the list
|
|
359
|
+
is read again at once.
|
|
360
|
+
|
|
361
|
+
**One act at a time per instance from this `oats tui`.** While a start or
|
|
362
|
+
restart it sent is still running, whether or not the confirmation is still
|
|
363
|
+
open, no act of that instance opens: the line says
|
|
364
|
+
`The start of <name> is still running.` While a stop or retire it sent is
|
|
365
|
+
still running, another stop or retire from it is refused, with the time
|
|
366
|
+
the running one started.
|
|
367
|
+
|
|
368
|
+
**An act you sent runs to its end.** Closing the confirmation, quitting,
|
|
369
|
+
`Ctrl+Z`, a signal to `oats tui`, or the terminal going away never ends
|
|
370
|
+
it: `oats tui` sends no signal to the kernel command it started, which runs
|
|
371
|
+
in a session of its own and writes to files of its own (below), never to
|
|
372
|
+
`oats tui`. When you leave while one is still running, one line per act is
|
|
373
|
+
printed after the screen is left, on standard error, when that is a
|
|
374
|
+
terminal or a file:
|
|
375
|
+
|
|
376
|
+
oats: the stop of dev-1 is still running; `oats status` shows its result.
|
|
377
|
+
|
|
378
|
+
The exit status never depends on it.
|
|
379
|
+
|
|
380
|
+
**Limits.**
|
|
381
|
+
|
|
382
|
+
- Another `oats tui`, the Desktop, and `oats` run by hand can act on the
|
|
383
|
+
same instance. The kernel's answers hold: from OATS 0.52.0 a stop and a
|
|
384
|
+
retire of one instance refuse each other before either changes anything.
|
|
385
|
+
A stop or a retire does not see a start in flight, and a start does not
|
|
386
|
+
see a retire in flight
|
|
387
|
+
([#866](https://github.com/awebai/oats/issues/866)).
|
|
388
|
+
- An `oats tui` started again knows nothing of the acts an earlier one
|
|
389
|
+
sent: `Check again` there answers that the plan expired, the list shows
|
|
390
|
+
what the kernel reports, and against an earlier one's start still running
|
|
391
|
+
the kernel's start lock is the only guard.
|
|
392
|
+
- An agent on a machine whose OATS is older than 0.52.0: a stop interrupted
|
|
393
|
+
there can leave `.oats-stop-pending.json` in the agent's home, and then
|
|
394
|
+
the agent can be started but not stopped while that file exists.
|
|
395
|
+
|
|
284
396
|
## Keys
|
|
285
397
|
|
|
286
398
|
| Key | Does |
|
|
@@ -295,9 +407,12 @@ nothing open.
|
|
|
295
407
|
| `r` | read now |
|
|
296
408
|
| `1` | the Instances view |
|
|
297
409
|
| `w` | opens [the switcher](#the-switcher) |
|
|
298
|
-
| `Enter` | in the switcher, opens the selected row |
|
|
410
|
+
| `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
|
|
411
|
+
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
412
|
+
| `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
|
|
413
|
+
| `Space` | in a confirmation, switches the plan's choice |
|
|
299
414
|
| `?` | opens the help; `?` again closes it |
|
|
300
|
-
| `Esc` | closes, in this order: the help, the filter field, a kept filter, then the detail or the switcher |
|
|
415
|
+
| `Esc` | closes, in this order: a confirmation, the help, the filter field, a kept filter, then the detail or the switcher |
|
|
301
416
|
| `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
|
|
302
417
|
| `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
|
|
303
418
|
| `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
|
|
@@ -310,10 +425,10 @@ the list has none), it scrolls the list instead, so the rows after the last
|
|
|
310
425
|
instance can always be read, however many they are. The selection stays
|
|
311
426
|
where it is, and the list returns to it at the next key that moves it.
|
|
312
427
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
428
|
+
The help screen is generated from the table the program acts on, so it
|
|
429
|
+
always lists the keys that work, with the marks and with what this version
|
|
430
|
+
does not do. The movement keys scroll it. While `oats tui` has the screen,
|
|
431
|
+
`Ctrl+\` does nothing.
|
|
317
432
|
|
|
318
433
|
**The filter.** `/` opens a field on the last row. What you type narrows the
|
|
319
434
|
list to the instances whose name, soul or repository contains it, with the
|
|
@@ -339,7 +454,7 @@ an absolute path, else `~/.config/oats/tui.json`, once, at the start. It
|
|
|
339
454
|
never writes it. With no file the keys are the ones above.
|
|
340
455
|
|
|
341
456
|
```json
|
|
342
|
-
{ "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false }
|
|
457
|
+
{ "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
|
|
343
458
|
```
|
|
344
459
|
|
|
345
460
|
- `keys.<action>` is the list of keys of that action. It **replaces** the
|
|
@@ -347,10 +462,11 @@ never writes it. With no file the keys are the ones above.
|
|
|
347
462
|
do not name keeps its keys.
|
|
348
463
|
- The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
|
|
349
464
|
`collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
|
|
350
|
-
`workspaces`, `open
|
|
351
|
-
`
|
|
352
|
-
|
|
353
|
-
the
|
|
465
|
+
`workspaces`, `open`, `help`, `close`, `quit`, `suspend` and `redraw`.
|
|
466
|
+
`workspaces` (`w`) opens the switcher and `open` (`enter`) opens the
|
|
467
|
+
selected agent's terminal in the list of instances and the selected row
|
|
468
|
+
in the switcher. In an open filter field `Enter` keeps the filter,
|
|
469
|
+
whatever key `open` has.
|
|
354
470
|
- A key is written as the help shows it, in lower case: `q`, `G`, `?`,
|
|
355
471
|
`space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
|
|
356
472
|
`ctrl+c`, `alt+x`, `shift+tab`, `ctrl+alt+up`. Modifiers come in the order
|
|
@@ -358,6 +474,12 @@ never writes it. With no file the keys are the ones above.
|
|
|
358
474
|
and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
|
|
359
475
|
keys of their own.
|
|
360
476
|
- `ascii: true` is `--ascii`.
|
|
477
|
+
- `open.detachKey` is the key that leaves an agent's terminal, written as
|
|
478
|
+
`oats session attach --detach-key` takes it: `C-\` when you name none.
|
|
479
|
+
[Execution targets](execution-targets.md) has the keys that can be chosen.
|
|
480
|
+
`oats tui` does not check it: a key OATS refuses is said when you open an
|
|
481
|
+
agent. A key that tmux's copy mode binds leaves the viewer once that mode
|
|
482
|
+
is left.
|
|
361
483
|
|
|
362
484
|
**A file it cannot honour stops the start.** Each problem is one line on
|
|
363
485
|
stderr, the status is 1 and nothing is drawn; it resolves no conflict and
|
|
@@ -368,7 +490,12 @@ guesses nothing. It refuses:
|
|
|
368
490
|
| is not a regular file (a link to one is read), or cannot be read | `it is not a regular file`, `it cannot be read` |
|
|
369
491
|
| is larger than 64 KiB | `it is larger than 64 KiB` |
|
|
370
492
|
| is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
|
|
371
|
-
| has a setting other than `keys` and `
|
|
493
|
+
| has a setting other than `keys`, `ascii` and `open`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false`, `open must be an object` |
|
|
494
|
+
| has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
|
|
495
|
+
| gives `open.detachKey` something that is not 1 to 16 printable ASCII characters | `open.detachKey must be 1 to 16 printable ASCII characters` |
|
|
496
|
+
| gives `open.detachKey` a value that begins with `-` | `open.detachKey cannot begin with -` |
|
|
497
|
+
| gives `open.detachKey` a value the help would draw as another key (a run of spaces, a space at an end) | `open.detachKey is a key the help cannot name` |
|
|
498
|
+
| names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
|
|
372
499
|
| names an action that does not exist | `unknown action …`, with the list of actions |
|
|
373
500
|
| gives an action something that is not a list of strings | `… must be a list of key ids` |
|
|
374
501
|
| has a string that is not a key | `the key … of … is not a key id` |
|
|
@@ -424,29 +551,51 @@ with the Desktop (`packages/client/`).
|
|
|
424
551
|
listed: at most 200, and each directory among them is asked for a regular
|
|
425
552
|
`oats-local.yaml`. An entry that is a link is not followed. When a folder
|
|
426
553
|
is opened, that one directory is asked again.
|
|
427
|
-
- **
|
|
554
|
+
- **Opening an agent runs one more command,** `oats session attach --home
|
|
555
|
+
<home> --detach-key <key>`, by the same kernel, with your terminal as its
|
|
556
|
+
terminal. For an agent on another machine `oats session inspect --server
|
|
557
|
+
<id> --home <home> --json` is asked first (20 seconds), then `oats session
|
|
558
|
+
attach --server <id> --home <home> --detach-key <key>`. Nothing is read
|
|
559
|
+
while the agent has the terminal, and the return reads at once.
|
|
560
|
+
- **Every read runs in a session of its own** and is ended when the TUI
|
|
428
561
|
ends, on every way out a process can handle (for SIGKILL see
|
|
429
|
-
[below](#what-it-changes-in-your-terminal-and-restores)).
|
|
562
|
+
[below](#what-it-changes-in-your-terminal-and-restores)). The viewer
|
|
563
|
+
shares your terminal, and is ended first when `oats tui` is ended while an
|
|
564
|
+
agent has the terminal. A read that was
|
|
430
565
|
running when the TUI is suspended is dropped, not shown: its answer could
|
|
431
566
|
arrive cut. That holds for the read of the other machines too. The return
|
|
432
567
|
reads again.
|
|
433
|
-
-
|
|
434
|
-
|
|
568
|
+
- **Stopping, starting, restarting and retiring runs the kernel's own
|
|
569
|
+
commands**, by the same kernel: for a stop or a retire, the plan
|
|
570
|
+
(`oats instance stop <instance> --plan --json`, `oats retire <instance>
|
|
571
|
+
--plan --json`; 30 seconds, 45 for another machine), a read like the
|
|
572
|
+
others, then, when you press the act, the apply of that plan
|
|
573
|
+
(`--plan-revision`, `--idempotency-key`); for a start or a restart,
|
|
574
|
+
`oats session start` or `oats session restart --home <home> --json`. An
|
|
575
|
+
agent on another machine is reached with `--server <id>`. An apply, a
|
|
576
|
+
start and a restart are changes: each runs in a session of its own, with
|
|
577
|
+
no time limit and no signal from `oats tui`, and its output goes to two
|
|
578
|
+
files in a directory of `oats tui`'s own (made with mode 0700 under the
|
|
579
|
+
system's temporary directory), read back when it ends and deleted. On the
|
|
580
|
+
way out the files of a change still running are deleted (it goes on
|
|
581
|
+
writing to them), and the directory is removed. `oats tui` waits for an
|
|
582
|
+
apply's answer for 10 minutes and for a start's for 60 seconds; then it
|
|
583
|
+
says so, and the change goes on.
|
|
584
|
+
- It runs no other command that changes a deployment or a registration, and
|
|
585
|
+
it writes no other file.
|
|
435
586
|
|
|
436
587
|
## What this version does not do
|
|
437
588
|
|
|
438
589
|
| To | Run |
|
|
439
590
|
|---|---|
|
|
440
|
-
|
|
|
441
|
-
| stop an agent | `oats instance stop <instance>` |
|
|
442
|
-
| start or restart an agent | `oats session start --home <home>` |
|
|
443
|
-
| retire an agent | `oats retire <instance>` |
|
|
591
|
+
| start an agent with another harness or model | `oats session start --home <home>` with its options |
|
|
444
592
|
| see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
|
|
445
593
|
| see capabilities | `oats capabilities` |
|
|
446
594
|
| add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
|
|
447
595
|
| check a machine | `oats server check <id>` |
|
|
448
596
|
| remove a machine | `oats server remove <id>` |
|
|
449
597
|
| open a deployment outside `~/Agents` | `oats tui --dir <path>` |
|
|
598
|
+
| open an agent in a tmux window or split of its own | `oats session attach --home <home>` in that window (the detail shows the home) |
|
|
450
599
|
|
|
451
600
|
The help screen (`?`) names the same commands. What else holds for this
|
|
452
601
|
version:
|
|
@@ -464,6 +613,9 @@ version:
|
|
|
464
613
|
- Souls and Capabilities, when they come, are this machine's.
|
|
465
614
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
466
615
|
folded.
|
|
616
|
+
- With an OATS older than 0.52.0, after an interrupted stop the instance can
|
|
617
|
+
be started and then cannot be stopped while `.oats-stop-pending.json` exists
|
|
618
|
+
in its home.
|
|
467
619
|
|
|
468
620
|
## What it changes in your terminal, and restores
|
|
469
621
|
|
|
@@ -504,6 +656,16 @@ It stops the whole foreground process group, as a `Ctrl+Z` does for any
|
|
|
504
656
|
other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
|
|
505
657
|
suspends as one job.
|
|
506
658
|
|
|
659
|
+
**While an agent has the terminal** `oats tui` has put the terminal back in
|
|
660
|
+
full, as for a suspend, and draws nothing. The viewer is OATS's own: it sets
|
|
661
|
+
what it needs, the mouse for scrolling among it, and puts that back when it
|
|
662
|
+
ends. Then `oats tui` sets its modes again. A SIGQUIT does not end
|
|
663
|
+
`oats tui` while an agent has the terminal (a second `Ctrl+\`, pressed as the
|
|
664
|
+
viewer leaves, is that signal). SIGINT, SIGTERM and SIGHUP end the viewer
|
|
665
|
+
first and then `oats tui`, with the status of the table above. A viewer
|
|
666
|
+
that has not ended 3 seconds after it was asked, or at a second signal, is
|
|
667
|
+
left as it is, and `oats tui` ends without it.
|
|
668
|
+
|
|
507
669
|
`Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
|
|
508
670
|
a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
|
|
509
671
|
130. A script that wraps `oats tui` meets that difference.
|
|
@@ -515,7 +677,9 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
|
|
|
515
677
|
stayed in the alternate screen until `tput rmcup`. Nothing else is left in
|
|
516
678
|
tmux: `oats tui` creates no session, window, option or key binding.
|
|
517
679
|
Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
|
|
518
|
-
read that was in flight runs to its own end.
|
|
680
|
+
read that was in flight runs to its own end. After a SIGKILL while an agent
|
|
681
|
+
has the terminal, the viewer still has it: leave it with the key and you are
|
|
682
|
+
in your shell.
|
|
519
683
|
|
|
520
684
|
## What it never does
|
|
521
685
|
|
|
@@ -542,11 +706,23 @@ read that was in flight runs to its own end. It only reads.
|
|
|
542
706
|
shared home's (`packages/client/`), and the TUI writes none of its own
|
|
543
707
|
for a speaker. They never stand before a withheld text: a reason that is
|
|
544
708
|
withheld is `[withheld]` alone.
|
|
545
|
-
- It changes nothing in tmux: no option, key binding, server,
|
|
546
|
-
window or pane. Its probe only lists panes.
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
709
|
+
- It changes nothing in tmux itself: no option, key binding, server,
|
|
710
|
+
session, window or pane. Its probe only lists panes. An agent's own
|
|
711
|
+
session is started, ended or restarted only by the kernel's commands of
|
|
712
|
+
an act you confirmed
|
|
713
|
+
([above](#stopping-starting-restarting-and-retiring)), and an agent's
|
|
714
|
+
terminal is opened by `oats session attach`, which makes its own viewer
|
|
715
|
+
session on the agents' tmux server and removes it; `oats tui` builds no
|
|
716
|
+
viewer and runs no tmux command for either.
|
|
717
|
+
- It starts no daemon, opens no socket and writes no file but the output of
|
|
718
|
+
a change, in its own directory ([above](#what-it-reads-and-what-it-runs)).
|
|
719
|
+
The processes it starts are the reads above, when you open an agent the
|
|
720
|
+
viewer, and the acts you confirm. No read and no viewer outlives it on
|
|
721
|
+
every way out a process can handle, except a viewer that does not end
|
|
722
|
+
when asked (see [above](#what-it-changes-in-your-terminal-and-restores));
|
|
723
|
+
after SIGKILL a read in flight runs to its own end, and a viewer stays
|
|
724
|
+
until you leave it. An act you confirmed is never ended by `oats tui`: it
|
|
725
|
+
runs to its own end.
|
|
550
726
|
|
|
551
727
|
## Errors
|
|
552
728
|
|
|
@@ -577,6 +753,14 @@ that is a bug worth reporting, with the terminal's name and `TERM`.
|
|
|
577
753
|
Another machine is reached only through the kernel's own read
|
|
578
754
|
(`oats server roster`): `oats tui` opens no connection of its own.
|
|
579
755
|
|
|
756
|
+
Opening an agent has been run in the automated tests only, in two private
|
|
757
|
+
tmux servers: one holds the agent's window, as a deployment records it, and
|
|
758
|
+
the other plays your terminal, with the real `oats tui` and the real
|
|
759
|
+
`oats session attach` in its pane. No real terminal emulator, no ssh and no
|
|
760
|
+
other machine reached for real were used: an agent of another machine is
|
|
761
|
+
opened in the tests from the kernel's answer handed to the client. So far no
|
|
762
|
+
person has opened an agent from `oats tui` in a real terminal.
|
|
763
|
+
|
|
580
764
|
With a registered machine it has been run only against one that did not
|
|
581
765
|
answer: the switcher lists it by its own name with the reason, and its view
|
|
582
766
|
says that it was not reached. A machine that answers is drawn in the
|
package/docs/upgrading.md
CHANGED
|
@@ -53,7 +53,10 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
|
53
53
|
plan starts with that install, and the bridges move to that same version in
|
|
54
54
|
the same run. So where the Desktop is installed, step 0 comes before such an
|
|
55
55
|
`oats update` too: `oats update --check` shows whether the plan holds that
|
|
56
|
-
install, and runs nothing.
|
|
56
|
+
install, and runs nothing. When that install is of another minor or major
|
|
57
|
+
version, the plan says so in one line under its steps, whether or not a
|
|
58
|
+
Desktop is installed: `OATS Desktop refuses a CLI newer than its own minor
|
|
59
|
+
version: if you use it, install OATS Desktop <version> first.`
|
|
57
60
|
|
|
58
61
|
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
59
62
|
older bridge than the one in place:
|
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.10.
|
|
58
|
-
oats.okf: v5.0
|
|
57
|
+
oats.framework: v1.10.2 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.2.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
|
|
@@ -161,6 +161,13 @@ Written by `oats sync`; the only persisted state at the deployment besides
|
|
|
161
161
|
|
|
162
162
|
## Repository references in diagnostics
|
|
163
163
|
|
|
164
|
+
Kernel call sites select the display context explicitly: `displayRepoRef`
|
|
165
|
+
for selected reference values, `displayDiagnosticText` for kernel-authored
|
|
166
|
+
diagnostic prose and `scrubGitLine` for Git's own lines. The entry points
|
|
167
|
+
share one private renderer; options on the first two cannot select Git-line
|
|
168
|
+
handling. The [development reference](implementation.md#remote-diagnostic-display)
|
|
169
|
+
documents their signatures and direct-module use.
|
|
170
|
+
|
|
164
171
|
Selected repository references in diagnostics are display values. A selected
|
|
165
172
|
original refused reference is shown verbatim when it is 1–256 characters long
|
|
166
173
|
and contains only ASCII letters, digits, spaces, `.`, `_`, `/`, `+`, `-` and
|
|
@@ -188,10 +195,13 @@ A diagnostic field that explicitly carries a pinned source uses the same
|
|
|
188
195
|
constructor with pinned-source context: a recognised reference followed by `@`
|
|
189
196
|
and a validated 40-hex-character commit can retain that commit in its display.
|
|
190
197
|
If either part cannot be recognised, the whole source is withheld: pinned
|
|
191
|
-
sources have no bounded plain-value fallback.
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
198
|
+
sources have no bounded plain-value fallback. `displayRepoRef` selects this
|
|
199
|
+
context with `pinned: true` for a complete `<ref>@<commit>` value, or with
|
|
200
|
+
`pinned: { ref, commit }` for its original components; both forms validate
|
|
201
|
+
both parts strictly. Rendering an already constructed pinned source does not
|
|
202
|
+
change it. Ordinary reference rendering does not infer a pin or admit a new
|
|
203
|
+
source form. Local/file reference semantics and operational external-source
|
|
204
|
+
values remain unchanged.
|
|
195
205
|
|
|
196
206
|
The same decision applies to the selected reference in error messages,
|
|
197
207
|
`details.ref`, `details.url`, `details.value`, `provenance.value`, nested
|
|
@@ -315,6 +325,16 @@ its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
|
|
|
315
325
|
Reading the workspace repo *is* being in the workspace — a workspace's access
|
|
316
326
|
control is Git's.
|
|
317
327
|
|
|
328
|
+
**Git version failures preserve the remote cache.** Partial caches need Git
|
|
329
|
+
2.45 or later. A successfully parsed older version causes OATS to rebuild a
|
|
330
|
+
partial cache with whole trees. If the version command fails, times out or
|
|
331
|
+
returns an unparseable version, the read instead fails with
|
|
332
|
+
`E_REMOTE_UNREADABLE` and an existing reason (`unknown` for unparseable
|
|
333
|
+
output, `timeout` for a timeout). The partial cache, its fetch mode and its
|
|
334
|
+
commit pins are preserved, and a later read can retry the version probe.
|
|
335
|
+
This also applies to library reads without a session. A cache already using
|
|
336
|
+
whole trees stays in that mode when a later probe finds a newer Git.
|
|
337
|
+
|
|
318
338
|
**Repo-owned capabilities.** `private: true` in a capability's `oats.json`
|
|
319
339
|
makes it **repo-owned**: it is listed like any other capability (with
|
|
320
340
|
`private: true`; the human table marks it "(repo-owned)"), and it is usable
|
package/lib/automations.mjs
CHANGED
|
@@ -33,12 +33,13 @@
|
|
|
33
33
|
* `oats automations refresh`, which the tick runs as a child when the snapshot is ten minutes
|
|
34
34
|
* old), one list per kind, and the tick reads it. The run state stays local. */
|
|
35
35
|
import { spawnSync } from "node:child_process";
|
|
36
|
-
import { mkdirSync, readFileSync,
|
|
36
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
37
37
|
import { dirname, join } from "node:path";
|
|
38
38
|
import { recordLocalInput } from "./local-inputs.mjs";
|
|
39
39
|
import YAML from "yaml";
|
|
40
40
|
import { parseConfigData } from "./config-data.mjs";
|
|
41
41
|
import { editLocal } from "./local-edit.mjs";
|
|
42
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
42
43
|
|
|
43
44
|
export const AUTOMATIONS_API = 1;
|
|
44
45
|
export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
|
|
@@ -231,9 +232,7 @@ export function readSnapshot(dep) {
|
|
|
231
232
|
export function writeSnapshot(dep, snap) {
|
|
232
233
|
const file = snapshotPath(dep);
|
|
233
234
|
mkdirSync(dirname(file), { recursive: true });
|
|
234
|
-
|
|
235
|
-
writeFileSync(tmp, JSON.stringify(snap, null, 2) + "\n");
|
|
236
|
-
renameSync(tmp, file);
|
|
235
|
+
writeThroughPrivateFile(file, `${file}.tmp-${process.pid}`, JSON.stringify(snap, null, 2) + "\n");
|
|
237
236
|
return file;
|
|
238
237
|
}
|
|
239
238
|
/** The snapshot document of one discovery: one list per kind (`triggers`, `schedules`). */
|
package/lib/bounded-read.mjs
CHANGED
|
@@ -24,3 +24,21 @@ export function readPortableBytes(path, { missingCode = "resource-not-found", in
|
|
|
24
24
|
return buffer.subarray(0, count);
|
|
25
25
|
} finally { closeSync(fd); }
|
|
26
26
|
}
|
|
27
|
+
|
|
28
|
+
/** At most `max` bytes from the start of a regular file, and its size, through one descriptor: lstat must find a
|
|
29
|
+
* regular file, the open refuses a symlink (O_NOFOLLOW) and never blocks on a FIFO swapped in meanwhile
|
|
30
|
+
* (O_NONBLOCK), and the opened file must be the one lstat found. → { bytes, size } */
|
|
31
|
+
export function readFileHead(path, max) {
|
|
32
|
+
const stat = lstatSync(path);
|
|
33
|
+
if (!stat.isFile()) throw oatsError("invalid-declaration", "not a regular file");
|
|
34
|
+
const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
|
|
35
|
+
try {
|
|
36
|
+
const opened = fstatSync(fd);
|
|
37
|
+
if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino) throw oatsError("integrity-drift", "the file changed during opening");
|
|
38
|
+
const want = Math.min(opened.size, max);
|
|
39
|
+
const buffer = Buffer.alloc(want);
|
|
40
|
+
let count = 0, size;
|
|
41
|
+
while (count < want && (size = readSync(fd, buffer, count, want - count, count)) > 0) count += size;
|
|
42
|
+
return { bytes: buffer.subarray(0, count), size: opened.size };
|
|
43
|
+
} finally { closeSync(fd); }
|
|
44
|
+
}
|
package/lib/capability-show.mjs
CHANGED
|
@@ -26,6 +26,7 @@ import { posix } from "node:path";
|
|
|
26
26
|
import YAML from "yaml";
|
|
27
27
|
import { oatsError } from "./errors.mjs";
|
|
28
28
|
import { bindRemote } from "./packages.mjs";
|
|
29
|
+
import { FILE_BUDGET } from "./remote.mjs";
|
|
29
30
|
import { locatedContractWarnings } from "./capability-contract.mjs";
|
|
30
31
|
import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
|
|
31
32
|
import { memberRowByKey } from "./workspace.mjs";
|
|
@@ -80,6 +81,9 @@ export function cutUtf8(text, limit) {
|
|
|
80
81
|
return bytes.length <= limit ? text : bytes.subarray(0, cutAt(bytes, limit)).toString("utf8");
|
|
81
82
|
}
|
|
82
83
|
|
|
84
|
+
/** Codepoint order of two strings: the order of their UTF-8 bytes, which a skill's files are listed in. */
|
|
85
|
+
export const compareCodepoints = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
|
|
86
|
+
|
|
83
87
|
const FRONT_MATTER_RE = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
|
|
84
88
|
/** The `description` of a SKILL.md's leading `---` YAML front matter (a string only), cut to DESCRIPTION_LIMIT
|
|
85
89
|
* bytes; null when there is no front matter, it does not parse, or the key is absent or not a string. */
|
|
@@ -103,6 +107,13 @@ function skillText(bytes) {
|
|
|
103
107
|
if (decodeText(bytes).binary) return null;
|
|
104
108
|
return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
|
|
105
109
|
}
|
|
110
|
+
/** A SKILL.md is read for its description up to this many bytes, the remote read budget (FILE_BUDGET). */
|
|
111
|
+
export const SKILL_DOC_BUDGET = FILE_BUDGET;
|
|
112
|
+
/** A SKILL.md's description from its bytes (`size`: the file's size): null for a file over SKILL_DOC_BUDGET, which
|
|
113
|
+
* is not read whole, or a binary one. `capabilities show` and `inspect --soul --skills` both describe by it. */
|
|
114
|
+
export function skillDocDescription(bytes, size = bytes.length) {
|
|
115
|
+
return size > SKILL_DOC_BUDGET ? null : skillDescription(skillText(bytes));
|
|
116
|
+
}
|
|
106
117
|
|
|
107
118
|
/** The catalog row a show reads: rows named `name`, narrowed by `--member <repoKey>` (a member row of that
|
|
108
119
|
* repository) or `--package <id>` (that package's row). 0 → E_CAPABILITY_UNKNOWN; >1 → E_CAPABILITY_AMBIGUOUS. */
|
|
@@ -202,8 +213,8 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
|
202
213
|
for (const skill of listed.skills) {
|
|
203
214
|
let description = null;
|
|
204
215
|
try {
|
|
205
|
-
const { bytes } = await r.readRemoteFile(ref, commit, posix.join(dir, skill.path, "SKILL.md"));
|
|
206
|
-
description =
|
|
216
|
+
const { bytes, size } = await r.readRemoteFile(ref, commit, posix.join(dir, skill.path, "SKILL.md"));
|
|
217
|
+
description = skillDocDescription(bytes, size);
|
|
207
218
|
} catch (e) { if (!isOatsError(e)) throw e; }
|
|
208
219
|
skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
|
|
209
220
|
}
|
package/lib/claim.mjs
CHANGED
|
@@ -93,10 +93,11 @@
|
|
|
93
93
|
* owner (a home's lifecycle claim: `action`, the holder's verb).
|
|
94
94
|
* It is in the record that is linked, so the claim is never
|
|
95
95
|
* seen without it; the owner's four fields win over it */
|
|
96
|
-
import { linkSync, lstatSync, readFileSync,
|
|
96
|
+
import { linkSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
|
|
97
97
|
import { randomBytes } from "node:crypto";
|
|
98
98
|
import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
|
|
99
99
|
import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
|
|
100
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
100
101
|
|
|
101
102
|
export const CLAIM_WAIT_MS = 3000;
|
|
102
103
|
const CLAIM_MAX_DEPTH = 8;
|
|
@@ -337,9 +338,7 @@ export function releaseClaim(path, me) {
|
|
|
337
338
|
/** Record (or, with null, clear) a step of the holding `me` in its claim `path`, for a takeover to
|
|
338
339
|
* end (`endHolderStep`). Only the live holder writes its claim. */
|
|
339
340
|
export function recordInClaim(path, me, step) {
|
|
340
|
-
|
|
341
|
-
writeFileSync(tmp, JSON.stringify({ ...me, ...(step ?? {}) }) + "\n", { mode: 0o600 });
|
|
342
|
-
renameSync(tmp, path);
|
|
341
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}-${me.nonce}`, JSON.stringify({ ...me, ...(step ?? {}) }) + "\n", 0o600);
|
|
343
342
|
}
|
|
344
343
|
|
|
345
344
|
/** Remove the claim `path` when its holder is verifiably gone, through the takeover above, and
|