@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.
@@ -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
@@ -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`. Some tests need something CI does not give them,
5
- and two workflows run them by hand:
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
@@ -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.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
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.16.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
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.1`) and the payload path. An id
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.1
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.1", "path": "oats-package" }
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.1`
362
- resolves to tag `oats-framework/v1.16.1`. Resolving through the catalog never
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.
@@ -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. Every other
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 two files
178
- every `uses:` is a row's id, the same action is the same id in both, and the
179
- comment beside an id is the row's version. In every other workflow a `uses:`
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 two workflow
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 `build-installers.yml`;
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
- **The two files name their runners by version too** (`ubuntu-24.04`, as they
220
- name `macos-14`), never by a label that GitHub moves to another system by
221
- itself (`ubuntu-latest`). The Linux installers are built on that runner, and
222
- what they need of a system follows the system that built them.
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 the two files may name are a list beside the table of actions in
227
- `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and `macos-14`. Every job
228
- of the two files runs on a label of that list, and both files build on the
229
- same Linux. A label is added to the list by whoever decides the runner, as an
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 the two
233
- files and in the list together, and says what the installers then need.
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 instructions or the
424
- human ask them to create another expert instance. The spawned agent is another
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.3** ([release notes](release-notes/v0.69.3.md)).
10
- The 0.69.3 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
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.3,** in the [release notes](release-notes/): it says what to do before
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.3 first
23
- npm install -g @awebai/oats@0.69.3 # 1. the CLI
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
  ```
@@ -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.1 # bare version → resolves through the official catalog
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
 
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.16.0",
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.1",
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",
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.1 # the installed CLI's catalog versions (below)
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.1`: write the part after the `/`) and
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