@awebai/oats 0.69.3 → 0.69.5
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 +68 -49
- package/docs/configuration.md +12 -0
- package/docs/desktop-cli-api.md +8 -1
- package/docs/execution-targets.md +25 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +9 -6
- package/docs/named-test-runs.md +4 -2
- package/docs/official-catalog.md +6 -6
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +25 -18
- package/docs/release-notes/v0.69.4.md +73 -0
- package/docs/release-notes/v0.69.5.md +146 -0
- package/docs/souls-and-instances.md +2 -2
- package/docs/tui.md +2 -1
- package/docs/upgrading.md +16 -5
- package/docs/workspaces.md +2 -2
- package/lib/agents-root.mjs +51 -0
- package/lib/automation-api.mjs +7 -0
- package/lib/automation-scope.mjs +35 -0
- package/lib/automations.mjs +2 -1
- 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 +131 -0
- package/lib/instance-address.mjs +21 -0
- package/lib/instance-lifecycle.mjs +4 -16
- package/lib/instance-listing.mjs +730 -0
- package/lib/instance-resolution.mjs +5 -166
- package/lib/materialize.mjs +2 -87
- package/lib/member-clone.mjs +188 -0
- package/lib/package-catalog.mjs +93 -0
- package/lib/packages.mjs +4 -24
- package/lib/reserved-launch-env.mjs +20 -0
- package/lib/resolved-deployment.mjs +1 -1
- 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-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/write-file-atomic.mjs +28 -0
- package/package-catalog.json +5 -5
- package/package.json +1 -1
- package/packages/tui/lib/store.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/release-lane.md
CHANGED
|
@@ -170,21 +170,26 @@ by a full commit id, with the exact version in a comment beside it:
|
|
|
170
170
|
|
|
171
171
|
A tag is the action owner's to move, and a commit is not: the code that runs
|
|
172
172
|
with the publishing rights is the code that was read. `build-installers.yml`
|
|
173
|
-
runs the same installer steps, so it names the same commits.
|
|
173
|
+
runs the same installer steps, so it names the same commits. So does
|
|
174
|
+
`tui-macos.yml`, the TUI's tests on macOS at pull-request time, by the release
|
|
175
|
+
lane's call of 2026-10-27: it runs a branch's code on the release's own
|
|
176
|
+
actions, and its run is that pull request's macOS evidence, so it names them
|
|
177
|
+
at the commits that were read
|
|
178
|
+
([Implementation](implementation.md#the-tuis-tests-on-macos)). Every other
|
|
174
179
|
workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
|
|
175
180
|
|
|
176
181
|
`test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
|
|
177
|
-
were read has a row for each action: `action`, `id`, `version`. In the
|
|
178
|
-
every `uses:` is a row's id, the same action is the same id in
|
|
179
|
-
comment beside an id is the row's version. In every other
|
|
180
|
-
is the major of a row's version.
|
|
182
|
+
were read has a row for each action: `action`, `id`, `version`. In the three
|
|
183
|
+
files every `uses:` is a row's id, the same action is the same id in all of
|
|
184
|
+
them, and the comment beside an id is the row's version. In every other
|
|
185
|
+
workflow a `uses:` is the major of a row's version.
|
|
181
186
|
|
|
182
187
|
**An id is moved by a pull request, reviewed like any change to that
|
|
183
|
-
workflow.** It changes these together, and nothing else in the
|
|
188
|
+
workflow.** It changes these together, and nothing else in the three workflow
|
|
184
189
|
files:
|
|
185
190
|
|
|
186
191
|
- the id and the version comment, on every `uses:` line of that action in
|
|
187
|
-
`release.yml` and `
|
|
192
|
+
`release.yml`, `build-installers.yml` and `tui-macos.yml`;
|
|
188
193
|
- the action's row in the table.
|
|
189
194
|
|
|
190
195
|
**The id is read from an exact version tag of the action's own repository**
|
|
@@ -216,21 +221,23 @@ and packages it depends on, and what its entry points call of a cache.
|
|
|
216
221
|
needs `package-manager-cache: false` on every step. The test takes the
|
|
217
222
|
version of an id from the row, so it refuses a step without it.
|
|
218
223
|
|
|
219
|
-
|
|
220
|
-
name `macos-14`), never by a label that GitHub
|
|
221
|
-
itself (`ubuntu-latest`). The Linux installers are
|
|
222
|
-
what they need of a system follows the system that
|
|
224
|
+
**`release.yml` and `build-installers.yml` name their runners by version
|
|
225
|
+
too** (`ubuntu-24.04`, as they name `macos-14`), never by a label that GitHub
|
|
226
|
+
moves to another system by itself (`ubuntu-latest`). The Linux installers are
|
|
227
|
+
built on that runner, and what they need of a system follows the system that
|
|
228
|
+
built them.
|
|
223
229
|
`pull-request.yml` keeps `ubuntu-latest` on purpose: when the label moves, a
|
|
224
230
|
break on the new system shows in pull-request CI first and not at a release.
|
|
225
231
|
|
|
226
|
-
The labels
|
|
227
|
-
`test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
|
|
228
|
-
of the two
|
|
229
|
-
same Linux. A label is added to the list by whoever decides the runner,
|
|
230
|
-
action's row is by whoever read it.
|
|
232
|
+
The labels `release.yml` and `build-installers.yml` may name are a list beside
|
|
233
|
+
the table of actions in `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
|
|
234
|
+
`macos-14`. Every job of the two runs on a label of that list, and both build
|
|
235
|
+
on the same Linux. A label is added to the list by whoever decides the runner,
|
|
236
|
+
as an action's row is by whoever read it.
|
|
231
237
|
|
|
232
|
-
**Moving the runner is a pull request** that changes the label in
|
|
233
|
-
|
|
238
|
+
**Moving the runner is a pull request** that changes the label in
|
|
239
|
+
`release.yml`, `build-installers.yml` and the list together, and says what the
|
|
240
|
+
installers then need.
|
|
234
241
|
|
|
235
242
|
**What the Linux installer needs today**, to compare with at the next move.
|
|
236
243
|
Read from `oats-desktop-0.52.0-linux-amd64.deb`, built on `ubuntu-24.04`
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# OATS 0.69.4
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
0.69.4 ships the new coordination skills. Finished instances retire
|
|
6
|
+
automatically, coordinated between agents without a human
|
|
7
|
+
(oats.engineering 1.17.2). An overrun maintainer gets an overflow seat. And
|
|
8
|
+
oats.core says a soul's capabilities can call for a spawn (oats.framework
|
|
9
|
+
1.16.2). There is no kernel or Desktop change beyond the version.
|
|
10
|
+
|
|
11
|
+
## Upgrade
|
|
12
|
+
|
|
13
|
+
- **Install the Desktop first and the CLI second,** as
|
|
14
|
+
[Upgrading](../upgrading.md) says. The 0.69.4 Desktop accepts OATS CLIs
|
|
15
|
+
`>=0.26.0 <0.70.0`.
|
|
16
|
+
- **Package moves:** the official catalog pins oats.framework 1.16.2 and
|
|
17
|
+
oats.engineering 1.17.2 (Provider updates, below). A deployment takes them
|
|
18
|
+
with `oats sync`.
|
|
19
|
+
- **Running instances keep the skills they were spawned with.** New spawns
|
|
20
|
+
get the new skills. A running instance is stopped first, moved with
|
|
21
|
+
`oats instance upgrade`, then started again (`oats session start`).
|
|
22
|
+
|
|
23
|
+
## Changed
|
|
24
|
+
|
|
25
|
+
- **oats.core: spawning a child your capabilities call for needs no human.**
|
|
26
|
+
`/oats-operate` and `/oats-souls` said to spawn only when your task or your
|
|
27
|
+
human asks (or a documented workflow requires it), and to ask your human
|
|
28
|
+
when a relation is unclear. They now also admit your soul's capabilities, as
|
|
29
|
+
the "You run on OATS" block already does (a developer spawning its
|
|
30
|
+
reviewer, an expert its developers), and send a question about an unclear
|
|
31
|
+
relation to your parent or the agent that gave you the task, and to your
|
|
32
|
+
human only when no agent can say. A capability that spawns its own helpers
|
|
33
|
+
no longer reads as needing a human for it.
|
|
34
|
+
|
|
35
|
+
## Provider updates
|
|
36
|
+
|
|
37
|
+
- **oats.engineering 1.17.2: finished instances retire automatically, and an
|
|
38
|
+
overrun maintainer gets an overflow seat.** The catalog and this workspace
|
|
39
|
+
pin `oats.engineering: v1.17.2`. The floor is unchanged.
|
|
40
|
+
- **Automatic retirement** (oats-engineering#28). An instance is finished
|
|
41
|
+
when three things hold:
|
|
42
|
+
- its PRs are merged and green, or closed (handed back is not landed);
|
|
43
|
+
- nothing waits on it;
|
|
44
|
+
- its final harvest is launched.
|
|
45
|
+
|
|
46
|
+
It then sends its parent a done line, and its parent retires it after
|
|
47
|
+
checking that the work tree is clean and pushed and that nothing is
|
|
48
|
+
attached, without asking or telling a human. A developer retires its
|
|
49
|
+
reviewer, an expert its developers, a maintainer the leads it spawned. An
|
|
50
|
+
instance with no OATS parent retires itself. Maintainers are standing
|
|
51
|
+
seats and are never retired this way.
|
|
52
|
+
- **Overflow seat** (oats-engineering#29). A maintainer with more than 5
|
|
53
|
+
efforts of its own in flight spawns one overflow seat as its child. The
|
|
54
|
+
seat drives the new intake up to hand-back. It holds no entry on the lane
|
|
55
|
+
map, and merges, second reads and sign-offs stay with its parent.
|
|
56
|
+
- 1.17.1 and 1.17.2 fix two lines of 1.17.0. An instance with no parent
|
|
57
|
+
retires itself with `oats retire "$OATS_INSTANCE" --self`, because the
|
|
58
|
+
kernel requires the name. The harvest condition names no knowledge-layer
|
|
59
|
+
command: your knowledge layer says whether you have a harvest duty.
|
|
60
|
+
- **Upgrade:** `oats sync` locks it. New spawns get it, and a stopped home
|
|
61
|
+
moves to it with `oats instance upgrade`.
|
|
62
|
+
|
|
63
|
+
- **oats.framework 1.16.2: oats.core 2.9.1.** oats.core's `/oats-operate`
|
|
64
|
+
and `/oats-souls` now state spawning authority the way its "You run on
|
|
65
|
+
OATS" inject already does. You spawn when your task, your human or your
|
|
66
|
+
soul's capabilities say so, so a developer spawning its reviewer, or an
|
|
67
|
+
expert its developers, needs no human. When a relation is unclear, ask
|
|
68
|
+
your parent or the agent that gave you the task first, and your human
|
|
69
|
+
only when no agent can say (#1621). This is text only. The floors are
|
|
70
|
+
unchanged, and the other capabilities are unchanged.
|
|
71
|
+
- **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
|
|
72
|
+
`oats.framework: v1.16.2`. New spawns get it, and a stopped home moves with
|
|
73
|
+
`oats instance upgrade`, from OATS 0.68.0.
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# OATS 0.69.5
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
0.69.5 makes the commands OATS runs most often start faster, and it shows a
|
|
6
|
+
lost session as `LOST` in `oats status` and `oats server roster`. A restart
|
|
7
|
+
whose relaunch fails no longer comes back on the next resume. The catalog
|
|
8
|
+
moves to oats.okf 5.6.0 and oats.cloning 1.1.0, whose one-shot service souls
|
|
9
|
+
are listed under Background, and to oats.aweb 1.32.1 and oats.framework
|
|
10
|
+
1.16.3. This workspace stops pinning oats.cloning.
|
|
11
|
+
|
|
12
|
+
## Upgrade
|
|
13
|
+
|
|
14
|
+
- **Install the Desktop first and the CLI second,** as
|
|
15
|
+
[Upgrading](../upgrading.md) says. The 0.69.5 Desktop accepts OATS CLIs
|
|
16
|
+
`>=0.26.0 <0.70.0`.
|
|
17
|
+
- **OATS 0.69.2 or later on every host that shares a workspace, before any of
|
|
18
|
+
them syncs:** oats.okf 5.6.0 and oats.cloning 1.1.0 require it. On an older
|
|
19
|
+
kernel, `oats sync` still locks them, but their souls are dropped and new
|
|
20
|
+
spawns that compose them are refused (`E_CAPABILITY_INCOMPATIBLE`, naming
|
|
21
|
+
the re-pin) (Provider updates, below). Where oats.okf is the workspace's
|
|
22
|
+
default knowledge slot, that is nearly every new spawn.
|
|
23
|
+
- **Package moves:** the official catalog pins oats.okf 5.6.0, oats.cloning
|
|
24
|
+
1.1.0, oats.aweb 1.32.1 and oats.framework 1.16.3. A deployment takes them
|
|
25
|
+
with `oats sync`. Running instances keep the modules they were spawned
|
|
26
|
+
with: new spawns get the new ones, and a stopped home moves with
|
|
27
|
+
`oats instance upgrade`.
|
|
28
|
+
- **A new cache directory:** every `oats` command keeps Node's compile cache
|
|
29
|
+
in `~/.oats/compile-cache` (Changed, below). It is safe to delete.
|
|
30
|
+
|
|
31
|
+
## Changed
|
|
32
|
+
|
|
33
|
+
- **`oats` commands start faster: the CLI keeps Node's compile cache.** Node
|
|
34
|
+
no longer recompiles the kernel on every command: each command starts
|
|
35
|
+
faster, by about a quarter for a cheap read such as `oats version`, and the
|
|
36
|
+
status polls the Desktop and the TUI make cost less. The cache is a new
|
|
37
|
+
directory, `~/.oats/compile-cache` (`$OATS_HOME_DIR/compile-cache`),
|
|
38
|
+
created mode 0700. It is safe to delete at any time. `NODE_COMPILE_CACHE`
|
|
39
|
+
moves it, and `NODE_DISABLE_COMPILE_CACHE=1` turns it off
|
|
40
|
+
([configuration](../configuration.md#the-compile-cache)). Nothing a command
|
|
41
|
+
prints changes.
|
|
42
|
+
|
|
43
|
+
- **The reads OATS makes most often load only what they use.** `oats version`,
|
|
44
|
+
`session inspect`, `status`, `workspace status`, `instance events` and
|
|
45
|
+
`instance waiting clear` no longer load the whole kernel. `oats version` takes
|
|
46
|
+
less than half its time and `session inspect` about half; `status` takes about
|
|
47
|
+
an eighth less and `workspace status` about a fifth less; `instance events` and
|
|
48
|
+
the waiting hook a Claude instance runs every turn take about a quarter less.
|
|
49
|
+
Nothing a command prints changes.
|
|
50
|
+
|
|
51
|
+
## Fixed
|
|
52
|
+
|
|
53
|
+
- **A restart whose relaunch fails no longer reads `lost`, so a resume does not bring back the session you were restarting.** `oats session restart` stopped the running harness and then relaunched it, without recording the stop. When the relaunch failed, or the restart died between the two, the home read `sessionEnd: "lost"`, and the next resume sweep (OATS Desktop or `oats tui` opening) started the old launch again. A restart now records the stop before it asks the harness to end, as a retire does, so such a home reads `stopped` and stays down; a successful relaunch records a new start, which reads as before. A restart whose stop is refused keeps that record, so its harness, should it die later, reads `stopped` rather than `lost` ([awebai/oats#1601](https://github.com/awebai/oats/issues/1601); [Resume after a shutdown](../execution-targets.md#resume-after-a-shutdown)).
|
|
54
|
+
|
|
55
|
+
- **`oats tui` no longer replaces the answer to what you did with its own line.** When the add of the deployment a run started in to this computer's list fails, the line that says so waits again until a line answering your own act has gone, as it did before 0.69.2. The add answers in the run's first moments, so this shows only when you act before it does: a correctness restore, rarely visible ([awebai/oats#1603](https://github.com/awebai/oats/issues/1603); [Start it](../tui.md#start-it)).
|
|
56
|
+
|
|
57
|
+
- **The pi bridge loads the kernel that launched its instance first**
|
|
58
|
+
([#1604](https://github.com/awebai/oats/issues/1604)). Pi instances were
|
|
59
|
+
never affected: each home's own `oats` link is first on the PATH pi
|
|
60
|
+
launches with, so the bridge found the launching kernel with no global
|
|
61
|
+
install. Now the bridge reads that link directly, after `OATS_PKG_ROOT`
|
|
62
|
+
and before any PATH or global lookup, so a home loads its own kernel
|
|
63
|
+
whatever PATH pi has. A pi started outside any instance, on a host with no
|
|
64
|
+
global install and an `oats` that is a script rather than a link to the
|
|
65
|
+
kernel, failed with "the pi adapter needs the oats CLI installed
|
|
66
|
+
globally". It now says "OATS kernel not found" and names the three ways
|
|
67
|
+
out: `npm install -g @awebai/oats`, an `oats` on PATH that links to the
|
|
68
|
+
kernel's `bin/oats.mjs` (`npm link` in a checkout), or `OATS_PKG_ROOT`
|
|
69
|
+
([the bridge's README](../../packages/pi/README.md)).
|
|
70
|
+
|
|
71
|
+
- **`oats status` printed a lost session as `idle`**
|
|
72
|
+
([#1617](https://github.com/awebai/oats/issues/1617)). The text views of
|
|
73
|
+
`oats status` and `oats status --server <id>` printed every row that does
|
|
74
|
+
not run as `idle`, so a session lost to a reboot or a dead tmux server read
|
|
75
|
+
the same as one stopped on purpose. A row whose `sessionEnd` is `lost` now
|
|
76
|
+
prints `LOST`, with one line under it naming the way back: `oats session
|
|
77
|
+
start --resume --home <home>`, or the next `oats session resume` (run when
|
|
78
|
+
OATS Desktop or `oats tui` opens) when it can vouch for the loss. A
|
|
79
|
+
`--server` row names the host to run them on. A stopped, exited or
|
|
80
|
+
never-launched row, and a row from a host whose kernel reports no
|
|
81
|
+
`sessionEnd`, still print `idle`.
|
|
82
|
+
The JSON is unchanged
|
|
83
|
+
([How a session's end is read](../execution-targets.md#how-a-sessions-end-is-read)).
|
|
84
|
+
|
|
85
|
+
- **`oats server roster` printed a lost session as `idle`**
|
|
86
|
+
([#1628](https://github.com/awebai/oats/issues/1628)). Its rows did not
|
|
87
|
+
relay the host's `sessionEnd`, so the roster could not tell a session lost
|
|
88
|
+
to a reboot or a dead tmux server from one stopped on purpose. A roster row
|
|
89
|
+
of `server roster --json` now carries `sessionEnd` when the host's row has
|
|
90
|
+
it, with the host's value: `lost`, `stopped` or `exited`. A host whose
|
|
91
|
+
kernel reports no `sessionEnd` gives rows as before. The roster line prints
|
|
92
|
+
a lost row as `LOST`, with one line under it naming the way back on that
|
|
93
|
+
host, as `oats status --server <id>` does
|
|
94
|
+
([`sessionEnd` on a roster row](../desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
|
|
95
|
+
|
|
96
|
+
## Provider updates
|
|
97
|
+
|
|
98
|
+
- **oats.aweb 1.32.1: recover pi mail lost on an interrupted turn.** The
|
|
99
|
+
catalog and this workspace pin `oats.aweb: v1.32.1`, from 1.32.0. It is
|
|
100
|
+
guidance only, cut from 1.32.0 with this one change: with `@awebai/pi`
|
|
101
|
+
0.4.0, mail that arrives during a turn can be lost when the human
|
|
102
|
+
interrupts it (awebai/aweb#68). The inject and `/oats-aweb` section 4 now
|
|
103
|
+
have affected pi instances scan `aw mail inbox --show-all --json` after any
|
|
104
|
+
interrupted turn and at task boundaries, and reconcile by message id. The
|
|
105
|
+
workaround goes once a fixed `@awebai/pi` is pinned. OATS >=0.68.0 and the
|
|
106
|
+
aw floor are unchanged.
|
|
107
|
+
|
|
108
|
+
- **oats.cloning 1.1.0: cloners are background instances.** The catalog
|
|
109
|
+
pins oats.cloning `v1.1.0`, from 1.0.1. The `cloner` soul says
|
|
110
|
+
`background: true`, so the Desktop and `oats tui` list a new cloner under
|
|
111
|
+
their Background section (oats-cloning#6, awebai/oats#1579). The clone
|
|
112
|
+
itself is placed as its own soul says.
|
|
113
|
+
- **Upgrade:** 1.1.0 requires **OATS >=0.69.2** (was >=0.34.0): an older
|
|
114
|
+
kernel drops the soul, so `oats cloning request` refuses with
|
|
115
|
+
`E_SOUL_UNKNOWN`. Upgrade OATS first, then `oats sync`.
|
|
116
|
+
- **This workspace no longer pins oats.cloning,** and its souls no longer
|
|
117
|
+
compose it: new instances of them have no `/clone-instance`. Running
|
|
118
|
+
instances keep the copy they were spawned with. A workspace that wants
|
|
119
|
+
cloning pins `oats.cloning: v1.1.0` and composes
|
|
120
|
+
`oats.cloning: { from: package }` in the souls that may request clones.
|
|
121
|
+
|
|
122
|
+
- **oats.framework 1.16.3: oats.setup 2.9.4.** oats.setup's `/oats-onboarding`
|
|
123
|
+
pins `oats.okf: v5.6.0` in its knowledge section and names its kernel floor,
|
|
124
|
+
OATS 0.69.2 (text only). The other capabilities are unchanged.
|
|
125
|
+
- **Upgrade:** `oats sync` locks it once the workspace or the catalog pins
|
|
126
|
+
`oats.framework: v1.16.3`. New spawns get it, and a stopped home moves with
|
|
127
|
+
`oats instance upgrade`.
|
|
128
|
+
|
|
129
|
+
- **oats.okf 5.6.0: knowledge harvesters and knowledge maintainers are
|
|
130
|
+
background instances.** The catalog and this workspace pin
|
|
131
|
+
`oats.okf: v5.6.0`, from 5.5.0. Both package souls say `background: true`,
|
|
132
|
+
so the Desktop and `oats tui` list new harvesters and knowledge maintainers
|
|
133
|
+
under their Background section (oats-okf#113, awebai/oats#1579). Existing
|
|
134
|
+
instances do not move, and harvest and review behave as before.
|
|
135
|
+
- **Upgrade:** 5.6.0 requires **OATS >=0.69.2** (was >=0.49.0): an older
|
|
136
|
+
kernel refuses the `background:` key, so it drops both souls and refuses
|
|
137
|
+
new spawns that compose oats.okf (`E_CAPABILITY_INCOMPATIBLE`, naming the
|
|
138
|
+
re-pin). Upgrade OATS on every host that shares the workspace first, then
|
|
139
|
+
`oats sync`.
|
|
140
|
+
|
|
141
|
+
## Documentation
|
|
142
|
+
|
|
143
|
+
- **Which losses come back** names one more limit: the 24-hour gap of clause
|
|
144
|
+
4 does not reach across a reboot, so after a quiet spell of more than a day
|
|
145
|
+
with no OATS read, the first sweep after a restart can bring back a session
|
|
146
|
+
lost during it ([Which losses come back](../execution-targets.md#which-losses-come-back)).
|
|
@@ -420,8 +420,8 @@ proposes promotions by pull request. See [knowledge](knowledge.md).
|
|
|
420
420
|
|
|
421
421
|
### Spawning and coordinating with other agents
|
|
422
422
|
|
|
423
|
-
OATS agents can run `oats spawn` when their
|
|
424
|
-
|
|
423
|
+
OATS agents can run `oats spawn` when their task, their human or their
|
|
424
|
+
soul's capabilities call for another instance. The spawned agent is another
|
|
425
425
|
full OATS instance, with its own soul, home, worktree, and lifecycle.
|
|
426
426
|
|
|
427
427
|
Spawn lineage is **explicit** and relation-based:
|
package/docs/tui.md
CHANGED
|
@@ -67,7 +67,8 @@ and is said once, in the line under the list of workspaces, in the kernel's word
|
|
|
67
67
|
it comes while the switcher, the help, a confirmation, the palette, the
|
|
68
68
|
spawn prompt, a detail or a terminal has the screen or the focus, it is said
|
|
69
69
|
once a view's list has the focus again, so no screen that covers the
|
|
70
|
-
sidebar hides it.
|
|
70
|
+
sidebar hides it. It never replaces a line that answers something you did:
|
|
71
|
+
it waits until that line goes. A deployment opened from the switcher is
|
|
71
72
|
on the list already.
|
|
72
73
|
|
|
73
74
|
**From inside an agent's pane it still reads the deployment you asked
|
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.5** ([release notes](release-notes/v0.69.5.md)).
|
|
10
|
+
The 0.69.5 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.5,** 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.5 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.5 # 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
|
```
|
|
@@ -53,6 +53,12 @@ must be at the same version: a pi session with an older bridge runs old
|
|
|
53
53
|
extension code against a new kernel. A host that launches no pi instance has
|
|
54
54
|
no bridge, and step 2 has nothing to move.
|
|
55
55
|
|
|
56
|
+
The bridge loads the kernel that launched its pi instance, so a host that
|
|
57
|
+
runs the CLI from a checkout or a local install needs no global one for its
|
|
58
|
+
instances. A pi started outside any instance looks for a global install, an
|
|
59
|
+
`oats` on PATH that links to the kernel, or `OATS_PKG_ROOT`
|
|
60
|
+
([the bridge's README](../packages/pi/README.md)).
|
|
61
|
+
|
|
56
62
|
**A release's own steps are in its notes**, in its `## Upgrade` section.
|
|
57
63
|
This page is the part that is the same for every release.
|
|
58
64
|
|
|
@@ -166,6 +172,11 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
166
172
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
167
173
|
here.
|
|
168
174
|
|
|
175
|
+
- **[0.69.5](release-notes/v0.69.5.md#upgrade):** the catalog pins oats.okf
|
|
176
|
+
5.6.0 and oats.cloning 1.1.0, which require OATS >=0.69.2. Every host that
|
|
177
|
+
shares a workspace runs OATS 0.69.2 or later before any of them syncs to
|
|
178
|
+
them; an older kernel drops their souls and refuses new spawns that compose
|
|
179
|
+
them. It also pins oats.aweb 1.32.1 and oats.framework 1.16.3.
|
|
169
180
|
- **[0.69.2](release-notes/v0.69.2.md#upgrade):** the catalog pins
|
|
170
181
|
oats.framework 1.16.1 and oats.okf 5.5.0. Sync each deployment before its
|
|
171
182
|
instances on oats.okf 5.5.0 write proposals: an older harvester refuses
|
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.3 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.6.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
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/** The agents root a command works in: found by walking up from a directory (findRoot), or checked
|
|
2
|
+
* where one is named (ensureRoot), and its canonical spelling. A leaf (awebai/oats#1630): the hot reads
|
|
3
|
+
* resolve their scope without loading core.mjs, which re-exports these. */
|
|
4
|
+
import { existsSync, lstatSync } from "node:fs";
|
|
5
|
+
import { resolve, dirname, join, basename } from "node:path";
|
|
6
|
+
import { resolvedDeployment } from "./resolved-deployment.mjs";
|
|
7
|
+
import { oatsError } from "./errors.mjs";
|
|
8
|
+
import { canonicalDeploymentPath } from "./deployment-path.mjs";
|
|
9
|
+
|
|
10
|
+
// ---------- root discovery ----------
|
|
11
|
+
/** Closest agents/ walking up from `cwd`. A deployment whose agents/ was never
|
|
12
|
+
* created has no root here; ensureRoot names the remedy. */
|
|
13
|
+
export function findRoot(cwd = process.cwd()) {
|
|
14
|
+
if (process.env.PI_AGENTS_ROOT) return resolve(process.env.PI_AGENTS_ROOT);
|
|
15
|
+
let d = resolve(cwd);
|
|
16
|
+
while (true) {
|
|
17
|
+
if (basename(d) === "agents" && lstatSync(d).isDirectory()) return d;
|
|
18
|
+
const candidate = join(d, "agents");
|
|
19
|
+
if (existsSync(candidate) && lstatSync(candidate).isDirectory()) return candidate;
|
|
20
|
+
const parent = dirname(d);
|
|
21
|
+
if (parent === d) return undefined;
|
|
22
|
+
d = parent;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** The canonical deployment root — where instance homes belong. */
|
|
27
|
+
export function canonicalAgentsRoot(root) { return canonicalDeploymentPath(root); }
|
|
28
|
+
export function ensureRoot(cwd) {
|
|
29
|
+
const root = findRoot(cwd);
|
|
30
|
+
if (!root) {
|
|
31
|
+
const from = resolve(cwd ?? process.cwd());
|
|
32
|
+
// Workspace model: an oats-local.yaml above `from` IS a deployment whose instance
|
|
33
|
+
// root (<deployment>/agents/) was never created — name that remedy, not a v1 verb.
|
|
34
|
+
let localDeployment = null;
|
|
35
|
+
for (let d = from; ; d = dirname(d)) { if (existsSync(join(d, "oats-local.yaml"))) { localDeployment = d; break; } if (dirname(d) === d) break; }
|
|
36
|
+
if (localDeployment) {
|
|
37
|
+
throw oatsError("E_NO_DEPLOYMENT",
|
|
38
|
+
`no instance root walking up from ${from}: ${join(localDeployment, "oats-local.yaml")} names this deployment but ${join(localDeployment, "agents")} does not exist — mkdir ${join(localDeployment, "agents")} (or run \`oats sync --dir ${localDeployment}\`, which creates it)`,
|
|
39
|
+
{ from, looked: ["agents/"], deployment: localDeployment, local: join(localDeployment, "oats-local.yaml"), remedy: `mkdir ${join(localDeployment, "agents")} (or run oats sync)` });
|
|
40
|
+
}
|
|
41
|
+
throw oatsError("E_NO_DEPLOYMENT",
|
|
42
|
+
`no deployment found walking up from ${from}: no agents/ directory — run from the deployment (where oats-local.yaml lives; \`oats onboard\` creates one), or set PI_AGENTS_ROOT`,
|
|
43
|
+
{ from, looked: ["agents/"] });
|
|
44
|
+
}
|
|
45
|
+
// Deployment root ≠ invocation CWD: homes always land in the primary checkout.
|
|
46
|
+
const canonical = canonicalAgentsRoot(root);
|
|
47
|
+
resolvedDeployment(dirname(canonical), { canonical: true });
|
|
48
|
+
return canonical;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function workspaceOf(root) { return dirname(root); }
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** The API versions of the automation answers (`scheduleApi` and `automationsApi` in `version --json`).
|
|
2
|
+
* A leaf (awebai/oats#1630): `oats version` reads them without loading schedule.mjs or automations.mjs,
|
|
3
|
+
* which re-export them. */
|
|
4
|
+
|
|
5
|
+
export const SCHEDULE_API = 2;
|
|
6
|
+
|
|
7
|
+
export const AUTOMATIONS_API = 1;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** scopeAutomations: the triggers and schedules a deployment declares, read with the clone each one
|
|
2
|
+
* needs, and childEnv, the environment a scheduled job runs with. A leaf (awebai/oats#1630):
|
|
3
|
+
* `oats workspace status` reads the automation scope without loading schedule.mjs and core.mjs;
|
|
4
|
+
* schedule.mjs imports both and re-exports them. */
|
|
5
|
+
import { loadLocal } from "./workspace.mjs";
|
|
6
|
+
import { resolveMemberClone } from "./member-clone.mjs";
|
|
7
|
+
import { automationContext } from "./automations.mjs";
|
|
8
|
+
import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
|
|
9
|
+
|
|
10
|
+
/** The environment a scheduler-launched oats child runs with: the caller's
|
|
11
|
+
* frozen instance identity and capability snapshot removed (a tick or run-now
|
|
12
|
+
* may be invoked from inside an unrelated instance; dispatch belongs to the
|
|
13
|
+
* job's cwd and explicit selectors, never to that caller), host configuration
|
|
14
|
+
* such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
|
|
15
|
+
export function childEnv() {
|
|
16
|
+
const env = { ...process.env };
|
|
17
|
+
for (const key of [...RESERVED_LAUNCH_ENV,
|
|
18
|
+
"OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
|
|
19
|
+
"OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
|
|
20
|
+
"OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
|
|
21
|
+
"OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
|
|
22
|
+
"OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
|
|
23
|
+
]) delete env[key];
|
|
24
|
+
return env;
|
|
25
|
+
}
|
|
26
|
+
|
|
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
|
+
export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
|
|
30
|
+
let local = null;
|
|
31
|
+
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
|
+
return Object.assign(ctx, { ws, local });
|
|
35
|
+
}
|
package/lib/automations.mjs
CHANGED
|
@@ -40,8 +40,9 @@ import YAML from "yaml";
|
|
|
40
40
|
import { parseConfigData } from "./config-data.mjs";
|
|
41
41
|
import { editLocal } from "./local-edit.mjs";
|
|
42
42
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
43
|
+
import { AUTOMATIONS_API } from "./automation-api.mjs";
|
|
44
|
+
export { AUTOMATIONS_API } from "./automation-api.mjs";
|
|
43
45
|
|
|
44
|
-
export const AUTOMATIONS_API = 1;
|
|
45
46
|
export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
|
|
46
47
|
export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewhere", "owner-mismatch", "untrusted"]);
|
|
47
48
|
/** The kinds, in the order the snapshot keeps them (`triggers`, `schedules`). */
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/** Node's compile cache for the CLI (awebai/oats#1630): V8 keeps the code it compiled for the
|
|
2
|
+
* kernel's modules, so a command does not recompile them all on every run. Kernel-private, not
|
|
3
|
+
* exported from `./core` and not a contract: `bin/oats.mjs` calls enableCliCompileCache before it
|
|
4
|
+
* imports the kernel (only the dependency-free lib/hot-reads.mjs is parsed before), and in-process
|
|
5
|
+
* consumers never call it (they run in their own processes).
|
|
6
|
+
*
|
|
7
|
+
* - The cache is `$OATS_HOME_DIR/compile-cache` (`~/.oats/compile-cache`), made 0700 here: Node's
|
|
8
|
+
* default, `os.tmpdir()/node-compile-cache`, is shared by every user of the computer, and Node
|
|
9
|
+
* would make the directory 0755. Node keeps one subdirectory per Node version under it; the whole
|
|
10
|
+
* directory is safe to delete at any time.
|
|
11
|
+
* - The caller's choice wins, and Node applies it before any of this runs: with NODE_COMPILE_CACHE
|
|
12
|
+
* (another place) or NODE_DISABLE_COMPILE_CACHE (none) set, nothing is made or written under
|
|
13
|
+
* OATS_HOME_DIR. There is no OATS variable for it.
|
|
14
|
+
* - Never in the way: a Node without enableCompileCache (22.0), a directory that cannot be made or
|
|
15
|
+
* written, any throw, is simply no cache, with nothing printed. NODE_COMPILE_CACHE is never set in
|
|
16
|
+
* the environment, so hooks and other children inherit only what the caller gave.
|
|
17
|
+
* Node built-ins only, so that it parses nothing of the kernel. */
|
|
18
|
+
import { mkdirSync } from "node:fs";
|
|
19
|
+
import module from "node:module";
|
|
20
|
+
import { homedir } from "node:os";
|
|
21
|
+
import { join } from "node:path";
|
|
22
|
+
|
|
23
|
+
export function enableCliCompileCache() {
|
|
24
|
+
// A named import would be a link-time SyntaxError on a Node that lacks it.
|
|
25
|
+
if (typeof module.enableCompileCache !== "function") return;
|
|
26
|
+
// As Node reads them: any NODE_DISABLE_COMPILE_CACHE disables, even "" or "0"; an empty
|
|
27
|
+
// NODE_COMPILE_CACHE is none.
|
|
28
|
+
if (process.env.NODE_COMPILE_CACHE || process.env.NODE_DISABLE_COMPILE_CACHE !== undefined) return;
|
|
29
|
+
try {
|
|
30
|
+
const dir = join(process.env.OATS_HOME_DIR || join(homedir(), ".oats"), "compile-cache");
|
|
31
|
+
// Made here first, also because Node 22 never returns from a directory it cannot make.
|
|
32
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
33
|
+
// The string form: Node 22 takes no options object.
|
|
34
|
+
module.enableCompileCache(dir);
|
|
35
|
+
} catch { /* no cache */ }
|
|
36
|
+
}
|