@awebai/oats 0.69.3 → 0.69.4
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/docs/implementation.md +32 -0
- package/docs/named-test-runs.md +4 -2
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +25 -18
- package/docs/release-notes/v0.69.4.md +73 -0
- package/docs/souls-and-instances.md +2 -2
- package/docs/upgrading.md +5 -5
- package/docs/workspaces.md +1 -1
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/implementation.md
CHANGED
|
@@ -509,6 +509,38 @@ dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
|
|
|
509
509
|
and is the gate. Tests use local bare repositories and fakes; none contacts
|
|
510
510
|
GitHub, aweb, Jira or Linear.
|
|
511
511
|
|
|
512
|
+
### The TUI's tests on macOS
|
|
513
|
+
|
|
514
|
+
A pull request that touches `packages/tui/`, `packages/client/`, a
|
|
515
|
+
`test/tui-*.test.mjs` file or the workflow itself also runs
|
|
516
|
+
[`tui-macos.yml`](../.github/workflows/tui-macos.yml): every TUI test file,
|
|
517
|
+
`packages/tui/test/*.test.mjs` and `test/tui-*.test.mjs`, one file at a time
|
|
518
|
+
and each test within five minutes, on `macos-14` with tmux installed, in about
|
|
519
|
+
five minutes. Its last step fails the run if a test left a tmux server on the
|
|
520
|
+
default `oats` socket, as a hand-started run checks after each file; it does
|
|
521
|
+
not give each file a process group of its own, as a hand-started run does. The
|
|
522
|
+
TUI reads tables keyed by platform (the shared keymap's macOS chords) and
|
|
523
|
+
drives macOS's own tmux, whose output differs from Linux's, and Linux CI sees
|
|
524
|
+
neither ([#1608](https://github.com/awebai/oats/issues/1608),
|
|
525
|
+
[#1613](https://github.com/awebai/oats/issues/1613)). It runs at pull-request
|
|
526
|
+
time, not on the tag's macOS legs: a failure found on the tag costs a version,
|
|
527
|
+
and `release.yml` holds the publishing rights, so a TUI flake there would hold
|
|
528
|
+
a publication (the release lane's call, 2026-10-27).
|
|
529
|
+
|
|
530
|
+
The paths are the TUI's own. A change the TUI depends on outside them (`lib/`,
|
|
531
|
+
`bin/`, `test/helpers/`, `package.json`, `package-lock.json`) starts no run,
|
|
532
|
+
and nothing runs on a push to `main`: such a change wants hand-started macOS
|
|
533
|
+
runs of the TUI's files, at most ten files a run
|
|
534
|
+
([Named test runs](named-test-runs.md)).
|
|
535
|
+
|
|
536
|
+
The job is not part of the gate above. A path filter that skips the workflow
|
|
537
|
+
reports no check, so a required check would hold every pull request that does
|
|
538
|
+
not touch the TUI. Its run on the pull request is that pull request's macOS
|
|
539
|
+
evidence. `test/tui-macos-workflow.test.mjs` pins its terms: the one trigger
|
|
540
|
+
and its paths, the read-only token, no secret, no artifact or cache, tmux, a
|
|
541
|
+
command that runs every TUI test file, and the leak check. Like the release's
|
|
542
|
+
workflows, it names its actions by commit (`test/workflow-no-cache.test.mjs`).
|
|
543
|
+
|
|
512
544
|
**Test output is pristine.** A warning that a test expects is captured and
|
|
513
545
|
asserted by the test, or by its fixture, and never left in the output: a line
|
|
514
546
|
nobody asserted is then one nobody expected. The root run holds the rule
|
package/docs/named-test-runs.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# Named test runs on macOS and Linux
|
|
2
2
|
|
|
3
3
|
Pull-request CI runs the tests on Linux, in its own way: sharded, and with no
|
|
4
|
-
working `systemctl --user`.
|
|
5
|
-
|
|
4
|
+
working `systemctl --user`. Beside it, a pull request that touches the TUI
|
|
5
|
+
also runs the TUI's tests on macOS ([The TUI's tests on
|
|
6
|
+
macOS](implementation.md#the-tuis-tests-on-macos)). Some tests need something
|
|
7
|
+
CI does not give them, and two workflows run them by hand:
|
|
6
8
|
|
|
7
9
|
- **macOS.** Some tests rest on what only macOS does: a file system that
|
|
8
10
|
ignores case, `/var` and `/tmp` as links, long temporary paths, the BSD
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,10 +9,10 @@ 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.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.16.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
|
-
| `oats.engineering` | `v1.
|
|
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` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.5.0`, `5.5.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.5.0` or `oats-framework/v1.16.
|
|
54
|
+
convention (`v5.5.0` or `oats-framework/v1.16.2`) 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,7 +74,7 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.16.
|
|
77
|
+
oats.framework: v1.16.2
|
|
78
78
|
oats.okf: v5.5.0
|
|
79
79
|
oats.aweb: v1.32.0
|
|
80
80
|
teams:
|
|
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
|
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
355
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.2", "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.2`
|
|
362
|
+
resolves to tag `oats-framework/v1.16.2`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
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.
|
|
@@ -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/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.4** ([release notes](release-notes/v0.69.4.md)).
|
|
10
|
+
The 0.69.4 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.4,** 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.4 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.4 # 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
|
```
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ 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.
|
|
57
|
+
oats.framework: v1.16.2 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.5.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
|
|
package/package-catalog.json
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"oats.engineering": {
|
|
30
30
|
"url": "https://github.com/awebai/oats-engineering.git",
|
|
31
|
-
"ref": "v1.
|
|
31
|
+
"ref": "v1.17.2",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"oats.framework": {
|
|
50
50
|
"url": "https://github.com/awebai/oats.git",
|
|
51
|
-
"ref": "oats-framework/v1.16.
|
|
51
|
+
"ref": "oats-framework/v1.16.2",
|
|
52
52
|
"path": "oats-package"
|
|
53
53
|
}
|
|
54
54
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.69.
|
|
3
|
+
"version": "0.69.4",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -350,7 +350,7 @@ name: acme
|
|
|
350
350
|
members:
|
|
351
351
|
- git:github.com/acme/acme-oats # the host is a member too
|
|
352
352
|
packages:
|
|
353
|
-
oats.framework: v1.16.
|
|
353
|
+
oats.framework: v1.16.2 # the installed CLI's catalog versions (below)
|
|
354
354
|
oats.aweb: v1.32.0 # messaging, and tasks: agent identities, mail, chat and tasks
|
|
355
355
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
356
356
|
defaults:
|
|
@@ -365,7 +365,7 @@ defaultTeam: acme # every soul starts in this team
|
|
|
365
365
|
|
|
366
366
|
- **The versions** are the installed CLI's catalog's:
|
|
367
367
|
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
|
|
368
|
-
(for example `oats-framework/v1.16.
|
|
368
|
+
(for example `oats-framework/v1.16.2`: write the part after the `/`) and
|
|
369
369
|
`packages."oats.aweb".ref`, but never below `v1.31.0`: that release
|
|
370
370
|
carries `oats.aweb-tasks`, and a bare version resolves through the
|
|
371
371
|
catalog's tag convention even when the installed catalog names an older
|