@awebai/oats 0.47.0 → 0.49.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 +293 -41
- package/docs/capabilities.md +264 -8
- package/docs/capability-manifest.schema.json +18 -5
- package/docs/configuration.md +7 -1
- package/docs/desktop-cli-api.md +439 -40
- package/docs/desktop.md +72 -5
- package/docs/execution-targets.md +19 -1
- package/docs/implementation.md +81 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.48.0.md +106 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/schedules.md +62 -39
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +395 -52
- package/docs/workspaces.md +18 -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 +5 -2
- package/lib/core.mjs +1147 -319
- package/lib/instance-events.mjs +6 -3
- package/lib/instance-git.mjs +11 -5
- package/lib/instance-inspect.mjs +14 -3
- 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/resolve.mjs +4 -4
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +1 -0
- package/lib/servers.mjs +32 -6
- package/lib/teams-verbs.mjs +40 -9
- package/lib/tree-copy.mjs +18 -7
- package/lib/triggers.mjs +201 -65
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +12 -5
- 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
|
|
@@ -301,6 +346,10 @@ from" line and "older build" chip show the facts the server relays. Only its pul
|
|
|
301
346
|
computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
|
|
302
347
|
<path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
|
|
303
348
|
against it.
|
|
349
|
+
When this computer's OATS advertises `server-probe-features` (0.49.0), each server's roster group
|
|
350
|
+
also carries the features of the server's own OATS, as its `oats status` reports them
|
|
351
|
+
([`probe.features`](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)); a server
|
|
352
|
+
before 0.49.0 reports none, so they read as unknown.
|
|
304
353
|
|
|
305
354
|
A read waits for the server: the view says "Reading from <server>…", and gives up after about
|
|
306
355
|
45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
|
|
@@ -377,7 +426,16 @@ has reached the execution host. Both CLI installations must advertise
|
|
|
377
426
|
`session-upload`. A failed transfer leaves the draft unchanged and shows an
|
|
378
427
|
error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
379
428
|
|
|
380
|
-
##
|
|
429
|
+
## Identity marks and harness badges
|
|
430
|
+
|
|
431
|
+
Souls, capabilities and workspaces carry a coloured two-letter mark beside
|
|
432
|
+
their name. It is decorative: the name beside it is authoritative. The letters
|
|
433
|
+
come from the name without its package qualifier (what follows the last `/`
|
|
434
|
+
or `--`), and from three words or more without its first (a namespace word like
|
|
435
|
+
`oats`): the initials of the first two words, or a one-word name's first two
|
|
436
|
+
letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-harvester` KH and
|
|
437
|
+
`oats.aweb` OA. Two names can share a mark (`oats-expert` and
|
|
438
|
+
`oats-operator-expert` are both OE); the name and the colour tell them apart.
|
|
381
439
|
|
|
382
440
|
Roster rows, soul cards, the soul page, the context panel and the spawn
|
|
383
441
|
dialog show each instance's or soul's harness as a small badge, next to its
|
|
@@ -399,7 +457,11 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
399
457
|
app-owned read-only reader. All lifecycle mutations go through the
|
|
400
458
|
installed CLI via `execFile` with an absolute binary — never a shell.
|
|
401
459
|
- Task text for spawns travels via an owner-only (0600) tempfile, never
|
|
402
|
-
argv.
|
|
460
|
+
argv. A local start or restart launches only in the server-verified
|
|
461
|
+
instance home. A provider operation on an instance (its harvest included)
|
|
462
|
+
is addressed with `--home` to a home the server's roster reports, and one
|
|
463
|
+
on a soul to a soul and agents root the server lists, never a path the
|
|
464
|
+
caller names.
|
|
403
465
|
- Workspace content is treated as untrusted: symlinked directories never
|
|
404
466
|
widen the file API, and capability packages cannot read outside their
|
|
405
467
|
own tree.
|
|
@@ -413,6 +475,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
413
475
|
| 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
476
|
| 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
477
|
| 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. |
|
|
478
|
+
| 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
479
|
| 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
480
|
|
|
418
481
|
For bugs, attach the terminal output of the app (`OATS Desktop` prints
|
|
@@ -426,5 +489,9 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
|
|
|
426
489
|
certificate auto-discovery disabled) and
|
|
427
490
|
`npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
|
|
428
491
|
marked build-verify mode (inventory + strict codesign verification +
|
|
429
|
-
node-pty ABI
|
|
430
|
-
|
|
492
|
+
node-pty ABI + a headless run of the bundled backend and its liveness
|
|
493
|
+
collector from `app.asar`, no GUI launch); a local
|
|
494
|
+
interactive run may also exercise the launch phase. The headless run starts
|
|
495
|
+
the backend as the app does, checks that it answers and that it exits when its
|
|
496
|
+
stdin closes, and runs the collector once; it does not exercise the GUI or,
|
|
497
|
+
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
|
|
@@ -744,6 +757,11 @@ oats session attach --home /abs/home
|
|
|
744
757
|
harness, `shell` for a fallback shell,
|
|
745
758
|
`stopped` for an absent or dead terminal, or `not-launched`. An unavailable
|
|
746
759
|
backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
|
|
760
|
+
A home without its session receipt is refused with
|
|
761
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
|
|
762
|
+
spelling that differs from the on-disk one, the path a kernel before 0.49.0
|
|
763
|
+
used for that spelling); what
|
|
764
|
+
to do is in [souls and instances](souls-and-instances.md#retire).
|
|
747
765
|
Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
|
|
748
766
|
live claim that the instance needs input from a human, `{since, producer,
|
|
749
767
|
reason, message}`, or `null`; it is non-null only for a running harness
|
package/docs/implementation.md
CHANGED
|
@@ -62,9 +62,11 @@ published to npm. Its developer docs are in
|
|
|
62
62
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
63
63
|
| `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
64
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
65
|
+
| `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 |
|
|
66
|
+
| `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
67
|
| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
|
|
66
68
|
| `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 |
|
|
69
|
+
| `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
70
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
69
71
|
| `servers.mjs` | routing commands to a registered server |
|
|
70
72
|
| `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 |
|
|
@@ -321,6 +323,16 @@ install, and the gate requires it. `test/continuous-integration.test.mjs` pins
|
|
|
321
323
|
that job against `desktop-build`: change how one installs or tests Desktop and
|
|
322
324
|
the other changes with it.
|
|
323
325
|
|
|
326
|
+
The Desktop suite runs in the root shards and in `desktop-standalone`, and
|
|
327
|
+
`desktop-standalone` is its release gate. `test/release-workflow.test.mjs` no
|
|
328
|
+
longer runs it nested inside a root shard: it checks that the Desktop scripts
|
|
329
|
+
the release invokes exist. `test/helpers/nested-test-failure.mjs` remains the
|
|
330
|
+
way to build a readable failure message from a nested `node --test` run's
|
|
331
|
+
output. The message names the failing tests (TAP or spec reporter) with their
|
|
332
|
+
location and error, then gives bounded stdout and stderr tails, and its size
|
|
333
|
+
is capped. It is built only when the run failed, and it never throws: if
|
|
334
|
+
reading the failures fails, the message says so and still carries the tails.
|
|
335
|
+
|
|
324
336
|
Cross-package tests that import both the kernel and Desktop belong under root
|
|
325
337
|
`test/`; install dependencies at the root and in `packages/desktop` before
|
|
326
338
|
running those tests. The schedule
|
|
@@ -361,6 +373,10 @@ and acts on every existing session through its recorded socket
|
|
|
361
373
|
fixture, with no user configuration unless the test asks for it;
|
|
362
374
|
`oatsSocket()` is the socket `-L oats` resolves to there. Its restore
|
|
363
375
|
function kills that server, by socket.
|
|
376
|
+
- A test may instead start its own server on a private socket it creates
|
|
377
|
+
under the temporary directory (`tmux -S <socket>`) and kill that server by
|
|
378
|
+
its socket, as the older live tests in `test/desktop-tmux-target.test.mjs`
|
|
379
|
+
(base-index, wheel, drag, Slice G) do.
|
|
364
380
|
- The shared fixture (`test/helpers/v2-deployment.mjs`) gives every command
|
|
365
381
|
it runs a private `TMUX_TMPDIR` too, so a test with a fake `tmux` on `PATH`
|
|
366
382
|
cannot reach a real server either. A fake answers what the kernel asks:
|
|
@@ -368,3 +384,67 @@ and acts on every existing session through its recorded socket
|
|
|
368
384
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
369
385
|
- A server a test starts is killed by its socket, never by name and never
|
|
370
386
|
with a bare `tmux kill-server`.
|
|
387
|
+
|
|
388
|
+
Nor does a test depend on where or how the suite runs:
|
|
389
|
+
|
|
390
|
+
- A worker whose working directory is inside an instance home (a developer
|
|
391
|
+
agent running the suite from its work tree) is that instance to the
|
|
392
|
+
kernel. `isolateSessionEnvironment` leaves it; a fixture that builds its
|
|
393
|
+
environment itself calls `leaveEnclosingInstance(base)` and moves back
|
|
394
|
+
when it is done.
|
|
395
|
+
- `isolateSessionEnvironment` drops `CLAUDECODE`, which a worker inherits
|
|
396
|
+
from a Claude Code session: a server the worker starts would hold it.
|
|
397
|
+
- An expected path is built on a canonical fixture base,
|
|
398
|
+
`realpathSync(mkdtempSync(…))`: the platform's temporary directory can be
|
|
399
|
+
a symlink (`/var` on macOS), and the kernel builds the paths it reports on
|
|
400
|
+
its working directory, which the OS gives as the physical path.
|
|
401
|
+
- A probe of the host that reads under `HOME` (the scheduler's installed
|
|
402
|
+
unit) runs with the fixture's own `HOME`.
|
|
403
|
+
- A fixture the filesystem may not represent (a file name that is not valid
|
|
404
|
+
UTF-8, which APFS refuses) is probed in the fixture directory and skipped
|
|
405
|
+
with its reason only when refused; Linux CI runs it.
|
|
406
|
+
|
|
407
|
+
A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
|
|
408
|
+
unit, a live operator tmux server and Apple git, run from inside an instance
|
|
409
|
+
home. A pull request that could not be run there says so in its hand-over. The
|
|
410
|
+
suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
|
|
411
|
+
with `require`), git ≥ 2.45, lsof and tmux (awebai/oats#783). The
|
|
412
|
+
helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
|
|
413
|
+
shared fixture (`v2Deployment`) applies all of it, so a suite built on it
|
|
414
|
+
inherits it (awebai/oats#816):
|
|
415
|
+
|
|
416
|
+
- **A short base.** `fixtureBase(prefix)` makes the fixture directory under
|
|
417
|
+
the platform's temporary directory, or under `/tmp` when that is longer than
|
|
418
|
+
20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
|
|
419
|
+
realpath, taken once.
|
|
420
|
+
- **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
|
|
421
|
+
name or branch segment) and `pathOfLength(base, n)` (an absolute path under
|
|
422
|
+
the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
|
|
423
|
+
the platform (255/1024 on macOS, 255/4096 on Linux), measured from the
|
|
424
|
+
actual base. A "too long" test then exercises the kernel's bound, never the
|
|
425
|
+
filesystem's.
|
|
426
|
+
- **An explicit environment for every child.** `fixtureEnv(base)` is what
|
|
427
|
+
every child the fixture starts gets, and `fx.inEnv` applies the same rules
|
|
428
|
+
to the test process for an in-process kernel call. It sets `HOME` and the XDG
|
|
429
|
+
base directories under the base, and `GIT_CONFIG_NOSYSTEM=1`,
|
|
430
|
+
`GIT_CONFIG_GLOBAL=/dev/null` and `GIT_TERMINAL_PROMPT=0`, so no host git
|
|
431
|
+
configuration or credential helper is read. It removes every `*_PROXY`,
|
|
432
|
+
`CLAUDECODE` and git configuration passed through the environment. PATH
|
|
433
|
+
starts with `launchctl` and `systemctl` stubs that answer as a service
|
|
434
|
+
manager with nothing loaded. A test that needs another answer puts its own
|
|
435
|
+
stub ahead of them.
|
|
436
|
+
- **The same rules under real tmux.** `isolateSessionEnvironment` applies the
|
|
437
|
+
same git, XDG and proxy rules. Its PATH stays its own small set of tools, so
|
|
438
|
+
no host service manager is reachable at all.
|
|
439
|
+
- **No leftover processes.** The fixture's cleanup fails when a process still
|
|
440
|
+
works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
|
|
441
|
+
`processesInHome` (lsof). It catches a hook's or a CLI's grandchild that
|
|
442
|
+
outlived the test, once its parent has exited. The scan leaves out its caller
|
|
443
|
+
and the caller's direct children, so a test's own forgotten child is not
|
|
444
|
+
found here: that is the test's bug to fix. A process still exiting gets 2 s.
|
|
445
|
+
Nothing is killed, the base is removed, and the failure names each pid and
|
|
446
|
+
command. A test that leaves a process running on purpose (a group the kernel
|
|
447
|
+
must not signal) ends it itself before that check, on failure too: node:test
|
|
448
|
+
runs `t.after` hooks in the order they were added, so its own hook added
|
|
449
|
+
after `t.after(fx.cleanup)` runs too late (`test/worktree-event.test.mjs`
|
|
450
|
+
ends them inside its cleanup hook, ahead of `fx.cleanup`).
|
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
|