@awebai/oats 0.56.0 → 0.57.1
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/bin/oats.mjs +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
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.2.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 |
|
|
@@ -14,6 +14,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
14
14
|
| Accepted Git or directory bases | Soul knowledge: OKF concepts in owned nodes. |
|
|
15
15
|
| `souls/<name>/okf.json` | The soul's stable owner and owned/read nodes. |
|
|
16
16
|
| Instance home: `STATE.md`, `log.md`, `notes/` | The instance's working knowledge. |
|
|
17
|
+
| Instance home: `okf-harvest-policy.json` | Provider-written duty at spawn, exposed by `oats okf status`; not publication authority. |
|
|
17
18
|
| Harvester home: `harvest-source/` | Private source evidence captured at spawn, not accepted knowledge. |
|
|
18
19
|
| Bindings file and `stateDir` | Host base locations and consultation/binding state, not a harvest queue. |
|
|
19
20
|
|
|
@@ -24,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
24
25
|
```yaml
|
|
25
26
|
# oats-workspace.yaml (excerpt)
|
|
26
27
|
packages:
|
|
27
|
-
oats.okf: v5.
|
|
28
|
+
oats.okf: v5.2.0
|
|
28
29
|
defaults:
|
|
29
30
|
knowledge: { oats.okf: { from: package } }
|
|
30
31
|
stores:
|
|
@@ -49,10 +50,15 @@ settings:
|
|
|
49
50
|
|
|
50
51
|
Upgrading from 4.x requires the ordered
|
|
51
52
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
52
|
-
just editing a version line. For 5.
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
53
|
+
just editing a version line. For 5.2.0, OATS >=0.49.0 remains required:
|
|
54
|
+
that kernel first supports the public source-event lookup after retirement.
|
|
55
|
+
|
|
56
|
+
**Upgrade:** pin `oats.okf: v5.2.0` and run `oats sync`. Only new spawns get
|
|
57
|
+
the capability-owned harvest duty, skill and spawn-recorded policy. Existing
|
|
58
|
+
homes keep their copied provider even after a session restart. Deployments
|
|
59
|
+
whose briefings never mentioned harvesting now get knowledge proposals at
|
|
60
|
+
eligible checkpoints; souls not ready for this must declare
|
|
61
|
+
`knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
|
|
56
62
|
|
|
57
63
|
### Bindings document
|
|
58
64
|
|
|
@@ -142,9 +148,11 @@ soul's opt-out:
|
|
|
142
148
|
knowledge: { harvest: off }
|
|
143
149
|
```
|
|
144
150
|
|
|
145
|
-
That soul keeps consultation and working-memory guidance
|
|
146
|
-
|
|
147
|
-
|
|
151
|
+
That soul keeps consultation and working-memory guidance but has no harvest
|
|
152
|
+
duty. The shared IMPORTANT block and compulsory skill pointer still ship,
|
|
153
|
+
with an explicit exception; the provider's spawn-recorded answer says `off`.
|
|
154
|
+
Independently, the harvester's required spawn hook refuses that soul's
|
|
155
|
+
material. Absence gives the normal proposal flow.
|
|
148
156
|
A soul's `harvest: on` is not a replacement switch. Host cleanup never
|
|
149
157
|
changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
150
158
|
|
|
@@ -152,36 +160,66 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
152
160
|
|
|
153
161
|
### The flow
|
|
154
162
|
|
|
155
|
-
1. **Consult
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
163
|
+
1. **Consult and keep instance knowledge current.** Read accepted soul
|
|
164
|
+
knowledge at task start, after compaction and before decisions. Keep
|
|
165
|
+
`STATE.md`, `log.md` and `notes/` up to date as work happens. The
|
|
166
|
+
capability's **IMPORTANT** inject block makes this upkeep and eligible
|
|
167
|
+
checkpoint harvesting a duty; reading **okf-propose** is compulsory.
|
|
168
|
+
Neither duty depends on TASK.md. Run `oats okf status` from instance home
|
|
169
|
+
to learn the duty recorded at spawn: `on` means follow the skill, `off`
|
|
170
|
+
means no harvest, and `unknown` or an error means stop and report, never
|
|
171
|
+
infer permission or edit the record. Working instances never write
|
|
172
|
+
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.
|
|
180
|
+
|
|
181
|
+
Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
|
|
182
|
+
home: What (one claim per concept), Why, Evidence (observations, dates,
|
|
183
|
+
limits and accepted concepts cited), and optional `## Backing notes` with
|
|
184
|
+
one `- notes/<file>.md` entry per note. It has exactly one line
|
|
185
|
+
`Source: instance <name>, home <path>, soul <name>` naming the actual
|
|
186
|
+
source, a pointer to verify rather than authority. Claim only for owned
|
|
187
|
+
nodes; a lesson for a node the soul only reads is named in one line in its
|
|
188
|
+
hand-back for that node's owner.
|
|
189
|
+
|
|
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:
|
|
162
203
|
|
|
163
204
|
```sh
|
|
164
205
|
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
|
165
206
|
```
|
|
166
207
|
|
|
167
|
-
Never combine `--relation unrelated` with `--relative-to
|
|
208
|
+
Never combine `--relation unrelated` with `--relative-to`, or override
|
|
209
|
+
the kernel's harness/model selection. An unrelated harvester can outlive
|
|
210
|
+
its proposer; a child would tie their lifetimes together. There is no
|
|
168
211
|
automatic transcript capture, source registry, worker cursor or retire
|
|
169
|
-
harvest.
|
|
170
|
-
not stay alive
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
meanwhile goes into its next proposal; an instance that hands back with one
|
|
181
|
-
still listed names it and the claims still waiting. A harvester retained
|
|
182
|
-
after a publication failure stays listed, so it holds back its source's
|
|
183
|
-
later proposals: once that failure is dealt with, the operator retires it
|
|
184
|
-
(`oats retire <harvester>`).
|
|
212
|
+
harvest. Keep backing notes until the harvester retires; the proposer
|
|
213
|
+
itself need not stay alive. Its recorded retirement recovery can supply
|
|
214
|
+
evidence before capture, so do not dispose of it before capture.
|
|
215
|
+
Missing source authority never permits inventing it.
|
|
216
|
+
|
|
217
|
+
A refused or uncertain spawn is reported, not retried in a loop. If the
|
|
218
|
+
last harvester is still listed at hand-back, name it and the claims still
|
|
219
|
+
waiting; do not wait for it or spawn around it. A harvester retained after
|
|
220
|
+
a publication failure stays listed and holds back later proposals. Once
|
|
221
|
+
that failure is dealt with, the operator retires it (`oats retire
|
|
222
|
+
<harvester>`).
|
|
185
223
|
3. **Capture, judge and submit.** Before the model starts, the required spawn
|
|
186
224
|
hook checks the source's live record or the completed recovery named by
|
|
187
225
|
its public retirement event. Source identity, single-incarnation history,
|
|
@@ -227,7 +265,7 @@ is historical 4.x context, not instructions for operating 5.0.
|
|
|
227
265
|
|
|
228
266
|
Secrets, credentials, private paths and verbatim third-party messages are
|
|
229
267
|
left out. So is personal data, in the same sentence at every place an agent
|
|
230
|
-
is told what to leave out (the capturing instance, the
|
|
268
|
+
is told what to leave out (the capturing instance, the proposing skill, the
|
|
231
269
|
harvester when it edits and when it reads its diff, and the maintainer's
|
|
232
270
|
review):
|
|
233
271
|
|
|
@@ -264,13 +302,14 @@ this provider. See [Knowledge harvest and review](schedules.md#knowledge-harvest
|
|
|
264
302
|
|
|
265
303
|
| Capability | Composed into | Skills |
|
|
266
304
|
|---|---|---|
|
|
267
|
-
| `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), `knowledge-theory` |
|
|
305
|
+
| `oats.okf` | Working souls it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md), [`okf-propose`](../mirrors/oats-okf/skills/okf-propose/SKILL.md), `knowledge-theory` |
|
|
268
306
|
| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` |
|
|
269
307
|
| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) |
|
|
270
308
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
309
|
+
The capability's **IMPORTANT** inject block gives the duty and compulsory
|
|
310
|
+
pointer; **okf-propose** holds the procedure. These shared texts also reach
|
|
311
|
+
opted-out souls, with the explicit exception and provider status answer.
|
|
312
|
+
No source TASK brief contains harvest or proposal direction.
|
|
274
313
|
|
|
275
314
|
## Inspection and operator commands
|
|
276
315
|
|
|
@@ -304,6 +343,22 @@ are rooted in the base, never outside it. A failed fetch may serve cached
|
|
|
304
343
|
accepted bytes marked stale. `read` and `refresh` remain removed: use `cat`
|
|
305
344
|
and `index`. The consultation skill teaches navigation and citation.
|
|
306
345
|
|
|
346
|
+
### Read the harvest duty
|
|
347
|
+
|
|
348
|
+
```sh
|
|
349
|
+
oats okf status --json
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
The provider's answer is `result.harvest: "on"` with `reason: "default"`, or
|
|
353
|
+
`"off"` with `reason: "soul-opt-out"`. It reads only home-local spawn state,
|
|
354
|
+
not the network, bases, TASK.md or a soul file. Missing state is `"unknown"`
|
|
355
|
+
with `reason: "spawn-state-missing"`; malformed or linked state refuses.
|
|
356
|
+
Neither unknown nor failure permits a proposal. Report it and respawn with
|
|
357
|
+
the current provider; never hand-create a policy or reinterpret later
|
|
358
|
+
settings as the spawn decision. `--home PATH` selects an explicit home.
|
|
359
|
+
This answer is instruction state, not publication authority: the harvester
|
|
360
|
+
still independently checks its recorded source's opt-out.
|
|
361
|
+
|
|
307
362
|
### Inspect
|
|
308
363
|
|
|
309
364
|
```sh
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,8 +9,8 @@ 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.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
@@ -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.
|
|
32
|
+
`packages:` map (`oats.okf: v5.2.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.
|
|
47
|
+
oats.okf: v5.2.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.2.0`, `5.2.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.2.0` or `oats-framework/v1.12.0`) 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,8 +74,8 @@ 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.
|
|
77
|
+
oats.framework: v1.12.0
|
|
78
|
+
oats.okf: v5.2.0
|
|
79
79
|
oats.aweb: v1.27.3
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
@@ -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.2.0 ✓ (@ 2ac86ccb)
|
|
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
|
|
@@ -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.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.2.0",
|
|
164
|
+
"commit": "2ac86ccba6ea3da19acf43274dd6d30ab2037653",
|
|
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.
|
|
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.2.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "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.12.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# OATS 0.57.0
|
|
2
|
+
|
|
3
|
+
2026-10-15
|
|
4
|
+
|
|
5
|
+
## Upgrade
|
|
6
|
+
|
|
7
|
+
- **Install the Desktop first and the CLI second,** as
|
|
8
|
+
[Upgrading](../upgrading.md) says: a 0.56 Desktop refuses a 0.57.0 CLI. The
|
|
9
|
+
0.57.0 Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`.
|
|
10
|
+
|
|
11
|
+
- **A script that runs `oats worktree remove`** may now get
|
|
12
|
+
`E_CHILDREN_RUNNING`: the tree is the work of an attached instance whose
|
|
13
|
+
session is running or cannot be read. Nothing is removed, and no flag
|
|
14
|
+
removes anyway: stop that instance (`oats instance stop <instance>`) or
|
|
15
|
+
retire it, then remove again. **A script that attaches a spawn to a tree of
|
|
16
|
+
no known instance** gets one `E_BAD_ARGS` naming every flag still missing,
|
|
17
|
+
where it got a repository refusal and then `E_SPAWN_FAILED` on the retry.
|
|
18
|
+
See Changed ([#958](https://github.com/awebai/oats/issues/958),
|
|
19
|
+
[#964](https://github.com/awebai/oats/issues/964)).
|
|
20
|
+
|
|
21
|
+
- **A retire plan taken before the upgrade** is refused once by the 0.57.0
|
|
22
|
+
kernel with `E_PLAN_STALE` and the fresh plan: the plan's revision now also
|
|
23
|
+
binds the instances attached to each tree. Read the fresh plan and retire
|
|
24
|
+
with it. See Changed ([#964](https://github.com/awebai/oats/issues/964)).
|
|
25
|
+
|
|
26
|
+
- **On Linux and Windows the Desktop's palette is Ctrl+Shift+K,** and
|
|
27
|
+
Ctrl+Shift+P now opens Quick Open, from a focused terminal too. macOS keeps
|
|
28
|
+
⌘K and ⌘P. See Changed
|
|
29
|
+
([#1217](https://github.com/awebai/oats/issues/1217)).
|
|
30
|
+
|
|
31
|
+
- **To get the new provider versions,** pin `oats.framework: v1.10.2` and
|
|
32
|
+
`oats.okf: v5.2.0` in your workspace and run `oats sync`. Instances already
|
|
33
|
+
running keep what they were spawned with. See Provider updates.
|
|
34
|
+
|
|
35
|
+
- **Pin `oats.okf: v5.2.0` and run `oats sync`; only new spawns get the
|
|
36
|
+
capability-owned harvest duty.** Existing homes keep their copied provider
|
|
37
|
+
and instructions, including across session restarts. Deployments whose
|
|
38
|
+
task briefings never mentioned harvests now propose eligible knowledge at
|
|
39
|
+
finished tasks or PR hand-overs. Souls not ready for that must declare
|
|
40
|
+
`knowledge: { harvest: off }`; consultation and working-memory upkeep
|
|
41
|
+
remain. OATS >=0.49.0 is still required.
|
|
42
|
+
|
|
43
|
+
- **The official catalog's versions in this release** are oats.framework
|
|
44
|
+
1.10.2, oats.okf 5.2.0, oats.aweb 1.27.3, oats.engineering 1.10.0,
|
|
45
|
+
oats.cloning 1.0.1, oats.authoring 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1
|
|
46
|
+
and oats.apps 1.0.0.
|
|
47
|
+
|
|
48
|
+
## Added
|
|
49
|
+
|
|
50
|
+
- **`oats tui` stops, starts, restarts and retires an agent**
|
|
51
|
+
([#855](https://github.com/awebai/oats/issues/855)). With an instance
|
|
52
|
+
selected, `X` stops it, `D` retires it, `S` starts it and `R` restarts it,
|
|
53
|
+
each after a confirmation that opens with the focus on `Cancel`: the act
|
|
54
|
+
takes a move (`Left`/`Right` or `Tab`) and a press of `Enter`, and pasted
|
|
55
|
+
text never acts. The rules and the words are the Desktop's: a stop or a
|
|
56
|
+
retire shows the kernel's plan first and applies exactly that plan, on
|
|
57
|
+
this machine or on a registered one; a start or a restart uses the launch
|
|
58
|
+
recorded for the agent. An act you sent runs to its end whatever
|
|
59
|
+
`oats tui` does: closing the confirmation, quitting, a suspend or a signal
|
|
60
|
+
never ends it, and when you leave while one runs a line on standard error
|
|
61
|
+
says so. `tui.json` changes the keys (`stop`, `retire`, `start`,
|
|
62
|
+
`restart`). See [the TUI page](../tui.md#stopping-starting-restarting-and-retiring).
|
|
63
|
+
|
|
64
|
+
- **Desktop: each team has its own page, with your instances on it.** Click
|
|
65
|
+
a card under Workspace › Teams, or press Enter on its name, to open it. The
|
|
66
|
+
page shows the team's card at the top (its default, description, who may
|
|
67
|
+
join, address, problems and actions), then **Your instances on this team**:
|
|
68
|
+
how many there are, how many run, how many are stopped or need attention,
|
|
69
|
+
and on how many machines. Below that, each machine gets a card, with a
|
|
70
|
+
table of its instances: the name, the soul, the state, when it was created
|
|
71
|
+
and a Terminal button when it can be opened. A click on the name shows the
|
|
72
|
+
instance in the roster. The page lists only your instances, the ones on
|
|
73
|
+
this computer and on the machines you added to this workspace. Instances
|
|
74
|
+
other people run on the team are not listed. Back or Esc returns to the
|
|
75
|
+
board, on that team's card.
|
|
76
|
+
|
|
77
|
+
## Changed
|
|
78
|
+
|
|
79
|
+
- **The Desktop accepts OATS CLIs `>=0.26.0 <0.58.0`**
|
|
80
|
+
([#1211](https://github.com/awebai/oats/issues/1211)). The compatibility band
|
|
81
|
+
admits 0.57; a 0.56 Desktop refuses a 0.57 CLI. No new gate on the band.
|
|
82
|
+
`oats tui` runs the kernel it ships with and is held to the same band.
|
|
83
|
+
|
|
84
|
+
- **Desktop on Linux and Windows: the palette is Ctrl+Shift+K, and Quick Open
|
|
85
|
+
is Ctrl+Shift+P and works from a focused terminal**
|
|
86
|
+
([#1217](https://github.com/awebai/oats/issues/1217)). Quick Open was
|
|
87
|
+
Ctrl+P, which a focused terminal keeps for the program in it (shell
|
|
88
|
+
history), so it did not open from there. **Ctrl+Shift+P changes meaning:**
|
|
89
|
+
it has opened the palette since 0.30.3 and now opens Quick Open; the
|
|
90
|
+
palette moves to Ctrl+Shift+K. While the palette is open, Ctrl+Shift+K
|
|
91
|
+
moves down its rows and ArrowUp moves up. xterm sends nothing for either
|
|
92
|
+
chord, so plain Ctrl+K and Ctrl+P still reach the program. A shortcut you
|
|
93
|
+
set yourself is kept; when it is one of these two chords, the shortcuts
|
|
94
|
+
editor shows the clash. A Quick Open shortcut you set yourself now works
|
|
95
|
+
from a terminal too: if it is a plain Ctrl+letter, such as Ctrl+P, the
|
|
96
|
+
program no longer gets that key, so choose a Ctrl+Shift chord. macOS is
|
|
97
|
+
unchanged (⌘K, ⌘P). See
|
|
98
|
+
[Desktop keyboard](../../packages/desktop/docs/desktop-keyboard.md).
|
|
99
|
+
|
|
100
|
+
- **An attached spawn on an extra tree derives its owner and its repository
|
|
101
|
+
(#958).** `oats spawn <soul> --work attached --work-dir
|
|
102
|
+
<home>/.work-<purpose>` was refused twice: first for the repository
|
|
103
|
+
(`pass --repo`), then, with that given, for the owner (`--parent
|
|
104
|
+
<instance>`). For `<home>/work` the kernel derived both. An extra tree of
|
|
105
|
+
a home is that home's tree too, so the same command now spawns with
|
|
106
|
+
neither flag: the owner is the instance in whose home the tree is, the new
|
|
107
|
+
instance is its child, and its repository is the repository of the tree
|
|
108
|
+
it is attached to (for an extra tree the one Git names for it, which can
|
|
109
|
+
be another member repository than the owner's own). `--parent <owner>`
|
|
110
|
+
and `--repo` given explicitly still work, so a command that passes both
|
|
111
|
+
runs on this kernel and on earlier ones. The tree is an extra tree by the
|
|
112
|
+
kernel's own test (a registered linked worktree in a home), never by the
|
|
113
|
+
shape of its path. Nothing changes for `<home>/work`, and no flag, key or
|
|
114
|
+
field changes.
|
|
115
|
+
|
|
116
|
+
A tree of no known instance still needs both flags. Its refusal is now
|
|
117
|
+
one, `E_BAD_ARGS`, and names every flag still missing: `attached workDir
|
|
118
|
+
<path> is not a known instance's <home>/work or an extra tree of a known
|
|
119
|
+
instance's home (<home>/.work-<purpose>), so neither its owner nor its
|
|
120
|
+
repository is derived — pass both: --parent <instance> (the owning
|
|
121
|
+
instance) and --repo <repository>`. With one of the two given it names
|
|
122
|
+
the other. Before, the missing repository was refused first (`no
|
|
123
|
+
repository for a attached instance — pass --repo (the work tree's owner
|
|
124
|
+
records none)`), and the missing owner only on the retry, under the code
|
|
125
|
+
`E_SPAWN_FAILED`. See
|
|
126
|
+
[`attached`](../souls-and-instances.md#attached--another-instances-tree).
|
|
127
|
+
|
|
128
|
+
- **A tree that goes away says what it leaves its attached instances with
|
|
129
|
+
(#964).** An instance can be attached to an extra tree of its owner as to
|
|
130
|
+
the owner's `work/` (#958). Four things change for such a tree:
|
|
131
|
+
|
|
132
|
+
- **A retire that re-homes an extra tree repoints its attached children**
|
|
133
|
+
to the tree's new path, as it does for `work/`: only the recorded
|
|
134
|
+
children the retire stopped, only once the tree is seen at its new path
|
|
135
|
+
with nothing left at the old one, and only a link that is still the one
|
|
136
|
+
the retire found. One that cannot be repointed is a warning in the
|
|
137
|
+
receipt, with the command to do it by hand.
|
|
138
|
+
- **A retire that removes a tree names the attached children it leaves
|
|
139
|
+
without one.** A clean extra tree is removed, as before, and so is
|
|
140
|
+
`work/` with `--discard-worktree`. The plan's note for the tree now
|
|
141
|
+
names its attached children and says that their `work` link would then
|
|
142
|
+
point at a path that is gone, and the receipt's `warnings` (and the
|
|
143
|
+
summary) say so afterwards, naming each child, the tree and the link.
|
|
144
|
+
Before, the plan and the receipt said nothing of them.
|
|
145
|
+
- **An attached instance the retire does not act on is named too.** An
|
|
146
|
+
instance that records the owner as its parent under a name that is not
|
|
147
|
+
unique is listed under the plan's `ambiguous` and is never stopped, so
|
|
148
|
+
its link is not repointed either. The plan's note for the tree it is
|
|
149
|
+
attached to (an extra tree, or `work/`) now names it and says that its
|
|
150
|
+
`work` link would then point at a path that is gone, and the receipt's
|
|
151
|
+
`warnings` say so for each tree that was moved or removed, with the
|
|
152
|
+
command to repoint the link by hand where the tree was re-homed. A
|
|
153
|
+
`--self` retirement's receipt does not carry those warnings.
|
|
154
|
+
- **`oats worktree remove` refuses a tree under a running session.** When
|
|
155
|
+
an instance attached to the tree has a session that is running, or that
|
|
156
|
+
cannot be read, the command answers `E_CHILDREN_RUNNING` before Git is
|
|
157
|
+
asked anything: nothing is removed and the record is kept. `details` is
|
|
158
|
+
`{purpose, path, children: [{instance, home, session}]}`, `session` being
|
|
159
|
+
`"running"` or `"unknown"`. The message names each instance and the
|
|
160
|
+
step: stop it (`oats instance stop <instance>`) or retire it, then remove
|
|
161
|
+
again. The command stops nobody, and no flag removes the tree anyway. An
|
|
162
|
+
attached instance whose session is stopped does not refuse: the tree is
|
|
163
|
+
removed and the answer's `warnings` name the instance and its link.
|
|
164
|
+
|
|
165
|
+
The new sentences are strings in arrays the plan and the answers already
|
|
166
|
+
have (`notes`, `warnings`): no key, field or flag is new, and a tree with
|
|
167
|
+
no attached instance is handled as before. `E_CHILDREN_RUNNING` is the code
|
|
168
|
+
a retire already answers, there for a child it asked to stop and that did
|
|
169
|
+
not; `oats worktree remove` answers it with `details` of its own and no
|
|
170
|
+
`childrenStopped`. See
|
|
171
|
+
[extra trees at retire](../souls-and-instances.md#extra-trees-at-retire)
|
|
172
|
+
and [extra trees](../souls-and-instances.md#extra-trees).
|
|
173
|
+
|
|
174
|
+
- **Desktop: the Workspace › Setup tab reads as one column.** The List view
|
|
175
|
+
puts what the workspace shares through Git above what lives only on this
|
|
176
|
+
computer. It shows the same facts as before.
|
|
177
|
+
- **Under the workspace's name**, a summary counts the members (and those
|
|
178
|
+
that need attention), the packages and the state of the lock. The line
|
|
179
|
+
under it says where the workspace is declared, for example "Declared in
|
|
180
|
+
agents's oats-workspace.yaml at 1a2b3c4."
|
|
181
|
+
- **An Overview** says that the host repository defines the workspace: its
|
|
182
|
+
members and its packages. **For developers**, folded, explains the two
|
|
183
|
+
links that make a repository a member: the host's workspace file lists
|
|
184
|
+
it, and its membership file names the workspace back. It also says what
|
|
185
|
+
each member state means. The Graph view shows the Overview too. The
|
|
186
|
+
legend of badges is gone.
|
|
187
|
+
- **Shared through Git** holds Members, Packages and Defaults. Only the
|
|
188
|
+
host's row carries a tag, **Host** with its workspace file; the Member
|
|
189
|
+
tag is gone from every row. A confirmed member shows a check and
|
|
190
|
+
"confirmed". Any other state keeps its warning chip. In a wide enough
|
|
191
|
+
window every row takes one line.
|
|
192
|
+
- **This computer** holds the deployment's folder, settings, lock, lock
|
|
193
|
+
file, CLI, instances and disabled souls, then the member clones, then the
|
|
194
|
+
Machines box. Instances reads "3, 1 running". The Machines box no longer
|
|
195
|
+
carries a "Not shared" tag; the zone says it.
|
|
196
|
+
- **The Graph view** labels read "Shared through Git", "Members, latest"
|
|
197
|
+
and "Packages, pinned", in sentence case.
|
|
198
|
+
|
|
199
|
+
- **Desktop: the Teams board is one calm column.** Shared teams, local teams
|
|
200
|
+
and which teams each soul may join each have a heading and one line saying
|
|
201
|
+
what they are. A team's card no longer lists its instances: it shows the
|
|
202
|
+
team's facts in labelled rows (Default for, May join, Address), any
|
|
203
|
+
warning with its fix, and a summary line at the bottom ("3 of your
|
|
204
|
+
instances, 1 on other machines"). A click anywhere on the card opens the
|
|
205
|
+
team's page, and each card is one Tab stop. Which teams each soul may join
|
|
206
|
+
is now a table: the pattern, its default team, and the other teams it may
|
|
207
|
+
also join. The type is calmer: fewer sizes and styles, no uppercase labels,
|
|
208
|
+
and the facts that matter stand out by size and weight, not by new colours.
|
|
209
|
+
|
|
210
|
+
## Fixed
|
|
211
|
+
|
|
212
|
+
- **Released in 0.56.0, not noted there: the Desktop's terminals draw again
|
|
213
|
+
after a GPU process restart
|
|
214
|
+
([#1190](https://github.com/awebai/oats/issues/1190), #1192).** After the GPU
|
|
215
|
+
process restarted, xterm's shared glyph store went stale and terminals
|
|
216
|
+
stopped drawing. They now draw again. A 0.56.0 or later Desktop has the
|
|
217
|
+
fix.
|
|
218
|
+
|
|
219
|
+
- **A retire's recovery of a worktree carries a stopped cherry-pick, revert,
|
|
220
|
+
rebase or merge, and the stash, in both ref formats
|
|
221
|
+
([#1038](https://github.com/awebai/oats/issues/1038)).** The recovery
|
|
222
|
+
copied an operation's state as files of the Git directory. Three things
|
|
223
|
+
were missing from it, and nothing said so:
|
|
224
|
+
- where the repository stores its refs in the reftable format,
|
|
225
|
+
`CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD` and `AUTO_MERGE` are not
|
|
226
|
+
files. The recovery had none of them, and its `git status` no longer said
|
|
227
|
+
a cherry-pick or a revert was in progress. The stash's log is not a file
|
|
228
|
+
there either: the recovery's `git stash list` was empty;
|
|
229
|
+
- in both formats, the commit or tree those refs and `MERGE_HEAD` name is
|
|
230
|
+
often in no branch (a commit reset away, a conflict's tree). The recovery
|
|
231
|
+
named it without holding it, so `git cherry-pick --continue`, `git merge
|
|
232
|
+
--continue` or a diff against `AUTO_MERGE` failed there;
|
|
233
|
+
- a link at one of the copied names was left out when it led nowhere.
|
|
234
|
+
|
|
235
|
+
The recovery now writes those four refs through Git at the same ids and
|
|
236
|
+
holds every object they and `MERGE_HEAD` name. It stores the stash's
|
|
237
|
+
entries again, oldest first, with their messages, so `git stash list`
|
|
238
|
+
reads the same. A link is copied as the same link. A ref the source holds
|
|
239
|
+
in the reftable format without its object cannot be written, and refuses
|
|
240
|
+
the retire with `E_WORK_PRESERVATION_FAILED`, the home kept, as any
|
|
241
|
+
recovery that cannot be made does. Which homes a retire recovers, the
|
|
242
|
+
receipt and every code are unchanged.
|
|
243
|
+
|
|
244
|
+
## Provider updates
|
|
245
|
+
|
|
246
|
+
- **oats.okf 5.2.0:** the IMPORTANT inject block requires current instance
|
|
247
|
+
knowledge and compulsory reading of `okf-propose`. The skill holds the
|
|
248
|
+
bounded checkpoint procedure, promotion/search checks, proposal format and
|
|
249
|
+
memory/concurrency gates. No harvest or proposal direction remains in the
|
|
250
|
+
working instance's TASK brief. At most one proposal per completed task or
|
|
251
|
+
PR hand-over, one harvester per instance, and no spawn under memory pressure
|
|
252
|
+
or below 8 GB available; most checkpoints propose nothing. An unrelated
|
|
253
|
+
harvester can outlive its proposer. These limits are instructions, not a
|
|
254
|
+
scheduler or resource reservation.
|
|
255
|
+
- `oats okf status` exposes the duty written by the provider at spawn (`on`,
|
|
256
|
+
`off`, or missing-state `unknown`). An unknown answer or failure permits no
|
|
257
|
+
proposal. Shared inject/skill text explicitly exempts opted-out souls, and
|
|
258
|
+
the harvester independently refuses their recorded source material. No
|
|
259
|
+
kernel composition mechanism is added.
|
|
260
|
+
|
|
261
|
+
- **oats.framework 1.10.2: oats.core 2.6.1 and oats.setup 2.5.4.**
|
|
262
|
+
Instruction text in two skills; no hook, command, schema or provider
|
|
263
|
+
contract changes, and the capability floors are unchanged (oats.core
|
|
264
|
+
`>=0.40.0`, oats.setup `>=0.30.0`).
|
|
265
|
+
- `oats-operate` (oats.core) says that from OATS 0.57.0 `oats worktree
|
|
266
|
+
remove` refuses a tree that is the work of an attached instance whose
|
|
267
|
+
session is running or cannot be read (`E_CHILDREN_RUNNING`): stop that
|
|
268
|
+
instance or retire it, then remove again, as the entry under Changed
|
|
269
|
+
says ([#964](https://github.com/awebai/oats/issues/964)).
|
|
270
|
+
- `oats-onboarding` (oats.setup) pins `oats.okf: v5.2.0` in its knowledge
|
|
271
|
+
section and describes the harvest duty that oats.okf 5.2.0 gives every
|
|
272
|
+
working soul: the compulsory `okf-propose` skill, `oats okf status`, and
|
|
273
|
+
the soul's own opt-out, as the oats.okf entry says.
|
|
274
|
+
- A deployment gets it by pinning `oats.framework: v1.10.2` and running
|
|
275
|
+
`oats sync`. Instances already running keep the skills they were spawned
|
|
276
|
+
with; new spawns get the new ones.
|
|
277
|
+
|
|
278
|
+
## Documentation
|
|
279
|
+
|
|
280
|
+
- [Knowledge operations](../knowledge.md#the-flow) now describes the
|
|
281
|
+
capability-owned flow, opt-out/status answer, narrow checkpoints and
|
|
282
|
+
deferred hand-back. Catalog/workspace pins, package examples, mirrors and
|
|
283
|
+
clean-room composition assertions move together to 5.2.0.
|