@awebai/oats 0.69.11 → 0.69.14
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/README.md +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +9 -5
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/knowledge.md +10 -3
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +42 -8
- package/docs/packages.md +101 -22
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.12.md +97 -0
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +30 -5
- package/docs/workspaces.md +32 -6
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +180 -49
- package/lib/tmux-config.mjs +0 -35
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
|
|
|
@@ -73,10 +73,19 @@
|
|
|
73
73
|
"additionalProperties": {
|
|
74
74
|
"oneOf": [
|
|
75
75
|
{ "type": "string" },
|
|
76
|
-
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
|
|
76
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
|
|
77
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromFile"], "properties": { "fromFile": { "type": "string", "pattern": "^/[^\\u0000]*$" } } }
|
|
77
78
|
]
|
|
78
79
|
},
|
|
79
|
-
"
|
|
80
|
+
"allOf": [{ "properties": {
|
|
81
|
+
"HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
82
|
+
"PATH": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
83
|
+
"CLAUDE_CONFIG_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
84
|
+
"CODEX_HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
85
|
+
"PI_CODING_AGENT_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
86
|
+
"PI_CODING_AGENT_SESSION_DIR": { "not": { "type": "object", "required": ["fromFile"] } }
|
|
87
|
+
} }],
|
|
88
|
+
"description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops. {fromFile: /absolute/path} reads a regular UTF-8 file of at most 64 KiB (source bytes including a final newline) on the execution host at every start, stripping one trailing LF or CRLF. NUL, missing, unreadable or nonregular files refuse with E_LAUNCH_ENV_MISSING. Both reference kinds are redacted and recorded only as keyed digests. fromFile is for credential values; directory selectors require a literal or fromEnv."
|
|
80
89
|
},
|
|
81
90
|
"model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
|
|
82
91
|
"yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
|
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.
|
|
13
|
-
| `oats.okf` | `v5.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
15
|
-
| `oats.engineering` | `v1.18.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.23.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `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
|
+
| `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `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` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
@@ -21,16 +21,50 @@ or workspace membership alone does not make a package official.
|
|
|
21
21
|
| `oats.machine` | `v0.1.1` | `oats.machine-care` | `steward`, `technician` |
|
|
22
22
|
|
|
23
23
|
Each package lives in its own `awebai/oats-*` repository except
|
|
24
|
-
`oats.framework`, whose payload root is `oats-package/` here. A capability
|
|
25
|
-
|
|
26
|
-
`oats.developer: { from: package }`
|
|
24
|
+
`oats.framework`, whose payload root is `oats-package/` here. A capability
|
|
25
|
+
written `{ from: package }` resolves through the workspace's lock, to the one
|
|
26
|
+
locked package whose capability list holds it: `oats.developer: { from: package }`
|
|
27
|
+
selects `oats.engineering` when that package is pinned and synced. Two locked
|
|
28
|
+
packages providing the same capability are refused with `E_PACKAGE_MISSING`,
|
|
29
|
+
which names both. The catalog's `capabilities` map records which official
|
|
30
|
+
package ships each capability (and a renamed capability's current name:
|
|
31
|
+
`oas.okf` is `oats.okf`); the kernel reads it only to pick a standalone
|
|
32
|
+
deployment's package (the one that ships `oats.core`). This catalog ships with
|
|
27
33
|
the CLI: an older installed CLI keeps its own copy, and a change here rewrites
|
|
28
34
|
no lock and adds nothing to an existing workspace.
|
|
29
35
|
|
|
36
|
+
## Coordination templates
|
|
37
|
+
|
|
38
|
+
OATS's coordination ships as templates, not packages: one for each way of
|
|
39
|
+
working, each in its own repository. An installed kernel's
|
|
40
|
+
copy of this catalog carries this section from the next kernel release; the
|
|
41
|
+
onboarding skills name the engineering template directly, so they work on an
|
|
42
|
+
older kernel too. A template is a
|
|
43
|
+
repository that a setup expert copies into a workspace's own capabilities and
|
|
44
|
+
adapts to the organisation by the repository's `ADAPTING.md`
|
|
45
|
+
(`/adapt-to-the-organisation`, in `oats.framework`); nobody pins it. Template
|
|
46
|
+
releases are tagged `template-v<version>`. Each copied capability records the
|
|
47
|
+
release it came from in its description, and the copy records it as a whole in
|
|
48
|
+
`capabilities/TEMPLATE-RELEASE`.
|
|
49
|
+
|
|
50
|
+
| Template | Latest release | Way of working |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `oats-project/oats-engineering-coordination` | `template-v3.0.1` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
|
|
53
|
+
| `oats-project/oats-research-coordination` | `template-v2.0.0` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
|
|
54
|
+
| `oats-project/oats-scientific-research-coordination` | `template-v2.0.0` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
|
|
55
|
+
|
|
56
|
+
The package `oats.engineering` is frozen at `v1.18.0`. Its entry and its four
|
|
57
|
+
aliases stay, so existing pins keep resolving, and its repository,
|
|
58
|
+
`oats-project/oats-engineering`, gets no further releases. The engineering
|
|
59
|
+
template that replaces it lives in its own repository, above; a workspace that
|
|
60
|
+
pins the package moves to it by the template's `ADAPTING.md` and the "From
|
|
61
|
+
v1.18.0" steps in its CHANGELOG. Open: retiring the entry and moving the
|
|
62
|
+
aliases, a later decision once no workspace we know of pins it.
|
|
63
|
+
|
|
30
64
|
## Find and use packages
|
|
31
65
|
|
|
32
66
|
- A workspace pins an official package by **bare version** in its
|
|
33
|
-
`packages:` map (`oats.okf: v5.
|
|
67
|
+
`packages:` map (`oats.okf: v5.8.0`); `oats sync` resolves it through the
|
|
34
68
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
35
69
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
36
70
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -28,7 +28,11 @@ A Git repository **contains** a package at `oats-package/`:
|
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
`oats-package.json` must declare `package` and `capabilities` (a list of
|
|
31
|
-
directories relative to the package root, each holding an `oats.json`).
|
|
31
|
+
directories relative to the package root, each holding an `oats.json`). The
|
|
32
|
+
`package` must equal the `packages:` key the package is pinned under: a
|
|
33
|
+
package is locked under its own id, and its souls are named after it
|
|
34
|
+
(`<package>/<soul>`). `sync` refuses a pin whose manifest names another id
|
|
35
|
+
(`E_PACKAGE_INTEGRITY { why: "package-id" }`, see [`oats sync`](#oats-sync--the-one-command-for-the-common-path)). It may
|
|
32
36
|
also declare `souls`: soul directories the package ships, see
|
|
33
37
|
[Package souls](#package-souls). A
|
|
34
38
|
directory entry need not equal the capability's name
|
|
@@ -44,14 +48,14 @@ whole organisation:
|
|
|
44
48
|
|
|
45
49
|
```yaml
|
|
46
50
|
packages:
|
|
47
|
-
oats.okf: v5.
|
|
51
|
+
oats.okf: v5.8.0 # bare version → the official catalog
|
|
48
52
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
53
|
```
|
|
50
54
|
|
|
51
|
-
- **Bare version** (`v5.
|
|
55
|
+
- **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
56
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
57
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.
|
|
58
|
+
convention (`v5.8.0` or `oats-framework/v1.23.0`) and the payload path. An id
|
|
55
59
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
60
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
61
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +78,9 @@ members:
|
|
|
74
78
|
- git:github.com/acme/agents
|
|
75
79
|
- git:github.com/acme/platform
|
|
76
80
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
78
|
-
oats.okf: v5.
|
|
79
|
-
oats.aweb: v1.
|
|
81
|
+
oats.framework: v1.23.0
|
|
82
|
+
oats.okf: v5.8.0
|
|
83
|
+
oats.aweb: v1.37.0
|
|
80
84
|
teams:
|
|
81
85
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
86
|
defaults:
|
|
@@ -105,7 +109,7 @@ decision recorded in the lock.
|
|
|
105
109
|
$ oats sync
|
|
106
110
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
111
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.
|
|
112
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.8.0 ✓ (@ cfc595a9)
|
|
109
113
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
114
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
115
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -117,12 +121,29 @@ lock oats-lock.json
|
|
|
117
121
|
|
|
118
122
|
1. discovers the workspace over the remotes and confirms every member;
|
|
119
123
|
2. resolves each `packages:` entry to a commit (`observeRemote`), reads its
|
|
120
|
-
manifests,
|
|
121
|
-
|
|
124
|
+
manifests, checks that `oats-package.json` names the `packages:` key it is
|
|
125
|
+
pinned under, computes the **integrity** (content digest of the package
|
|
126
|
+
tree) and records `url`, `path`, `version`, `commit`, `integrity`,
|
|
127
|
+
`capabilities`. A manifest naming another package is refused before
|
|
128
|
+
anything is written: `E_PACKAGE_INTEGRITY { why: "package-id", id,
|
|
129
|
+
manifestPackage, commit }`, whose message names the line to write instead:
|
|
130
|
+
- a catalog version whose named package is in the catalog: `<named>: <the
|
|
131
|
+
same version>`;
|
|
132
|
+
- a catalog version whose named package is not: `<named>:
|
|
133
|
+
git:<the catalog entry's repo>@<the resolved tag>` (no line when the
|
|
134
|
+
catalog entry reads another `path` than `oats-package/`, which a `git:`
|
|
135
|
+
pin cannot reach);
|
|
136
|
+
- a `git:` pin: `<named>: <the same git: value>`.
|
|
137
|
+
|
|
138
|
+
The other way out is a version of the key's package whose manifest names
|
|
139
|
+
that key;
|
|
122
140
|
3. for an entry already locked at the same version/source/path: the commit must
|
|
123
141
|
be unchanged (else `E_PACKAGE_INTEGRITY` — "the tag moved; a version string
|
|
124
|
-
must change when its content does")
|
|
125
|
-
(`E_PACKAGE_INTEGRITY`)
|
|
142
|
+
must change when its content does"), the integrity must match
|
|
143
|
+
(`E_PACKAGE_INTEGRITY`), and the manifest must still name the key
|
|
144
|
+
(`why: "package-id"`, as in step 2: a lock an older kernel wrote under
|
|
145
|
+
another package's id is refused at the next sync; spawns from it keep
|
|
146
|
+
working until then);
|
|
126
147
|
4. writes `oats-lock.json` and reports the diff. Entries dropped from
|
|
127
148
|
`packages:` are dropped from the lock.
|
|
128
149
|
|
|
@@ -134,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
155
|
## `oats package add | remove`
|
|
135
156
|
|
|
136
157
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
158
|
+
oats package add oats.aweb v1.37.0 # a catalog version
|
|
138
159
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
160
|
oats package remove acme.tools
|
|
140
161
|
```
|
|
@@ -160,7 +181,7 @@ same workspace commit hold identical locks.
|
|
|
160
181
|
"source": "catalog:oats.okf",
|
|
161
182
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
183
|
"path": "oats-package",
|
|
163
|
-
"version": "5.
|
|
184
|
+
"version": "5.8.0",
|
|
164
185
|
"commit": "56dbc167394bbc13cc900bd8af0c64b74fecae54",
|
|
165
186
|
"integrity": "sha256-…",
|
|
166
187
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
@@ -202,9 +223,12 @@ Member capabilities are trusted by membership; **a package is trusted by its
|
|
|
202
223
|
declaration in the workspace's `packages:`**. People declare a package only
|
|
203
224
|
when they trust it, so there is no second, per-version approval step. The lock is reproducibility, not approval: it pins
|
|
204
225
|
the exact commit and the content integrity, a moved tag or drifted content is
|
|
205
|
-
`E_PACKAGE_INTEGRITY`,
|
|
206
|
-
|
|
207
|
-
|
|
226
|
+
`E_PACKAGE_INTEGRITY`, a package pinned under another package's id is
|
|
227
|
+
`E_PACKAGE_INTEGRITY { why: "package-id" }` at sync, and at spawn the lock's
|
|
228
|
+
capability list must match what the package declares at the locked commit
|
|
229
|
+
(`E_PACKAGE_INTEGRITY { why: "capabilities" }`) and the package tree there must
|
|
230
|
+
digest to the lock's `integrity`
|
|
231
|
+
([The integrity check at spawn](#the-integrity-check-at-spawn)).
|
|
208
232
|
|
|
209
233
|
## Materialization from a package
|
|
210
234
|
|
|
@@ -217,6 +241,56 @@ against what the fetch reported; skills are copied to
|
|
|
217
241
|
`packages:` and syncing affects **only new spawns**; `oats status` shows a
|
|
218
242
|
running instance's package module as `moved` once the lock points elsewhere.
|
|
219
243
|
|
|
244
|
+
### The integrity check at spawn
|
|
245
|
+
|
|
246
|
+
A spawn copies a package's capabilities only when the package is the content
|
|
247
|
+
the lock records. For each package the soul composes a capability from, the
|
|
248
|
+
kernel digests the package tree (the lock entry's `path`) at the lock's
|
|
249
|
+
`commit`, as `oats sync` does, and compares the digest with the lock's
|
|
250
|
+
`integrity`.
|
|
251
|
+
|
|
252
|
+
- **When.** After the soul is resolved and before the spawn writes anything:
|
|
253
|
+
no soul copy, no worktree, no instance home. `oats spawn --preview` makes
|
|
254
|
+
the same check. `oats instance upgrade` makes it for each package it moves
|
|
255
|
+
a module to.
|
|
256
|
+
- **The refusal** is `E_PACKAGE_INTEGRITY` with `details: {package, version,
|
|
257
|
+
commit, expected, actual}`: `expected` is the lock's `integrity`, `actual`
|
|
258
|
+
the digest of the tree as this computer reads it. The message names the
|
|
259
|
+
package, the commit and both digests. Two things produce it: a lock whose
|
|
260
|
+
`commit` and `integrity` describe different content (a hand edit, a bad
|
|
261
|
+
merge), which is fixed by restoring the lock; and a copy of the
|
|
262
|
+
package in this computer's remote cache that changed after it was fetched,
|
|
263
|
+
which is fixed by removing the cache (`$OATS_REMOTE_CACHE`, default
|
|
264
|
+
`~/.cache/oats/remotes`).
|
|
265
|
+
- **Once per package version and computer.** A tree that matched is recorded
|
|
266
|
+
under the remote cache, in `.verified/`, one file per (repository key,
|
|
267
|
+
commit, path, integrity). The record also holds the state of the cached
|
|
268
|
+
repository the tree was read from: every file under it, by path, size,
|
|
269
|
+
mode, inode, modification time and status-change time. A later spawn
|
|
270
|
+
believes a record only when each of its fields is the one asked for and the
|
|
271
|
+
cached repository is still in that state, and then digests nothing. Any
|
|
272
|
+
file added, removed, replaced or rewritten there (a later fetch of the same
|
|
273
|
+
repository included) makes the next spawn digest the tree again. Nothing
|
|
274
|
+
is recorded when the cached repository changed while the tree was read (the
|
|
275
|
+
first fetch of the package's files): the next spawn digests it again. With
|
|
276
|
+
a missing or unreadable record the tree is digested, and a cached
|
|
277
|
+
repository that reads objects from outside itself (a symbolic link, an
|
|
278
|
+
alternates file) is digested every time. A record older than 30 days is
|
|
279
|
+
removed when the cache is next pruned. The records are the kernel's own and
|
|
280
|
+
no contract: deleting them only costs the next spawn a digest.
|
|
281
|
+
- **What a record does not see.**
|
|
282
|
+
- A change to the cached repository that leaves every file's size, mode,
|
|
283
|
+
inode and both times as they were. That takes writing to the disk under
|
|
284
|
+
the filesystem, setting the clock back, or, on a filesystem that keeps
|
|
285
|
+
times to the second, rewriting a file in place to the same size within
|
|
286
|
+
the second it was last changed.
|
|
287
|
+
- A record written by whoever changed the cache: both live in the same
|
|
288
|
+
directory, so the cache is as trusted as the account that owns it.
|
|
289
|
+
- What Git reads outside the cached repository: its own configuration and
|
|
290
|
+
environment.
|
|
291
|
+
- A change made between the check and the copy of the modules a moment
|
|
292
|
+
later in the same spawn.
|
|
293
|
+
|
|
220
294
|
## Package souls
|
|
221
295
|
|
|
222
296
|
A package may ship **souls** as well as capabilities. One pin in
|
|
@@ -273,7 +347,12 @@ oats-package/
|
|
|
273
347
|
{ id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
|
|
274
348
|
in `oats status` the soul is `moved` once the package pin moves.
|
|
275
349
|
- **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
|
|
276
|
-
name (`E_SOUL_DISABLED` at spawn).
|
|
350
|
+
name (`E_SOUL_DISABLED` at spawn). An entry is matched by name only, so an
|
|
351
|
+
entry naming a soul that no longer exists fails open: after a pin's removal
|
|
352
|
+
or rename, the soul it was meant to keep off spawns again under its new
|
|
353
|
+
name. After removing or renaming a pin, or a soul it provided, run
|
|
354
|
+
`oats doctor` and fix what it reports, and check `souls.disabled` by hand: an
|
|
355
|
+
older kernel's doctor doesn't report such an entry.
|
|
277
356
|
- **Trusted** as the package's capabilities are: declaring the package is the
|
|
278
357
|
trust decision.
|
|
279
358
|
|
|
@@ -352,12 +431,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
431
|
{
|
|
353
432
|
"policy": "docs/official-catalog.md",
|
|
354
433
|
"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.
|
|
434
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.8.0", "path": "oats-package" },
|
|
435
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.23.0", "path": "oats-package" }
|
|
357
436
|
}
|
|
358
437
|
}
|
|
359
438
|
```
|
|
360
439
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
440
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.23.0`
|
|
441
|
+
resolves to tag `oats-framework/v1.23.0`. Resolving through the catalog never
|
|
363
442
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -480,7 +480,8 @@ always records `release.status: pending`.
|
|
|
480
480
|
## Releasing `oats.framework`
|
|
481
481
|
|
|
482
482
|
The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
|
|
483
|
-
`oats.onboarding`, `oats.
|
|
483
|
+
`oats.onboarding`, `oats.coordination-setup`, `oats.support`,
|
|
484
|
+
`oats.knowledge-theory`) is not published
|
|
484
485
|
by `release.yml` or by this lane. A deployment takes it from this repository at the tag
|
|
485
486
|
`oats-framework/v<version>`, through the catalog ref or its workspace pin. A
|
|
486
487
|
skill changed under `oats-package/` therefore reaches deployments only when
|
|
@@ -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.
|