@awebai/oats 0.69.11 → 0.69.12
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/integrations.md +6 -3
- package/docs/knowledge.md +10 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.12.md +97 -0
- package/docs/upgrading.md +11 -5
- package/docs/workspaces.md +2 -2
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +90 -26
package/docs/integrations.md
CHANGED
|
@@ -40,8 +40,8 @@ arrives from.
|
|
|
40
40
|
```yaml
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
|
-
oats.okf: v5.
|
|
44
|
-
oats.aweb: v1.
|
|
43
|
+
oats.okf: v5.8.0
|
|
44
|
+
oats.aweb: v1.37.0
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
47
47
|
defaults:
|
|
@@ -107,7 +107,10 @@ operations in full.
|
|
|
107
107
|
skill writes this default (the team's first aweb task opts it in), unless
|
|
108
108
|
the person's projects
|
|
109
109
|
already use a tracker (GitHub issues in use, Jira, Linear and the like),
|
|
110
|
-
when it writes `tasks: none
|
|
110
|
+
when it writes `tasks: none`. The setup expert then offers to make a tasks
|
|
111
|
+
capability of the workspace's own for that tracker, from how the team uses
|
|
112
|
+
it, and makes it the tasks default on the person's yes; it pins no
|
|
113
|
+
generic provider in its place.
|
|
111
114
|
- **`oats.aweb`** mints a messaging identity for each instance at spawn and
|
|
112
115
|
removes it at retire, contributes the aweb messaging skills, and wires the
|
|
113
116
|
channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
|
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.8.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.8.0
|
|
29
29
|
defaults:
|
|
30
30
|
knowledge: { oats.okf: { from: package } }
|
|
31
31
|
stores:
|
|
@@ -54,7 +54,7 @@ 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.8.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
|
|
@@ -71,6 +71,13 @@ propose. 5.6.0 lists new harvesters and knowledge maintainers under the
|
|
|
71
71
|
clients' Background section; existing ones do not move. 5.7.0 stops parking
|
|
72
72
|
harvest PRs under `okf-needs-human` (step 4 of [the flow](#the-flow)); PRs an
|
|
73
73
|
older maintainer parked are re-reviewed by the steps in okf's CHANGELOG.
|
|
74
|
+
5.8.0 screens what harvest and maintenance publish (the outgoing history,
|
|
75
|
+
paths, blobs and text) before any push, comment or merge, and reports only
|
|
76
|
+
the location, line and rule; a harvest PR behind the accepted tip is
|
|
77
|
+
rewritten onto it for a fresh exact-head verdict, never merged on an
|
|
78
|
+
approximate squash. Structural validation is unchanged. A harvester or
|
|
79
|
+
knowledge maintainer spawned after the sync uses it; existing homes keep
|
|
80
|
+
their copy until respawned or upgraded.
|
|
74
81
|
|
|
75
82
|
### Bindings document
|
|
76
83
|
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ 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.
|
|
13
|
-
| `oats.okf` | `v5.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.22.1` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
|
|
13
|
+
| `oats.okf` | `v5.8.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.37.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
15
|
| `oats.engineering` | `v1.18.0` | `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.1.0` | `oats.cloning` | `cloner` |
|
|
@@ -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.8.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.8.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.8.0`, `5.8.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.8.0` or `oats-framework/v1.22.1`) 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,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
78
|
-
oats.okf: v5.
|
|
79
|
-
oats.aweb: v1.
|
|
77
|
+
oats.framework: v1.22.1
|
|
78
|
+
oats.okf: v5.8.0
|
|
79
|
+
oats.aweb: v1.37.0
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -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.8.0 ✓ (@ cfc595a9)
|
|
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
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
137
|
+
oats package add oats.aweb v1.37.0 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,7 +160,7 @@ 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.
|
|
163
|
+
"version": "5.8.0",
|
|
164
164
|
"commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
@@ -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.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.22.1", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.22.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.22.1`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# OATS 0.69.12
|
|
2
|
+
|
|
3
|
+
0.69.12 moves the official catalog to `oats.okf` 5.8.0, `oats.aweb` 1.37.0 and
|
|
4
|
+
`oats.framework` 1.22.1. `oats.okf` checks every harvest publication's content
|
|
5
|
+
before it is pushed. `oats.aweb` lets a person join a team by pasting one
|
|
6
|
+
invite, keeps every invite token off the command line, names the cause of a
|
|
7
|
+
refused join, warns when whatever keeps a home's aweb task claims present is
|
|
8
|
+
too old, and on macOS restarts its launchd jobs so they come back after an aw
|
|
9
|
+
upgrade. The setup expert and getting started take a second round of fixes
|
|
10
|
+
from newcomer runs on fresh machines.
|
|
11
|
+
|
|
12
|
+
## Upgrade
|
|
13
|
+
|
|
14
|
+
- **Either order of the Desktop and the CLI works.**
|
|
15
|
+
[Upgrading](../upgrading.md) installs the Desktop first, and a host that
|
|
16
|
+
installed the CLI first is fine too: the 0.69.12 Desktop accepts OATS CLIs
|
|
17
|
+
`>=0.26.0 <0.70.0`, as the 0.69.11 and 0.69.10 Desktops do.
|
|
18
|
+
- **Package moves:** the official catalog pins oats.okf 5.8.0 (from 5.7.0),
|
|
19
|
+
oats.aweb 1.37.0 (from 1.35.0, crossing 1.36.0) and oats.framework 1.22.1
|
|
20
|
+
(from 1.21.0, crossing 1.22.0). None changes its OATS floor: oats.okf stays >=0.69.2,
|
|
21
|
+
oats.aweb >=0.68.0 with aw >=1.36.33 (tested with 1.36.53). A deployment
|
|
22
|
+
takes each by raising its own pin (`/oats-package-pins`), then `oats sync`.
|
|
23
|
+
Running instances keep the modules they were spawned with: new spawns get
|
|
24
|
+
the new ones, and a stopped home moves with `oats instance upgrade`. A
|
|
25
|
+
knowledge harvester spawned after the sync publishes through oats.okf
|
|
26
|
+
5.8.0's content gate.
|
|
27
|
+
- **Where `oats.aweb-tasks` is composed, readiness may warn** (oats.aweb
|
|
28
|
+
1.37.0) `wake-daemon-outdated` (a home the host wake daemon serves, while
|
|
29
|
+
the daemon runs aw below 1.36.54), `aweb-channel-outdated` (a Claude home,
|
|
30
|
+
below aweb-channel 1.8.2) or `pi-extension-outdated` (a pi home, below
|
|
31
|
+
@awebai/pi 0.4.1). These are warnings, not refusals: an older component
|
|
32
|
+
still delivers, but a claim it doesn't heartbeat can be taken over once it
|
|
33
|
+
goes stale. Messaging-only homes get none of them.
|
|
34
|
+
- **aw 1.36.54 is on npm's `next` tag; `latest` is still 1.36.53.** Install
|
|
35
|
+
it by version, `npm install -g @awebai/aw@1.36.54`: a plain
|
|
36
|
+
`npm install -g @awebai/aw`, and `oats aweb setup --install-aw`, install
|
|
37
|
+
1.36.53. Then rerun `oats aweb wake install` to restart the host wake
|
|
38
|
+
daemon on it. On macOS that rerun now unloads and reloads the daemon
|
|
39
|
+
(bootout, then bootstrap), because launchd refuses to respawn a job whose
|
|
40
|
+
binary an upgrade replaced; before oats.aweb 1.37.0 it left the daemon
|
|
41
|
+
down. Against a server other than the aweb Cloud, aw 1.36.54 is newer than
|
|
42
|
+
the tested aw, so oats.aweb also warns `aw-newer-than-tested` there.
|
|
43
|
+
- **Known issue (macOS): a running custody job is not restarted for you
|
|
44
|
+
after an aw upgrade.** Reload each one by hand:
|
|
45
|
+
`launchctl bootout gui/$(id -u)/<label>`; wait until
|
|
46
|
+
`launchctl print gui/$(id -u)/<label>` no longer finds it; then
|
|
47
|
+
`launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist`;
|
|
48
|
+
then rerun `oats aweb resident create <name>` to verify (oats.aweb 1.37.0's
|
|
49
|
+
CHANGELOG).
|
|
50
|
+
- **`oats aweb setup --invite` or `--invite-stdin` without `--join` is no
|
|
51
|
+
longer a usage error** (exit 2, "requires --join <label>"). From oats.aweb
|
|
52
|
+
1.36.0 it is setup from the invite alone: it needs aw 1.36.53 or later,
|
|
53
|
+
refuses with `E_SETUP_AW_VERSION` on an older one, and refuses every other
|
|
54
|
+
problem before anything is redeemed. `--join <label>` works as before.
|
|
55
|
+
Every invite acceptance now reads the token on stdin, so a malformed token
|
|
56
|
+
fails as an aw usage error (exit 2) before anything is redeemed.
|
|
57
|
+
|
|
58
|
+
## Changed
|
|
59
|
+
|
|
60
|
+
- **oats.okf 5.8.0: a content-safety gate on every harvest publication.**
|
|
61
|
+
Harvest and maintenance screen what they would publish (the outgoing
|
|
62
|
+
history, paths, blobs and text) before any push, comment or merge, and
|
|
63
|
+
report only the location, line and rule. A harvest PR left behind the
|
|
64
|
+
accepted tip is rewritten onto it for a fresh exact-head verdict, never
|
|
65
|
+
merged on an approximate squash. Structural OKF validation is unchanged
|
|
66
|
+
([awebai/oats-okf#121](https://github.com/awebai/oats-okf/pull/121)).
|
|
67
|
+
- **oats.aweb 1.36.0: setup from one pasted invite.** `oats aweb setup --soul
|
|
68
|
+
<soul> --invite-stdin --name <alias>`, without `--join`, reads the invite's
|
|
69
|
+
team and service with aw's `team invite inspect` (redeeming nothing),
|
|
70
|
+
derives the label from the team's name, joins into a per-team root, and
|
|
71
|
+
ends with one next step. `oats aweb invite --json` answers that command at
|
|
72
|
+
`result.joinCommand`, with no token in it. A refused `oats aweb join` and a
|
|
73
|
+
failed `aw team invite` name their cause and fix, and new team roots go
|
|
74
|
+
beside the default team's root
|
|
75
|
+
([awebai/oats-aweb#56](https://github.com/awebai/oats-aweb/issues/56),
|
|
76
|
+
[#52](https://github.com/awebai/oats-aweb/issues/52),
|
|
77
|
+
[#45](https://github.com/awebai/oats-aweb/issues/45)).
|
|
78
|
+
- **oats.aweb 1.37.0: claim floors for aweb tasks, and launchd restarts.**
|
|
79
|
+
oats.aweb-tasks's readiness warns per home on the component that keeps its
|
|
80
|
+
claims present (above). `oats aweb wake install` and
|
|
81
|
+
`oats aweb resident create` restart a loaded launchd job with bootout and
|
|
82
|
+
bootstrap, never `kickstart`
|
|
83
|
+
([awebai/oats-aweb#196](https://github.com/awebai/oats-aweb/pull/196),
|
|
84
|
+
[#198](https://github.com/awebai/oats-aweb/pull/198)).
|
|
85
|
+
- **`oats.framework` 1.22.0 ships the second round of newcomer fixes to the setup expert.** `oats.setup` 2.13.0's `/oats-setup-expert`, `/oats-setup-model` and `/oats-package-pins`, `oats.onboarding` 1.2.0's `/oats-tailor-workspace`, and the `oats-setup-expert` soul carry them: the hand-over and hand-back, the tasks rule for each case, human attribution, both instance-name forms, and a harness entry for each new soul whose declared harness differs (#1726, #1729). The onboarding round-two entry in these notes describes each fix. The per-soul launch lines say from OATS 0.53.0. Apart from `oats tui` (OATS 0.52.0), which the hand-back leaves unversioned, no other command they name needs a newer OATS than each capability already admits ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
|
|
86
|
+
- **`oats.framework` 1.22.1: `oats.setup` 2.13.1's `/oats-onboarding` names `oats.okf` 5.8.0**, the release the catalog pins, as what knowledge operations need beside kernel 0.69.2 or later, and its workspace example pins `oats.okf: v5.8.0`. No other change.
|
|
87
|
+
|
|
88
|
+
- **Getting started and the setup expert: fixes from further newcomer runs on fresh machines** ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
|
|
89
|
+
- **`oats-getting-started`, the machine's round is always asked:** on a machine found-list, the round's one yes, naming the changes, is asked even when the prompt that started the run says to ask for nothing more. It is the consent the harness's permission check reads; without it, each change (the repository, the aweb signup, the folder trust) was refused on its own and cost the person a round. After it, nothing more is asked.
|
|
90
|
+
- **`oats-getting-started`, the Desktop's system libraries on Linux x64** are checked with step 2's other checks, before step 1's message, so a missing ALSA library goes on the one-yes list as a system package (dropped if the person declines the Desktop) and the Desktop's install needs no second yes.
|
|
91
|
+
- **`oats-getting-started`, the harness for every soul:** the skill records the chosen harness with `oats soul launch set '*' --harness <harness>` (plan first), for every soul on the machine without an entry of its own, in place of the setup soul alone. Package souls the setup expert or the steward spawns later no longer fall back to pi. `'*'` wins over a soul's own `launch:` on that machine, so each soul whose declared harness differs, and is installed and logged in on that machine, gets its own entry with that harness (and its model), by the `key` `oats souls --json` prints, plan first; a declared harness the machine lacks stays under `'*'`, so the soul can run, and the hand-over names it. The setup soul is the exception: it keeps the harness the person chose. Souls added later are covered when they declare no `launch:` of their own; one that declares one gets its own entry from the skill that adds it (`/oats-tailor-workspace`, `/oats-package-pins`) ([Launch preferences](../configuration.md#launch-preferences)).
|
|
92
|
+
- **`/oats-tailor-workspace` (oats.onboarding), tasks, one rule per case:** with aweb's task list by default, it keeps it. Beside a tracker the agents already use (`tasks: none`), the setup expert offers to make a tasks capability of the workspace's own for it, from how the team works (its labels and states, who files and closes issues, what agents may do), holds that conversation itself and builds it with the person (over `gh issue` for GitHub issues, a manifest with `"layer": "tasks"`), and makes it the tasks default on their yes. The getting-started skill's tasks line now says the setup assistant offers to connect the tracker. It never leaves `none` without asking and pins no generic provider in its place ([Official providers](../integrations.md#official-providers)).
|
|
93
|
+
- **`/oats-tailor-workspace`, human attribution:** the step where the person typed a deployment-agent command and a passphrase at a terminal is gone, as #1665 decided. Agents run every command, and the person's one act is a click in their aweb dashboard; agents already running are attached in place, with no respawn. The setup expert first looks for the step in the messaging capability's own skill; until `oats.aweb` ships it, and for a self-custodial key or an account off aweb Cloud, it runs nothing, and its brief says the agents stay unattributed and keep working. A declined or expired request is reported, never re-prompted.
|
|
94
|
+
- **`/oats-setup-expert` (oats.setup):** its list of what the hand-over holds matches the getting-started template (the host and its type, the steward lines, the channel mode, Tasks, and what the person may want later), and step 1 reads the tasks default. Its hand-back names no versions and no commands unless the person asks, and when a session spawned before messaging should be replaced, on the person's yes the setup expert spawns the new one as `<its name>-2`, checks that it runs and is in the team, tells the person its name, asks before its retirement would stop any of the person's agents, writes its state and only then retires itself; if a check fails it keeps its session. The person runs none of it. It describes the workspace's tasks capability as made beside a tracker on the person's yes.
|
|
95
|
+
- **`/oats-setup-model` (oats.setup)** describes the setup expert as `oats.framework`'s package soul `oats-setup-expert`, chosen by `oats onboard` after a workspace's own `<workspace>-oats-setup-expert` and before the first by name, and lists `oats.aweb-tasks` among the tasks providers. It, `/oats-setup-expert` and the `oats-setup-expert` soul's own instructions name both instance-name forms, `<workspace>-oats-setup-expert` and `<workspace>-<machine>-oats-setup-expert`, and the kernel's `<workspace>-oats-setup` when a soul holds the first name.
|
|
96
|
+
- **`oats-getting-started`, a person without a GitHub account:** step 1 asks whether they have one when gh is not logged in. Without one, step 3 opens GitHub's sign-up page in their browser (they create the account there, never in the conversation), then runs the usual device login; gh is installed like any missing tool, on the one yes.
|
|
97
|
+
- **`oats-getting-started`, a join never runs `aw team ensure`:** on a join, `ensure` would silently make a new team of the person's own for the same repository rather than find the teammate's. It stays step 5's, for a new workspace, and a test pins every `ensure` line there.
|
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.12** ([release notes](release-notes/v0.69.12.md)).
|
|
10
|
+
The 0.69.12 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.12,** 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.12 first
|
|
23
|
+
npm install -g @awebai/oats@0.69.12 # 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
|
```
|
|
@@ -202,6 +202,12 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
202
202
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
203
203
|
here.
|
|
204
204
|
|
|
205
|
+
- **[0.69.12](release-notes/v0.69.12.md#upgrade):** the catalog pins
|
|
206
|
+
oats.okf 5.8.0, oats.aweb 1.37.0 and oats.framework 1.22.1. Where
|
|
207
|
+
`oats.aweb-tasks` is composed, readiness warns until the host wake daemon
|
|
208
|
+
runs aw 1.36.54 (install it by version while npm's `latest` is 1.36.53),
|
|
209
|
+
aweb-channel 1.8.2 or @awebai/pi 0.4.1; on macOS, reload running custody
|
|
210
|
+
jobs by hand after the aw upgrade.
|
|
205
211
|
- **[0.69.11](release-notes/v0.69.11.md#upgrade):** the catalog pins
|
|
206
212
|
oats.framework 1.21.0 and oats.aweb 1.35.0. Upgrade every deployment of a
|
|
207
213
|
workspace before its shared `oats-workspace.yaml` sets `tasks:` (an older
|
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.
|
|
58
|
-
oats.okf: v5.
|
|
57
|
+
oats.framework: v1.22.1 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.8.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/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.
|
|
6
|
+
"ref": "v5.8.0",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.37.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"oats.framework": {
|
|
50
50
|
"url": "https://github.com/awebai/oats.git",
|
|
51
|
-
"ref": "oats-framework/v1.
|
|
51
|
+
"ref": "oats-framework/v1.22.1",
|
|
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.12",
|
|
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",
|
|
@@ -46,6 +46,12 @@ tell the person this machine already has its workspace and steward, and
|
|
|
46
46
|
stop. Wherever a later step says to ask the
|
|
47
47
|
person, on a machine found-list you tell them what happened, as it is, and
|
|
48
48
|
stop instead: the person answers nothing after step 1.
|
|
49
|
+
Step 1's machine round is always asked, even when the prompt that started
|
|
50
|
+
you says to ask for nothing more (an installer's "beyond starting this, ask
|
|
51
|
+
no other yes"). Its one yes, naming the changes, is the consent your
|
|
52
|
+
harness's permission check reads; without it, the check refuses each change
|
|
53
|
+
on its own (the repository, the aweb signup, the folder trust), and each
|
|
54
|
+
costs the person a round. After that yes, nothing more is asked.
|
|
49
55
|
|
|
50
56
|
**How to work.**
|
|
51
57
|
- **Ask first, then run.** Ask everything in one round (step 1), then run the
|
|
@@ -154,7 +160,15 @@ On a machine found-list, ask the machine's round below instead of this list.
|
|
|
154
160
|
|
|
155
161
|
**First, step 2's checks.** They only read, so run them before the message
|
|
156
162
|
(not its installs): the changes to their computer that the message lists
|
|
157
|
-
are what they found missing.
|
|
163
|
+
are what they found missing. On Linux x64 they include the Desktop's system
|
|
164
|
+
libraries: a missing one goes on the list as a system package, dropped if
|
|
165
|
+
they decline the Desktop, so the Desktop's install needs no second yes.
|
|
166
|
+
|
|
167
|
+
**No GitHub account.** Their agents' shared setup and their projects live
|
|
168
|
+
on GitHub. When gh is not logged in, ask in the same message whether they
|
|
169
|
+
have a GitHub account. Without one, they make one, free, in their browser
|
|
170
|
+
at step 3, and nothing else changes: gh goes on the list of changes like
|
|
171
|
+
any missing tool, and you install it.
|
|
158
172
|
|
|
159
173
|
**The message.** Ask three things, and in the same message propose
|
|
160
174
|
everything else as defaults they accept with "ok" or change:
|
|
@@ -263,9 +277,9 @@ the final values in one short message before you go on. The rules:
|
|
|
263
277
|
`PEP` and `GPT`.
|
|
264
278
|
|
|
265
279
|
With a tracker, the agents keep using it: the line says so ("your agents
|
|
266
|
-
use your GitHub issues; the setup assistant
|
|
267
|
-
writes `tasks: none`; the setup expert
|
|
268
|
-
person later. Without one, the line says "aweb's task list, shared by your
|
|
280
|
+
use your GitHub issues; the setup assistant offers to connect them") and
|
|
281
|
+
step 7 writes `tasks: none`; the setup expert offers to connect the
|
|
282
|
+
tracker with the person later. Without one, the line says "aweb's task list, shared by your
|
|
269
283
|
agents". Ask only when unsure, as the final-values message's one open
|
|
270
284
|
line, prefilled with the answer you'd pick: ticket keys the person didn't
|
|
271
285
|
name, a project kept somewhere other than GitHub (its issues can't be
|
|
@@ -275,8 +289,9 @@ the final values in one short message before you go on. The rules:
|
|
|
275
289
|
**The machine's round.** Read the found-list, then ask only these choices,
|
|
276
290
|
together, each with its default and one line on what it is. Enter, or
|
|
277
291
|
"yes", accepts every default. Nothing is asked after this round, and never
|
|
278
|
-
a key.
|
|
279
|
-
|
|
292
|
+
a key. Ask it even when your prompt says to ask nothing more (above). The
|
|
293
|
+
use case, repositories and knowledge tools are not asked: the steward takes
|
|
294
|
+
them up with the person later.
|
|
280
295
|
- **The workspace:** a new one, the machine's own. Its name defaults to the
|
|
281
296
|
hostname, lowercased, with every character outside `[a-z0-9-]` turned
|
|
282
297
|
into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
|
|
@@ -330,6 +345,13 @@ before the first line that needs `sudo`.
|
|
|
330
345
|
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g; { git config --global user.name && git config --global user.email; } >/dev/null || echo NO_GIT_IDENTITY
|
|
331
346
|
```
|
|
332
347
|
|
|
348
|
+
On Linux x64, also check the Desktop's system libraries, ALSA and FUSE 2
|
|
349
|
+
(what a missing one means is under "The Desktop's system libraries", below):
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
353
|
+
```
|
|
354
|
+
|
|
333
355
|
- **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
|
|
334
356
|
caches; older Git works with whole-tree fetches); `gh` 2.49 or later
|
|
335
357
|
(step 3 uses `gh attestation`).
|
|
@@ -360,15 +382,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
|
|
|
360
382
|
```bash
|
|
361
383
|
sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
|
|
362
384
|
```
|
|
363
|
-
- **The Desktop's system libraries** (x64)
|
|
364
|
-
|
|
365
|
-
```bash
|
|
366
|
-
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
367
|
-
```
|
|
368
|
-
|
|
385
|
+
- **The Desktop's system libraries** (x64), from the check above, run
|
|
386
|
+
before step 1's message:
|
|
369
387
|
- **ALSA missing:** the Desktop needs it, so step 1's list names its
|
|
370
|
-
package
|
|
371
|
-
before them, `alsa-lib` on
|
|
388
|
+
package, to install with the other system packages: `libasound2t64`
|
|
389
|
+
on Ubuntu 24.04 and Debian 13, `libasound2` before them, `alsa-lib` on
|
|
390
|
+
Fedora.
|
|
372
391
|
- **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
|
|
373
392
|
`--appimage-extract-and-run`, which needs no FUSE.
|
|
374
393
|
- **Passwords:** a line that needs `sudo` runs only after their yes in
|
|
@@ -411,7 +430,15 @@ fail with "could not read Username"), then go on below:
|
|
|
411
430
|
gh auth setup-git
|
|
412
431
|
```
|
|
413
432
|
|
|
414
|
-
|
|
433
|
+
**When they have no GitHub account** (step 1), open GitHub's sign-up page
|
|
434
|
+
in their browser first: `open https://github.com/signup` on macOS,
|
|
435
|
+
`xdg-open https://github.com/signup` on Linux, or give them the URL if that
|
|
436
|
+
fails. Tell them it is free, and that they choose a username, an email and a
|
|
437
|
+
password there, in their browser, never in this conversation; GitHub emails
|
|
438
|
+
them a code to confirm the address. Wait until they say the account is
|
|
439
|
+
made, then start the login below.
|
|
440
|
+
|
|
441
|
+
If not logged in, start the login yourself, detached and without a terminal (your
|
|
415
442
|
harness's background mode if it has one); gh prints a one-time code and a
|
|
416
443
|
URL instead of opening a browser, and waits:
|
|
417
444
|
|
|
@@ -485,7 +512,7 @@ installed CLI's catalog:
|
|
|
485
512
|
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
486
513
|
```
|
|
487
514
|
|
|
488
|
-
It prints the two refs, for example `oats-framework/v1.
|
|
515
|
+
It prints the two refs, for example `oats-framework/v1.22.1 v1.37.0`. If the
|
|
489
516
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
490
517
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
491
518
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -717,8 +744,8 @@ name: acme
|
|
|
717
744
|
members:
|
|
718
745
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
719
746
|
packages:
|
|
720
|
-
oats.framework: v1.
|
|
721
|
-
oats.aweb: v1.
|
|
747
|
+
oats.framework: v1.22.1 # the installed CLI's catalog versions (below)
|
|
748
|
+
oats.aweb: v1.37.0 # messaging: agent identities, mail and chat
|
|
722
749
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
723
750
|
defaults:
|
|
724
751
|
capabilities:
|
|
@@ -759,9 +786,11 @@ workspace: git:github.com/acme/acme-oats
|
|
|
759
786
|
which named it, without asking again; show the person the files only if
|
|
760
787
|
they ask. When others can push to the repository (`gh api
|
|
761
788
|
repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
|
|
762
|
-
fails), its default branch is protected
|
|
763
|
-
branch
|
|
764
|
-
|
|
789
|
+
fails), its default branch `<branch>` is protected (`gh api
|
|
790
|
+
repos/<owner>/<repo>/branches/<branch> --jq .protected` prints `true`,
|
|
791
|
+
`gh api repos/<owner>/<repo>/rules/branches/<branch> --jq length` prints
|
|
792
|
+
more than 0, or either fails), or the push is refused: push a branch
|
|
793
|
+
instead, open a pull request, tell them, and stop until it is merged.
|
|
765
794
|
- If `git config user.name` or `git config user.email` prints nothing in
|
|
766
795
|
`D/<repo>`, commit with the name step 1's yes covered:
|
|
767
796
|
`-c user.name="<their name>" -c user.email="<their noreply address>"`,
|
|
@@ -806,9 +835,39 @@ needs a clone of its repository at `D/<repo name>`: for an existing
|
|
|
806
835
|
workspace whose setup soul is its own, run the `git clone` line
|
|
807
836
|
`oats onboard` printed for it, if it says it is missing.
|
|
808
837
|
|
|
809
|
-
**Record the
|
|
810
|
-
none, and without this every later check (readiness, harness trust) and
|
|
811
|
-
spawn would use the default, pi
|
|
838
|
+
**Record the harness for every soul** on this machine: a package soul names
|
|
839
|
+
none, and without this every later check (readiness, harness trust) and
|
|
840
|
+
every spawn would use the default, pi, for `S` and for each soul the setup
|
|
841
|
+
expert or the steward spawns later. `'*'` is every soul without an entry of
|
|
842
|
+
its own, `S` among them, and souls added later that name no harness of
|
|
843
|
+
their own:
|
|
844
|
+
|
|
845
|
+
```bash
|
|
846
|
+
oats soul launch set '*' --harness <harness> --dir D --plan
|
|
847
|
+
oats soul launch set '*' --harness <harness> --dir D
|
|
848
|
+
```
|
|
849
|
+
|
|
850
|
+
`'*'` wins over a soul's own `launch:` on this machine. So read
|
|
851
|
+
`oats souls --dir D --json` first, in a new workspace too (a package soul
|
|
852
|
+
may name its harness). For each row whose `launch.declared.harness`
|
|
853
|
+
differs from `<harness>` and whose declared harness is installed and
|
|
854
|
+
logged in here (`claude --version`, `codex --version` or `pi --version`,
|
|
855
|
+
as in step 2), give that soul its own entry with its declared harness, so
|
|
856
|
+
it keeps its choice. A declared harness that isn't installed here stays
|
|
857
|
+
under `'*'`, so the soul can run; name it in the hand-over ("For the
|
|
858
|
+
person, later"). Use the row's `key` (`<package>/<soul>`
|
|
859
|
+
for a package's soul, so the name is never ambiguous), add
|
|
860
|
+
`--model <its model>` only when `launch.declared.model` names one, and plan
|
|
861
|
+
first:
|
|
862
|
+
|
|
863
|
+
```bash
|
|
864
|
+
oats soul launch set <key> --harness <its harness> --model <its model> --dir D --plan
|
|
865
|
+
oats soul launch set <key> --harness <its harness> --model <its model> --dir D
|
|
866
|
+
```
|
|
867
|
+
|
|
868
|
+
`S` is the exception: it always keeps `<harness>`, the person's choice in
|
|
869
|
+
step 1. When `S` declares another harness, give it its own entry with
|
|
870
|
+
`<harness>` instead:
|
|
812
871
|
|
|
813
872
|
```bash
|
|
814
873
|
oats soul launch set S --harness <harness> --dir D --plan
|
|
@@ -970,7 +1029,8 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
|
|
|
970
1029
|
|
|
971
1030
|
- Workspace: <workspace> (W), new | existing; deployment directory: D
|
|
972
1031
|
- Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
|
|
973
|
-
- Setup expert: S, instance <name>, harness <harness>
|
|
1032
|
+
- Setup expert: S, instance <name>, harness <harness> (this machine's
|
|
1033
|
+
harness for every soul without its own)
|
|
974
1034
|
- Machine found-list only: steward R, address N.aweb.ai/R | local team
|
|
975
1035
|
identity (<the fallback's reason>)
|
|
976
1036
|
|
|
@@ -1127,7 +1187,7 @@ and say yes to it in the hand-over below.
|
|
|
1127
1187
|
line, with how to change it: "Your agents share aweb's task list; to use
|
|
1128
1188
|
another tracker later, ask the setup assistant to switch." With a
|
|
1129
1189
|
tracker: "Your agents use your <GitHub issues | tracker>; the setup
|
|
1130
|
-
assistant
|
|
1190
|
+
assistant offers to connect them. Leave aweb's task list empty: one task there
|
|
1131
1191
|
opts your whole group in to it. To use aweb's task list instead, ask the
|
|
1132
1192
|
setup assistant."
|
|
1133
1193
|
|
|
@@ -1140,6 +1200,10 @@ the setup expert, not in this message. You are done.
|
|
|
1140
1200
|
|
|
1141
1201
|
## Never
|
|
1142
1202
|
|
|
1203
|
+
- **Run `aw team ensure` when joining an existing workspace.** It is only
|
|
1204
|
+
step 5's, for a new workspace. On a join it doesn't find the teammate's
|
|
1205
|
+
team: it makes a new team of the person's own for the same repository,
|
|
1206
|
+
silently. A join goes through step 9's invite.
|
|
1143
1207
|
- **Ask for, read, print or store a secret,** or suggest Claude Code's
|
|
1144
1208
|
`! <command>` for one: its command and output enter your context. If the
|
|
1145
1209
|
person pastes one anyway, don't repeat it, and tell them to rotate it.
|