@awebai/oats 0.69.5 → 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 +78 -320
- 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 +250 -12
- package/docs/execution-targets.md +11 -2
- package/docs/implementation.md +26 -8
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +14 -7
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +21 -4
- package/docs/upgrading.md +9 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +41 -0
- package/lib/automation-scope.mjs +6 -4
- package/lib/automations.mjs +61 -11
- package/lib/captured-context.mjs +12 -0
- package/lib/hot-reads.mjs +21 -15
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-listing.mjs +13 -5
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/member-clone.mjs +15 -11
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/resolved-deployment.mjs +12 -4
- package/lib/roster-read.mjs +199 -0
- package/lib/session-input.mjs +35 -11
- package/lib/workspace-read.mjs +160 -0
- package/package-catalog.json +2 -2
- 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/skills/oats-getting-started/SKILL.md +2 -2
package/docs/implementation.md
CHANGED
|
@@ -52,9 +52,13 @@ from it, and the test lists the stable surface a second client may import.
|
|
|
52
52
|
layers that each do one thing. `lib/term/` is the terminal: the key parser,
|
|
53
53
|
cell widths, safe text, the screen and the guard that restores the terminal;
|
|
54
54
|
only the screen and the guard write an escape byte. `lib/read.mjs` is every
|
|
55
|
-
effect of reading: for each deployment opened in a run it
|
|
56
|
-
|
|
57
|
-
|
|
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
|
|
58
62
|
other machines (`oats server roster --json`), one at a time and awaited by
|
|
59
63
|
no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
|
|
60
64
|
system the workspace switcher needs (whether a picked row is a deployment).
|
|
@@ -100,7 +104,13 @@ and the rules its tests pin.
|
|
|
100
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`) |
|
|
101
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 |
|
|
102
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` |
|
|
103
|
-
| `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630): 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` |
|
|
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 |
|
|
104
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` |
|
|
105
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 |
|
|
106
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) |
|
|
@@ -138,10 +148,10 @@ and the rules its tests pin.
|
|
|
138
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 |
|
|
139
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 |
|
|
140
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` |
|
|
141
|
-
| `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 |
|
|
142
152
|
| `servers.mjs` | routing commands to a registered server |
|
|
143
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 |
|
|
144
|
-
| `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. Dependency-free |
|
|
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 |
|
|
145
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 |
|
|
146
156
|
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
|
147
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 |
|
|
@@ -338,7 +348,7 @@ gets the plain per-call behaviour. Within a session:
|
|
|
338
348
|
exit hook (`closeNow`), and the system reaps them once the process is gone;
|
|
339
349
|
- a session may have a `deadline` (`READ_REMOTE_BUDGET_MS`, 12 s after it
|
|
340
350
|
starts): the CLI gives one to `status` and `workspace status` only
|
|
341
|
-
(`
|
|
351
|
+
(`read-call.mjs` `readBudget`; `OATS_READ_REMOTE_BUDGET_MS` is a test and ops override,
|
|
342
352
|
not a contract). Every
|
|
343
353
|
remote step then gets what is left of it instead of its own default: each
|
|
344
354
|
git call's timeout (`sessionExec`: ls-remote, fetch, ls-tree, the cache's
|
|
@@ -491,7 +501,15 @@ atomically, a corrupt one is a miss, and `pruneStores` bounds the store
|
|
|
491
501
|
(`PARSED_LIMITS`, least recently used first). `--max-age` adds the observation
|
|
492
502
|
store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
|
|
493
503
|
one record per (repo key, ref args, url digest), so two spellings of one repo
|
|
494
|
-
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
|
|
495
513
|
means choosing an item name unique to its producer (the item string its
|
|
496
514
|
call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
|
|
497
515
|
adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
|
package/docs/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.
|
|
9
|
+
This is the operator guide for **oats.okf 5.7.0** (OATS **>=0.69.2**). Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
25
25
|
```yaml
|
|
26
26
|
# oats-workspace.yaml (excerpt)
|
|
27
27
|
packages:
|
|
28
|
-
oats.okf: v5.
|
|
28
|
+
oats.okf: v5.7.0
|
|
29
29
|
defaults:
|
|
30
30
|
knowledge: { oats.okf: { from: package } }
|
|
31
31
|
stores:
|
|
@@ -50,11 +50,11 @@ settings:
|
|
|
50
50
|
|
|
51
51
|
Upgrading from 4.x requires the ordered
|
|
52
52
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
53
|
-
just editing a version line. 5.6.0 requires OATS >=0.69.2: its
|
|
53
|
+
just editing a version line. From 5.6.0 it requires OATS >=0.69.2: its
|
|
54
54
|
`knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
|
|
55
55
|
which an older kernel refuses. Upgrade OATS first, then the package.
|
|
56
56
|
|
|
57
|
-
**Upgrade:** pin `oats.okf: v5.
|
|
57
|
+
**Upgrade:** pin `oats.okf: v5.7.0` and run `oats sync`. Only new spawns get
|
|
58
58
|
the capability-owned harvest duty, skill and spawn-recorded policy. Existing
|
|
59
59
|
homes keep their copied provider even after a session restart; from 5.4.0, a
|
|
60
60
|
stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
|
|
@@ -68,7 +68,9 @@ proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
|
|
|
68
68
|
the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
|
|
69
69
|
that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
|
|
70
70
|
propose. 5.6.0 lists new harvesters and knowledge maintainers under the
|
|
71
|
-
clients' Background section; existing ones do not move.
|
|
71
|
+
clients' Background section; existing ones do not move. 5.7.0 stops parking
|
|
72
|
+
harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
|
|
73
|
+
older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
|
|
72
74
|
|
|
73
75
|
### Bindings document
|
|
74
76
|
|
|
@@ -280,8 +282,13 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
280
282
|
for a labelled PR. A gh error can leave remote effects, so partial or
|
|
281
283
|
uncertain publication is not completion or permission to clean up.
|
|
282
284
|
4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
|
|
283
|
-
|
|
284
|
-
|
|
285
|
+
A PR is not accepted knowledge until merged. Human-accepted decisions are
|
|
286
|
+
not silently superseded. Before oats.okf 5.7.0 the maintainer labels a PR
|
|
287
|
+
that would supersede one `okf-needs-human` and leaves it to a human. From
|
|
288
|
+
5.7.0 the review never parks a PR: such a supersession merges only with the
|
|
289
|
+
human's acceptance cited (checked when the record is on GitHub, otherwise
|
|
290
|
+
recorded as source-reported), and is closed without it
|
|
291
|
+
([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
|
|
285
292
|
|
|
286
293
|
The promotion test belongs to
|
|
287
294
|
[What deserves to become knowledge](knowledge-theory.md#what-deserves-to-become-knowledge),
|
package/docs/named-test-runs.md
CHANGED
|
@@ -187,6 +187,10 @@ leaves out the request's two variables, the runner's command files
|
|
|
187
187
|
(`GITHUB_ENV`, `GITHUB_OUTPUT`, `GITHUB_PATH`, `GITHUB_STATE`,
|
|
188
188
|
`GITHUB_STEP_SUMMARY`) and node's nested-run marker. So `GITHUB_WORKFLOW` and
|
|
189
189
|
`GITHUB_EVENT_NAME` reach the test, and on Linux so does `XDG_RUNTIME_DIR`.
|
|
190
|
+
It puts the tested tree's `node_modules/.bin` first on `PATH`, as `npm test`
|
|
191
|
+
does in pull-request CI and the release workflow: a test that starts a
|
|
192
|
+
fixture instance finds there the `pi` that the workflow's `npm ci` installs
|
|
193
|
+
in the tested tree.
|
|
190
194
|
|
|
191
195
|
A guard is a switch, not a proof. Anyone can set these variables on their own
|
|
192
196
|
machine, and a guarded test that runs there drives that machine's real
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,8 +9,8 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.16.
|
|
13
|
-
| `oats.okf` | `v5.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.16.4` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
15
|
| `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
30
30
|
## Find and use packages
|
|
31
31
|
|
|
32
32
|
- A workspace pins an official package by **bare version** in its
|
|
33
|
-
`packages:` map (`oats.okf: v5.
|
|
33
|
+
`packages:` map (`oats.okf: v5.7.0`); `oats sync` resolves it through the
|
|
34
34
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
35
35
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
36
36
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.
|
|
47
|
+
oats.okf: v5.7.0 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.
|
|
51
|
+
- **Bare version** (`v5.7.0`, `5.7.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.
|
|
54
|
+
convention (`v5.7.0` or `oats-framework/v1.16.4`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,8 +74,8 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.16.
|
|
78
|
-
oats.okf: v5.
|
|
77
|
+
oats.framework: v1.16.4
|
|
78
|
+
oats.okf: v5.7.0
|
|
79
79
|
oats.aweb: v1.32.1
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.7.0 ✓ (@ 56dbc167)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.7.0",
|
|
164
|
+
"commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.7.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.4", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.16.
|
|
362
|
-
resolves to tag `oats-framework/v1.16.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.16.4`
|
|
362
|
+
resolves to tag `oats-framework/v1.16.4`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# OATS 0.69.6
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
0.69.6 makes the Desktop and `oats tui` refresh without starting a new CLI
|
|
6
|
+
process for every read. Both now read through one warm `oats reader --stdio`,
|
|
7
|
+
and under the new feature `status-liveness` they take each instance's
|
|
8
|
+
liveness from `oats status` instead of running their own terminal probe.
|
|
9
|
+
`oats status` and `oats workspace status` also do less work per read. A
|
|
10
|
+
working instance no longer reads idle when the process scan can't see it.
|
|
11
|
+
The catalog moves to oats.okf 5.7.0, whose knowledge maintainer never parks a
|
|
12
|
+
harvest PR for a human, and to oats.framework 1.16.4.
|
|
13
|
+
|
|
14
|
+
## Upgrade
|
|
15
|
+
|
|
16
|
+
- **Either order of the Desktop and the CLI works.**
|
|
17
|
+
[Upgrading](../upgrading.md) installs the Desktop first, and a host that
|
|
18
|
+
installed the CLI first is fine too: the 0.69.6 Desktop accepts OATS CLIs
|
|
19
|
+
`>=0.26.0 <0.70.0`, and so does the 0.69.5 Desktop. The warm reader needs
|
|
20
|
+
both: a Desktop or TUI uses it only with a CLI that lists feature
|
|
21
|
+
`warm-reader`, and otherwise reads through the CLI, as before.
|
|
22
|
+
- **Package moves:** the official catalog pins oats.okf 5.7.0 and
|
|
23
|
+
oats.framework 1.16.4, with no change to their OATS floors. A deployment
|
|
24
|
+
takes them with `oats sync`. Running instances keep the modules they were
|
|
25
|
+
spawned with: new spawns get the new ones, and a stopped home moves with
|
|
26
|
+
`oats instance upgrade`.
|
|
27
|
+
- **Knowledge PRs parked on `okf-needs-human`:** on the review host of the
|
|
28
|
+
workspace's harvest-review trigger, once its lock has oats.okf 5.7.0,
|
|
29
|
+
re-review each one as Provider updates (below) says. A label left in place
|
|
30
|
+
does nothing, and no new review starts on its own.
|
|
31
|
+
|
|
32
|
+
## Added
|
|
33
|
+
|
|
34
|
+
- The warm reader, `oats reader --stdio` (feature `warm-reader`,
|
|
35
|
+
`readerApi: 1`, #1630). A client starts it as its own child, from the same
|
|
36
|
+
install it runs its CLI reads with, and sends it `oats status --json` and
|
|
37
|
+
`oats workspace status --json` reads over its stdin and stdout, one JSON
|
|
38
|
+
line each way, many times. It answers with the kernel's own read code, kept
|
|
39
|
+
loaded: warm code, not warm data. Every request reads the deployment
|
|
40
|
+
afresh, and each answer's `exit` and `answer` are what the same CLI read
|
|
41
|
+
prints and exits with, with cwd = `--dir`. What it cannot answer that way it
|
|
42
|
+
refuses (`E_READER_BAD_REQUEST`, `E_READER_UNSUPPORTED`), and the client
|
|
43
|
+
runs the CLI. A reader whose install changed under it (an upgrade, a Node
|
|
44
|
+
upgrade) answers nothing more from the old code: it refuses with
|
|
45
|
+
`E_READER_STALE` and exits. It ends when its client closes its stdin or
|
|
46
|
+
dies. Bare `oats reader` is `E_USAGE`. The protocol and the client rules
|
|
47
|
+
are in [The warm reader](../desktop-cli-api.md#the-warm-reader); the
|
|
48
|
+
decisions in [the design record](../design/2026-10-29-warm-reader.md).
|
|
49
|
+
- Feature `status-liveness`: `oats status --json` instance rows' `running`
|
|
50
|
+
and `runtimeState` are the complete local liveness reading, read live at
|
|
51
|
+
every call under the kernel's pane rule, so a client that sees the feature
|
|
52
|
+
in the probe needs no liveness probe of its own beside the roster
|
|
53
|
+
([The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
|
|
54
|
+
|
|
55
|
+
## Changed
|
|
56
|
+
|
|
57
|
+
- **OATS Desktop: the poll's reads go through the warm reader** (#1630).
|
|
58
|
+
Where the installed CLI lists `warm-reader` (`readerApi: 1`), the Desktop's
|
|
59
|
+
bundled server starts one `oats reader --stdio` from that CLI. It answers
|
|
60
|
+
the background `oats status` and `oats workspace status` reads of every
|
|
61
|
+
refresh cycle (`--max-age` above 0) with the kernel's read code kept
|
|
62
|
+
loaded, instead of a Node start per read. The answers are the CLI's own and
|
|
63
|
+
are checked the same way. A live read (the first cycle, a refresh after a
|
|
64
|
+
change, Refresh) still runs the CLI. Whenever the reader is absent, refuses,
|
|
65
|
+
times out, stops answering or exits, that read runs the CLI as before.
|
|
66
|
+
After repeated failures the Desktop uses the CLI until the CLI changes. A
|
|
67
|
+
reader whose install was upgraded under it makes the Desktop probe the CLI
|
|
68
|
+
again. The reader dies with the server that started it, also when the app
|
|
69
|
+
or the server is killed. Nothing about it is shown. `/api/cli` reports its
|
|
70
|
+
state as a diagnostic.
|
|
71
|
+
- **OATS Desktop: no liveness child under `status-liveness`.** With a CLI
|
|
72
|
+
that lists `status-liveness`, the refresh cycle no longer starts its
|
|
73
|
+
terminal-liveness child. A local row's running state, reason and tmux
|
|
74
|
+
record are the ones `oats status` reports, and a reason on a local row is
|
|
75
|
+
always the kernel's. As a result, an instance home with no tmux record
|
|
76
|
+
(every spawn records one) has no terminal for the Desktop to open, where
|
|
77
|
+
the child used to fill in the default session. With an older CLI the child
|
|
78
|
+
runs as before.
|
|
79
|
+
|
|
80
|
+
- `oats tui` reads its deployments in the background through one warm
|
|
81
|
+
`oats reader --stdio` of its own kernel, when that kernel lists feature
|
|
82
|
+
`warm-reader`, in place of two kernel commands per deployment each cycle.
|
|
83
|
+
Its answers are the commands' own, and a live read (`r`), every read
|
|
84
|
+
before the reader is ready and every read it does not answer still run
|
|
85
|
+
the commands, as before. Under feature `status-liveness` the TUI no
|
|
86
|
+
longer runs its probe of the terminals: each instance's running state,
|
|
87
|
+
reason and tmux record are the ones `oats status` reports. As a result,
|
|
88
|
+
an instance home with no tmux record (every spawn records one) has no
|
|
89
|
+
terminal for the TUI to open, where the probe used to fill in the default
|
|
90
|
+
session. With an older kernel the probe runs as before (#1630; [What it
|
|
91
|
+
reads, and what it runs](../tui.md#what-it-reads-and-what-it-runs)).
|
|
92
|
+
- The warm reader (`oats reader --stdio`, #1630) starts with only the code
|
|
93
|
+
its reads use: the CLI no longer loads its whole command set for it first.
|
|
94
|
+
On a real deployment its hello comes in about 140–180 ms instead of about
|
|
95
|
+
300, and it holds about 20 MiB less memory while it answers a poll. Its protocol, its answers
|
|
96
|
+
and its install stamp are unchanged; a client needs no change
|
|
97
|
+
([The warm reader](../desktop-cli-api.md#the-warm-reader)).
|
|
98
|
+
|
|
99
|
+
- `oats status` and `oats workspace status` do less work per read, with the same answers ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630)). `status` shares each instance home's `instance.json`, as its listing read it, with its legacy-home check and its waiting-claim read instead of each parsing it again, and `workspace status` asks git for a member clone's remotes once, where it verified the clone an automation lives in twice. Nothing is kept between reads, in the CLI or in the warm reader (`oats reader --stdio`).
|
|
100
|
+
|
|
101
|
+
- **`oats workspace status --max-age <s>` reuses the host's `gh` login, for display only** ([awebai/oats#1630](https://github.com/awebai/oats/issues/1630); [Observation reuse](../desktop-cli-api.md#the-gh-login-display-only)). To show where each workspace trigger and schedule runs, `workspace status` asks `gh api user` which account this host acts as: a GitHub API call on every read, which a client polling every few seconds made every few seconds, and most of each read's time. Under `--max-age <s>` it now reuses a login observed at most `<s>` seconds ago, as it reuses remote heads, and counts it in the `observation` block (`reused`, `observedAt`). A login is reused only under the same `gh` context (host, `gh` binary, which token variables are set, `GH_HOST`, the config directory and its `hosts.yml`); no token or digest of one is kept; a failed answer is never reused and ends the reuse of the one before it. Without `--max-age`, or with `0`, it asks every time. What runs does not change: a schedule tick, `oats trigger poll` and every run still ask `gh` live. Within `<s>`, a token revoked on GitHub still shows the login, as a moved head shows unmoved.
|
|
102
|
+
- **A `gh` that hangs costs `oats workspace status` 5 s, not 30.** The display waits at most 5 s for `gh api user` (ticks and runs keep 30 s); a `gh` that does not answer in time reads `owner-mismatch`, as one that is not logged in does.
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
## Fixed
|
|
106
|
+
|
|
107
|
+
- **A working instance no longer reads idle when the process scan cannot see it.** tmux names the launch's own shell as a pane's command while the harness runs below it, so `oats status` and `oats session inspect` decide such a pane from the process table. A table that could not establish the fallback prompt still read it: a `ps` that could not see the pane's process (another PID namespace, a pane respawned between the two reads), a process in the pane with no command name, or a line that is not a process each made a running harness read `running: false` (idle) in the Desktop and the TUI. `false` now needs the pane's own shell in the table with no non-shell process below it; anything else reads `running: null` with the reason as `runtimeError` (`session inspect`: `E_SESSION_UNAVAILABLE`), and a lifecycle command refuses rather than taking the pane for a fallback shell. A pane at its fallback prompt still reads `running: false` with `runtimeState: "shell"` ([awebai/oats#1641](https://github.com/awebai/oats/issues/1641); [The roster](../desktop-cli-api.md#the-roster-oats-status---json)).
|
|
108
|
+
|
|
109
|
+
## Provider updates
|
|
110
|
+
|
|
111
|
+
- **oats.okf 5.7.0: the knowledge maintainer never parks a harvest PR**
|
|
112
|
+
([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)).
|
|
113
|
+
When a deployment pins oats.okf 5.7.0, a PR that would supersede a
|
|
114
|
+
human-accepted decision is settled at review instead of waiting for a
|
|
115
|
+
human under the `okf-needs-human` label. The OATS floor is unchanged.
|
|
116
|
+
- It is closed when it cites no acceptance (who accepted the change, when
|
|
117
|
+
and where).
|
|
118
|
+
- A cited record on GitHub (an issue or PR comment, or a commit) is
|
|
119
|
+
checked: it must exist at the cited link, under the account the citation
|
|
120
|
+
names, and say the cited thing. Confirmed, the PR merges as an explicit
|
|
121
|
+
supersession with the acceptance recorded as verified at its link, which
|
|
122
|
+
shows the account and the record, not that the human typed it: agents
|
|
123
|
+
may post under their human's account. Otherwise it is closed.
|
|
124
|
+
- A relay on GitHub (a record that presents itself as an agent reporting
|
|
125
|
+
the human's words) is checked the same way: it must exist at the cited
|
|
126
|
+
link and say that the relaying agent reported the human's acceptance of
|
|
127
|
+
this change. Confirmed, the PR merges as an explicit supersession with
|
|
128
|
+
the acceptance recorded as `source-reported (relay at <link>)`, never as
|
|
129
|
+
verified; otherwise it is closed.
|
|
130
|
+
- A cited record the maintainer cannot read (mail, a session, a call) is
|
|
131
|
+
trusted without a check: the PR merges as an explicit supersession with
|
|
132
|
+
the acceptance recorded as source-reported.
|
|
133
|
+
- `oats okf-maintenance review-context` no longer reports `blocked`, and
|
|
134
|
+
`settled` now means only that the PR is not open.
|
|
135
|
+
- **Re-review each parked PR.** A label left in place is inert, but the
|
|
136
|
+
PR is reviewed again only on a new `harvest-review` event. The trigger
|
|
137
|
+
polls: a close it never saw is no reopen. On the trigger's review host,
|
|
138
|
+
once its lock has 5.7.0:
|
|
139
|
+
1. Retire the knowledge-maintainer instances left from older reviews,
|
|
140
|
+
running or stopped: a retained home holds a concurrency slot (`max`
|
|
141
|
+
2, `perKey` 1), and one composed from an older package keeps the old
|
|
142
|
+
behaviour.
|
|
143
|
+
2. Remove `okf-needs-human` from each parked PR, then close it.
|
|
144
|
+
3. Wait until `oats trigger status <id> --json` shows a `lastPoll`
|
|
145
|
+
after the closes with `ok: true` and `prs` under 100 (every 2m). Only
|
|
146
|
+
such a poll records a close: a failed poll records none (keep
|
|
147
|
+
waiting), and one that fetched 100 open PRs may be truncated (stop
|
|
148
|
+
and report the poll cap; do not reopen). `oats trigger test` does not
|
|
149
|
+
count: it records nothing.
|
|
150
|
+
4. Reopen each PR, and check that `oats trigger status <id> --json`
|
|
151
|
+
lists a `pending` or `fired` entry with `event: "reopened"` for each
|
|
152
|
+
PR's number. At most two reviews run at once; the rest wait as `held`
|
|
153
|
+
until a maintainer retires.
|
|
154
|
+
|
|
155
|
+
Never clear the trigger's dedup state.
|
|
156
|
+
- [Knowledge operations: the flow](../knowledge.md#the-flow), step 4,
|
|
157
|
+
says what holds before and after 5.7.0.
|
|
158
|
+
|
|
159
|
+
- **oats.framework 1.16.4: oats.setup 2.9.5.** oats.setup's `/oats-onboarding`
|
|
160
|
+
pins `oats.okf: v5.7.0` in its knowledge section (text only), so a new
|
|
161
|
+
deployment sets up knowledge operations whose review never parks a harvest
|
|
162
|
+
PR. The floors and the other capabilities are unchanged.
|
|
163
|
+
- **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
|
|
164
|
+
`oats.framework: v1.16.4`. New spawns get it, and a stopped home moves with
|
|
165
|
+
`oats instance upgrade`.
|
package/docs/schedules.md
CHANGED
|
@@ -542,7 +542,14 @@ Otherwise the item is listed with a reason: `assigned-elsewhere`,
|
|
|
542
542
|
else or not at all), `host-unnamed`, or `untrusted` (placed here but not
|
|
543
543
|
trusted: it never runs, and `oats workspace status` warns with the exact
|
|
544
544
|
line to add). Both names come from a commit, so anyone who can commit to a
|
|
545
|
-
member could name your host; trust is the operator's own yes.
|
|
545
|
+
member could name your host; trust is the operator's own yes.
|
|
546
|
+
|
|
547
|
+
`oats workspace status` shows the same placement. Under `--max-age <s>` it
|
|
548
|
+
may show it with a `gh` login observed up to `<s>` seconds ago, and it waits
|
|
549
|
+
at most 5 s for `gh` (a `gh` that does not answer in time reads
|
|
550
|
+
`owner-mismatch`): [the `gh` login, display only](desktop-cli-api.md#the-gh-login-display-only).
|
|
551
|
+
What runs never depends on that: a tick, `oats trigger poll` and every run
|
|
552
|
+
ask `gh` live and wait up to 30 s. A trust entry
|
|
546
553
|
that names no workspace automation is a warning (`automation-trust-stale`),
|
|
547
554
|
not an error: its member may not have synced yet. Your own `oats trigger
|
|
548
555
|
add` / `oats schedule add` definitions need no trust.
|
package/docs/tui.md
CHANGED
|
@@ -2366,10 +2366,27 @@ with the Desktop (`packages/client/`).
|
|
|
2366
2366
|
deployment, run with **the kernel it shipped with** (the `bin/oats.mjs` of
|
|
2367
2367
|
the same install, with the Node that runs the TUI), never an `oats` found
|
|
2368
2368
|
on `PATH`. Each has 30 seconds and 4 MiB.
|
|
2369
|
-
- **
|
|
2370
|
-
|
|
2371
|
-
|
|
2372
|
-
|
|
2369
|
+
- **The background reads go through one warm reader** when that kernel
|
|
2370
|
+
lists feature `warm-reader`: `oats reader --stdio`, started once by the
|
|
2371
|
+
TUI as it starts every kernel command (`node <bin> reader --stdio`, in a
|
|
2372
|
+
session of its own), answers them from one process with the same answers
|
|
2373
|
+
as the two commands. A live read (`r`, the return from a suspend, a row
|
|
2374
|
+
opened in the switcher), every read before the reader is ready, and every
|
|
2375
|
+
read it does not answer are the two commands, as above: nothing waits for
|
|
2376
|
+
it and nothing shows it. The rules are the Desktop's: the client rules
|
|
2377
|
+
of [The warm reader](desktop-cli-api.md#the-warm-reader). An install that changed
|
|
2378
|
+
under the run leaves the TUI on the two commands until it is started
|
|
2379
|
+
again. The reader ends when the TUI does: the TUI holds its stdin, and
|
|
2380
|
+
closing it, on the way out or by the TUI's death, ends it.
|
|
2381
|
+
- **Then one probe of the terminals**, only for a kernel without feature
|
|
2382
|
+
`status-liveness`: a small program of the shared readers asks tmux which
|
|
2383
|
+
instances have a live pane (`tmux list-panes`, and `ps` for what runs in
|
|
2384
|
+
them). It has 30 seconds. An instance the kernel itself reported as
|
|
2385
|
+
unknown is not probed and stays unknown. A kernel with the feature reads
|
|
2386
|
+
that itself, live, in `oats status`: no probe runs, and each instance is
|
|
2387
|
+
as the kernel reported it, its tmux record included. An instance home
|
|
2388
|
+
with no tmux record (every spawn records one) then has no terminal to
|
|
2389
|
+
open, where the probe fills in the default session.
|
|
2373
2390
|
- **Every deployment opened in the run is read each time**, at most two at
|
|
2374
2391
|
a time.
|
|
2375
2392
|
- **How often:** 5 seconds after the last read ended; 30 seconds once ten
|
package/docs/upgrading.md
CHANGED
|
@@ -6,11 +6,11 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.69.
|
|
10
|
-
The 0.69.
|
|
9
|
+
The latest version is **OATS 0.69.6** ([release notes](release-notes/v0.69.6.md)).
|
|
10
|
+
The 0.69.6 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
|
|
11
11
|
|
|
12
12
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
13
|
-
0.69.
|
|
13
|
+
0.69.6,** in the [release notes](release-notes/): it says what to do before
|
|
14
14
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
15
15
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
16
16
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -19,8 +19,8 @@ prints the version you have.
|
|
|
19
19
|
Then, on each host:
|
|
20
20
|
|
|
21
21
|
```sh
|
|
22
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
23
|
-
npm install -g @awebai/oats@0.69.
|
|
22
|
+
# 0. where the Desktop is installed: Desktop 0.69.6 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.6 # 1. the CLI
|
|
24
24
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
25
25
|
oats doctor # 3. in the same deployment
|
|
26
26
|
```
|
|
@@ -172,6 +172,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
172
172
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
173
173
|
here.
|
|
174
174
|
|
|
175
|
+
- **[0.69.6](release-notes/v0.69.6.md#upgrade):** the catalog pins oats.okf
|
|
176
|
+
5.7.0 and oats.framework 1.16.4. On the review host of a workspace's
|
|
177
|
+
harvest-review trigger, re-review each knowledge PR parked on
|
|
178
|
+
`okf-needs-human` as its notes say.
|
|
175
179
|
- **[0.69.5](release-notes/v0.69.5.md#upgrade):** the catalog pins oats.okf
|
|
176
180
|
5.6.0 and oats.cloning 1.1.0, which require OATS >=0.69.2. Every host that
|
|
177
181
|
shares a workspace runs OATS 0.69.2 or later before any of them syncs to
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.16.
|
|
58
|
-
oats.okf: v5.
|
|
57
|
+
oats.framework: v1.16.4 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.7.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
package/lib/argv.mjs
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/** lib/argv.mjs — how the kernel reads `--flag=value` (docs/desktop-cli-api.md "Flag syntax"): the CLI's
|
|
2
|
+
* dispatch expands its argv here once, and a process answering reads (lib/reader.mjs) expands each request's
|
|
3
|
+
* argv here, so both give a malformed flag the same E_BAD_ARGS. Kernel-private, not exported from `./core`.
|
|
4
|
+
* Dependency-free. */
|
|
5
|
+
|
|
6
|
+
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
7
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
|
|
8
|
+
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
9
|
+
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
10
|
+
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
11
|
+
* expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
|
|
12
|
+
/** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
|
|
13
|
+
* value is kept out of argv, where it would read as a flag (`--message=--clear` must not
|
|
14
|
+
* clear), and flag() answers it from `inline`. */
|
|
15
|
+
const INLINE_TEXT_FLAGS = new Set(["message"]);
|
|
16
|
+
/** Free-text flags whose inline value is always kept whole, the empty one included:
|
|
17
|
+
* `--description=` clears a trigger's or schedule's description. */
|
|
18
|
+
const INLINE_WHOLE_FLAGS = new Set(["description"]);
|
|
19
|
+
export function expandInlineValues(argv) {
|
|
20
|
+
const out = [];
|
|
21
|
+
const inline = new Map();
|
|
22
|
+
let problem;
|
|
23
|
+
for (const a of argv) {
|
|
24
|
+
const eq = a.indexOf("=");
|
|
25
|
+
if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
|
|
26
|
+
const name = a.slice(2, eq), value = a.slice(eq + 1);
|
|
27
|
+
if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
|
|
28
|
+
problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
|
|
29
|
+
out.push(`--${name}`, value);
|
|
30
|
+
}
|
|
31
|
+
return { argv: out, problem, inline };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** A flag's value in an expanded argv (`args`, `inline`: expandInlineValues's): its free text from `inline`, the word
|
|
35
|
+
* after it, `true` when it has none (the next word is absent, empty or another flag), undefined when it is not given.
|
|
36
|
+
* The first `--name` wins. */
|
|
37
|
+
export function flagValue(args, inline, name) {
|
|
38
|
+
const i = args.indexOf(`--${name}`);
|
|
39
|
+
if (i >= 0 && inline.has(name)) return inline.get(name);
|
|
40
|
+
return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
|
|
41
|
+
}
|
package/lib/automation-scope.mjs
CHANGED
|
@@ -25,11 +25,13 @@ export function childEnv() {
|
|
|
25
25
|
}
|
|
26
26
|
|
|
27
27
|
/** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
|
|
28
|
-
* an unreadable oats-local.yaml means no workspace automations (the local jobs still run).
|
|
29
|
-
|
|
28
|
+
* an unreadable oats-local.yaml means no workspace automations (the local jobs still run). `remotes`:
|
|
29
|
+
* lib/member-clone.mjs verifyMemberClone's, for a read that verifies the same clones again. `lookup`: the
|
|
30
|
+
* status display's gh login lookup (lib/automations.mjs ghLogin), never an act's. */
|
|
31
|
+
export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map(), remotes, lookup } = {}) {
|
|
30
32
|
let local = null;
|
|
31
33
|
try { local = loadLocal(ws).local; } catch { local = null; }
|
|
32
|
-
const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
|
|
33
|
-
const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
|
|
34
|
+
const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local }, { remotes });
|
|
35
|
+
const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf, lookup });
|
|
34
36
|
return Object.assign(ctx, { ws, local });
|
|
35
37
|
}
|