@awebai/oats 0.69.10 → 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/capabilities.md +21 -2
- package/docs/capability-manifest.schema.json +8 -0
- package/docs/desktop-cli-api.md +2 -0
- package/docs/integrations.md +12 -3
- package/docs/knowledge.md +10 -3
- package/docs/oats-workspace.schema.json +4 -0
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.11.md +107 -0
- package/docs/release-notes/v0.69.12.md +97 -0
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +16 -5
- package/docs/workspaces.md +21 -6
- package/lib/kernel-features.mjs +1 -1
- package/lib/resolve.mjs +51 -8
- package/lib/workspace.mjs +10 -1
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +155 -45
package/docs/capabilities.md
CHANGED
|
@@ -419,8 +419,8 @@ the workspace's slot default. Teams compose nothing, so a soul's composition
|
|
|
419
419
|
is the same for every person and machine. A resolved capability whose manifest says `layer: X` fills slot X; two for one slot are
|
|
420
420
|
`E_SLOT_CONFLICT`. Provider settings start from the manifest's own declared
|
|
421
421
|
defaults (`settings.<key>.default`, the lowest layer), then take the workspace's
|
|
422
|
-
`messaging` payload for the messaging slot
|
|
423
|
-
slot payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider`,
|
|
422
|
+
`messaging` payload for the messaging slot or its `tasks` payload for the tasks
|
|
423
|
+
slot, the soul's slot payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider`,
|
|
424
424
|
deep-merged in that order. There are no agent types, no `global`, no
|
|
425
425
|
per-deployment activation or exclusion maps.
|
|
426
426
|
|
|
@@ -805,6 +805,25 @@ resolver accepts it only from the deployment's own `oats-local.yaml`
|
|
|
805
805
|
Declare it for any key whose value points at something a committed file must
|
|
806
806
|
never be able to choose.
|
|
807
807
|
|
|
808
|
+
The mirror is `committedOnly: true`: a key that must be the same for every
|
|
809
|
+
deployment of the workspace, such as which shared list a tasks provider uses.
|
|
810
|
+
The resolver accepts it only from committed, reviewed files, and refuses it in
|
|
811
|
+
the deployment's `oats-local.yaml` `settings.<capability>` and in a
|
|
812
|
+
`--provider` flag (`E_WORKSPACE_SCHEMA`, reason `committed-only-key`). It is a
|
|
813
|
+
refusal, not a warning, and the key's presence is enough, even with the
|
|
814
|
+
committed value. Where it may be set follows the capability's layer: for a
|
|
815
|
+
messaging or tasks capability, `oats-workspace.yaml` under `messaging:` or
|
|
816
|
+
`tasks:`, or a soul's slot payload; for a knowledge capability, a soul's
|
|
817
|
+
`knowledge:` payload; for a capability with no layer, only its manifest
|
|
818
|
+
default. The refusal names the key, where it was set (`details.layer` `host` or
|
|
819
|
+
`spawn`, `details.at`), where it may be set (`details.allowed`) and the fix. A
|
|
820
|
+
key marked both `hostOnly` and `committedOnly` could be set by nothing but its
|
|
821
|
+
default, so the resolver refuses the manifest (`E_PACKAGE_MANIFEST` for a
|
|
822
|
+
package capability, `E_CAPABILITY_MISSING` for a member one, `details.why`
|
|
823
|
+
`settings-flag-conflict`). The kernel does not validate manifests against the
|
|
824
|
+
schema, so a kernel without the feature `settings-committed-only` ignores the
|
|
825
|
+
flag and merges the key from any layer.
|
|
826
|
+
|
|
808
827
|
A hook may return only names in its manifest's exact `environment` declaration.
|
|
809
828
|
For package capabilities that declaration is part of the integrity-locked tree
|
|
810
829
|
the workspace declared; for member capabilities it is part of what membership
|
|
@@ -335,8 +335,16 @@
|
|
|
335
335
|
"hostOnly": {
|
|
336
336
|
"type": "boolean",
|
|
337
337
|
"description": "When true, this key is a host fact (a custody path, a state directory): the resolver accepts it only from the deployment's oats-local.yaml settings.<capability> and refuses it in the workspace file, a soul's slot payload and --provider flags (E_WORKSPACE_SCHEMA reason host-only-key). Decision 27."
|
|
338
|
+
},
|
|
339
|
+
"committedOnly": {
|
|
340
|
+
"type": "boolean",
|
|
341
|
+
"description": "When true, this key must be the same for every deployment (the mirror of hostOnly): the resolver accepts it only from committed, reviewed files (the manifest default, oats-workspace.yaml's messaging: or tasks: payload for a capability of that slot, a soul's slot payload) and refuses it in oats-local.yaml settings.<capability> and --provider flags (E_WORKSPACE_SCHEMA reason committed-only-key). Never true together with hostOnly. Kernels without the settings-committed-only feature ignore it."
|
|
338
342
|
}
|
|
339
343
|
},
|
|
344
|
+
"not": {
|
|
345
|
+
"required": ["hostOnly", "committedOnly"],
|
|
346
|
+
"properties": { "hostOnly": { "const": true }, "committedOnly": { "const": true } }
|
|
347
|
+
},
|
|
340
348
|
"additionalProperties": false
|
|
341
349
|
}
|
|
342
350
|
},
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -169,6 +169,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
169
169
|
| `wake-hold` | a scheduled wake sends no key while the home has a live `permission`, `question` or unknown-reason claim, or a claims read that can't be trusted: the run is `skipped`, `reason: "waiting-on-you"`, `pending: true`, with `held` ([A held wake](schedules.md#a-held-wake)); the `wake-held` event ([the event kinds](#events)); `wakeHold` on every successful `session inspect --json` ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)), from the hook answer `dialogClaims` ([Commands and hooks](capabilities.md#commands-and-hooks)). Gate on the feature, then on `wakeHold`: the feature says this kernel holds, `wakeHold` whether this home's dialogs become claims, and `unknown` is not covered | |
|
|
170
170
|
| `lifecycle-claim-start` | every `oats session start` and `oats session restart`, and a scheduled start, holds the home's lifecycle claim for the whole start (#1602), as `details.action: "start"`: a retire, a stop apply or an upgrade apply that arrives while it runs is refused `E_LIFECYCLE_BUSY` with `details.action: "start"`; the start or restart is refused `E_INSTANCE_RETIRING` beside a retire and `E_LIFECYCLE_BUSY` (with `details.holder` and `details.action`) beside a stop or an upgrade, before any effect; two starts still answer `E_SESSION_START_BUSY` ([Commands that meet on one home](#lifecycle-pairs)). A restart holds one claim across its stop and its launch. A kernel without it takes no claim for these, and reads a `start` holder as a retire | |
|
|
171
171
|
| `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
|
|
172
|
+
| `workspace-tasks-payload` | oats-workspace.yaml may carry a top-level `tasks:` payload, merged for the capability that fills the tasks slot exactly as `messaging:` is for the messaging one; its leaves' `settingsOrigins` are `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}` ([Provider payloads have three homes](workspaces.md#provider-payloads-have-three-homes)). A kernel without it refuses a workspace file that carries `tasks:` (unknown property) | |
|
|
173
|
+
| `settings-committed-only` | a manifest `settings.<key>.committedOnly: true` is enforced: that key in oats-local.yaml `settings.<cap>` or a `--provider <cap>` flag is refused `E_WORKSPACE_SCHEMA` reason `committed-only-key`, with `details.layer`, `details.at` and `details.allowed` ([Commands and hooks](capabilities.md#commands-and-hooks)). A kernel without it ignores the flag and merges the key | |
|
|
172
174
|
|
|
173
175
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
174
176
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
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
|
|
@@ -156,6 +159,12 @@ Building an integration is implementing a contract. The framework's
|
|
|
156
159
|
`oats-local.yaml` `settings.<cap>` and refuses it elsewhere
|
|
157
160
|
(`E_WORKSPACE_SCHEMA`, reason `host-only-key`). The provider cannot enforce
|
|
158
161
|
this itself: it receives one merged payload without provenance.
|
|
162
|
+
- A setting every deployment must share (which shared task list to use) is
|
|
163
|
+
declared `committedOnly: true`, the mirror: the resolver refuses it from
|
|
164
|
+
`oats-local.yaml` `settings.<cap>` and `--provider` (`E_WORKSPACE_SCHEMA`,
|
|
165
|
+
reason `committed-only-key`), so it comes only from the workspace's
|
|
166
|
+
`messaging:` or `tasks:`, a soul's slot payload or the manifest default.
|
|
167
|
+
Kernels without the feature `settings-committed-only` ignore the flag.
|
|
159
168
|
- A slot provider that declares `binding` answers `oats readiness` through
|
|
160
169
|
its `binding.check` command
|
|
161
170
|
([capabilities.md](capabilities.md#readiness-check-bindingcheck)).
|
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
|
|
|
@@ -52,6 +52,10 @@
|
|
|
52
52
|
"type": "object",
|
|
53
53
|
"description": "Opaque provider payload consumed by the messaging core capability. A team's provider id is teams.<label>.team."
|
|
54
54
|
},
|
|
55
|
+
"tasks": {
|
|
56
|
+
"type": "object",
|
|
57
|
+
"description": "Opaque provider payload consumed by the capability that fills the tasks slot, merged at the same layer as messaging: (above the manifest's defaults, below a soul's tasks: payload). Kernels before the workspace-tasks-payload feature refuse this key."
|
|
58
|
+
},
|
|
55
59
|
"external": {
|
|
56
60
|
"type": "array",
|
|
57
61
|
"items": { "$ref": "#/$defs/external" },
|
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,107 @@
|
|
|
1
|
+
# OATS 0.69.11
|
|
2
|
+
|
|
3
|
+
0.69.11 lets a workspace give the tasks provider one shared setting in
|
|
4
|
+
`oats-workspace.yaml` (`tasks:`), and lets a capability mark a setting
|
|
5
|
+
`committedOnly`, so no deployment can override it locally. It moves the official
|
|
6
|
+
catalog to `oats.framework` 1.21.0 (`/oats-host-delivery` installs the pi
|
|
7
|
+
extension without its bundled skills, and `/oats-upgrade` covers a first Desktop
|
|
8
|
+
install) and `oats.aweb` 1.35.0 (`oats.aweb-tasks` gains a shared `team`
|
|
9
|
+
setting and a readiness check, and pi homes get a warning while the extension
|
|
10
|
+
still loads its skills). Getting started takes fixes from a second round of
|
|
11
|
+
newcomer runs on fresh machines.
|
|
12
|
+
|
|
13
|
+
## Upgrade
|
|
14
|
+
|
|
15
|
+
- **Either order of the Desktop and the CLI works.**
|
|
16
|
+
[Upgrading](../upgrading.md) installs the Desktop first, and a host that
|
|
17
|
+
installed the CLI first is fine too: the 0.69.11 Desktop accepts OATS CLIs
|
|
18
|
+
`>=0.26.0 <0.70.0`, as the 0.69.10 and 0.69.9 Desktops do.
|
|
19
|
+
- **Package moves:** the official catalog pins oats.framework 1.21.0 and
|
|
20
|
+
oats.aweb 1.35.0, with no change to their OATS floors (oats.aweb keeps aw
|
|
21
|
+
>=1.36.33, and is tested with 1.36.53). A deployment takes each by raising
|
|
22
|
+
its own pin (`/oats-package-pins`), then `oats sync`. Running instances keep
|
|
23
|
+
the modules they were spawned with: new spawns get the new ones, and a
|
|
24
|
+
stopped home moves with `oats instance upgrade`.
|
|
25
|
+
- **A pi home may warn `pi-extension-skills-loaded`** (oats.aweb 1.35.0) when
|
|
26
|
+
its pi folder's `settings.json` lists `npm:@awebai/pi` without
|
|
27
|
+
`"skills": []`. The warning names the file and the one entry to change; the
|
|
28
|
+
extension still loads, and `pi install` and `pi update` keep the filter.
|
|
29
|
+
- **Where `oats.aweb-tasks` is composed, readiness gains one provider item.**
|
|
30
|
+
With no `team` setting it passes and reads nothing.
|
|
31
|
+
- **Since oats.aweb 1.33.2 (pinned from 0.69.10 on), spawn and readiness warn
|
|
32
|
+
`aw-newer-than-tested`** when the aw on PATH is newer than the aw the
|
|
33
|
+
provider is tested with and the home's team root names a service other than
|
|
34
|
+
the aweb Cloud: a server on an older aweb may refuse it. The fix it names
|
|
35
|
+
first is upgrading that server's aweb. Cloud homes never warn, and it is
|
|
36
|
+
never a refusal. (0.69.10's notes left this out.)
|
|
37
|
+
- **A workspace sets `tasks:` only once every deployment that reads it runs a
|
|
38
|
+
kernel listing `workspace-tasks-payload`** (`oats version --json`
|
|
39
|
+
features). An older kernel refuses the whole file, so every resolve and spawn
|
|
40
|
+
on that deployment stops. A file without `tasks:` resolves exactly as before.
|
|
41
|
+
- **A capability's `committedOnly` setting is enforced only by kernels with
|
|
42
|
+
`settings-committed-only`.** An older kernel ignores the flag and still merges
|
|
43
|
+
the key from oats-local.yaml and `--provider`. A provider that relies on it
|
|
44
|
+
sets its kernel range to this release or later.
|
|
45
|
+
|
|
46
|
+
## Added
|
|
47
|
+
|
|
48
|
+
- **A workspace `tasks:` payload** (feature `workspace-tasks-payload`). The
|
|
49
|
+
workspace file may carry a top-level `tasks:`, an opaque payload for whichever
|
|
50
|
+
capability fills the tasks slot, merged at the same layer as `messaging:`:
|
|
51
|
+
the manifest's defaults, then the workspace's `messaging:` or `tasks:`, the
|
|
52
|
+
soul's slot payload, oats-local.yaml `settings.<cap>`, then `--provider`. Its
|
|
53
|
+
leaves' origin is `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}`. A
|
|
54
|
+
`hostOnly` key or `byTeam` in it is refused, as in `messaging:`. There is no
|
|
55
|
+
workspace `knowledge:` payload
|
|
56
|
+
([Provider payloads have three homes](../workspaces.md#provider-payloads-have-three-homes),
|
|
57
|
+
[awebai/oats#1719](https://github.com/awebai/oats/issues/1719)).
|
|
58
|
+
- **`committedOnly` settings** (feature `settings-committed-only`), the mirror
|
|
59
|
+
of `hostOnly`. A manifest's `settings.<key>.committedOnly: true` makes the
|
|
60
|
+
resolver refuse that key in oats-local.yaml `settings.<cap>` and in
|
|
61
|
+
`--provider <cap>` with `E_WORKSPACE_SCHEMA`, reason `committed-only-key`. The
|
|
62
|
+
key's presence is refused, even with the committed value. The refusal names
|
|
63
|
+
the key, where it was set, where it may be set (`details.allowed`) and the
|
|
64
|
+
fix. For a messaging or tasks capability, that is oats-workspace.yaml under
|
|
65
|
+
`messaging:` or `tasks:`, or a soul's slot payload. A key marked both
|
|
66
|
+
`hostOnly` and `committedOnly` is a manifest fault, `details.why`
|
|
67
|
+
`settings-flag-conflict`
|
|
68
|
+
([Commands and hooks](../capabilities.md#commands-and-hooks)).
|
|
69
|
+
- **An unknown top-level key in oats-workspace.yaml says the workspace may be
|
|
70
|
+
newer than the kernel.** Beside "unknown property", the problem adds "if this
|
|
71
|
+
is not a typo, the workspace uses a feature newer than this kernel (OATS
|
|
72
|
+
<version>): upgrade OATS", with reason `unknown-root-key`. Nested unknown keys
|
|
73
|
+
are unchanged.
|
|
74
|
+
|
|
75
|
+
## Changed
|
|
76
|
+
|
|
77
|
+
- **`oats.framework` 1.21.0 ships two setup steps.** `oats.setup` 2.12.0's `/oats-host-delivery` gains the pi step of channel delivery: install `@awebai/pi`, then set its entry in the pi folder's `settings.json` to `{"source": "npm:@awebai/pi", "skills": []}`, so pi loads the extension without the skills it bundles (#1722). Its `/oats-upgrade` now covers a first Desktop install: on a host without the Desktop it asks whether the person wants it, and installs that release's Desktop (#1724). No command they name needs a newer OATS than `oats.setup` already admits ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
|
|
78
|
+
- **`oats.aweb` 1.35.0: one tasks team for every deployment; pi without its
|
|
79
|
+
bundled skills.** `oats.aweb-tasks` gains `team: <label>`, the aweb team
|
|
80
|
+
whose task list every deployment shares. It is set only in the workspace's
|
|
81
|
+
or a soul's `tasks:` payload, and marked `committedOnly`. Its new readiness
|
|
82
|
+
check refuses a home that has not joined the team, naming
|
|
83
|
+
`oats aweb join --labels <label>` or `tasks: none`. Both pi `install` texts
|
|
84
|
+
install `@awebai/pi` with `"skills": []`, and readiness warns
|
|
85
|
+
`pi-extension-skills-loaded` where it still loads them. A joined team that has
|
|
86
|
+
become the default is kept, with a warning, until the home is respawned
|
|
87
|
+
([awebai/oats-aweb#188](https://github.com/awebai/oats-aweb/pull/188)-[#191](https://github.com/awebai/oats-aweb/pull/191)).
|
|
88
|
+
- **Getting started: the steward's global address waits for a release that
|
|
89
|
+
carries its route.** The skill named oats.aweb 1.35.0 as the first release
|
|
90
|
+
with the resident root route, but 1.35.0 ships without it
|
|
91
|
+
([awebai/oats-aweb#147](https://github.com/awebai/oats-aweb/pull/147) is not
|
|
92
|
+
merged). It now names no version and always takes the fallback, a local team
|
|
93
|
+
identity, until a release carries the route. That was already the outcome on
|
|
94
|
+
1.35.0, because the plan fell back; only the stated version changes.
|
|
95
|
+
- **Getting started: fixes from a second round of newcomer runs on fresh machines.** In `oats-getting-started`:
|
|
96
|
+
- **The whole file:** its description and its first line tell the agent to download it whole with `curl -fsSL` and follow it as written; a summary of it, from a web fetch that summarises, is not the procedure.
|
|
97
|
+
- **One change per command:** each change step 1's yes named runs as its own command, never batched with others, so a permission check that reads the conversation sees it by name. A refused command is never split into pieces or re-run in parts, `sudo` included: the agent asks the person once, naming the change, and retries once on their yes.
|
|
98
|
+
- **The time budget:** the setup takes a few minutes and seconds of the person's time. The agent waits about a minute for the Desktop's background download once the CLI is installed; when it hasn't verified by then, it goes on without the Desktop and records that in the hand-over; the person can install it later with the setup expert, through `/oats-upgrade`. `/oats-upgrade` (oats.setup) now covers that first install: on a host without the Desktop it asks whether the person wants it, and its Desktop step installs that release's Desktop.
|
|
99
|
+
- **A terminal window on Linux** that `systemd-run --user` can't open (no user session bus) is started directly and detached (`setsid -f xdg-terminal-exec` or `setsid -f x-terminal-emulator`, with the display variables the agent already has, never guessed) before the person is given a command to type.
|
|
100
|
+
- **GitHub:** the skill always checks the login, even right after it installed `gh`, before starting a device login.
|
|
101
|
+
- **A monorepo host:** step 1's one yes names the two setup files pushed straight to its default branch (which runs its automatic checks or deploys), and step 7 pushes them without asking again. A repository others can push to, a protected default branch or a refused push takes a pull request instead, and the hand-over records the skeleton as pushed or merged.
|
|
102
|
+
- **The hand-off** names no versions, package sources or internal flags or codes, and the setup expert, when named as the Desktop lists it, only by its display form; anything the person may want later goes in the hand-over file.
|
|
103
|
+
- **pi's skills filter** matches `npm:@awebai/pi` alone or with a version, never another `@awebai/pi-…` package. The skill now says that Claude's aweb channel plugin still carries one skill of its own until aweb ships it without one, a known gap ([awebai/oats#1665](https://github.com/awebai/oats/issues/1665)).
|
|
104
|
+
|
|
105
|
+
## Documentation
|
|
106
|
+
|
|
107
|
+
- **`/oats-host-delivery` installs the pi extension without its skills.** `oats.framework`'s host-delivery skill gains the pi step of channel delivery: the setup expert runs `pi install npm:@awebai/pi`, then makes the extension's entry in the pi folder's `settings.json` `{"source": "npm:@awebai/pi", "skills": []}`, so pi loads the extension and none of the skills `@awebai/pi` bundles. A home gets its skills through its OATS capabilities only. The filter is interim, until aweb publishes the extension without skills; oats.aweb's readiness warns `pi-extension-skills-loaded` while it is missing.
|
|
@@ -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.
|
|
@@ -187,7 +187,8 @@ For current settings and the respawn/cleanup sequence, see [knowledge.md](knowle
|
|
|
187
187
|
digest. `oats status` compares these with the workspace's current state and
|
|
188
188
|
shows `moved` / `missing` per module (drift is shown, not prevented).
|
|
189
189
|
- `providers.<cap>`: the merged provider payload the capability was bound with
|
|
190
|
-
(
|
|
190
|
+
(manifest defaults ⊕ the workspace's `messaging:` or `tasks:` ⊕ soul ⊕
|
|
191
|
+
machine settings ⊕ `--provider`), so a later inspection can tell
|
|
191
192
|
which instance holds a retained seat or a one-off state root. `spawn
|
|
192
193
|
--preview` shows the same map before anything exists, as `settings.<cap>`,
|
|
193
194
|
beside `providers` (the `--provider` flags as given).
|
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,17 @@ 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.
|
|
211
|
+
- **[0.69.11](release-notes/v0.69.11.md#upgrade):** the catalog pins
|
|
212
|
+
oats.framework 1.21.0 and oats.aweb 1.35.0. Upgrade every deployment of a
|
|
213
|
+
workspace before its shared `oats-workspace.yaml` sets `tasks:` (an older
|
|
214
|
+
kernel refuses the file). A pi home may warn `pi-extension-skills-loaded`
|
|
215
|
+
until its pi extension entry carries `"skills": []`.
|
|
205
216
|
- **[0.69.10](release-notes/v0.69.10.md#upgrade):** the catalog pins
|
|
206
217
|
oats.framework 1.20.0 and oats.aweb 1.34.0. With oats.aweb 1.34.0, a
|
|
207
218
|
deployment that uses aweb tasks composes `oats.aweb-tasks`. Upgrade every
|
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
|
|
@@ -78,6 +78,8 @@ stores: # knowledge stores, declared once
|
|
|
78
78
|
|
|
79
79
|
messaging: # an opaque provider payload for the messaging slot
|
|
80
80
|
private: per-human
|
|
81
|
+
tasks: # the same, for whichever capability fills the tasks slot
|
|
82
|
+
team: engineering # (ignored while the slot is empty, as here unless a soul fills it)
|
|
81
83
|
|
|
82
84
|
external: # souls borrowed from NON-members; revision REQUIRED
|
|
83
85
|
- source: git:github.com/oss-collective/experts@9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a9c4e1f2a
|
|
@@ -625,10 +627,23 @@ Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
|
|
|
625
627
|
| A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
|
|
626
628
|
| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
|
|
627
629
|
|
|
628
|
-
The merged payload is
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
630
|
+
The merged payload is the manifest's setting defaults ⊕ the workspace's
|
|
631
|
+
`messaging:` (for the messaging-slot capability only) or `tasks:` (for the
|
|
632
|
+
tasks-slot capability only) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
|
|
633
|
+
`spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
|
|
634
|
+
There is no workspace `knowledge:` payload. A workspace `tasks:` needs a kernel
|
|
635
|
+
with the feature `workspace-tasks-payload`: an older one refuses the file
|
|
636
|
+
(unknown property). The provider's own `binding` contract (its readiness
|
|
637
|
+
check) runs over the merged payload.
|
|
638
|
+
|
|
639
|
+
A capability's manifest may pin a setting to one of these layers. A key it
|
|
640
|
+
marks `hostOnly` comes only from `oats-local.yaml`; a key it marks
|
|
641
|
+
`committedOnly` never comes from `oats-local.yaml` or `--provider`: it is set
|
|
642
|
+
in the workspace's `messaging:` or `tasks:`, a soul's slot payload, or left at
|
|
643
|
+
the manifest default, so every deployment shares one value. Either one set in
|
|
644
|
+
the wrong layer is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key` or
|
|
645
|
+
`committed-only-key`), naming the key, where it was set and where it may be set
|
|
646
|
+
([Commands and hooks](capabilities.md#commands-and-hooks)). Teams are **not** settings:
|
|
632
647
|
they reach the provider beside them, in its environment ([Teams](#teams)).
|
|
633
648
|
Where a provider keeps its own state (for oats.aweb, its identity roots) is the
|
|
634
649
|
provider's concern; see its documentation.
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -5,6 +5,6 @@
|
|
|
5
5
|
* (test/cli-json-contract.test.mjs). Kernel-private, not exported from `./core`. Dependency-free. */
|
|
6
6
|
import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
7
7
|
|
|
8
|
-
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution"]);
|
|
8
|
+
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only"]);
|
|
9
9
|
/** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
|
|
10
10
|
export const READER_API = 1;
|
package/lib/resolve.mjs
CHANGED
|
@@ -44,8 +44,10 @@
|
|
|
44
44
|
* everything, while a preview can say WHAT changed since the previous instance (declarations | payload | both).
|
|
45
45
|
*
|
|
46
46
|
* Payloads (decision 14), later wins on scalars/arrays, objects deep-merge:
|
|
47
|
-
* workspace
|
|
47
|
+
* manifest defaults ⊕ workspace.<slot> (messaging and tasks slots only: WORKSPACE_PAYLOAD_SLOTS)
|
|
48
48
|
* ⊕ soul.<slot> ⊕ local.settings[cap] ⊕ spawn.providers[cap]
|
|
49
|
+
* A manifest settings key marked hostOnly comes only from local.settings[cap]; one marked committedOnly
|
|
50
|
+
* never comes from local.settings[cap] or spawn.providers[cap] (#1719).
|
|
49
51
|
*
|
|
50
52
|
* This module shells out to nothing. Remote access is injected (`remote`, default
|
|
51
53
|
* lib/remote.mjs; `remoteOptions` threaded into every call). `resolveSoul` is
|
|
@@ -65,6 +67,8 @@ import { currentRepoKey, sameRepo } from "./repo-moves.mjs";
|
|
|
65
67
|
|
|
66
68
|
export const RESOLUTION_API = 1;
|
|
67
69
|
export const SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
|
|
70
|
+
/** The slots whose payload oats-workspace.yaml may carry at its root (`messaging:`, `tasks:` since #1719). */
|
|
71
|
+
const WORKSPACE_PAYLOAD_SLOTS = Object.freeze(["messaging", "tasks"]);
|
|
68
72
|
const CONTRACT_DOC = "docs/design/2026-09-23-workspace-module-contracts.md";
|
|
69
73
|
|
|
70
74
|
/* ───────────────────────────── helpers ────────────────────────────────── */
|
|
@@ -179,6 +183,34 @@ function assertNoHostOnlyKey(value, path, hostOnly, capability) {
|
|
|
179
183
|
}
|
|
180
184
|
}
|
|
181
185
|
|
|
186
|
+
/** Settings keys a manifest marks `committedOnly: true` (#1719): the mirror of hostOnly. */
|
|
187
|
+
export function committedOnlyKeys(manifest) {
|
|
188
|
+
const out = new Set();
|
|
189
|
+
const decl = isObject(manifest?.settings) ? manifest.settings : {};
|
|
190
|
+
for (const [key, spec] of Object.entries(decl)) if (isObject(spec) && spec.committedOnly === true) out.add(key);
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
/** Where a committedOnly key of a capability with this layer may be set: the committed payload layers the
|
|
194
|
+
* resolver merges for it (`at` strings, as payloadOrigins names them), and the words for the refusal. */
|
|
195
|
+
function committedOnlyHomes(layer, key) {
|
|
196
|
+
if (WORKSPACE_PAYLOAD_SLOTS.includes(layer)) {
|
|
197
|
+
return { allowed: [`oats-workspace.yaml#/${layer}`, `soul.yaml#/${layer}`], where: `oats-workspace.yaml under ${layer}: or a soul's ${layer}: payload`, fix: `Set it in oats-workspace.yaml under ${layer}:, or remove it` };
|
|
198
|
+
}
|
|
199
|
+
if (layer) return { allowed: [`soul.yaml#/${layer}`], where: `a soul's ${layer}: payload`, fix: `Set it in the soul's ${layer}: payload, or remove it` };
|
|
200
|
+
return { allowed: [`oats.json#/settings/${key.replace(/~/g, "~0").replace(/\//g, "~1")}/default`], where: "its manifest default (the capability has no layer, so no committed payload reaches it)", fix: "Remove it" };
|
|
201
|
+
}
|
|
202
|
+
/** Refuse a committedOnly key in the host or spawn layer: only committed, reviewed files may set it (#1719). */
|
|
203
|
+
function assertNoCommittedOnlyKey(value, { path, layer, at, committedOnly, capability, capabilityLayer }) {
|
|
204
|
+
if (!committedOnly.size || !isObject(value)) return;
|
|
205
|
+
for (const key of committedOnly) {
|
|
206
|
+
if (!Object.hasOwn(value, key)) continue;
|
|
207
|
+
const homes = committedOnlyHomes(capabilityLayer, key);
|
|
208
|
+
const setIn = layer === "host" ? `oats-local.yaml settings.${capability}` : `--provider ${capability}`;
|
|
209
|
+
throw fail("E_WORKSPACE_SCHEMA", `${path}/${key}: ${show(key)} is a committed-only setting of ${capability} (its manifest marks it committedOnly): it was set in ${setIn}, and may be set only in a committed file — ${homes.where}. ${homes.fix} from ${setIn}`,
|
|
210
|
+
{ path: `${path}/${key}`, key, capability, reason: "committed-only-key", layer, at, allowed: homes.allowed });
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
182
214
|
/** Canonical JSON: object keys sorted (recursively), arrays in order, no whitespace. */
|
|
183
215
|
export function canonicalJson(value) {
|
|
184
216
|
if (value === undefined) return "null";
|
|
@@ -737,7 +769,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
737
769
|
seenSkills.set(s.name, s);
|
|
738
770
|
}
|
|
739
771
|
|
|
740
|
-
// Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace
|
|
772
|
+
// Payloads (decision 14; addendum 5): manifest defaults ⊕ workspace.<slot> (messaging and tasks slots) ⊕ soul.<slot>
|
|
741
773
|
// ⊕ local.settings[cap] ⊕ spawn.providers[cap], each leaf's origin kept in payloadOrigins.
|
|
742
774
|
const settings = isObject(local?.settings) ? local.settings : {};
|
|
743
775
|
const providers = isObject(spawn.providers) ? spawn.providers : {};
|
|
@@ -767,15 +799,26 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
767
799
|
// provider receives one merged payload without provenance and cannot enforce this itself.
|
|
768
800
|
const hostOnly = hostOnlyKeys(m.manifest);
|
|
769
801
|
const committed = (payload, path, origin) => { assertNoHostOnlyKey(payload, path, hostOnly, m.name); add(payload, origin); };
|
|
770
|
-
//
|
|
802
|
+
// #1719: the mirror — a key marked `committedOnly` must be the same for every deployment (a shared
|
|
803
|
+
// task list), so the host layer and --provider are refused with it present, BEFORE the merge, for the
|
|
804
|
+
// same reason. Marked both, no layer but the manifest default could set it: a fault of the manifest.
|
|
805
|
+
const committedOnly = committedOnlyKeys(m.manifest);
|
|
806
|
+
for (const key of committedOnly) {
|
|
807
|
+
if (hostOnly.has(key)) throw fail(m.from.kind === "package" ? "E_PACKAGE_MANIFEST" : "E_CAPABILITY_MISSING", `${m.name} marks setting ${show(key)} both hostOnly and committedOnly, so no layer but its manifest default could set it — drop one of the two flags`, { capability: m.name, key, why: "settings-flag-conflict" });
|
|
808
|
+
}
|
|
809
|
+
const notCommitted = (payload, path, layer, at) => assertNoCommittedOnlyKey(payload, { path, layer, at, committedOnly, capability: m.name, capabilityLayer: m.layer });
|
|
810
|
+
// The provider's settings are base ⊕ workspace ⊕ soul ⊕ host ⊕ spawn. Teams are not settings: they reach the
|
|
771
811
|
// provider beside them (OATS_DEFAULT_TEAM*, OATS_TEAMS).
|
|
772
|
-
if (m.layer
|
|
773
|
-
assertNoReservedKey(workspace.
|
|
774
|
-
committed(workspace.
|
|
812
|
+
if (WORKSPACE_PAYLOAD_SLOTS.includes(m.layer) && isObject(workspace?.[m.layer])) {
|
|
813
|
+
assertNoReservedKey(workspace[m.layer], `/${m.layer}`);
|
|
814
|
+
committed(workspace[m.layer], `/${m.layer}`, { kind: "workspace", at: `oats-workspace.yaml#/${m.layer}` });
|
|
775
815
|
}
|
|
776
816
|
if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); committed(definition[m.layer], `/${m.layer}`, { kind: "soul", at: `soul.yaml#/${m.layer}` }); }
|
|
777
|
-
if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here
|
|
778
|
-
if (Object.hasOwn(providers, m.name) && isObject(providers[m.name]))
|
|
817
|
+
if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); notCommitted(settings[m.name], `/settings/${m.name}`, "host", `oats-local.yaml#/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here, committedOnly ones are not
|
|
818
|
+
if (Object.hasOwn(providers, m.name) && isObject(providers[m.name])) {
|
|
819
|
+
notCommitted(providers[m.name], `/spawn/providers/${m.name}`, "spawn", `--provider ${m.name}`);
|
|
820
|
+
committed(providers[m.name], `/spawn/providers/${m.name}`, { kind: "spawn", at: `--provider ${m.name}` });
|
|
821
|
+
}
|
|
779
822
|
payloads[m.name] = mergePayload(...layers);
|
|
780
823
|
origins[m.name] = payloadOrigins(sourced);
|
|
781
824
|
// A value outside the manifest's `settings.<key>.values` is refused where it was set: a
|
package/lib/workspace.mjs
CHANGED
|
@@ -223,7 +223,7 @@ function keyOrProblem(remote, ref, path, problems) {
|
|
|
223
223
|
/** Schema + domain problems for an oats-workspace.yaml value. Refs are parsed with `remote`
|
|
224
224
|
* (default lib/remote.mjs) so duplicate members and malformed refs are always caught. */
|
|
225
225
|
export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
226
|
-
const problems = validateAgainst(schemaFor("workspace"), value);
|
|
226
|
+
const problems = validateAgainst(schemaFor("workspace"), value).map(newerRootKeyHint);
|
|
227
227
|
if (!isObject(value)) return problems;
|
|
228
228
|
if (value.schemaVersion !== 2) return referenceProblems(problems, refFields(value));
|
|
229
229
|
// Absolute-path refusal applies to REF/PATH fields only (L2): never to descriptions or the provider payload.
|
|
@@ -250,6 +250,7 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
|
250
250
|
if (isObject(value.messaging) && Object.hasOwn(value.messaging, "byTeam")) {
|
|
251
251
|
problems.push({ path: "/messaging/byTeam", reason: "removed-key", message: "messaging.byTeam was removed in 0.30: a team's provider id is teams.<label>.team (committed, shared) or oats-local.yaml teams.<label>.team (local)" });
|
|
252
252
|
}
|
|
253
|
+
if (isObject(value.tasks)) reservedKeyProblems(value.tasks, "/tasks", problems);
|
|
253
254
|
if (Array.isArray(value.external)) value.external.forEach((entry, i) => {
|
|
254
255
|
if (!isObject(entry)) return;
|
|
255
256
|
if (typeof entry.source === "string") {
|
|
@@ -264,6 +265,14 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
|
|
|
264
265
|
sharedLabelProblems(value, problems);
|
|
265
266
|
return referenceProblems(withRemovedKeys(problems, value, REMOVED_KEYS.workspace), refFields(value));
|
|
266
267
|
}
|
|
268
|
+
/** An unknown key at the workspace file's root is most often one a newer kernel added (a slot payload, a
|
|
269
|
+
* new section): the problem says so, beside the schema's own "unknown property" text. Nested keys keep it
|
|
270
|
+
* bare, and a removed key's own message (withRemovedKeys) replaces it. */
|
|
271
|
+
const KERNEL = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
|
|
272
|
+
function newerRootKeyHint(problem) {
|
|
273
|
+
if (!/^\/[^/]+$/.test(problem.path) || !problem.message.startsWith("unknown property ")) return problem;
|
|
274
|
+
return { ...problem, reason: "unknown-root-key", message: `${problem.message} — if this is not a typo, the workspace uses a feature newer than this kernel (OATS ${KERNEL}): upgrade OATS` };
|
|
275
|
+
}
|
|
267
276
|
/** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
|
|
268
277
|
* unknown label is refused when the file is read, never at a spawn on someone else's machine. */
|
|
269
278
|
function sharedLabelProblems(value, problems) {
|
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",
|
|
@@ -10,9 +10,16 @@ description: >-
|
|
|
10
10
|
Desktop on it. Offers the TUI.
|
|
11
11
|
Use for "get started with OATS", "set up / install / adopt OATS", "set up
|
|
12
12
|
OATS for this project", "join our OATS workspace", or when someone gives
|
|
13
|
-
you this file or its URL.
|
|
13
|
+
you this file or its URL. Download this file whole (`curl -fsSL
|
|
14
|
+
https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`)
|
|
15
|
+
and follow it as written: a summary of it is not the procedure.
|
|
14
16
|
---
|
|
15
17
|
|
|
18
|
+
**Read this whole file, never a summary of it.** If you only have a summary
|
|
19
|
+
(a web fetch that summarises, say), download it whole with
|
|
20
|
+
`curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md`
|
|
21
|
+
and follow it as written.
|
|
22
|
+
|
|
16
23
|
# Getting started with OATS
|
|
17
24
|
|
|
18
25
|
You are the person's own coding agent. This skill takes them from nothing to
|
|
@@ -39,11 +46,23 @@ tell the person this machine already has its workspace and steward, and
|
|
|
39
46
|
stop. Wherever a later step says to ask the
|
|
40
47
|
person, on a machine found-list you tell them what happened, as it is, and
|
|
41
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.
|
|
42
55
|
|
|
43
56
|
**How to work.**
|
|
44
57
|
- **Ask first, then run.** Ask everything in one round (step 1), then run the
|
|
45
58
|
steps yourself and read back what each did. Touch nothing you were not
|
|
46
59
|
asked to (see "Never").
|
|
60
|
+
- **The time budget.** The whole setup should take a few minutes, and only
|
|
61
|
+
seconds of the person's time: their answers, a login to approve, a secret
|
|
62
|
+
to type. Don't wait more than about a minute for the Desktop's background
|
|
63
|
+
download once the CLI is installed: if it hasn't verified by then, go on
|
|
64
|
+
without the Desktop and record that in the hand-over (the person can
|
|
65
|
+
install it later with the setup expert, through `/oats-upgrade`).
|
|
47
66
|
- **Talk to a newcomer, in everyday words.** They may not know what a
|
|
48
67
|
repository, Git, a terminal or a command is. Talk about their projects,
|
|
49
68
|
code and folders: "your agents' shared setup" (the workspace), "the setup
|
|
@@ -72,16 +91,23 @@ stop instead: the person answers nothing after step 1.
|
|
|
72
91
|
missing, with what it is for, Git told to use their GitHub login (`gh auth
|
|
73
92
|
setup-git`, in `~/.gitconfig`), on Linux npm's per-user folder (in
|
|
74
93
|
`~/.npmrc`), and, for a new workspace whose host step 6 creates, the
|
|
75
|
-
private repository `<owner>/<repo>` on GitHub
|
|
94
|
+
private repository `<owner>/<repo>` on GitHub, or, when the host is an
|
|
95
|
+
existing repository (a monorepo), the two setup files committed and
|
|
96
|
+
pushed straight to `<owner>/<repo>`'s default branch, which runs its
|
|
97
|
+
automatic checks or deploys if it has any (or a pull request, step 7).
|
|
76
98
|
Name each change by what and where, not by kind: a permission check that
|
|
77
99
|
reads the conversation lets a step through only when their yes named it.
|
|
100
|
+
Run each change on the list as its own command, never batched with other
|
|
101
|
+
changes, so that check sees it by the name their yes gave it (a fenced
|
|
102
|
+
block below that makes one change on the list counts as one).
|
|
78
103
|
Never run `sudo` for something that was not on that list, even where no
|
|
79
104
|
password is asked; if they say no to a system package, tell them what will
|
|
80
105
|
not work without it.
|
|
81
106
|
- **When your harness's permission check stops a step on the list** and
|
|
82
107
|
asks the person to approve, tell them it is one of the changes they said
|
|
83
108
|
yes to. If it refuses the step outright, never run it another way
|
|
84
|
-
(another shell, a script, a window you open)
|
|
109
|
+
(another shell, a script, a window you open), and never split it into
|
|
110
|
+
pieces or re-run its parts, `sudo` included: ask the person once, naming
|
|
85
111
|
the change, whether you may make it, and try again once on their yes.
|
|
86
112
|
Still refused: tell them in one sentence which change is missing and what
|
|
87
113
|
won't work without it, and go on where you can. Never ask them to type a
|
|
@@ -111,7 +137,14 @@ stop instead: the person answers nothing after step 1.
|
|
|
111
137
|
- **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
|
|
112
138
|
or `x-terminal-emulator -e sh "F"` in place of `xdg-terminal-exec` where
|
|
113
139
|
only that exists. Through `systemd-run` the window gets their desktop
|
|
114
|
-
session's environment, not yours.
|
|
140
|
+
session's environment, not yours. If `systemd-run` fails (for example
|
|
141
|
+
"Failed to connect to bus", when there is no user session bus), start
|
|
142
|
+
the terminal directly, detached, before you give them a command to type:
|
|
143
|
+
`setsid -f xdg-terminal-exec sh "F" </dev/null >/dev/null 2>&1`, or
|
|
144
|
+
`setsid -f x-terminal-emulator -e sh "F" </dev/null >/dev/null 2>&1`.
|
|
145
|
+
It uses the `DISPLAY`, `WAYLAND_DISPLAY`, `XAUTHORITY` and
|
|
146
|
+
`XDG_RUNTIME_DIR` your environment already has; when they are unset,
|
|
147
|
+
don't guess them: take "When no window opens".
|
|
115
148
|
|
|
116
149
|
Tell them what to type there, and ask whether the window opened (a
|
|
117
150
|
command that started is no proof of one). Check the result with a
|
|
@@ -127,7 +160,15 @@ On a machine found-list, ask the machine's round below instead of this list.
|
|
|
127
160
|
|
|
128
161
|
**First, step 2's checks.** They only read, so run them before the message
|
|
129
162
|
(not its installs): the changes to their computer that the message lists
|
|
130
|
-
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.
|
|
131
172
|
|
|
132
173
|
**The message.** Ask three things, and in the same message propose
|
|
133
174
|
everything else as defaults they accept with "ok" or change:
|
|
@@ -236,9 +277,9 @@ the final values in one short message before you go on. The rules:
|
|
|
236
277
|
`PEP` and `GPT`.
|
|
237
278
|
|
|
238
279
|
With a tracker, the agents keep using it: the line says so ("your agents
|
|
239
|
-
use your GitHub issues; the setup assistant
|
|
240
|
-
writes `tasks: none`; the setup expert
|
|
241
|
-
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
|
|
242
283
|
agents". Ask only when unsure, as the final-values message's one open
|
|
243
284
|
line, prefilled with the answer you'd pick: ticket keys the person didn't
|
|
244
285
|
name, a project kept somewhere other than GitHub (its issues can't be
|
|
@@ -248,8 +289,9 @@ the final values in one short message before you go on. The rules:
|
|
|
248
289
|
**The machine's round.** Read the found-list, then ask only these choices,
|
|
249
290
|
together, each with its default and one line on what it is. Enter, or
|
|
250
291
|
"yes", accepts every default. Nothing is asked after this round, and never
|
|
251
|
-
a key.
|
|
252
|
-
|
|
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.
|
|
253
295
|
- **The workspace:** a new one, the machine's own. Its name defaults to the
|
|
254
296
|
hostname, lowercased, with every character outside `[a-z0-9-]` turned
|
|
255
297
|
into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
|
|
@@ -303,6 +345,13 @@ before the first line that needs `sudo`.
|
|
|
303
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
|
|
304
346
|
```
|
|
305
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
|
+
|
|
306
355
|
- **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
|
|
307
356
|
caches; older Git works with whole-tree fetches); `gh` 2.49 or later
|
|
308
357
|
(step 3 uses `gh attestation`).
|
|
@@ -333,15 +382,12 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
|
|
|
333
382
|
```bash
|
|
334
383
|
sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
|
|
335
384
|
```
|
|
336
|
-
- **The Desktop's system libraries** (x64)
|
|
337
|
-
|
|
338
|
-
```bash
|
|
339
|
-
for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
|
|
340
|
-
```
|
|
341
|
-
|
|
385
|
+
- **The Desktop's system libraries** (x64), from the check above, run
|
|
386
|
+
before step 1's message:
|
|
342
387
|
- **ALSA missing:** the Desktop needs it, so step 1's list names its
|
|
343
|
-
package
|
|
344
|
-
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.
|
|
345
391
|
- **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
|
|
346
392
|
`--appimage-extract-and-run`, which needs no FUSE.
|
|
347
393
|
- **Passwords:** a line that needs `sudo` runs only after their yes in
|
|
@@ -369,7 +415,9 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g;
|
|
|
369
415
|
|
|
370
416
|
## 3. Log in to GitHub
|
|
371
417
|
|
|
372
|
-
|
|
418
|
+
Always run this check, even when step 2 just installed gh (an existing gh
|
|
419
|
+
config or `GH_TOKEN` may already log it in), and start the device login
|
|
420
|
+
below only if it says gh is not logged in.
|
|
373
421
|
|
|
374
422
|
```bash
|
|
375
423
|
gh auth status
|
|
@@ -382,7 +430,15 @@ fail with "could not read Username"), then go on below:
|
|
|
382
430
|
gh auth setup-git
|
|
383
431
|
```
|
|
384
432
|
|
|
385
|
-
|
|
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
|
|
386
442
|
harness's background mode if it has one); gh prints a one-time code and a
|
|
387
443
|
URL instead of opening a browser, and waits:
|
|
388
444
|
|
|
@@ -456,7 +512,7 @@ installed CLI's catalog:
|
|
|
456
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"
|
|
457
513
|
```
|
|
458
514
|
|
|
459
|
-
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
|
|
460
516
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
461
517
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
462
518
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -466,12 +522,16 @@ release. Never write a setup soul into the workspace in its place.
|
|
|
466
522
|
wakes an agent when mail arrives (skip this without messaging): Claude
|
|
467
523
|
`claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
|
|
468
524
|
pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
|
|
469
|
-
to load none of the skills it bundles (
|
|
470
|
-
|
|
471
|
-
|
|
525
|
+
to load none of the skills it bundles (pi's extension is installed without
|
|
526
|
+
its skills, so it puts none on the computer; each agent gets its own);
|
|
527
|
+
Codex nothing (the setup expert sets up its wake). Claude's aweb channel
|
|
528
|
+
plugin still carries one skill of its own, until aweb ships it without
|
|
529
|
+
(a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
|
|
530
|
+
`@` and a version, never another `@awebai/pi-…` package, and prints it so
|
|
531
|
+
you can check `"skills":[]`:
|
|
472
532
|
|
|
473
533
|
```bash
|
|
474
|
-
node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)
|
|
534
|
+
node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)=>/^npm:@awebai\/pi(@|$)/.test(typeof e==="string"?e:e&&e.source||"");s.packages=(s.packages||[]).map((e)=>ours(e)?{...(typeof e==="object"?e:{}),source:typeof e==="string"?e:e.source,skills:[]}:e);fs.writeFileSync(f,JSON.stringify(s,null,2)+"\n");console.log(JSON.stringify(s.packages.filter(ours)))'
|
|
475
535
|
```
|
|
476
536
|
|
|
477
537
|
```bash
|
|
@@ -481,8 +541,8 @@ npm install -g @awebai/aw && aw version
|
|
|
481
541
|
`aw` must be 1.36.33 or later.
|
|
482
542
|
|
|
483
543
|
**Then the Desktop. Every step verifies before it installs.** Wait for step
|
|
484
|
-
3's download, then read its log.
|
|
485
|
-
|
|
544
|
+
3's download, then read its log. Run this once: it waits up to a minute
|
|
545
|
+
for a `DONE` line ("How to work", the time budget):
|
|
486
546
|
|
|
487
547
|
```bash
|
|
488
548
|
for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n 5 "<W>.log"
|
|
@@ -490,7 +550,9 @@ for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n
|
|
|
490
550
|
|
|
491
551
|
Install the Desktop only when the log has a `VERIFIED` line. If a download or
|
|
492
552
|
a check failed (its assets can lag the npm package), or it still has not
|
|
493
|
-
finished,
|
|
553
|
+
finished, go on without the Desktop, say so, and record it in the
|
|
554
|
+
hand-over: the person can install it later with the setup expert, through
|
|
555
|
+
`/oats-upgrade`. Never skip a check to
|
|
494
556
|
make it install, and never install or open this download before its
|
|
495
557
|
attestation has passed. A Desktop installed before this run stays as it is.
|
|
496
558
|
|
|
@@ -682,8 +744,8 @@ name: acme
|
|
|
682
744
|
members:
|
|
683
745
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
684
746
|
packages:
|
|
685
|
-
oats.framework: v1.
|
|
686
|
-
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
|
|
687
749
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
688
750
|
defaults:
|
|
689
751
|
capabilities:
|
|
@@ -720,10 +782,15 @@ workspace: git:github.com/acme/acme-oats
|
|
|
720
782
|
**Commit and push.**
|
|
721
783
|
- **A repository created in step 6:** straight to its default branch (it
|
|
722
784
|
is the person's own, just created).
|
|
723
|
-
- **A monorepo:**
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
785
|
+
- **A monorepo:** push the commit to its default branch on step 1's yes,
|
|
786
|
+
which named it, without asking again; show the person the files only if
|
|
787
|
+
they ask. When others can push to the repository (`gh api
|
|
788
|
+
repos/<owner>/<repo>/collaborators --jq length` prints more than 1, or
|
|
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.
|
|
727
794
|
- If `git config user.name` or `git config user.email` prints nothing in
|
|
728
795
|
`D/<repo>`, commit with the name step 1's yes covered:
|
|
729
796
|
`-c user.name="<their name>" -c user.email="<their noreply address>"`,
|
|
@@ -768,9 +835,39 @@ needs a clone of its repository at `D/<repo name>`: for an existing
|
|
|
768
835
|
workspace whose setup soul is its own, run the `git clone` line
|
|
769
836
|
`oats onboard` printed for it, if it says it is missing.
|
|
770
837
|
|
|
771
|
-
**Record the
|
|
772
|
-
none, and without this every later check (readiness, harness trust) and
|
|
773
|
-
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:
|
|
774
871
|
|
|
775
872
|
```bash
|
|
776
873
|
oats soul launch set S --harness <harness> --dir D --plan
|
|
@@ -889,8 +986,10 @@ with no API key and nothing for the person to type. Without messaging, skip
|
|
|
889
986
|
this. It needs all of these; when one fails, take the fallback below:
|
|
890
987
|
- a new workspace: a root that joined by invite (items 3 and 4) does not own
|
|
891
988
|
the namespace, so aweb would refuse the create;
|
|
892
|
-
- `oats.aweb`
|
|
893
|
-
|
|
989
|
+
- an `oats.aweb` release that carries the root route
|
|
990
|
+
([awebai/oats-aweb#147](https://github.com/awebai/oats-aweb/pull/147)).
|
|
991
|
+
None is released yet: until one is, take the fallback below, whatever
|
|
992
|
+
`oats.aweb` version the `oats inspect` you read above reports;
|
|
894
993
|
- aw 1.36.48 or later: `aw.version` in the check (item 1).
|
|
895
994
|
|
|
896
995
|
Plan, then create, both from `D` and with no `AWEB_API_KEY`:
|
|
@@ -930,7 +1029,8 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
|
|
|
930
1029
|
|
|
931
1030
|
- Workspace: <workspace> (W), new | existing; deployment directory: D
|
|
932
1031
|
- Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
|
|
933
|
-
- 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)
|
|
934
1034
|
- Machine found-list only: steward R, address N.aweb.ai/R | local team
|
|
935
1035
|
identity (<the fallback's reason>)
|
|
936
1036
|
|
|
@@ -941,8 +1041,8 @@ are cloned, knowledge tools, messaging wanted or not>
|
|
|
941
1041
|
## Done by the getting-started skill
|
|
942
1042
|
- Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
|
|
943
1043
|
- GitHub: gh logged in over https as <login>; no SSH key or signing set up
|
|
944
|
-
- New workspace only: host <owner>/<repo>, skeleton committed (pushed |
|
|
945
|
-
|
|
1044
|
+
- New workspace only: host <owner>/<repo>, skeleton committed (pushed |
|
|
1045
|
+
merged from <url>)
|
|
946
1046
|
- Messaging: <capability>, aw <version>, <harness> channel installed;
|
|
947
1047
|
team T on aweb account N, created for the workspace, not yet attached to
|
|
948
1048
|
the person (new workspace), or T owned by aweb account <handle>
|
|
@@ -955,6 +1055,8 @@ are cloned, knowledge tools, messaging wanted or not>
|
|
|
955
1055
|
<GitHub issues in <repo> | <tracker the person named> | ticket keys
|
|
956
1056
|
<PREFIX>-n>, for you to connect with the person; aweb's task list stays
|
|
957
1057
|
empty
|
|
1058
|
+
- For the person, later: <what they may want to know but the hand-off
|
|
1059
|
+
message leaves out, such as a version, a skipped step and why>
|
|
958
1060
|
|
|
959
1061
|
## Left to you
|
|
960
1062
|
Everything else, starting with /oats-setup-expert.
|
|
@@ -1085,15 +1187,23 @@ and say yes to it in the hand-over below.
|
|
|
1085
1187
|
line, with how to change it: "Your agents share aweb's task list; to use
|
|
1086
1188
|
another tracker later, ask the setup assistant to switch." With a
|
|
1087
1189
|
tracker: "Your agents use your <GitHub issues | tracker>; the setup
|
|
1088
|
-
assistant
|
|
1190
|
+
assistant offers to connect them. Leave aweb's task list empty: one task there
|
|
1089
1191
|
opts your whole group in to it. To use aweb's task list instead, ask the
|
|
1090
1192
|
setup assistant."
|
|
1091
1193
|
|
|
1092
|
-
Don't list homes, paths
|
|
1093
|
-
|
|
1194
|
+
Keep this message in plain words. Don't list homes, paths or commands, and
|
|
1195
|
+
name no versions (Git's, OATS's or any other), no package sources (a PPA,
|
|
1196
|
+
say) and no internal flags or codes (a "development-channel flag", a
|
|
1197
|
+
"channel-not-connected", say). When you name the setup expert as the
|
|
1198
|
+
Desktop lists it, use its display form, never its instance name. Anything they may want to know later goes in the hand-over file, for
|
|
1199
|
+
the setup expert, not in this message. You are done.
|
|
1094
1200
|
|
|
1095
1201
|
## Never
|
|
1096
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.
|
|
1097
1207
|
- **Ask for, read, print or store a secret,** or suggest Claude Code's
|
|
1098
1208
|
`! <command>` for one: its command and output enter your context. If the
|
|
1099
1209
|
person pastes one anyway, don't repeat it, and tell them to rotate it.
|