@awebai/oats 0.48.0 → 0.50.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 +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/desktop.md
CHANGED
|
@@ -45,6 +45,15 @@ it, but opening a terminal will fail until tmux is installed. The DEB
|
|
|
45
45
|
declares the dependency; for the AppImage install it yourself
|
|
46
46
|
(`apt install tmux`, `dnf install tmux`, …) and verify with `tmux -V`.
|
|
47
47
|
|
|
48
|
+
The AppImage mounts itself with FUSE, which some current distributions
|
|
49
|
+
don't install. Without it, start the AppImage with
|
|
50
|
+
`--appimage-extract-and-run`. Don't extract the image and run its `AppRun`
|
|
51
|
+
yourself: started that way, Desktop can't tell which entries in `PATH`,
|
|
52
|
+
`XDG_DATA_DIRS`, `LD_LIBRARY_PATH` and `GSETTINGS_SCHEMA_DIR` the image
|
|
53
|
+
added, so the programs it starts keep them, among them the tmux server it
|
|
54
|
+
starts and every agent pane on it (see
|
|
55
|
+
[the environment of the programs Desktop starts](../packages/desktop/README.md#the-environment-of-the-programs-desktop-starts)).
|
|
56
|
+
|
|
48
57
|
### The `oats` CLI
|
|
49
58
|
|
|
50
59
|
Reads (roster, hierarchy, files, terminals) work with no CLI at all.
|
|
@@ -167,11 +176,47 @@ pills (**All**, then one per repository, each with its count) show one
|
|
|
167
176
|
repository at a time; "N of M shown" appears while a pill or the search
|
|
168
177
|
narrows the list.
|
|
169
178
|
|
|
179
|
+
A soul's page (open a soul from **Workspace › Souls**) ends with
|
|
180
|
+
**Instructions**, what its instances are told: the soul's own `AGENTS.md`,
|
|
181
|
+
read like a capability's injected instructions (a navigation tree on the left,
|
|
182
|
+
the file on the right), at its path in the soul's repository. It comes from the
|
|
183
|
+
same inspection as the rest of the page, so **Refresh** re-reads it and keeps
|
|
184
|
+
what you had open, and your place in it. A file over 200,000 characters is
|
|
185
|
+
shown cut, and says so.
|
|
186
|
+
|
|
187
|
+
With an OATS that composes a soul's instructions (0.46.0 and later), the tree
|
|
188
|
+
also has **Instance**: its **AGENTS.md**, *after spawn, with injects*, is the
|
|
189
|
+
file a spawn of this soul on this computer would write, with one entry per part
|
|
190
|
+
(the soul's own text, then each block OATS and the soul's capabilities add, in
|
|
191
|
+
order). Open it to read the whole document; choose a part to go to it. Each
|
|
192
|
+
part's header says where it comes from (**From this soul** or **Injected by …**)
|
|
193
|
+
and names its file; a capability's part has **Open capability**, and **Copy
|
|
194
|
+
composed AGENTS.md** copies the exact file. When the soul can't be composed
|
|
195
|
+
here, the group says so and the problem shows at the top of the page. For a
|
|
196
|
+
soul on another machine (a server workspace), the page shows the composed file
|
|
197
|
+
when that machine supports it: this computer's OATS must be 0.49.0 or later, to
|
|
198
|
+
pass on what each server reports about itself, and the server's OATS must say
|
|
199
|
+
it composes a soul's instructions (0.49.0 and later report this). Until a
|
|
200
|
+
server reports it (an older server, or one whose last read failed), its soul
|
|
201
|
+
pages show only the soul's own `AGENTS.md`, with no **Instance** group.
|
|
202
|
+
|
|
170
203
|
The **Spawn** dialog's left column, **What will be created**, starts with the
|
|
171
204
|
new instance's name and its home. Then come where it works, its harness and
|
|
172
205
|
model (with where that choice came from), its default team and the teams it may
|
|
173
206
|
also join, and its relationship when it has one. Under them are its core
|
|
174
|
-
capabilities and its other capabilities.
|
|
207
|
+
capabilities and its other capabilities.
|
|
208
|
+
|
|
209
|
+
When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
|
|
210
|
+
names them, in the order they run, and says this can take several minutes. Such
|
|
211
|
+
a spawn may run for a long time: its roster row reads **Setting up worktree…**
|
|
212
|
+
until the worktree is ready, and offers no actions meanwhile. If the spawn was
|
|
213
|
+
interrupted or a capability couldn't set up the worktree, the spawn was rolled
|
|
214
|
+
back, and the notification says that nothing was created. A home whose spawn
|
|
215
|
+
didn't finish its cleanup reads **Spawn didn't finish**, and one whose retire
|
|
216
|
+
didn't finish reads **Retire didn't finish**; both offer only **Retire
|
|
217
|
+
instance…**, which completes them. A server spawn whose worktree hooks take
|
|
218
|
+
more than about a minute is not yet supported from the Desktop; use the CLI on
|
|
219
|
+
the server. Every dropdown in the app has the
|
|
175
220
|
same themed look, and its open list follows the light or dark theme.
|
|
176
221
|
|
|
177
222
|
## One workspace, several machines
|
|
@@ -243,6 +288,19 @@ arguments as written, an operation and its home), its run state and where it
|
|
|
243
288
|
comes from. Writing summaries needs OATS 0.43 or later; an older OATS still
|
|
244
289
|
shows the ones it reports.
|
|
245
290
|
|
|
291
|
+
A trigger can take its events from a source a capability declares instead of
|
|
292
|
+
GitHub pull requests (OATS 0.50.0 or later). Its page shows the source and
|
|
293
|
+
what the trigger passes to it, what the source's last poll found or why it
|
|
294
|
+
failed, and which events OATS refused or the source skipped. Text that comes
|
|
295
|
+
from the source, from the trigger's file or from the capability's manifest is
|
|
296
|
+
shown as a quote with a line saying whose it is; it is never a link or a
|
|
297
|
+
button. **Test** on a pull-request trigger reads GitHub and reports what would
|
|
298
|
+
fire. **Test** on such a capability trigger runs the capability's source
|
|
299
|
+
command on this computer, so it first shows what will run and with which
|
|
300
|
+
parameters, and runs it once only when you press **Run test**. Nothing is
|
|
301
|
+
recorded or spawned, and testing does not trust or start a trigger that this
|
|
302
|
+
computer doesn't trust.
|
|
303
|
+
|
|
246
304
|
The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
|
|
247
305
|
the schedule to the newly created home, preserving that agent's identity and
|
|
248
306
|
work. A wake starts that same home if it is stopped, then sends the saved
|
|
@@ -301,6 +359,10 @@ from" line and "older build" chip show the facts the server relays. Only its pul
|
|
|
301
359
|
computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
|
|
302
360
|
<path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
|
|
303
361
|
against it.
|
|
362
|
+
When this computer's OATS advertises `server-probe-features` (0.49.0), each server's roster group
|
|
363
|
+
also carries the features of the server's own OATS, as its `oats status` reports them
|
|
364
|
+
([`probe.features`](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)); a server
|
|
365
|
+
before 0.49.0 reports none, so they read as unknown.
|
|
304
366
|
|
|
305
367
|
A read waits for the server: the view says "Reading from <server>…", and gives up after about
|
|
306
368
|
45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
|
|
@@ -377,7 +439,16 @@ has reached the execution host. Both CLI installations must advertise
|
|
|
377
439
|
`session-upload`. A failed transfer leaves the draft unchanged and shows an
|
|
378
440
|
error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
379
441
|
|
|
380
|
-
##
|
|
442
|
+
## Identity marks and harness badges
|
|
443
|
+
|
|
444
|
+
Souls, capabilities and workspaces carry a coloured two-letter mark beside
|
|
445
|
+
their name. It is decorative: the name beside it is authoritative. The letters
|
|
446
|
+
come from the name without its package qualifier (what follows the last `/`
|
|
447
|
+
or `--`), and from three words or more without its first (a namespace word like
|
|
448
|
+
`oats`): the initials of the first two words, or a one-word name's first two
|
|
449
|
+
letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-harvester` KH and
|
|
450
|
+
`oats.aweb` OA. Two names can share a mark (`oats-expert` and
|
|
451
|
+
`oats-operator-expert` are both OE); the name and the colour tell them apart.
|
|
381
452
|
|
|
382
453
|
Roster rows, soul cards, the soul page, the context panel and the spawn
|
|
383
454
|
dialog show each instance's or soul's harness as a small badge, next to its
|
|
@@ -399,7 +470,11 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
399
470
|
app-owned read-only reader. All lifecycle mutations go through the
|
|
400
471
|
installed CLI via `execFile` with an absolute binary — never a shell.
|
|
401
472
|
- Task text for spawns travels via an owner-only (0600) tempfile, never
|
|
402
|
-
argv.
|
|
473
|
+
argv. A local start or restart launches only in the server-verified
|
|
474
|
+
instance home. A provider operation on an instance (its harvest included)
|
|
475
|
+
is addressed with `--home` to a home the server's roster reports, and one
|
|
476
|
+
on a soul to a soul and agents root the server lists, never a path the
|
|
477
|
+
caller names.
|
|
403
478
|
- Workspace content is treated as untrusted: symlinked directories never
|
|
404
479
|
widen the file API, and capability packages cannot read outside their
|
|
405
480
|
own tree.
|
|
@@ -413,6 +488,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
413
488
|
| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
|
|
414
489
|
| Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
|
|
415
490
|
| macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
|
|
491
|
+
| Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
|
|
416
492
|
| Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use the workspace switcher → Add workspace to select the right folder. |
|
|
417
493
|
|
|
418
494
|
For bugs, attach the terminal output of the app (`OATS Desktop` prints
|
|
@@ -426,5 +502,9 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
|
|
|
426
502
|
certificate auto-discovery disabled) and
|
|
427
503
|
`npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
|
|
428
504
|
marked build-verify mode (inventory + strict codesign verification +
|
|
429
|
-
node-pty ABI
|
|
430
|
-
|
|
505
|
+
node-pty ABI + a headless run of the bundled backend and its liveness
|
|
506
|
+
collector from `app.asar`, no GUI launch); a local
|
|
507
|
+
interactive run may also exercise the launch phase. The headless run starts
|
|
508
|
+
the backend as the app does, checks that it answers and that it exits when its
|
|
509
|
+
stdin closes, and runs the collector once; it does not exercise the GUI or,
|
|
510
|
+
on Linux, the AppImage's launcher and runtime.
|
|
@@ -326,7 +326,11 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
|
|
|
326
326
|
`OATS_PREVIOUS_RUNTIME`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
|
|
327
327
|
`OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
|
|
328
328
|
the login shell, honoured only for a process whose `HOME` is not your home
|
|
329
|
-
directory; a launch configuration cannot set it),
|
|
329
|
+
directory; a launch configuration cannot set it),
|
|
330
|
+
`OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`
|
|
331
|
+
and `OATS_TEST_PROCESS_START_PS` (below), a `worktree` hook's tree
|
|
332
|
+
(`OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`, `OATS_TREE_MEMBER`,
|
|
333
|
+
`OATS_TREE_BASE`, `OATS_TREE_BASE_OID`, `OATS_PURPOSE`, `OATS_TREE_ORIGIN`), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
|
|
330
334
|
`OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
|
|
331
335
|
`OATS_TEAMS_SOURCE`, `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
|
|
332
336
|
`OATS_DEFAULT_TEAM_FROM`, `OATS_WORKSPACE_NAME`, `OATS_WORKSPACE_KEY`); and
|
|
@@ -336,6 +340,15 @@ for. Other `OATS_` variables you export (`OATS_HOME_DIR`,
|
|
|
336
340
|
with your login environment (above). An agent's plain `oats` finds its
|
|
337
341
|
deployment from its home.
|
|
338
342
|
|
|
343
|
+
`OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS` is another test seam, not a setting: a
|
|
344
|
+
positive whole number of milliseconds replaces the fixed 30-minute timeout of
|
|
345
|
+
[`worktree` hooks](capabilities.md#the-worktree-event), so the kernel's own
|
|
346
|
+
tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
|
|
347
|
+
10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
|
|
348
|
+
the kernel read a process's start time with `ps`, as on a host without
|
|
349
|
+
`/proc` (macOS), on a host that has it. A launch configuration cannot set
|
|
350
|
+
any of them. Do not set them in a deployment.
|
|
351
|
+
|
|
339
352
|
**An instance creates an agents' session or window without its own
|
|
340
353
|
environment.** Nothing of an instance's environment reaches a server or a
|
|
341
354
|
pane through the calls that create an agents' session or window. A harness
|
|
@@ -473,12 +486,33 @@ tmux -L oats kill-server # replace it: ends EVERY sessio
|
|
|
473
486
|
- `-L oats` reaches the server of the environment you type it in
|
|
474
487
|
(`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
|
|
475
488
|
row in `oats status --json`: `tmux -S <socket> …`.
|
|
476
|
-
- A tmux server whose socket file is missing
|
|
477
|
-
|
|
478
|
-
that
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
489
|
+
- <a id="missing-socket"></a>A tmux server whose socket file is missing
|
|
490
|
+
(`error connecting to <socket> (No such file or directory)`) is not proof
|
|
491
|
+
that it exited: a server outlives its removed socket file (a
|
|
492
|
+
temporary-files cleaner, a removed socket directory), and tmux gives the
|
|
493
|
+
same words after a reboot, when the server is gone. So OATS reads it as
|
|
494
|
+
stopped only when no process works in the instance's home
|
|
495
|
+
([the process scan](souls-and-instances.md#the-process-scan)): the row is
|
|
496
|
+
not running and a start creates the window again, as after a reboot. When
|
|
497
|
+
a process works there, or the scan cannot run, the state is not
|
|
498
|
+
established: `oats status` shows the row `running: null` with
|
|
499
|
+
`runtimeState: "unreachable"` and a `runtimeError` that names the
|
|
500
|
+
processes (pid and program, at most five) or the scan's error;
|
|
501
|
+
`oats session start` and `restart` refuse with `E_SESSION_UNKNOWN` and
|
|
502
|
+
create no server at that path; `oats instance stop` refuses with
|
|
503
|
+
`E_SESSION_UNAVAILABLE`, never "already idle". tmux recreates a removed
|
|
504
|
+
socket file when its server process receives `SIGUSR1`
|
|
505
|
+
(`kill -USR1 <pid of that tmux server>`); OATS names that and never sends
|
|
506
|
+
it. Any process working in the
|
|
507
|
+
home counts, a shell left in that directory included, as for retire: the
|
|
508
|
+
message names its pid and program, so end it or leave the directory. A
|
|
509
|
+
socket file no server listens on (`no server running on <socket>`) is
|
|
510
|
+
definitive: stopped, with no scan
|
|
511
|
+
([#624](https://github.com/awebai/oats/issues/624)). This holds for every
|
|
512
|
+
tmux server OATS reads, not only the `oats` server, and for a home that
|
|
513
|
+
records no socket and reads your default server. A home that records
|
|
514
|
+
neither a socket nor a launch (`--no-launch`) reads as not running
|
|
515
|
+
whatever works in it.
|
|
482
516
|
|
|
483
517
|
<a id="existing-instances"></a>
|
|
484
518
|
#### Existing instances
|
|
@@ -569,6 +603,8 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
|
|
|
569
603
|
pane is reused in place. A missing window, or one whose tmux server cannot
|
|
570
604
|
be reached, is created again on the OATS tmux server, and the start warns when that is
|
|
571
605
|
not the server the home recorded ([Existing instances](#existing-instances)).
|
|
606
|
+
A server whose socket file is missing counts as gone only when no process
|
|
607
|
+
works in the home ([missing socket file](#missing-socket)).
|
|
572
608
|
- A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
|
|
573
609
|
starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
|
|
574
610
|
is refused (`E_INSTANCE_RETIRING`).
|
|
@@ -730,7 +766,10 @@ children and uncommitted work, with a `planRevision`. `--apply --plan-revision
|
|
|
730
766
|
<rev> --idempotency-key <key>` stops the instance and its recorded children
|
|
731
767
|
first (`--no-recursive` stops only the instance), with the same bounded
|
|
732
768
|
SIGTERM. Restart the instance later with `oats session start` or
|
|
733
|
-
`oats session restart`.
|
|
769
|
+
`oats session restart`. An instance whose recorded tmux socket file is
|
|
770
|
+
missing while a process works in its home, or the process scan cannot run,
|
|
771
|
+
is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
|
|
772
|
+
stopped ([missing socket file](#missing-socket)).
|
|
734
773
|
|
|
735
774
|
### Inspect, input and attach
|
|
736
775
|
|
|
@@ -745,7 +784,9 @@ oats session attach --home /abs/home
|
|
|
745
784
|
`stopped` for an absent or dead terminal, or `not-launched`. An unavailable
|
|
746
785
|
backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
|
|
747
786
|
A home without its session receipt is refused with
|
|
748
|
-
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for
|
|
787
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
|
|
788
|
+
spelling that differs from the on-disk one, the path a kernel before 0.49.0
|
|
789
|
+
used for that spelling); what
|
|
749
790
|
to do is in [souls and instances](souls-and-instances.md#retire).
|
|
750
791
|
Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
|
|
751
792
|
live claim that the instance needs input from a human, `{since, producer,
|
package/docs/implementation.md
CHANGED
|
@@ -58,14 +58,19 @@ published to npm. Its developer docs are in
|
|
|
58
58
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
59
59
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
60
60
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
61
|
+
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
62
|
+
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
61
63
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
62
64
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
63
65
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
64
66
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
67
|
+
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
|
|
68
|
+
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
|
|
65
69
|
| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
|
|
66
70
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
67
|
-
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
|
|
71
|
+
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
68
72
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
73
|
+
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
69
74
|
| `servers.mjs` | routing commands to a registered server |
|
|
70
75
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
71
76
|
| `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
|
|
@@ -321,6 +326,16 @@ install, and the gate requires it. `test/continuous-integration.test.mjs` pins
|
|
|
321
326
|
that job against `desktop-build`: change how one installs or tests Desktop and
|
|
322
327
|
the other changes with it.
|
|
323
328
|
|
|
329
|
+
The Desktop suite runs in the root shards and in `desktop-standalone`, and
|
|
330
|
+
`desktop-standalone` is its release gate. `test/release-workflow.test.mjs` no
|
|
331
|
+
longer runs it nested inside a root shard: it checks that the Desktop scripts
|
|
332
|
+
the release invokes exist. `test/helpers/nested-test-failure.mjs` remains the
|
|
333
|
+
way to build a readable failure message from a nested `node --test` run's
|
|
334
|
+
output. The message names the failing tests (TAP or spec reporter) with their
|
|
335
|
+
location and error, then gives bounded stdout and stderr tails, and its size
|
|
336
|
+
is capped. It is built only when the run failed, and it never throws: if
|
|
337
|
+
reading the failures fails, the message says so and still carries the tails.
|
|
338
|
+
|
|
324
339
|
Cross-package tests that import both the kernel and Desktop belong under root
|
|
325
340
|
`test/`; install dependencies at the root and in `packages/desktop` before
|
|
326
341
|
running those tests. The schedule
|
|
@@ -361,6 +376,10 @@ and acts on every existing session through its recorded socket
|
|
|
361
376
|
fixture, with no user configuration unless the test asks for it;
|
|
362
377
|
`oatsSocket()` is the socket `-L oats` resolves to there. Its restore
|
|
363
378
|
function kills that server, by socket.
|
|
379
|
+
- A test may instead start its own server on a private socket it creates
|
|
380
|
+
under the temporary directory (`tmux -S <socket>`) and kill that server by
|
|
381
|
+
its socket, as the older live tests in `test/desktop-tmux-target.test.mjs`
|
|
382
|
+
(base-index, wheel, drag, Slice G) do.
|
|
364
383
|
- The shared fixture (`test/helpers/v2-deployment.mjs`) gives every command
|
|
365
384
|
it runs a private `TMUX_TMPDIR` too, so a test with a fake `tmux` on `PATH`
|
|
366
385
|
cannot reach a real server either. A fake answers what the kernel asks:
|
|
@@ -387,3 +406,57 @@ Nor does a test depend on where or how the suite runs:
|
|
|
387
406
|
- A fixture the filesystem may not represent (a file name that is not valid
|
|
388
407
|
UTF-8, which APFS refuses) is probed in the fixture directory and skipped
|
|
389
408
|
with its reason only when refused; Linux CI runs it.
|
|
409
|
+
|
|
410
|
+
A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
|
|
411
|
+
unit, a live operator tmux server and Apple git, run from inside an instance
|
|
412
|
+
home. A pull request that could not be run there says so in its hand-over. The
|
|
413
|
+
suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
|
|
414
|
+
with `require`), git ≥ 2.45, tmux, and lsof where `/proc` cannot be read
|
|
415
|
+
(awebai/oats#783, #625). The
|
|
416
|
+
helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
|
|
417
|
+
shared fixture (`v2Deployment`) applies all of it, so a suite built on it
|
|
418
|
+
inherits it (awebai/oats#816):
|
|
419
|
+
|
|
420
|
+
- **A short base.** `fixtureBase(prefix)` makes the fixture directory under
|
|
421
|
+
the platform's temporary directory, or under `/tmp` when that is longer than
|
|
422
|
+
20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
|
|
423
|
+
realpath, taken once.
|
|
424
|
+
- **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
|
|
425
|
+
name or branch segment) and `pathOfLength(base, n)` (an absolute path under
|
|
426
|
+
the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
|
|
427
|
+
the platform (255/1024 on macOS, 255/4096 on Linux), measured from the
|
|
428
|
+
actual base. A "too long" test then exercises the kernel's bound, never the
|
|
429
|
+
filesystem's.
|
|
430
|
+
- **An explicit environment for every child.** `fixtureEnv(base)` is what
|
|
431
|
+
every child the fixture starts gets, and `fx.inEnv` applies the same rules
|
|
432
|
+
to the test process for an in-process kernel call. It sets `HOME` and the XDG
|
|
433
|
+
base directories under the base, and `GIT_CONFIG_NOSYSTEM=1`,
|
|
434
|
+
`GIT_CONFIG_GLOBAL=/dev/null` and `GIT_TERMINAL_PROMPT=0`, so no host git
|
|
435
|
+
configuration or credential helper is read. It removes every `*_PROXY`,
|
|
436
|
+
`CLAUDECODE` and git configuration passed through the environment. PATH
|
|
437
|
+
starts with `launchctl` and `systemctl` stubs that answer as a service
|
|
438
|
+
manager with nothing loaded. A test that needs another answer puts its own
|
|
439
|
+
stub ahead of them.
|
|
440
|
+
- **The same rules under real tmux.** `isolateSessionEnvironment` applies the
|
|
441
|
+
same git, XDG and proxy rules. Its PATH stays its own small set of tools, so
|
|
442
|
+
no host service manager is reachable at all.
|
|
443
|
+
- **No leftover processes.** The fixture's cleanup fails when a process still
|
|
444
|
+
works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
|
|
445
|
+
`processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
|
|
446
|
+
outlived the test, once its parent has exited. The scan leaves out its caller
|
|
447
|
+
and the caller's direct children, so a test's own forgotten child is not
|
|
448
|
+
found here: that is the test's bug to fix. A process still exiting gets 2 s.
|
|
449
|
+
Nothing is killed, the base is removed, and the failure names each pid and
|
|
450
|
+
command. A test that leaves a process running on purpose (a group the kernel
|
|
451
|
+
must not signal) ends it itself before that check, on failure too, through
|
|
452
|
+
`fx.beforeCleanup(fn)`: the cleanup runs those synchronous functions first,
|
|
453
|
+
in order, and still runs when one throws. Never end it with a later `t.after`: node:test
|
|
454
|
+
runs `t.after` hooks in the order they were added, so a hook added after the
|
|
455
|
+
fixture's runs after the check (`test/worktree-event.test.mjs`).
|
|
456
|
+
- **Cleanup even when a test fails.** Pass the test context,
|
|
457
|
+
`v2Deployment({ t })`: the fixture registers its own cleanup with
|
|
458
|
+
`t.after` when it is created, so a test that throws, rejects or times out
|
|
459
|
+
still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
|
|
460
|
+
and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
|
|
461
|
+
`t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
|
|
462
|
+
built removes its base itself.
|
package/docs/integrations.md
CHANGED
|
@@ -40,7 +40,7 @@ arrives from.
|
|
|
40
40
|
```yaml
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
|
-
oats.okf:
|
|
43
|
+
oats.okf: v5.0.0
|
|
44
44
|
oats.aweb: v1.21.1
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
@@ -78,15 +78,17 @@ operations in full.
|
|
|
78
78
|
|
|
79
79
|
| Slot | Provider | Needs on the host | Documentation |
|
|
80
80
|
| --- | --- | --- | --- |
|
|
81
|
-
| `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` and `gh` for
|
|
81
|
+
| `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
|
|
82
82
|
| `messaging` | `oats.aweb` | the `aw` CLI at 1.36.13 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
|
|
83
83
|
| `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
|
|
84
84
|
| `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
|
|
85
85
|
|
|
86
86
|
- **`oats.okf`** consults the soul's external OKF bases, keeps instance
|
|
87
|
-
knowledge, and
|
|
88
|
-
|
|
89
|
-
`knowledge
|
|
87
|
+
knowledge, and briefs eligible working instances to propose durable claims
|
|
88
|
+
at checkpoints by directly spawning `oats.okf/knowledge-harvester`. The
|
|
89
|
+
soul-only `knowledge: { harvest: off }` forbids harvest while retaining
|
|
90
|
+
consultation. No host switch or automatic transcript/retire capture remains;
|
|
91
|
+
`knowledge-maintainer` reviews the resulting Git PRs.
|
|
90
92
|
- **`oats.aweb`** mints a messaging identity for each instance at spawn and
|
|
91
93
|
removes it at retire, contributes the aweb messaging skills, and wires the
|
|
92
94
|
channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
|