@awebai/oats 0.67.1 → 0.68.0

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.
Files changed (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -15,7 +15,7 @@ For each soul, OATS resolves zero or one implementation per slot:
15
15
  | --- | --- | --- |
16
16
  | `knowledge` | [knowledge](layers.md#the-knowledge-contract) | `oats.okf` |
17
17
  | `messaging` | [communication](layers.md#the-communication-contract) | `oats.aweb` |
18
- | `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.jira`, `oats.linear` |
18
+ | `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.aweb-tasks`, `oats.jira`, `oats.linear` |
19
19
 
20
20
  A capability becomes an integration by declaring exactly one `layer` in its
21
21
  manifest. Capabilities without `layer` compose additively.
@@ -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.2.1
44
- oats.aweb: v1.30.0
43
+ oats.okf: v5.3.0
44
+ oats.aweb: v1.31.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -57,7 +57,8 @@ tasks:
57
57
  # souls/support-triager/soul.yaml: opt out of one slot, replace another
58
58
  knowledge: none # empties the slot
59
59
  capabilities:
60
- oats.jira: { from: package } # its manifest says layer: tasks, so it replaces the default
60
+ oats.linear: off # removes the tasks default...
61
+ oats.jira: { from: package } # ...so this one fills the slot (two would be E_SLOT_CONFLICT)
61
62
  ```
62
63
 
63
64
  - A soul's slot key is either `none` or that slot's payload (settings for the
@@ -80,6 +81,7 @@ operations in full.
80
81
  | --- | --- | --- | --- |
81
82
  | `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
82
83
  | `messaging` | `oats.aweb` | the `aw` CLI at 1.36.33 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
84
+ | `tasks` | `oats.aweb-tasks` | the `aw` CLI at 1.36.33 or later, and `oats.aweb` as the soul's messaging: tasks act as the instance's own oats.aweb identity in its default team; nothing in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
83
85
  | `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
84
86
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
85
87
 
@@ -91,6 +93,16 @@ operations in full.
91
93
  soul-only `knowledge: { harvest: off }` forbids harvest while retaining
92
94
  consultation. No host switch or automatic transcript/retire capture remains;
93
95
  `knowledge-maintainer` reviews the resulting Git PRs.
96
+ - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
97
+ tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
98
+ identity in its default team. **An existing workspace opts in** by pinning
99
+ `oats.aweb: v1.31.0` (or later), adding
100
+ `tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
101
+ `oats sync`. Only new spawns get it. A soul that names its own tasks
102
+ provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
103
+ fails with `E_SLOT_CONFLICT`: to keep its own, it adds
104
+ `oats.aweb-tasks: off` to its `capabilities:`. A soul opts out of tasks
105
+ entirely with `tasks: none`.
94
106
  - **`oats.aweb`** mints a messaging identity for each instance at spawn and
95
107
  removes it at retire, contributes the aweb messaging skills, and wires the
96
108
  channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.2.1** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.3.0** (OATS **>=0.49.0**). 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.2.1
28
+ oats.okf: v5.3.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,15 +50,18 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.2.1, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.3.0, OATS >=0.49.0 remains required:
54
54
  that kernel first supports the public source-event lookup after retirement.
55
55
 
56
- **Upgrade:** pin `oats.okf: v5.2.1` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.3.0` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
58
  homes keep their copied provider even after a session restart. Deployments
59
59
  whose briefings never mentioned harvesting now get knowledge proposals at
60
- eligible checkpoints; souls not ready for this must declare
60
+ the harvest checkpoints; souls not ready for this must declare
61
61
  `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
62
+ From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the checkpoint
63
+ line in `log.md`, drops the available-memory gate, and has the proposer name
64
+ each harvester (`--name`, below).
62
65
 
63
66
  ### Bindings document
64
67
 
@@ -170,13 +173,19 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
170
173
  means no harvest, and `unknown` or an error means stop and report, never
171
174
  infer permission or edit the record. Working instances never write
172
175
  accepted knowledge themselves.
173
- 2. **Propose only at a finished task or PR hand-over.** First update state,
174
- log and relevant notes. Apply `knowledge-theory` and search accepted
175
- knowledge (`oats okf search`, then `cat`): already accepted with nothing
176
- to add means no proposal. Most checkpoints propose nothing. Make at most
177
- **one proposal for that completed unit of work**; handing over its PR and
178
- closing the same task are not two opportunities. Never launch per commit,
179
- per decision, per review round or merely because a PR opened.
176
+ 2. **Propose at each harvest checkpoint.** The checkpoints are a PR handed
177
+ over for review and a finished task. In a long-lived role whose task
178
+ never finishes (a maintainer, an expert holding an area, a support desk),
179
+ they also include a feature ready, a release or deploy shipped, and a
180
+ direction decision taken with the human. A commit, a review round, a new
181
+ head of the same PR and each decision made while working are not
182
+ checkpoints: those are captured in `notes/`, and the next checkpoint
183
+ carries them. First update state, log and relevant notes. Apply
184
+ `knowledge-theory` and search accepted knowledge (`oats okf search`, then
185
+ `cat`): already accepted with nothing to add means no proposal. Make **one
186
+ proposal per checkpoint, carrying only what no earlier proposal carried**,
187
+ and record every checkpoint in `log.md`, either with its proposal and
188
+ harvester or with `nothing to propose` and the reason.
180
189
 
181
190
  Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
182
191
  home: What (one claim per concept), Why, Evidence (observations, dates,
@@ -187,22 +196,25 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
187
196
  nodes; a lesson for a node the soul only reads is named in one line in its
188
197
  hand-back for that node's owner.
189
198
 
190
- **Before spawning:** one harvester at a time per instance. Record its
191
- returned name and proposal in log.md, and do not spawn another while
192
- `oats status` still lists the last one. Check available memory immediately
193
- before spawning: on Linux, `free -g` must show at least 8 GB available;
194
- elsewhere use the host's documented check. If availability cannot be
195
- established, is below the floor, or the host is under memory pressure,
196
- defer. These are instructions, not a scheduler or a memory reservation.
197
- Keep deferred proposals/notes and record the reason and waiting claims in
198
- STATE.md, log.md and the hand-back. Reconsider at a natural task boundary,
199
- never by polling, sleeping or stopping other instances to make room.
200
-
201
- From instance home, preview and then apply the skill's command when the
202
- gates permit it:
199
+ **Before spawning:** one harvester at a time per instance. Do not spawn
200
+ another while `oats status` still lists the last one: keep the proposal
201
+ pending in STATE.md and log.md, add the next checkpoint's claims to it,
202
+ and launch it at that checkpoint once the last harvester is gone. Never
203
+ poll, sleep or stop other instances to make room. (5.3.0 removed the
204
+ 5.2.x available-memory gate.)
205
+
206
+ **The proposer names its harvester.** For each new proposal,
207
+ **okf-propose** prints a fresh name: up to 21 characters of the source
208
+ instance's name, a dash, a random UUID without dashes, and `-harvester`,
209
+ 64 characters at most (the kernel's and aweb's alias limit). The proposer
210
+ records it with the proposal in log.md before the preview, checks that
211
+ `oats status` doesn't list it, and uses it unchanged in both the preview and
212
+ the apply. Never leave the name to the kernel's numbered default: a retired
213
+ harvester's messaging alias can stay occupied with no instance listed, and
214
+ a numbered name can land on it.
203
215
 
204
216
  ```sh
205
- oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
217
+ oats spawn oats.okf/knowledge-harvester --name <harvester-name> --task-file <proposal> --relation unrelated
206
218
  ```
207
219
 
208
220
  Never combine `--relation unrelated` with `--relative-to`, or override
@@ -214,7 +226,12 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
214
226
  evidence before capture, so do not dispose of it before capture.
215
227
  Missing source authority never permits inventing it.
216
228
 
217
- A refused or uncertain spawn is reported, not retried in a loop. If the
229
+ A refused or uncertain spawn is reported, not retried in a loop. On
230
+ `E_INSTANCE_NAME_TAKEN`, the proposer stops and reports the name and the
231
+ refusal: no `--purpose`, no counter, no new UUID in a retry. A messaging
232
+ identity failure (for example a stale certificate on the alias) is
233
+ reported to the operator; the proposer never removes certificates or
234
+ renames around it. If the
218
235
  last harvester is still listed at hand-back, name it and the claims still
219
236
  waiting; do not wait for it or spawn around it. A harvester retained after
220
237
  a publication failure stays listed and holds back later proposals. Once
package/docs/layers.md CHANGED
@@ -46,8 +46,8 @@ not proof that an agent is enrolled. The official provider is `oats.aweb`.
46
46
  ### The tasks contract
47
47
 
48
48
  The tasks capability owns assignment, claims, status, blockers and handoff.
49
- `oats.jira` and `oats.linear` are the official providers. Messaging is
50
- conversation, not task state.
49
+ The official providers are `oats.aweb-tasks` (from the `oats.aweb` package),
50
+ `oats.jira` and `oats.linear`. Messaging is conversation, not task state.
51
51
 
52
52
  ## What the kernel does not own
53
53
 
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.13.5` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.30.0` | `oats.aweb` (messaging) | |
15
- | `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.14.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.31.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.11.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.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
29
29
  ## Find and use packages
30
30
 
31
31
  - A workspace pins an official package by **bare version** in its
32
- `packages:` map (`oats.okf: v5.2.1`); `oats sync` resolves it through the
32
+ `packages:` map (`oats.okf: v5.3.0`); `oats sync` resolves it through the
33
33
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
34
34
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
35
35
  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.2.1 # bare version → the official catalog
47
+ oats.okf: v5.3.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.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.3.0`, `5.3.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.2.1` or `oats-framework/v1.13.5`) and the payload path. An id
54
+ convention (`v5.3.0` or `oats-framework/v1.14.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.13.5
78
- oats.okf: v5.2.1
79
- oats.aweb: v1.30.0
77
+ oats.framework: v1.14.1
78
+ oats.okf: v5.3.0
79
+ oats.aweb: v1.31.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.2.1 ✓ (@ 72e989b9)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.3.0 ✓ (@ 79befeaf)
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.30.0 # a catalog version
137
+ oats package add oats.aweb v1.31.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,8 +160,8 @@ 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.2.1",
164
- "commit": "72e989b926e8ac1b7b912785beff396d1fc41cbb",
163
+ "version": "5.3.0",
164
+ "commit": "79befeaf98e04a5a46896ddad8ac3333ee90bce3",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -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.2.1", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.5", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.3.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.14.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.13.5`
362
- resolves to tag `oats-framework/v1.13.5`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.14.1`
362
+ resolves to tag `oats-framework/v1.14.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.