@awebai/oats 0.69.4 → 0.69.6
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 +141 -364
- package/docs/configuration.md +12 -0
- package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
- package/docs/design/2026-10-29-warm-reader.md +261 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +258 -13
- package/docs/execution-targets.md +36 -5
- package/docs/implementation.md +34 -9
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +18 -8
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.5.md +146 -0
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +23 -5
- package/docs/upgrading.md +20 -5
- package/docs/workspaces.md +2 -2
- package/lib/agents-root.mjs +51 -0
- package/lib/argv.mjs +41 -0
- package/lib/automation-api.mjs +7 -0
- package/lib/automation-scope.mjs +37 -0
- package/lib/automations.mjs +63 -12
- package/lib/captured-context.mjs +12 -0
- package/lib/compile-cache.mjs +36 -0
- package/lib/core.mjs +39 -1348
- package/lib/deployment-path.mjs +127 -0
- package/lib/deployments.mjs +2 -2
- package/lib/drift.mjs +95 -0
- package/lib/hot-reads.mjs +137 -0
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-address.mjs +21 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-lifecycle.mjs +4 -16
- package/lib/instance-listing.mjs +738 -0
- package/lib/instance-resolution.mjs +5 -166
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/materialize.mjs +2 -87
- package/lib/member-clone.mjs +192 -0
- package/lib/package-catalog.mjs +93 -0
- package/lib/packages.mjs +4 -24
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/reserved-launch-env.mjs +20 -0
- package/lib/resolved-deployment.mjs +13 -5
- package/lib/roster-read.mjs +199 -0
- package/lib/schedule.mjs +5 -29
- package/lib/semver.mjs +12 -0
- package/lib/servers.mjs +10 -12
- package/lib/session-end.mjs +3 -2
- package/lib/session-input.mjs +35 -11
- package/lib/session-inspect.mjs +219 -0
- package/lib/soul-listing.mjs +216 -0
- package/lib/status-words.mjs +30 -0
- package/lib/version.mjs +9 -0
- package/lib/workspace-read.mjs +160 -0
- package/lib/write-file-atomic.mjs +28 -0
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +1 -0
- package/packages/client/cli-probe-contract.mjs +4 -2
- package/packages/client/deployment-observer.mjs +8 -3
- package/packages/client/deployment-panel.mjs +17 -1
- package/packages/client/deployment-read-cli.mjs +48 -27
- package/packages/client/own-codes.mjs +3 -0
- package/packages/client/warm-reader.mjs +241 -0
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/read.mjs +59 -11
- package/packages/tui/lib/store.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/desktop-cli-api.md
CHANGED
|
@@ -73,6 +73,10 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
73
73
|
at every run and keeps no answer, so read it again after a tmux upgrade.
|
|
74
74
|
The feature is in every kernel's list that has the field, whatever this
|
|
75
75
|
host's tmux: gate on the feature, then read the field.
|
|
76
|
+
- `readerApi` (feature `warm-reader`) is the protocol of `oats reader
|
|
77
|
+
--stdio`, which the reader's hello repeats. Start a reader only where the
|
|
78
|
+
probe lists both the feature and `readerApi: 1`
|
|
79
|
+
([The warm reader](#the-warm-reader)).
|
|
76
80
|
- In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
|
|
77
81
|
|
|
78
82
|
### Features
|
|
@@ -135,7 +139,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
135
139
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
136
140
|
| `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
|
|
137
141
|
| `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
138
|
-
| `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
142
|
+
| `session-inspect-running` | `running` on every successful `session inspect --json` result: `true` exactly when `oats status --json` reads the same observation as `running: true` (a live non-shell process in the agent pane, a harness behind a wrapper shell included), `false` for a fallback shell, an absent or dead pane, a missing home and a home that never launched. It is endpoint activity, not health, readiness, busy or idle, the executable's identity or a consumed wake. A failed observation stays an error, never `false`, a gone tmux server included (status reads that row `running: false`; inspect answers `E_SESSION_UNAVAILABLE`), and so does a process scan that cannot establish a fallback shell ([#1641](https://github.com/awebai/oats/issues/1641): status reads it `null`); `state` and its enum are unchanged. `E_RUNTIME_AUTHORITY_MISMATCH` carries `details.fields`, the differing fields among `launched`, `tmux.session`, `tmux.window`, `tmux.socket`, never their values. Remote inspect relays the execution host's answer; a host without the feature omits `running`, and nothing adds it ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
139
143
|
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
140
144
|
| `session-attach-no-status-line` | `oats session attach … --no-status-line`, local and `--server`: a viewer without a detach key, without its status line (`Shift+PgUp or C-b [ to scroll back`), for a caller that shows the scroll keys itself ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe: a kernel without it ignores the flag and shows the line. A routed attach sends it to any host, with no probe of its own | |
|
|
141
145
|
| `session-attach-prefix-scroll` | `sessionViewer: {prefixScroll}` on `oats version --json` and `oats status --json`, and `probe.sessionViewer` on each `oats server roster --json` group: whether that host's viewer without a detach key binds `C-b [` (tmux 3.3 and later), read afresh per host at each run. A kernel with the feature has the viewer's `Shift+PgUp` binding; one without it may not, so don't name the viewer's scroll keys for its tabs ([execution-targets.md](execution-targets.md#inspect-input-and-attach)) | |
|
|
@@ -156,6 +160,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
156
160
|
| `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
|
|
157
161
|
| `instance-background` | background instances (awebai/oats#1579): `soul.yaml` `background:`; `oats spawn … --background\|--no-background`, whose preview and result carry `background` and `backgroundFrom`; `oats instance background <instance> on\|off`, local and `--server`; `background: true` on `oats status --json` instance rows, `oats server roster --json` rows, `oats inspect --home` `instance` and `oats souls --json` soul rows, absent otherwise ([Background instances](#background-instances-oats-instance-background)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the flags and the verb, and its rows have no `background`. A routed spawn with either flag needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) | `instanceBackgroundApi: 1` (payload only) |
|
|
158
162
|
| `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
|
|
163
|
+
| `warm-reader` | `oats reader --stdio`, the warm reader: a child process a client starts, which answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, with the CLI's own answers ([The warm reader](#the-warm-reader)). Gate on the probe, never by trying: a kernel without it has no `oats reader` | `readerApi: 1` |
|
|
164
|
+
| `status-liveness` | the local liveness on `oats status --json` instance rows is complete: `running` and `runtimeState` are read live at every call, from the row's recorded tmux server under the pane and shell-descendant rule, with `false` for a shell only on positive evidence and `null` when the reading is inconclusive ([The roster](#the-roster-oats-status---json)). A client needs no liveness probe of its own beside the roster where the probe lists it, whether the read goes through the warm reader or the CLI. Independent of `warm-reader` | |
|
|
159
165
|
|
|
160
166
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
161
167
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -267,6 +273,7 @@ stdout (progress goes to stderr):
|
|
|
267
273
|
| `oats version --json` | the probe |
|
|
268
274
|
| `oats status --json` | the [roster document](#the-roster-oats-status---json) |
|
|
269
275
|
| a first `oats retire --json`, and a deferred self-retire | the raw [retire receipt](#retire) |
|
|
276
|
+
| `oats reader --stdio` | the reader's protocol lines ([The warm reader](#the-warm-reader)) |
|
|
270
277
|
|
|
271
278
|
<a id="flags"></a>
|
|
272
279
|
### Flag syntax
|
|
@@ -326,7 +333,8 @@ message}` and `legacy-local-agents {code, dirs, instances, message}`.
|
|
|
326
333
|
Every read asks each remote for its current head (`git ls-remote`). With
|
|
327
334
|
`--max-age <seconds>` a read verb reuses a head this machine observed at most
|
|
328
335
|
that many seconds ago instead, so a refresh right after another costs no
|
|
329
|
-
network round trip.
|
|
336
|
+
network round trip. `oats workspace status` reuses the host's `gh` login the
|
|
337
|
+
same way, for display only ([below](#the-gh-login-display-only)). Gate the flag on the feature: an older kernel may ignore
|
|
330
338
|
it and answer live, without the block.
|
|
331
339
|
|
|
332
340
|
```text
|
|
@@ -344,10 +352,11 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
344
352
|
- **The block:** with the flag (`0` included) the document gains one key,
|
|
345
353
|
`observation: {observedAt, reused, localRevision}`: in the result of an
|
|
346
354
|
envelope, at the top level of the roster (after `agents`). `observedAt` is the
|
|
347
|
-
OLDEST remote
|
|
348
|
-
everywhere; `reused` is `true` when any
|
|
349
|
-
|
|
350
|
-
|
|
355
|
+
OLDEST remote observation the answer used (a head, or a reused `gh` login),
|
|
356
|
+
so the answer is at least that fresh everywhere; `reused` is `true` when any
|
|
357
|
+
head or that login came from an earlier observation.
|
|
358
|
+
A command that used no remote observation (no head, and no reused `gh`
|
|
359
|
+
login) reports the time it started and `reused: false`. Without the flag the key is absent and every document is
|
|
351
360
|
exactly as before. A refusal (`E_SOUL_UNKNOWN`, any error envelope) never
|
|
352
361
|
carries the block.
|
|
353
362
|
- **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
|
|
@@ -376,8 +385,9 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
376
385
|
not through `localRevision`: the bundled catalog is not an input. Instance
|
|
377
386
|
homes, member clones and tmux are not inputs either, because the answer
|
|
378
387
|
itself reports them.
|
|
379
|
-
- **What is reused:**
|
|
380
|
-
|
|
388
|
+
- **What is reused:** remote heads (the commit a branch or tag named) and,
|
|
389
|
+
in `workspace status`, the `gh` login it places automations with; never
|
|
390
|
+
local state. Instances, `oats-local.yaml` and the lock are read afresh
|
|
381
391
|
by every command. A member's backlink (`oats-membership.yaml`) is read at
|
|
382
392
|
the member's observed head, which may be a reused one: a backlink removed
|
|
383
393
|
less than `<s>` seconds ago can still show the member `confirmed` under
|
|
@@ -385,6 +395,27 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
385
395
|
afresh. A reused head's
|
|
386
396
|
`observedAt` (for example `workspace.observedAt` in `workspace status`) is
|
|
387
397
|
the time it was observed, not now.
|
|
398
|
+
- <a id="the-gh-login-display-only"></a>**The `gh` login, display only:**
|
|
399
|
+
`workspace status` places each workspace trigger and schedule
|
|
400
|
+
with the account this host's `gh` is logged in as (`gh api user`;
|
|
401
|
+
[who runs it](schedules.md#workspace-triggers-and-schedules)). Under `--max-age <s>`
|
|
402
|
+
it reuses a login a status read observed at most `<s>` seconds ago, so a
|
|
403
|
+
client polling every few seconds asks GitHub about once per `<s>`. Only
|
|
404
|
+
that display does: a schedule tick, `oats trigger poll` (with `--max-age`
|
|
405
|
+
too), `oats trigger run` and every other act that places or fires an
|
|
406
|
+
automation asks `gh` live. A login is reused only under the same `gh`
|
|
407
|
+
context: the same GitHub host, the same `gh` binary (as `PATH` finds it
|
|
408
|
+
from the deployment), the same set of token variables (`GH_TOKEN`,
|
|
409
|
+
`GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN`: which are
|
|
410
|
+
set, never their values), the same `GH_HOST` and config directory, and an
|
|
411
|
+
unchanged `hosts.yml` there (a `gh auth login`, `logout` or `switch`
|
|
412
|
+
rewrites it). Only a successful answer is kept, never a token or its
|
|
413
|
+
digest; a failed one is not, and it ends the reuse of the success before
|
|
414
|
+
it. Within `<s>`, a token variable given another value or a token revoked
|
|
415
|
+
on GitHub still shows the login, as a head moved on the remote shows
|
|
416
|
+
unmoved. The display waits at most 5 s for `gh` (an act waits 30 s): a
|
|
417
|
+
`gh` that does not answer in time reads `owner-mismatch`, as one that is
|
|
418
|
+
not logged in does.
|
|
388
419
|
- **When a head is not reused:** it is older than the flag allows (or dated
|
|
389
420
|
more than 5 s in the future); it was observed through a different URL
|
|
390
421
|
spelling of the same repository (ssh vs https) or for a different ref; its
|
|
@@ -3269,14 +3300,21 @@ its absence.
|
|
|
3269
3300
|
`true` means the harness is running, using the same pane and shell-descendant
|
|
3270
3301
|
rule as session inspection. A fallback shell is `false` with `runtimeState:
|
|
3271
3302
|
"shell"`, even though the window remains; a dead pane or absent window is
|
|
3272
|
-
`false`. A wrapper shell with a live non-shell descendant stays `true
|
|
3303
|
+
`false`. A wrapper shell with a live non-shell descendant stays `true`.
|
|
3304
|
+
`false` for a shell needs positive evidence: the process table holds the
|
|
3305
|
+
pane's own process as a shell and no non-shell process below it
|
|
3306
|
+
([#1641](https://github.com/awebai/oats/issues/1641)); a table that cannot
|
|
3307
|
+
establish that reads `null` with the reason as `runtimeError`: one without
|
|
3308
|
+
the pane's process (a `ps` in another PID namespace, a pane respawned since
|
|
3309
|
+
tmux answered), one with a process in the pane that has no command name, or
|
|
3310
|
+
one with a line that is not a process when nothing non-shell was found.
|
|
3273
3311
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
3274
3312
|
`runtimeError` when that server or its panes cannot be read (including a
|
|
3275
3313
|
window where OATS cannot tell which pane is the agent's
|
|
3276
3314
|
([which pane is the agent's](execution-targets.md#which-pane-is-the-agents)),
|
|
3277
|
-
a session with two windows of the instance's name, or a failed
|
|
3278
|
-
shell-descendant process scan; a window whose agent's pane is
|
|
3279
|
-
that pane alone), and also when its socket
|
|
3315
|
+
a session with two windows of the instance's name, or a failed or
|
|
3316
|
+
inconclusive shell-descendant process scan; a window whose agent's pane is
|
|
3317
|
+
found reads by that pane alone), and also when its socket
|
|
3280
3318
|
file is missing while a process works in the home or the process scan
|
|
3281
3319
|
cannot run, `runtimeError` then naming the processes or the scan's error
|
|
3282
3320
|
([#624](execution-targets.md#missing-socket); with no process in the home
|
|
@@ -3332,7 +3370,8 @@ its absence.
|
|
|
3332
3370
|
`lost` (the host went down, its tmux server died, or the harness was killed
|
|
3333
3371
|
by a signal: the sweep brings it back when it can vouch for the loss,
|
|
3334
3372
|
[Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
|
|
3335
|
-
`oats instance stop`, Desktop's Stop
|
|
3373
|
+
`oats instance stop`, Desktop's Stop, or an `oats session restart` whose
|
|
3374
|
+
relaunch did not happen) or `exited` (the harness ended by
|
|
3336
3375
|
itself: `/exit`, its own error). Present only on a row that reads
|
|
3337
3376
|
`running: false` and records `launched: true`, a row at its fallback shell
|
|
3338
3377
|
(`runtimeState: "shell"`) included; absent while it runs or reads unknown
|
|
@@ -3621,6 +3660,12 @@ route target:
|
|
|
3621
3660
|
whose kernel predates the feature, and a saved route the host did not list
|
|
3622
3661
|
carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
|
|
3623
3662
|
--json` relays the host's answer verbatim, `sameWork` included.
|
|
3663
|
+
- **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
|
|
3664
|
+
when the host's row has the key, with the host's value: a host whose kernel
|
|
3665
|
+
predates the feature, a row the host reports without it (one that runs,
|
|
3666
|
+
for example), and a saved route the host did not list carry none. Its
|
|
3667
|
+
meaning and when the host sends it are the [local row's](#row-session-end).
|
|
3668
|
+
A value that is not `lost`, `stopped` or `exited` drops the key.
|
|
3624
3669
|
- **`addressable`** (0.31): `true` for every row the host reports. Routed
|
|
3625
3670
|
session and lifecycle commands reach it by `--home`, or by name when the
|
|
3626
3671
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
@@ -3871,6 +3916,206 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
3871
3916
|
`E_REMOTE_INCOMPATIBLE`, naming both and the host's version, before
|
|
3872
3917
|
anything is sent. A name two homes share on the host is `E_AMBIGUOUS`.
|
|
3873
3918
|
|
|
3919
|
+
<a id="the-warm-reader"></a>
|
|
3920
|
+
## The warm reader (`oats reader --stdio`)
|
|
3921
|
+
|
|
3922
|
+
Feature `warm-reader`, `readerApi: 1`. A client that polls a deployment can
|
|
3923
|
+
start one long-lived child, `oats reader --stdio`, and send it the poll's
|
|
3924
|
+
reads, `oats status --json` and `oats workspace status --json`, over its
|
|
3925
|
+
stdin and stdout instead of running the CLI for each one. The reader answers
|
|
3926
|
+
with the kernel's own read code, kept loaded. It is an accelerator of
|
|
3927
|
+
identical answers: whenever it is absent, refuses, times out or dies, the
|
|
3928
|
+
client runs that same read through the CLI, unchanged. The decisions are in
|
|
3929
|
+
the [design record](design/2026-10-29-warm-reader.md).
|
|
3930
|
+
|
|
3931
|
+
```text
|
|
3932
|
+
oats reader --stdio
|
|
3933
|
+
```
|
|
3934
|
+
|
|
3935
|
+
It takes no other argument: bare `oats reader`, or anything else after it,
|
|
3936
|
+
is `E_USAGE`.
|
|
3937
|
+
|
|
3938
|
+
- **Warm code, not warm data.** The reader keeps only loaded kernel code and
|
|
3939
|
+
install-derived constants (the kernel's code fingerprint, the parsed JSON
|
|
3940
|
+
schemas, the boot id). Every request reads the deployment afresh: instances
|
|
3941
|
+
spawned or retired by another process, an edited `oats-local.yaml` or
|
|
3942
|
+
lock, a dead session all show in the next answer exactly as in a CLI run.
|
|
3943
|
+
`--max-age` reuse is the CLI's own on-disk
|
|
3944
|
+
[observation reuse](#observation-reuse-feature-observe-max-age-oats-0311),
|
|
3945
|
+
unchanged.
|
|
3946
|
+
- **Same answer as the CLI.** For an accepted request, `exit` and `answer` are
|
|
3947
|
+
what `oats <argv>`, run by the same install with the same environment and
|
|
3948
|
+
with cwd = `--dir`, prints and exits with at that moment: the same envelope
|
|
3949
|
+
and schema versions, the same error codes and refusals, the same `null` and
|
|
3950
|
+
unknown facts. An environment that carries `OATS_RESOLUTION` or
|
|
3951
|
+
`OATS_DEPLOYMENT` is one of them: the reader starts, and answers each
|
|
3952
|
+
request with the CLI's `E_UNSUPPORTED_MODE`. Anything the reader cannot
|
|
3953
|
+
answer that way is a refusal, a frame of its own, on which the client runs
|
|
3954
|
+
the CLI: a client cannot tell the warm path from the fallback.
|
|
3955
|
+
|
|
3956
|
+
### Starting it and the probe
|
|
3957
|
+
|
|
3958
|
+
- `oats version --json` lists feature `warm-reader` and `readerApi: 1` (the
|
|
3959
|
+
feature and API number convention). A client starts a reader only when the
|
|
3960
|
+
probe it holds lists both.
|
|
3961
|
+
- The client starts `oats reader --stdio` from the same binary, Node and
|
|
3962
|
+
environment it runs its CLI reads with.
|
|
3963
|
+
- The version rule is the CLI's own: a reader is trusted only when its
|
|
3964
|
+
version equals the probe's, which the client has already accepted under its
|
|
3965
|
+
normal range. There is no second rule. Remote routes are out: a reader
|
|
3966
|
+
answers reads of this machine's deployments only.
|
|
3967
|
+
|
|
3968
|
+
### Wire format
|
|
3969
|
+
|
|
3970
|
+
UTF-8, one JSON object per line (`\n`), both directions. Frames are told
|
|
3971
|
+
apart by their keys. A client ignores unknown keys and any line that is no
|
|
3972
|
+
frame it knows (a request it then misses times out and falls back).
|
|
3973
|
+
|
|
3974
|
+
- **Hello** (reader to client, the first line, once every module the reads
|
|
3975
|
+
use is loaded, so a hello means ready):
|
|
3976
|
+
|
|
3977
|
+
```json
|
|
3978
|
+
{"readerApi":1,"version":"<the kernel's version>","reads":["status","workspace status"]}
|
|
3979
|
+
```
|
|
3980
|
+
|
|
3981
|
+
- **Request** (client to reader), at most 64 KiB a line:
|
|
3982
|
+
|
|
3983
|
+
```json
|
|
3984
|
+
{"id":"<a string of at most 64 characters, or a safe integer>","argv":["status","--dir","/w","--max-age","60","--json"]}
|
|
3985
|
+
```
|
|
3986
|
+
|
|
3987
|
+
Accepted: an argv the kernel's own hot-read classification
|
|
3988
|
+
(`lib/hot-reads.mjs`) names as one of `reads`, that includes `--json` and
|
|
3989
|
+
an absolute `--dir`. So the flags, [`--flag=value`](#flags) and the
|
|
3990
|
+
exclusion of `--help` are exactly the CLI's; `--team` or a bad `--max-age`
|
|
3991
|
+
get the CLI's own `E_BAD_ARGS` answer; `status --server` is another read
|
|
3992
|
+
and is refused. A relative, blank or missing `--dir`, or no `--json`, is
|
|
3993
|
+
refused. Other keys of a request are ignored.
|
|
3994
|
+
- **Answer** (reader to client):
|
|
3995
|
+
|
|
3996
|
+
```json
|
|
3997
|
+
{"id":"…","exit":0,"answer":{"…":"…"},"stderr":"<text>"}
|
|
3998
|
+
```
|
|
3999
|
+
|
|
4000
|
+
`answer` is the JSON value the CLI prints on stdout, an error envelope
|
|
4001
|
+
included. Equivalence is `exit` and `answer`. `stderr`, present only when
|
|
4002
|
+
there is some, is diagnostic text (the CLI's stderr for that read),
|
|
4003
|
+
informative only, never parsed and outside the equivalence. It is at most
|
|
4004
|
+
8 KiB of UTF-8, cut at a character boundary, so that it never pushes an
|
|
4005
|
+
answer line over a client's bound.
|
|
4006
|
+
- **Refusal** (reader to client), never a CLI answer:
|
|
4007
|
+
|
|
4008
|
+
```json
|
|
4009
|
+
{"id":"…","refused":{"code":"E_READER_UNSUPPORTED","message":"…"}}
|
|
4010
|
+
```
|
|
4011
|
+
|
|
4012
|
+
`id` is `null` when the line's id cannot be read. The codes are used only
|
|
4013
|
+
here, never in an envelope:
|
|
4014
|
+
|
|
4015
|
+
| Code | When | Then the reader |
|
|
4016
|
+
|---|---|---|
|
|
4017
|
+
| `E_READER_BAD_REQUEST` | a line that is not a request: not one JSON object, an `id` that is neither a string of at most 64 characters nor a safe integer, an `argv` that is not an array of strings, a line over 64 KiB | answers the next request |
|
|
4018
|
+
| `E_READER_UNSUPPORTED` | an argv outside the accepted forms; a `--dir` the reader cannot make its working directory (a removed deployment), which the CLI then answers with its own failure | answers the next request |
|
|
4019
|
+
| `E_READER_STALE` | the install changed since the reader started ([The install stamp](#reader-install-stamp)) | refuses every queued request the same way, then exits 0 |
|
|
4020
|
+
| `E_READER_DEFECT` | an unexpected failure of the reader | writes the stack to its stderr and exits 1: per-request state may be half reset |
|
|
4021
|
+
|
|
4022
|
+
- Answers may arrive in any order: match them by `id`. This kernel answers
|
|
4023
|
+
one request at a time, in arrival order.
|
|
4024
|
+
|
|
4025
|
+
<a id="reader-install-stamp"></a>
|
|
4026
|
+
### The install stamp
|
|
4027
|
+
|
|
4028
|
+
An install that changed under a reader (an upgrade, a Node upgrade) is never
|
|
4029
|
+
answered from the old code. The reader takes a stamp of its install before
|
|
4030
|
+
any of the kernel's own modules load (only the CLI's entry point and three
|
|
4031
|
+
small modules of Node built-ins load before it), so an install that changes
|
|
4032
|
+
while the reader starts is seen too:
|
|
4033
|
+
the install root directory's device and inode; device, inode, size and mtime
|
|
4034
|
+
of `package.json`, `bin/oats.mjs`, `package-catalog.json`, every file under
|
|
4035
|
+
`lib/`, `docs/*.schema.json`, each runtime dependency's `package.json`
|
|
4036
|
+
where it resolves at that moment (a dependency newly installed nearer the
|
|
4037
|
+
install moves it) and the Node binary (its real path); and the mtime of each
|
|
4038
|
+
directory under `lib/` and of `docs/` (a file added or removed). It takes the
|
|
4039
|
+
stamp again when a request starts and again just before that request's answer
|
|
4040
|
+
is written. Any difference, or a file gone (an npm global update replaces the
|
|
4041
|
+
package directory; a half-written install reads as changed too), refuses that
|
|
4042
|
+
request and every queued one with `E_READER_STALE`, and the reader exits 0.
|
|
4043
|
+
No hashing, no timers, no file watchers. A `PATH` symlink re-pointed at
|
|
4044
|
+
another install of the same version is invisible to any stamp: the client's
|
|
4045
|
+
binding of its reader to the probe record it started it for covers it.
|
|
4046
|
+
|
|
4047
|
+
### Lifetime
|
|
4048
|
+
|
|
4049
|
+
The reader's lifetime is its client's. Its exit and signal handlers are
|
|
4050
|
+
installed once, at start.
|
|
4051
|
+
|
|
4052
|
+
| The reader exits | Status |
|
|
4053
|
+
|---|---|
|
|
4054
|
+
| on stdin's end or a read error on it (its client is gone) | 0 |
|
|
4055
|
+
| on `EPIPE` on stdout | 0 |
|
|
4056
|
+
| on `SIGTERM`, `SIGINT`, `SIGHUP` | 128 + the signal's number: 143, 130, 129 |
|
|
4057
|
+
| after `E_READER_STALE` | 0 |
|
|
4058
|
+
| after `E_READER_DEFECT` | 1 |
|
|
4059
|
+
|
|
4060
|
+
A request in flight when the reader ends is not answered, and its read session
|
|
4061
|
+
is closed on the way out, which kills its `git` children. A reader killed
|
|
4062
|
+
with `SIGKILL` leaves its `git` process groups to their own timeouts, as the
|
|
4063
|
+
CLI does. Its stdout carries protocol lines only: anything else written there
|
|
4064
|
+
goes to its stderr, and no child it runs inherits its stdout.
|
|
4065
|
+
|
|
4066
|
+
<a id="reader-working-directory"></a>
|
|
4067
|
+
### The working directory
|
|
4068
|
+
|
|
4069
|
+
The reads read no working directory, but the programs they run by name
|
|
4070
|
+
(`tmux`, `git`) are found on `PATH`, and a relative or empty `PATH` entry
|
|
4071
|
+
resolves against the process's working directory, not the deployment's. So
|
|
4072
|
+
that it resolves as in a CLI run with cwd = `--dir`, the reader changes its
|
|
4073
|
+
working directory to the request's `--dir` for the read and back to its
|
|
4074
|
+
install root when the request ends, answered or failed: it never keeps a
|
|
4075
|
+
deployment directory that may be removed or unmounted. This depends on
|
|
4076
|
+
answering one request at a time. A reader that answers two at once must first
|
|
4077
|
+
give each child it runs its own working directory.
|
|
4078
|
+
|
|
4079
|
+
### Client rules
|
|
4080
|
+
|
|
4081
|
+
- **Start.** Exactly as the client runs its CLI reads: the same realpath'd
|
|
4082
|
+
binary, the same Node, the same environment, no shell. Stdin and stdout
|
|
4083
|
+
piped, stderr ignored or drained with a bound (an undrained pipe would
|
|
4084
|
+
block the reader). Reads issued before the hello arrives go to the CLI: no
|
|
4085
|
+
tick waits on the reader's start.
|
|
4086
|
+
- **Trust.** Only after a hello, within the CLI read's timeout, with
|
|
4087
|
+
`readerApi === 1`, a `version` equal to that of the probe that gated it,
|
|
4088
|
+
and the read in `reads`. A mismatch: end the reader and use the CLI until
|
|
4089
|
+
the client's probe changes; no retries. A reader is bound to the probe
|
|
4090
|
+
record it was started for: a read under another record ends it, and the
|
|
4091
|
+
next one starts for the new record.
|
|
4092
|
+
- **What goes to the reader.** Background reads (`--max-age` above 0). Live
|
|
4093
|
+
reads (`--max-age 0`: after a mutation, an admission, a probe change) go to
|
|
4094
|
+
the CLI, so they never queue behind the reader's one-at-a-time answers.
|
|
4095
|
+
- **Refusals.** `E_READER_UNSUPPORTED` or `E_READER_BAD_REQUEST`: that read
|
|
4096
|
+
goes to the CLI, and the reader is kept. `E_READER_STALE`: the install
|
|
4097
|
+
changed; the read goes to the CLI, the client probes again and starts a
|
|
4098
|
+
fresh reader on a later tick (not counted as a failure). A client that
|
|
4099
|
+
never probes again uses the CLI for the rest of its session.
|
|
4100
|
+
- **Failures**, which count toward giving up: an exit without an answer, a
|
|
4101
|
+
hello timeout, a request timeout, `E_READER_DEFECT`. The reads in flight go
|
|
4102
|
+
to the CLI; a new reader starts on a later tick with backoff (1 s, doubling
|
|
4103
|
+
to 5 min); after 5 consecutive failures without an answer, the CLI until
|
|
4104
|
+
the client's probe changes, or until its session ends.
|
|
4105
|
+
- **Timeout.** A request's deadline is the CLI read's own timeout, counted
|
|
4106
|
+
from when it becomes the oldest unanswered request: time in the queue does
|
|
4107
|
+
not count.
|
|
4108
|
+
- **Answers.** The client bounds the raw answer line by the CLI read's output
|
|
4109
|
+
limit before parsing it, parses it once, and passes `answer` and `exit`
|
|
4110
|
+
through the same validation as the CLI's stdout and exit status: an error
|
|
4111
|
+
envelope with a nonzero `exit` is handled exactly as from the CLI. The
|
|
4112
|
+
reader's stderr, the answer's field and its own, is never forwarded, as
|
|
4113
|
+
the CLI read's stderr is not. A client never
|
|
4114
|
+
treats the reader as authority beyond what the same CLI read would be.
|
|
4115
|
+
- **End.** The app ends its reader when it quits: closing its stdin is
|
|
4116
|
+
enough, and `SIGTERM` works too. The reader's lifeline is the app's
|
|
4117
|
+
exclusive hold of its stdin: the app's death closes it.
|
|
4118
|
+
|
|
3874
4119
|
<a id="instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247"></a>
|
|
3875
4120
|
## Git and diff
|
|
3876
4121
|
|
|
@@ -56,7 +56,16 @@ agents' tmux (ssh, cron, a plain terminal) sees the same liveness as `session
|
|
|
56
56
|
inspect`. `running` means the harness is running, not merely that its window
|
|
57
57
|
exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
|
|
58
58
|
a retained dead pane also reads `false`. A wrapper shell with a live non-shell
|
|
59
|
-
descendant still reads `true`.
|
|
59
|
+
descendant still reads `true`. tmux names the pane's foreground process group,
|
|
60
|
+
which is the launch's own shell while the harness runs as its child, so a
|
|
61
|
+
running instance is usually read through this process scan. `false` needs
|
|
62
|
+
positive evidence of the fallback prompt: the process table holds the pane's
|
|
63
|
+
own process as a shell and no non-shell process below it. A table that cannot
|
|
64
|
+
establish that (no pane process in it, as for a `ps` in another PID
|
|
65
|
+
namespace; a process in the pane with no command name; a line that is not a
|
|
66
|
+
process, when nothing non-shell was found) reads `running: null` with its
|
|
67
|
+
reason, and `session inspect` answers `E_SESSION_UNAVAILABLE`
|
|
68
|
+
([#1641](https://github.com/awebai/oats/issues/1641)). Status shares session inspection's pane rule,
|
|
60
69
|
with one batched pane read per socket/session and one lazy process scan across
|
|
61
70
|
all panes that need it. It reads the agent's pane alone, so a window with
|
|
62
71
|
another pane reads as one without it
|
|
@@ -1185,6 +1194,16 @@ it ends, before it ends it, so a home it was retiring reads `stopped`, never
|
|
|
1185
1194
|
stop record itself cannot be written (a full disk) and the retire then fails
|
|
1186
1195
|
as well: that home reads `lost`, as it did before 0.69.2.
|
|
1187
1196
|
|
|
1197
|
+
`oats session restart` records the stop of the session it replaces the same
|
|
1198
|
+
way, before it asks the harness to end (#1601): a restart whose relaunch
|
|
1199
|
+
fails, or that dies between the stop and the relaunch, leaves a home that
|
|
1200
|
+
reads `stopped`, so no resume starts again the launch it was replacing. The
|
|
1201
|
+
relaunch records a new start, which that record does not name. A restart
|
|
1202
|
+
whose stop is refused (`E_SESSION_STOP_FAILED`, the harness still there after
|
|
1203
|
+
the grace) keeps its record: should that harness die later, the home reads
|
|
1204
|
+
`stopped`, not `lost`. A restart of a home that does not run stops nothing and
|
|
1205
|
+
records nothing, so it keeps its reading.
|
|
1206
|
+
|
|
1188
1207
|
#### How a session's end is read
|
|
1189
1208
|
|
|
1190
1209
|
A launched home that does not run reads one of three ends, `sessionEnd` on
|
|
@@ -1198,10 +1217,18 @@ for its current start (`startId` in `instance.json`):
|
|
|
1198
1217
|
| an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
|
|
1199
1218
|
| neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
|
|
1200
1219
|
|
|
1220
|
+
In text, `oats status`, `oats status --server <id>` and `oats server roster`
|
|
1221
|
+
print a `lost` row as `LOST`, where a `stopped` or `exited` row, or one
|
|
1222
|
+
without `sessionEnd`, prints `idle`, with one line under it naming the way
|
|
1223
|
+
back: `oats session start --resume --home <home>`, or the next sweep (`oats
|
|
1224
|
+
session resume`, which OATS Desktop and `oats tui` run when they open) when
|
|
1225
|
+
it can vouch for the loss. Both act on this machine's homes only, so a row
|
|
1226
|
+
of another host names the host to run them on.
|
|
1227
|
+
|
|
1201
1228
|
The window a spawn or a start makes writes the exit marker,
|
|
1202
1229
|
`.oats-start-exited`, when the harness exits; `oats instance stop` writes its
|
|
1203
|
-
record, `.oats-stop.json`, and so
|
|
1204
|
-
(0.69.2). Both are kernel-private files of the home, not a
|
|
1230
|
+
record, `.oats-stop.json`, and so do a retire, before it ends the window
|
|
1231
|
+
(0.69.2), and `oats session restart`, before it stops the harness (#1601). Both are kernel-private files of the home, not a
|
|
1205
1232
|
contract: read `sessionEnd`. A shutdown kills the window's shell with the
|
|
1206
1233
|
harness, so a lost session leaves no marker. A home spawned before 0.69 and
|
|
1207
1234
|
never restarted since names no start: it reads `stopped` only after a stop,
|
|
@@ -1325,13 +1352,17 @@ resumes it. So:
|
|
|
1325
1352
|
- a loss first seen a day ago or more, or a session that died before any read
|
|
1326
1353
|
of OATS saw it run, stays down.
|
|
1327
1354
|
|
|
1328
|
-
|
|
1355
|
+
Three limits follow from reading only what OATS saw:
|
|
1329
1356
|
|
|
1330
1357
|
- **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
|
|
1331
1358
|
status`, once before you restart the computer, or nothing from before the
|
|
1332
1359
|
upgrade comes back.
|
|
1333
1360
|
- A whole boot with no OATS read leaves that boot unknown: what ran in it and
|
|
1334
1361
|
was lost there is not resumed.
|
|
1362
|
+
- Clause 4 does not reach across a reboot. On a computer where nothing read
|
|
1363
|
+
OATS for more than a day before a restart (every agent already down, no
|
|
1364
|
+
client open), the first sweep after the restart can bring back a session
|
|
1365
|
+
that was lost during that quiet spell.
|
|
1335
1366
|
|
|
1336
1367
|
Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
|
|
1337
1368
|
to every loss and the 3-resumes-per-boot guard (below) is off.
|
|
@@ -1448,7 +1479,7 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1448
1479
|
for input, nor that it consumed a wake, and it does not prove which
|
|
1449
1480
|
executable runs if a process inside the pane was replaced. When the backend
|
|
1450
1481
|
cannot be read, a required process-table read for an explicitly labelled
|
|
1451
|
-
shell fails, the pane answer is
|
|
1482
|
+
shell fails or cannot establish a fallback shell (above), the pane answer is
|
|
1452
1483
|
malformed, or OATS cannot tell which of the window's panes is the agent's,
|
|
1453
1484
|
inspect is an error as before, never `running: false`.
|
|
1454
1485
|
That includes a tmux server that is gone (`no server running on` its
|
package/docs/implementation.md
CHANGED
|
@@ -23,7 +23,10 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
23
23
|
and may never add one: with a dependency it could no longer ship in this
|
|
24
24
|
tarball.
|
|
25
25
|
- **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
|
|
26
|
-
instance's own resources. It registers no agent tools.
|
|
26
|
+
instance's own resources. It registers no agent tools. It ships no kernel:
|
|
27
|
+
`extension/core-loader.mjs` imports the kernel that launched the instance,
|
|
28
|
+
through the home's `oats` link, before any PATH or global lookup (the
|
|
29
|
+
order is in [its README](../packages/pi/README.md)).
|
|
27
30
|
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
28
31
|
`oats.support` and `oats.knowledge-theory` capabilities and the
|
|
29
32
|
`knowledge-theory-expert` soul,
|
|
@@ -49,9 +52,13 @@ from it, and the test lists the stable surface a second client may import.
|
|
|
49
52
|
layers that each do one thing. `lib/term/` is the terminal: the key parser,
|
|
50
53
|
cell widths, safe text, the screen and the guard that restores the terminal;
|
|
51
54
|
only the screen and the guard write an escape byte. `lib/read.mjs` is every
|
|
52
|
-
effect of reading: for each deployment opened in a run it
|
|
53
|
-
|
|
54
|
-
|
|
55
|
+
effect of reading: for each deployment opened in a run it reads through
|
|
56
|
+
the shared observer and refresh loop, its background reads through one
|
|
57
|
+
warm `oats reader --stdio` of the kernel of the same install (the shared
|
|
58
|
+
`createWarmReader`), every other read through that kernel as a child, and,
|
|
59
|
+
for a kernel without feature `status-liveness`, the shared liveness
|
|
60
|
+
collector as a child too; a void cycle's reads are answered at once,
|
|
61
|
+
the warm reader's included; it runs that kernel's read of the
|
|
55
62
|
other machines (`oats server roster --json`), one at a time and awaited by
|
|
56
63
|
no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
|
|
57
64
|
system the workspace switcher needs (whether a picked row is a deployment).
|
|
@@ -71,7 +78,7 @@ and the rules its tests pin.
|
|
|
71
78
|
|
|
72
79
|
| path | contents |
|
|
73
80
|
|---|---|
|
|
74
|
-
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs |
|
|
81
|
+
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its only static imports are Node built-ins and two dependency-free modules, `lib/compile-cache.mjs` and `lib/hot-reads.mjs`: it turns Node's compile cache on first, then imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
|
|
75
82
|
| `lib/` | the kernel (below) |
|
|
76
83
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
77
84
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
@@ -96,6 +103,15 @@ and the rules its tests pin.
|
|
|
96
103
|
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
|
|
97
104
|
| `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
|
|
98
105
|
| `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
|
|
106
|
+
| `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
|
|
107
|
+
| `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630), and the warm reader's start (`oats reader --stdio`, whose reads `reader.mjs` imports itself): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
|
|
108
|
+
| `roster-read.mjs`, `workspace-read.mjs`, `read-call.mjs` | the deployment reads (awebai/oats#1630): `oats status` (`roster-read.mjs`: the roster, its drift and its workspace identity) and `oats workspace status` (`workspace-read.mjs`: members, packages, automations, the desktop facts, and the rows `oats sync` reports too), one implementation behind the CLI and a process that answers them many times. Each has an answer function (`statusAnswer`, `workspaceStatusAnswer`: `{ exit, answer, stderr }`, `answer` the JSON the CLI prints, a refusal included) and a data function (`statusView`, `workspaceStatusView`) bin's text renderer reads. `read-call.mjs` is one call's scope: it takes an explicit context (the absolute `dir`, `maxAge`, the caller's read session, the cache, an optional deployments observer), resets at its start every piece of module-level state the reads can reach (`READ_STATE`; `test/read-call-state.test.mjs` scans the reads' import closure and fails on a binding with no row), answers refusals as envelopes, and drains the session's notices. Within one call, two pieces of work are not repeated: `listInstances` hands the records it read to the rest of the read (`records`: `legacyCapturedHomes` and the waiting read take them instead of parsing them again), and `workspace status` asks git for each member clone's remotes once (`remotes`, shared by the automation scope and the desktop facts); both are maps the read makes and drops, never module state. A call registers no process listener, closes no session and reads no argv or cwd: the CLI passes `commandSession` (created at the first remote read, with its exit and signal listeners) and closes it at the end of the command, as for every verb. The read part of the dispatch is there too (`parseMaxAge`, `readBudget`, `callSession`); `test/read-call-equivalence.test.mjs` answers both reads many times in one process and compares each answer with a fresh CLI run's. Leaves: never `core.mjs`. Kernel-private, not in `./core` |
|
|
109
|
+
| `reader.mjs` | `oats reader --stdio`, the warm reader (awebai/oats#1630; [the contract](desktop-cli-api.md#the-warm-reader), [the decisions](design/2026-10-29-warm-reader.md)): a client's child that answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, through `read-call.mjs` and the two answer functions, never a copy of them. It loads every module the reads import lazily (`PRELOAD`) before its hello; classifies a request with `hot-reads.mjs` `hotRead` and expands its flags with `argv.mjs`, then runs the dispatch's read part in the CLI's order (the flag syntax, `--max-age`, the inherited context), so a refusal there is the CLI's own answer; answers one request at a time, in arrival order, each with its own read session, closed at its end, and its deployments observer; changes its working directory to the request's `--dir` for the read and back to the install root after, because the programs the reads run by name resolve a relative `PATH` entry against it (a second lane must first give each child its own cwd). It compares `install-stamp.mjs`'s stamp, taken by `bin` before the kernel loaded, when a request starts and before its answer is written: a change refuses `E_READER_STALE` and exits. Its stdout carries protocol lines only (other writes go to stderr); a request in flight at exit has its session closed from the `exit` handler. `test/reader-protocol.test.mjs` pins the protocol and `PRELOAD` against the reads' closure. `oats reader --stdio` is a hot-read form, so `bin` loads only its dispatch's leaves for it, never `core.mjs` (`test/cli-hot-reads.test.mjs`). Kernel-private, not in `./core`. Dependency-free |
|
|
110
|
+
| `install-stamp.mjs` | the warm reader's install stamp: `stat` of the install's code and data (package.json, bin/oats.mjs, the catalog, every file under lib/, the docs schemas, each runtime dependency's package.json where it resolves now, the Node binary) as one string. Node built-ins only: `bin` imports it statically and takes the reader's baseline before any kernel module loads; `reader.mjs` compares each request against it |
|
|
111
|
+
| `argv.mjs` | how the kernel reads `--flag=value` ([Flag syntax](desktop-cli-api.md#flags)): `expandInlineValues`, which the CLI's dispatch runs once on its argv and the reader on each request's, so both give a malformed flag the same `E_BAD_ARGS`, and `flagValue`, a flag's value in an expanded argv. Kernel-private, not in `./core`. Dependency-free |
|
|
112
|
+
| `kernel-features.mjs` | `KERNEL_FEATURES`, the features this kernel implements: `features` in `version --json` and in `status --json`; `READER_API`, the warm reader's protocol number (`readerApi` in `version --json` and in the reader's hello). Kernel-private, not in `./core` |
|
|
113
|
+
| `captured-context.mjs` | the refusal (`E_UNSUPPORTED_MODE`) of an environment that carries `OATS_RESOLUTION` or `OATS_DEPLOYMENT`, which the dispatch asks for every command but `version` and `reader`; the reader asks it for each request instead, so it starts and answers each read as the CLI would. Dependency-free |
|
|
114
|
+
| `version.mjs`, `deployment-path.mjs`, `write-file-atomic.mjs`, `agents-root.mjs`, `soul-listing.mjs`, `instance-address.mjs`, `session-inspect.mjs`, `instance-listing.mjs`, `drift.mjs`, `package-catalog.mjs`, `member-clone.mjs`, `reserved-launch-env.mjs`, `automation-scope.mjs`, `automation-api.mjs`, `semver.mjs` | the leaves the hot reads load instead of the modules that re-export them (awebai/oats#1630): the version; the canonical deployment path; the atomic file write; the agents root; souls and instance homes; `resolveInstance`; `inspectInstanceSession`; `listInstances` and the status rows; soul and module drift; the official package catalog; discovery and member clones; the reserved launch environment; the automation scope; the automation API versions; `compareSemver`. Each name is still exported, under the same name, from the module it left (`core.mjs`, `packages.mjs`, `instance-lifecycle.mjs`, `materialize.mjs`, `instance-resolution.mjs`, `schedule.mjs`, `automations.mjs`, `servers.mjs`), so `./core` is unchanged (`test/core-exports.test.mjs`), and no leaf imports `core.mjs` or the module it left. Code a hot read reaches goes in a leaf, never in `core.mjs` |
|
|
99
115
|
| `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
|
|
100
116
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
101
117
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
@@ -127,14 +143,15 @@ and the rules its tests pin.
|
|
|
127
143
|
| `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)) |
|
|
128
144
|
| `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 |
|
|
129
145
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
146
|
+
| `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
|
|
130
147
|
| `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
|
|
131
148
|
| `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 |
|
|
132
149
|
| `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
|
|
133
150
|
| `file-pieces.mjs` | a regular file's bytes read in pieces of 1 MiB (`readFilePieces`, `hashFile`, and `readFileUpTo` for a home's `instance.json`, read whole up to 16 MiB for its neutral form), for every digest of the retire path: what a digest holds of a file is bounded whatever its size (Node reads no file over 2 GiB whole), and a file is read for the size it had when it was opened. One that ends before that size refuses with `E_WORK_INSPECTION_FAILED` |
|
|
134
|
-
| `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
|
|
151
|
+
| `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; a shell-labelled pane is a fallback shell only when that scan shows the pane's own process as a shell with no non-shell descendant, and a scan that cannot show it throws its reason (unknown, never idle: #1641); `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
|
|
135
152
|
| `servers.mjs` | routing commands to a registered server |
|
|
136
153
|
| `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
|
|
137
|
-
| `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`
|
|
154
|
+
| `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. A process that answers many reads sets its observer with `atExit: false` and settles it at the end of each read (`read-call.mjs`), which also forgets what the last one reported (`resetResolvedDeployment`). Dependency-free |
|
|
138
155
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
139
156
|
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
|
140
157
|
| `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
|
|
@@ -331,7 +348,7 @@ gets the plain per-call behaviour. Within a session:
|
|
|
331
348
|
exit hook (`closeNow`), and the system reaps them once the process is gone;
|
|
332
349
|
- a session may have a `deadline` (`READ_REMOTE_BUDGET_MS`, 12 s after it
|
|
333
350
|
starts): the CLI gives one to `status` and `workspace status` only
|
|
334
|
-
(`
|
|
351
|
+
(`read-call.mjs` `readBudget`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
|
|
335
352
|
not a contract). Every
|
|
336
353
|
remote step then gets what is left of it instead of its own default: each
|
|
337
354
|
git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
|
|
@@ -484,7 +501,15 @@ atomically, a corrupt one is a miss, and `pruneStores` bounds the store
|
|
|
484
501
|
(`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
|
|
485
502
|
store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
|
|
486
503
|
one record per (repo key, ref args, url digest), so two spellings of one repo
|
|
487
|
-
keep a record each; the url itself is never written.
|
|
504
|
+
keep a record each; the url itself is never written. Beside it,
|
|
505
|
+
`<cache>/.observed-facts/` holds the remote facts that are not heads
|
|
506
|
+
(`factObservation`): today the `gh` login `workspace status` places automations
|
|
507
|
+
with for display ([the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only)).
|
|
508
|
+
A record is named by the digest of its fact's context (`ghLoginParts` in
|
|
509
|
+
`automations.mjs`: never a token value) and holds only the answer and when it
|
|
510
|
+
was observed; only `workspace-read.mjs` passes the reuse to `ghLogin` (its
|
|
511
|
+
`lookup`, with the display's 5 s wait), so a tick, a poll or a run always asks
|
|
512
|
+
`gh` live. `pruneStores` bounds both stores alike. Adding a cached item
|
|
488
513
|
means choosing an item name unique to its producer (the item string its
|
|
489
514
|
call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
|
|
490
515
|
adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
|
package/docs/integrations.md
CHANGED