@awebai/oats 0.69.22 → 0.69.24
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 +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +151 -17
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# OATS 0.69.24
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
The kernel can run an agent on a session backend a capability supplies, beside
|
|
6
|
+
tmux (session providers, experimental until the follow-up change). The Desktop
|
|
7
|
+
shows an agent's board around its terminal: its facts, and its questions
|
|
8
|
+
answered by number. OATS now refuses to start on Node.js older than 22.
|
|
9
|
+
oats.framework 1.28.0 and oats.aweb 1.47.0 are pinned.
|
|
10
|
+
|
|
11
|
+
## Upgrade
|
|
12
|
+
|
|
13
|
+
- **The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0**; oats.okf
|
|
14
|
+
stays 6.3.0. `oats sync` takes them. Existing homes take oats.core 2.16.0
|
|
15
|
+
(the `tui` default) through `oats instance upgrade` or a respawn.
|
|
16
|
+
- **A legacy oats.aweb grant seat** (one spawned with oats.aweb 1.12–1.24)
|
|
17
|
+
fills its `.oats-aweb/seat.json` once at its next start, from facts that
|
|
18
|
+
must agree; otherwise its start refuses with the respawn remedy. Such a
|
|
19
|
+
seat no longer follows a changed default team: respawn it to move it.
|
|
20
|
+
|
|
21
|
+
- **What users must do: move to Node.js 22.5 or later.** OATS now stops before
|
|
22
|
+
every command on Node below 22, including `version`, the reader and
|
|
23
|
+
capability commands. If you run OATS on Node 20 today, upgrade Node before continuing.
|
|
24
|
+
Node 18 and 20 receive `E_NODE_UNSUPPORTED` with exit 1, as one failure
|
|
25
|
+
envelope on stdout with `--json`, or a message on stderr without it. Remote
|
|
26
|
+
probes and Desktop discovery retain the host's refusal message. The npm
|
|
27
|
+
package retains its Node 22.5.0 floor so installation warns about it.
|
|
28
|
+
|
|
29
|
+
- **Respawn an instance of `oats-maintainer` or `oats-setup-admin` once**
|
|
30
|
+
after `oats sync`. An instance keeps the `okf.json` its spawn recorded, so
|
|
31
|
+
one started before this release still reads and proposes to its old node; a
|
|
32
|
+
new spawn reads the soul's subjects. The soul needs a knowledge base bound
|
|
33
|
+
with the subject layout: on a base that is not bridged, its spawn refuses
|
|
34
|
+
with `E_CONFIG` naming the base
|
|
35
|
+
([okf.json version 2](../knowledge.md#the-souls-okfjson)).
|
|
36
|
+
|
|
37
|
+
## Added
|
|
38
|
+
|
|
39
|
+
- **Doctor reports Git's cache support.** Text and JSON doctor output name
|
|
40
|
+
the Git version and whether it supports partial caches or uses the
|
|
41
|
+
whole-tree fallback. This uses the existing `information[]` field, adds no
|
|
42
|
+
warning and refuses nothing. Git 2.45 or later is recommended for partial
|
|
43
|
+
caches; an older Git works with whole-tree fetches.
|
|
44
|
+
|
|
45
|
+
- **The Desktop and the TUI show an agent that runs on a session provider
|
|
46
|
+
as OATS reports it.** A session provider is a session backend a capability
|
|
47
|
+
supplies, in place of tmux; this release's kernel reports them (session
|
|
48
|
+
providers, below), and no released provider exists yet. For such an agent:
|
|
49
|
+
- its state is the one OATS reports, and no client asks tmux about it;
|
|
50
|
+
- Start, Restart, Stop and Retire are offered by its state, as for any
|
|
51
|
+
agent;
|
|
52
|
+
- it shows as needing input whenever OATS reports that it waits on you
|
|
53
|
+
and it is not stopped, and the Desktop's Home lists it under Running
|
|
54
|
+
while it runs;
|
|
55
|
+
- there is no terminal to open. The clients say where it runs ("Runs in a
|
|
56
|
+
bb thread; open it in bb.") and show the link the provider offers: the
|
|
57
|
+
Desktop in the row's context menu, opened in your browser, and the TUI
|
|
58
|
+
printed under the line after `Enter`. Neither opens, splits or restores
|
|
59
|
+
a terminal tab for it;
|
|
60
|
+
- the row's tooltip in the Desktop names the backend and the provider's
|
|
61
|
+
thread id.
|
|
62
|
+
|
|
63
|
+
An agent in tmux, and one recorded on Herdr, read as before
|
|
64
|
+
([how the clients read `backend`](../desktop-cli-api.md#row-backend-clients)).
|
|
65
|
+
|
|
66
|
+
- **The agent view in the Desktop.** With an OATS that reports the agent's board (feature `instance-board`), an agent's terminal tab shows what the agent keeps in your view and what it asks you:
|
|
67
|
+
- **Facts** above the terminal: `label · value unit`, "updated <time>", at most three shown and the rest folded, a sparkline once the view has read the history, and links shown as attributed text: a press shows the whole address, and Open in browser opens it. In a short pane the facts give way so the terminal keeps its room. × or u hides a fact on this computer only, until its value changes.
|
|
68
|
+
- **Questions** under the terminal, one at a time, with "question n of N", ‹ › and the dots, and a context fold (c opens it from the keyboard).
|
|
69
|
+
- **Answering:** The questions and the facts are F6 regions (Ctrl+Shift+F6 from the terminal reaches the questions), and the palette's Agent: questions and facts (focus) moves through them; no chord takes Alt+T, Claude Code's extended thinking. A number puts `<id>: <option>` on the agent's input line, unsent, and your Enter in the terminal sends it. No bare digit is ever typed, and nothing is typed into a terminal that isn't on screen, or into one in its scrollback or one it can't check. A question's card stays until the agent clears it. On an agent on another machine the numbers are disabled and the zone says to type the answer in its terminal. While the agent's terminal shows a harness prompt (a live `permission` or `question` claim), the numbers are disabled and the zone says to answer the prompt there first.
|
|
70
|
+
|
|
71
|
+
Without the feature the terminal tab and its waiting row are as before.
|
|
72
|
+
|
|
73
|
+
- **Session providers: a capability can supply a session backend** (feature
|
|
74
|
+
`session-providers`). tmux stays the kernel's own backend and the default,
|
|
75
|
+
and tmux homes are unchanged. A capability declares `sessionProviders` in
|
|
76
|
+
its manifest, four of its own commands (`launch`, `inspect`, `input`,
|
|
77
|
+
`stop`, and optionally `inspectMany` and `check`), and `oats spawn <soul>
|
|
78
|
+
--backend <name>` (a schedule's `backend`, a trigger's `spawn.backend`)
|
|
79
|
+
runs the instance there. OATS keeps the home, the records, the lifecycle
|
|
80
|
+
and the answers.
|
|
81
|
+
- **The session-provider wire is experimental**: it is not stable until
|
|
82
|
+
the follow-up change (sandbox allowances and wire 1.3), and no released
|
|
83
|
+
provider speaks it.
|
|
84
|
+
- A provider home records `backend` and `session: {provider, endpoint}`.
|
|
85
|
+
Its status row carries `backend`, `session: {provider}` and `open` (a
|
|
86
|
+
link to show instead of a terminal), and on its own host the endpoint's
|
|
87
|
+
thread id; the endpoint is on its local inspect, spawn and start answers
|
|
88
|
+
only, and nothing of it is relayed to another machine. `oats inspect` and
|
|
89
|
+
`oats capabilities show` list `sessionProviders`.
|
|
90
|
+
- A spawn holds its new home's lifecycle claim while the provider
|
|
91
|
+
launches, and the home's receipt records that a launch was sent until
|
|
92
|
+
its outcome is recorded (`runtime.launchSent`): a spawn or a start
|
|
93
|
+
killed mid-launch leaves a home that reads as unknown, whose next stop,
|
|
94
|
+
start or retire first asks the provider to stop what it started.
|
|
95
|
+
- Each command of a provider runs in a process group of its own, ended
|
|
96
|
+
whole at its timeout. A `launch`, an `input` or a `stop` whose `oats`
|
|
97
|
+
command was killed is ended, with its group, by the next stop, start,
|
|
98
|
+
input or retire of the home, before the provider is called again: it
|
|
99
|
+
starts no session that OATS has no record of. A stop of a provider home
|
|
100
|
+
waits for an input that is being sent (up to its timeout) before it
|
|
101
|
+
asks the provider. A provider's command runs its helpers
|
|
102
|
+
inside that group.
|
|
103
|
+
- A stop made with OATS stays stopped: inspect answers stopped and every
|
|
104
|
+
input is refused `E_SESSION_NOT_RUNNING` until the home is started,
|
|
105
|
+
without asking the provider.
|
|
106
|
+
- Only a lost session is resumed, in its own conversation: one stopped by
|
|
107
|
+
`oats host run`'s shutdown, or one that is gone while OATS did not stop
|
|
108
|
+
it. `oats session resume` sends it one notice through the provider's
|
|
109
|
+
input, under a cap of 3 resumes of one home in an hour; any input to a
|
|
110
|
+
lost session counts as one.
|
|
111
|
+
- A provider's readiness (`check`) is asked right before every launch
|
|
112
|
+
(`E_BACKEND_NOT_READY`), and `oats readiness` relays it.
|
|
113
|
+
- New codes: `E_BACKEND_UNKNOWN`, `E_BACKEND_AMBIGUOUS`,
|
|
114
|
+
`E_BACKEND_HARNESS`, `E_BACKEND_LAUNCH_ARG`, `E_BACKEND_NOT_READY`,
|
|
115
|
+
`E_SESSION_NO_TERMINAL` (attach), `E_SESSION_PROMPT_OPEN` and
|
|
116
|
+
`E_SESSION_INPUT_QUEUED` (input).
|
|
117
|
+
- A routed `--backend <provider>` is sent only to a host that lists the
|
|
118
|
+
feature. A kernel without it that meets a provider home only refuses.
|
|
119
|
+
|
|
120
|
+
See [Session providers](../execution-targets.md#session-providers) and, for
|
|
121
|
+
a capability's author,
|
|
122
|
+
[Session providers (`sessionProviders`)](../capabilities.md#session-providers-sessionproviders).
|
|
123
|
+
- **A harness-package requirement can name its backends.** A `requires` row
|
|
124
|
+
of a capability manifest takes `backends: ["tmux"]`, `["session-provider"]`
|
|
125
|
+
or both; without it the row applies to every launch. A kernel without
|
|
126
|
+
`session-providers` applies such a row to every launch, so a package that
|
|
127
|
+
uses the key raises its OATS floor.
|
|
128
|
+
|
|
129
|
+
## Changed
|
|
130
|
+
|
|
131
|
+
- **Desktop: Home shows what needs you, and the Workspace page has its own row and a way back.**
|
|
132
|
+
([Workspaces](../desktop.md#workspaces))
|
|
133
|
+
- **Home is one centred column.** **Needs you** comes first: each agent waiting on you, with its
|
|
134
|
+
soul, its machine and its message, newest first. Eight show at most, then **Show all N**. With
|
|
135
|
+
none, "Nothing needs you."
|
|
136
|
+
- **One summary line** counts the rest: "24 agents · 21 running · 3 need you · 0 stopped".
|
|
137
|
+
- **The workspace is one row of tiles**, each a button with its count: Agents, Souls,
|
|
138
|
+
Capabilities, Teams, Machines and Automations (with the red dot while a run failed). They show
|
|
139
|
+
without scrolling, even with eight agents waiting on you. The Graph tile is gone; Machines keeps
|
|
140
|
+
its List and Map.
|
|
141
|
+
- **Running**, under the tiles, shows five running agents, then **Show all N running**. No row
|
|
142
|
+
says "running" any more: the heading does.
|
|
143
|
+
- **The sidebar's pinned rows are Home, Workspace and Automations.** Opening any Workspace page
|
|
144
|
+
(from a tile, the command palette, ⌘2 / Ctrl+2, or a soul's or capability's page) marks the
|
|
145
|
+
Workspace row, no longer Home's. Its palette command is now **View: Workspace**.
|
|
146
|
+
- **Every Workspace page says where you are, and the way back:** **Home › Workspace › Souls**
|
|
147
|
+
above the tabs, and **Home › Workspace › Souls › dev** on a soul's page, each part a link. Esc
|
|
148
|
+
goes up one level: twice from a soul's page reaches Home.
|
|
149
|
+
- **Capabilities shows the Workspace defaults again**, above the list: the Core slots (Knowledge,
|
|
150
|
+
Messaging, Tasks) and the Additional defaults, each as the list's own row.
|
|
151
|
+
- **Soul cards read more clearly:** the name larger and bolder, what the soul does in muted body
|
|
152
|
+
text, its agents and kind on a smaller line.
|
|
153
|
+
|
|
154
|
+
- **Desktop: the Workspace pages look like the prototype.** ([Capabilities and spawning](../desktop.md#capabilities-and-spawning))
|
|
155
|
+
- **The Dark theme takes Tokyo Night's blues and greys** in the window: backgrounds, raised surfaces, ink, the blue
|
|
156
|
+
accent, green, amber and red. Every text colour still meets WCAG AA; the terminals keep their own colours, and their
|
|
157
|
+
cells their size. Light and Solarized keep their colours.
|
|
158
|
+
- **Souls**: **Grid** | **Table** sits beside the page's title. The first line counts the souls and those with
|
|
159
|
+
agents running ("You have 10 souls, 4 with agents running, …"). Group headings are small capitals with their count.
|
|
160
|
+
The grid has three columns at most; a card is a calmer tile, its name in semibold, what it does on two lines, then
|
|
161
|
+
one meta line, and a refused spawn says so in one quiet line.
|
|
162
|
+
- **Capabilities**: a first line says what a capability is, how many there are and how many are official, and what
|
|
163
|
+
✓, **core** and **default** mean. The rows sit on the page with a thin rule under each, the ✓ or **by** right after
|
|
164
|
+
the name, **core** and **default** as small pills. **Workspace defaults** stays above **All capabilities**, styled the
|
|
165
|
+
same way.
|
|
166
|
+
- **A soul's page and a capability's page** use the same type and spacing: a smaller title, section titles in small
|
|
167
|
+
capitals, the capability and skill rows as Capabilities' rows, quieter tabs and folds.
|
|
168
|
+
- **The status line shows the page's keys** on these pages: "↑↓ move · Enter open · v table · Esc Home" on Souls,
|
|
169
|
+
and "Esc back" on a soul's or a capability's page.
|
|
170
|
+
|
|
171
|
+
- **oats.framework 1.28.0** (`oats.core` 2.16.0, `oats.coordination-setup`
|
|
172
|
+
1.1.1, `oats.knowledge-theory` 1.1.3, `oats.onboarding` 1.3.1, `oats.setup`
|
|
173
|
+
2.16.2).
|
|
174
|
+
- `oats.core` adds `tui: "default"` to an agent's Claude settings when the
|
|
175
|
+
key is absent, so Claude's fullscreen-renderer offer no longer takes a
|
|
176
|
+
wake; a value already there stays (#1692). `/oats-operate` names the Node
|
|
177
|
+
floor and doctor's `git-version:` line, from OATS 0.69.24.
|
|
178
|
+
- `oats.coordination-setup` and `oats.onboarding` teach related work: a
|
|
179
|
+
lead's children and its sibling leads, with `--related-work` from OATS
|
|
180
|
+
0.69.23 (#2022).
|
|
181
|
+
- `oats.knowledge-theory`'s proposal reference names `oats.okf` 6.3's
|
|
182
|
+
division of work as an option (#2030).
|
|
183
|
+
- `oats.setup`'s `oats-agent-permissions` skill explains why launch
|
|
184
|
+
`args` are refused where a capability requires a harness package, and
|
|
185
|
+
how to choose auto mode through the launch configuration's `env` (#1692).
|
|
186
|
+
- Guidance text, plus the one `tui` default. Nothing changes for a
|
|
187
|
+
deployment beyond `oats sync` taking the new tag; existing homes take
|
|
188
|
+
oats.core 2.16.0 through `oats instance upgrade` or a new spawn.
|
|
189
|
+
|
|
190
|
+
- **The framework's coordination guidance teaches related work.**
|
|
191
|
+
`oats.coordination-setup`'s `/coordination-best-practices` and
|
|
192
|
+
`/adapt-to-the-organisation`, and `oats.onboarding`'s
|
|
193
|
+
`/oats-tailor-workspace`, say that a lead's children are spawned with
|
|
194
|
+
related work, and that a lead for a related effort, the first lead's
|
|
195
|
+
sibling, gets it too. The flag is `--related-work` from OATS 0.69.23 and
|
|
196
|
+
`--same-work` before, which binds a child only. Guidance text only: no
|
|
197
|
+
floor moves. See [Related work](../desktop-cli-api.md#related-work-oats-instance-related-work).
|
|
198
|
+
|
|
199
|
+
- **`oats-maintainer` and `oats-setup-admin` read by subject** (`okf.json`
|
|
200
|
+
version 2). The maintainer's subjects are `workstream/oats-direction`,
|
|
201
|
+
`workstream/coordination`, `system/oats-kernel`, `system/oats-desktop`,
|
|
202
|
+
`workstream/provider-integration`, `workstream/operations`,
|
|
203
|
+
`workstream/positioning` and `workstream/workspace-administration`: the
|
|
204
|
+
subjects that absorb the nodes it owned and read. The setup admin's are
|
|
205
|
+
`workstream/workspace-administration`, `workstream/operations`,
|
|
206
|
+
`workstream/oats-direction`, `workstream/coordination` and
|
|
207
|
+
`system/oats-kernel`. Their texts say each proposed claim names the subjects
|
|
208
|
+
it is about.
|
|
209
|
+
|
|
210
|
+
- **OATS's own coordination capabilities teach related work.** The
|
|
211
|
+
engineering expert's, the build and the maintainer's skills spawn with
|
|
212
|
+
`--related-work` where they passed `--same-work`. A lead's children
|
|
213
|
+
(specialists, helpers, probes, developers and reviewers) get it, as before,
|
|
214
|
+
and now so does a sibling lead started for an effort that arises from the
|
|
215
|
+
lead's own (`--relation sibling --relative-to <lead> --related-work`). An
|
|
216
|
+
independent lead, and a lead a maintainer launches, still don't. The kernel
|
|
217
|
+
and its injects set no default. An OATS before 0.69.23 refuses
|
|
218
|
+
`--related-work`: hosts that run these capabilities need 0.69.23 or later.
|
|
219
|
+
See [Related work](../desktop-cli-api.md#related-work-oats-instance-related-work).
|
|
220
|
+
|
|
221
|
+
- **Capability hooks get `OATS_BACKEND`.** Every spawn hook and launch hook
|
|
222
|
+
is given the session backend the instance launches on: `tmux`, or a session
|
|
223
|
+
provider's name.
|
|
224
|
+
- **A tmux home's row of `oats status --json` carries `backend: "tmux"`.** A
|
|
225
|
+
row with no `backend` key comes from a kernel without `session-providers`,
|
|
226
|
+
and reads as a tmux home's.
|
|
227
|
+
|
|
228
|
+
## Fixed
|
|
229
|
+
|
|
230
|
+
- **Claude agent panes skip the fullscreen-renderer offer.** At spawn and
|
|
231
|
+
every launch, oats.core 2.16.0 adds `"tui": "default"` to a Claude home's
|
|
232
|
+
`.claude/settings.json` if no `tui` key is present. Any existing value is
|
|
233
|
+
kept. Agent panes use Claude's classic renderer even where Claude now
|
|
234
|
+
defaults to fullscreen, and even over a user-level `"tui": "fullscreen"`;
|
|
235
|
+
this keeps tmux scrollback and the renderer used by the launch-prompt
|
|
236
|
+
captures. An existing project `tui` still wins. If oats.core stops adding
|
|
237
|
+
the key, existing homes keep it until respawn. See
|
|
238
|
+
[oats.core](../capabilities.md#oatscore-needs-input).
|
|
239
|
+
|
|
240
|
+
## Documentation
|
|
241
|
+
|
|
242
|
+
- **Launch args guidance matches the package-probe refusal.** Any non-empty
|
|
243
|
+
launch-configuration `args` is refused at spawn with
|
|
244
|
+
`E_LAUNCH_PROBE_UNSUPPORTED` while an active capability requires a package
|
|
245
|
+
for that harness; with oats.aweb, every Claude launch has such a requirement.
|
|
246
|
+
`claude plugin list --json` cannot carry those args, and `--settings` can
|
|
247
|
+
change which plugins load. The supported routes are user `settings.json`
|
|
248
|
+
in the Claude config selected by `CLAUDE_CONFIG_DIR` through `env`, which
|
|
249
|
+
the probe carries, or a wrapper executable. `/oats-agent-permissions` now
|
|
250
|
+
teaches `permissions.defaultMode: "auto"` in that user file, replacing its
|
|
251
|
+
launch-args advice. See [launch configurations](../configuration.md#launch-configurations).
|
|
252
|
+
|
|
253
|
+
- **Knowledge proposals as oats.okf 6.3 runs them.** The
|
|
254
|
+
[operator guide](../knowledge.md#the-flow) still said a claim
|
|
255
|
+
goes only in the soul's owned nodes, that the proposer settles duplicates
|
|
256
|
+
before proposing, and that the write surface is enforced. With 6.3 a quick
|
|
257
|
+
search is enough, duplicates, the canonical home and the subject are the
|
|
258
|
+
knowledge maintainer's, and a path outside the write surface is a `W_*`
|
|
259
|
+
warning under `## Check warnings` in the PR body, which the maintainer
|
|
260
|
+
resolves before merging. The authors' guide's
|
|
261
|
+
[judgment and proposal](../knowledge-reference/proposal.md#judgment-procedure)
|
|
262
|
+
page now says a capability may divide the work that way; the exclusions and
|
|
263
|
+
the screen before delivery stay with the proposer. The
|
|
264
|
+
`oats.knowledge-theory` copy changes with it.
|
package/docs/servers.md
CHANGED
|
@@ -462,7 +462,7 @@ schedule's spec still travel as arguments.
|
|
|
462
462
|
|
|
463
463
|
| Command | Where it runs | The server must advertise |
|
|
464
464
|
|---|---|---|
|
|
465
|
-
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-
|
|
465
|
+
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-related-work` for `--related-work`, or `instance-same-work` alone (an older OATS), which is sent `--same-work` for a parent binding and refuses a sibling one with `E_REMOTE_INCOMPATIBLE`, the binding read from the spawn's arguments and the host's roster |
|
|
466
466
|
| `status` | registered workspace | |
|
|
467
467
|
| `retire` | the instance's home | `retire-home` to retire by exact home |
|
|
468
468
|
| `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
|
|
@@ -479,7 +479,7 @@ schedule's spec still travel as arguments.
|
|
|
479
479
|
| `instance color` | the instance's home | `instance-color` |
|
|
480
480
|
| `instance background` | the instance's home | `instance-background` |
|
|
481
481
|
| `instance pin` | the instance's home | `instance-pin` |
|
|
482
|
-
| `instance
|
|
482
|
+
| `instance related-work` | the instance's home | `instance-related-work`; a host with only `instance-same-work` (an older OATS) is asked `instance same-work` for an instance bound to its parent, and `on` for one bound to its sibling is `E_REMOTE_INCOMPATIBLE` there |
|
|
483
483
|
|
|
484
484
|
`instance suggest-name` and `instance upgrade` are never routed: `--server` is
|
|
485
485
|
`E_BAD_ARGS`. `instance suggest-name` names a spawn on the machine that asks,
|
|
@@ -646,10 +646,14 @@ carries `waitingOnYou` (needs input) when the host's kernel reports it, and
|
|
|
646
646
|
only then: an older host's row has no such key. `retire` (0.59.0, a retire
|
|
647
647
|
of the home running, unknown, failed or interrupted) is relayed the same
|
|
648
648
|
way, through the kernel's own read of it, and a value that read refuses is
|
|
649
|
-
dropped ([`retire`](desktop-cli-api.md#row-retire)). `
|
|
650
|
-
`instance-
|
|
651
|
-
relayed only when the host's row has `
|
|
652
|
-
otherwise
|
|
649
|
+
dropped ([`retire`](desktop-cli-api.md#row-retire)). `relatedWork` (feature
|
|
650
|
+
`instance-related-work`, the instance does related work with its parent, or
|
|
651
|
+
with its sibling) is relayed only when the host's row has `relatedWork:
|
|
652
|
+
true`, and is absent otherwise. From a host whose features list
|
|
653
|
+
`instance-same-work` and not `instance-related-work` (an older OATS), its
|
|
654
|
+
row's `sameWork: true` is relayed as `relatedWork: true`. `sameWork: true`
|
|
655
|
+
is relayed beside `relatedWork: true` for a parent binding, and never alone
|
|
656
|
+
([`relatedWork`](desktop-cli-api.md#row-related-work)). `pinned` (feature
|
|
653
657
|
`instance-pin`, the instance is pinned at the top of its machine's list) is
|
|
654
658
|
relayed only when the host's row has exactly `pinned: true`, and is absent
|
|
655
659
|
otherwise ([`pinned`](desktop-cli-api.md#row-pinned)). A removed or edited registration keeps
|
|
@@ -459,29 +459,46 @@ extra trees: see [`attached`](#attached--another-instances-tree)),
|
|
|
459
459
|
because an attached agent serves that owner; relation flags other than a
|
|
460
460
|
redundant child-of-owner are rejected.
|
|
461
461
|
|
|
462
|
-
`--
|
|
463
|
-
does
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
462
|
+
`--related-work` (feature `instance-related-work`) records that the new
|
|
463
|
+
instance does related work with its parent, or, when it has no parent, with
|
|
464
|
+
its sibling; clients draw the line between the two for an instance that
|
|
465
|
+
carries it. The kernel never sets it on its own. It is bound to the parent
|
|
466
|
+
the new home records, whichever relation gave it: a child, a sibling of an
|
|
467
|
+
anchor that has a parent, a `parent` relation whose anchor had a parent (the
|
|
468
|
+
new instance inherits it), or an attached spawn (the owner). With no parent
|
|
469
|
+
it is bound to the sibling the new home records: a sibling of an anchor with
|
|
470
|
+
no parent binds that anchor, and a `parent` relation over an anchor with a
|
|
471
|
+
sibling link and no parent binds the sibling it inherits. The sibling is the
|
|
472
|
+
one the home records, the anchor it was spawned beside: a sibling of a
|
|
473
|
+
top-level R binds R, and a sibling of R's sibling S binds S, not R. A spawn
|
|
474
|
+
that would record neither (unrelated, a `parent` relation over a top-level
|
|
475
|
+
anchor with no sibling link) is refused with `E_BAD_ARGS` before anything is
|
|
476
|
+
created, a preview included. The flag is the home's own file,
|
|
477
|
+
`.oats-related-work.json`, naming the parent or the sibling it was set
|
|
478
|
+
against. A parent binding is on only while that is still the home's
|
|
479
|
+
recorded `parentInstance`, and a sibling binding only while the home records
|
|
480
|
+
no parent and that sibling is still its `siblingInstance`: after a relink (a
|
|
481
|
+
retire's lineage splice, or a `parent` spawn re-pointing its anchor) it
|
|
482
|
+
reads off. It survives a restart, a stop and a start, a resume and `oats
|
|
483
|
+
instance upgrade`; only `off` or retirement clears it.
|
|
484
|
+
|
|
485
|
+
`oats instance related-work <instance> on|off` sets or clears the flag on an
|
|
478
486
|
existing instance, addressed as `oats instance color` addresses it and routed
|
|
479
|
-
with `--server`. `on` needs a recorded parent and binds the flag
|
|
480
|
-
current one, so it also rebinds after a
|
|
481
|
-
instance with the flag on carries `
|
|
482
|
-
--json` row
|
|
483
|
-
|
|
484
|
-
|
|
487
|
+
with `--server`. `on` needs a recorded parent or sibling and binds the flag
|
|
488
|
+
to the current one, so it also rebinds after a relink; `off` always
|
|
489
|
+
succeeds. An instance with the flag on carries `relatedWork: true` on its
|
|
490
|
+
`oats status --json` row, and `sameWork: true` beside it when the flag is
|
|
491
|
+
bound to its parent; otherwise the keys are absent.
|
|
492
|
+
|
|
493
|
+
The flag was the same-work flag (`--same-work`, `oats instance same-work`,
|
|
494
|
+
`.oats-same-work.json`, a parent binding only). The old spellings are
|
|
495
|
+
deprecated aliases of the new ones: they work the same, by the same binding
|
|
496
|
+
rule, and each use prints one line on stderr naming the new spelling, never
|
|
497
|
+
in `--json` output. Move skills and scripts to `--related-work` once their
|
|
498
|
+
hosts run an OATS that has it. An old `.oats-same-work.json` still reads as
|
|
499
|
+
a parent binding until the new record is written, which removes it; `off`
|
|
500
|
+
removes both. The answer, the errors and the remote relay are in
|
|
501
|
+
[desktop-cli-api.md](desktop-cli-api.md#related-work-oats-instance-related-work).
|
|
485
502
|
|
|
486
503
|
`oats instance pin <instance> on|off` (feature `instance-pin`) pins an
|
|
487
504
|
instance at the top of its machine's list, or removes the pin, addressed as
|
|
@@ -494,6 +511,18 @@ retire removes it with the home. No spawn flag or `soul.yaml` key sets it.
|
|
|
494
511
|
The answer and the errors are in
|
|
495
512
|
[desktop-cli-api.md](desktop-cli-api.md#pinned-instances-oats-instance-pin).
|
|
496
513
|
|
|
514
|
+
`oats instance board` (feature `instance-board`) is the agent's board, written
|
|
515
|
+
by the agent from its own session, like `oats instance attention`. `board set
|
|
516
|
+
<key> --label <text> --value <text>` keeps a fact in its person's view (`board
|
|
517
|
+
unset <key>` removes it), and `board ask <question> --option <text> --option
|
|
518
|
+
<text>` asks them a question with 2 to 4 options, which it closes with `board
|
|
519
|
+
ask --clear <id>` once it has read the answer. The answer arrives typed in its
|
|
520
|
+
terminal as `<id>: <text>`. Facts last as long as the home; a question belongs
|
|
521
|
+
to the session it was asked in. Clients read the board from the `board` on the
|
|
522
|
+
instance's `oats status --json` row. Its bounds, the claim it holds while a
|
|
523
|
+
question is open and the errors are in
|
|
524
|
+
[desktop-cli-api.md](desktop-cli-api.md#the-agents-board-oats-instance-board).
|
|
525
|
+
|
|
497
526
|
`spawnOrigin` records the caller independently of these links. For new spawns
|
|
498
527
|
from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
|
|
499
528
|
`OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
|
|
@@ -1521,6 +1550,51 @@ still name the old path. A child attached to one of the home's extra trees
|
|
|
1521
1550
|
is handled the same way, tree by tree
|
|
1522
1551
|
([extra trees at retire](#extra-trees-at-retire)).
|
|
1523
1552
|
|
|
1553
|
+
#### Retiring a home on a session provider
|
|
1554
|
+
|
|
1555
|
+
A home whose session runs on a
|
|
1556
|
+
[session provider](execution-targets.md#session-providers) (its
|
|
1557
|
+
`instance.json` records `backend` and `session`) is retired by a kernel that
|
|
1558
|
+
lists the feature `session-providers`, in this order:
|
|
1559
|
+
|
|
1560
|
+
1. **The stop is recorded** (`stoppedAt` in the home's receipt): from then on
|
|
1561
|
+
inspect answers stopped and every input to the home is refused
|
|
1562
|
+
`E_SESSION_NOT_RUNNING`, so nothing restarts its session.
|
|
1563
|
+
2. **Inputs that were being sent are waited for.** An input already on its
|
|
1564
|
+
way when the stop was recorded can have the provider restart the session,
|
|
1565
|
+
and once the home is gone nothing could stop it. The retire waits for
|
|
1566
|
+
those inputs to end (at most an input's timeout and 5 s). An input still
|
|
1567
|
+
being sent after that does not hold the retire: its provider command is
|
|
1568
|
+
ended, and the retire goes on, with a warning that names that input's
|
|
1569
|
+
process. An input whose `oats` command was killed is not waited for: its
|
|
1570
|
+
provider command is ended at once. (Every stop of a provider home waits
|
|
1571
|
+
so, a plain `oats instance stop` too.)
|
|
1572
|
+
3. **The provider is asked to stop the session**, with the usual grace,
|
|
1573
|
+
never escalated. A launch that was sent and never recorded (a command
|
|
1574
|
+
killed while it launched) is settled the same way: the provider is asked
|
|
1575
|
+
to stop whatever it runs for the home.
|
|
1576
|
+
4. **No process may work in the home**, whatever the provider answered: a
|
|
1577
|
+
stop it confirms can still leave one behind (a harness that outlives its
|
|
1578
|
+
server for a while), and there is no window whose absence would say
|
|
1579
|
+
otherwise. With a process working in the home, or when that cannot be
|
|
1580
|
+
told, the retire refuses `E_RUNTIME_QUIESCE_FAILED` at once, names the
|
|
1581
|
+
processes and keeps the home; its stop stays recorded. A shell whose
|
|
1582
|
+
working directory is in the home counts too, and one named in the
|
|
1583
|
+
refusal may be your own: leaving the home's directory clears it.
|
|
1584
|
+
5. The retire hooks run (the provider's own archives its session there), the
|
|
1585
|
+
work is preserved as for any home, and the home is removed.
|
|
1586
|
+
|
|
1587
|
+
**When the provider cannot confirm the stop** (it fails, it does not answer,
|
|
1588
|
+
or its capability is no longer among the home's modules after an upgrade),
|
|
1589
|
+
the retire does not strand the home. It goes on when step 4 finds no
|
|
1590
|
+
process in the home, and its answer then carries a warning that the session
|
|
1591
|
+
was not stopped through its backend: archive or remove that session with the
|
|
1592
|
+
provider's own tooling.
|
|
1593
|
+
|
|
1594
|
+
A retire's plan (`oats retire <instance> --plan`) reads the session through
|
|
1595
|
+
the provider, as `oats session inspect` does. A kernel without the feature
|
|
1596
|
+
refuses to retire such a home (`E_RUNTIME_ENDPOINT_UNKNOWN`) and keeps it.
|
|
1597
|
+
|
|
1524
1598
|
#### What `work/` is at retire
|
|
1525
1599
|
|
|
1526
1600
|
The retire and its plan read what is at `<home>/work` once, by one rule
|
package/docs/tui.md
CHANGED
|
@@ -180,7 +180,7 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
180
180
|
group's top instance, so starting or stopping an instance moves nothing. An instance
|
|
181
181
|
that others were spawned from has them indented under it, and keeps its
|
|
182
182
|
place when it gains or loses one. Under one parent, the instances that do
|
|
183
|
-
its work (the kernel's `
|
|
183
|
+
its work (the kernel's `relatedWork`, from an OATS with `instance-related-work`)
|
|
184
184
|
come first, then the others, each part newest first, as the Desktop lists
|
|
185
185
|
them. Pinned instances come before all of these, at every level, and an
|
|
186
186
|
instance with a pinned one below it counts as pinned
|
|
@@ -267,6 +267,25 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
267
267
|
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
268
268
|
beside the sidebar, where the detail was, as a tab: see
|
|
269
269
|
[Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
|
|
270
|
+
- **An agent that runs on a session provider** (a capability's session
|
|
271
|
+
backend, such as bb) has no terminal. The list shows it in the state OATS
|
|
272
|
+
reports (the detail says `running` or `stopped` when OATS says which, else
|
|
273
|
+
the provider's own word), and `S`, `R`, `X` and `D` act on it as on any agent. `Enter` opens
|
|
274
|
+
nothing: the line says where it runs ("Runs in a bb thread; open it in
|
|
275
|
+
bb.") and, when the provider offers a link, prints it under that
|
|
276
|
+
(`"Open in bb: http://…"`) for you to open. The palette does not
|
|
277
|
+
list it among the agents to open, the agent steps pass over it, and a
|
|
278
|
+
workspace's remembered tabs never open it. Its `!` mark shows whenever
|
|
279
|
+
OATS reports that it waits on you and it is not stopped
|
|
280
|
+
([how the clients read `backend`](desktop-cli-api.md#row-backend-clients)).
|
|
281
|
+
Start the TUI outside an agent's home: OATS refuses to retire a home while
|
|
282
|
+
a process works in it, the TUI's own included, and names that process.
|
|
283
|
+
A known limit: when another machine's agent moves to a session provider
|
|
284
|
+
while the TUI is opening it, a check of its terminal that fails says
|
|
285
|
+
OATS's failure ("The session is no longer running on …") and not where
|
|
286
|
+
it runs, and an agent OATS holds by then (a retire that began) may have a
|
|
287
|
+
viewer started for it, which OATS refuses (`E_SESSION_NO_TERMINAL`).
|
|
288
|
+
Neither reaches another agent.
|
|
270
289
|
|
|
271
290
|
**A view of more than one deployment** (this machine and another, or two
|
|
272
291
|
deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
@@ -704,7 +723,8 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
704
723
|
as the workspace was left. The shown tab is the most recent for
|
|
705
724
|
[the palette](#the-palette).
|
|
706
725
|
- A tab whose instance is gone or cannot be opened now (retired,
|
|
707
|
-
stopped
|
|
726
|
+
stopped, or now running on a session provider, which has no terminal)
|
|
727
|
+
is dropped, and nothing is said of it. A group the drops
|
|
708
728
|
leave with no tab goes, as when its last tab is closed; a group that
|
|
709
729
|
was empty when the workspace was left is empty again. A shown tab
|
|
710
730
|
dropped gives its place to the next, else the one before.
|
|
@@ -1895,8 +1915,9 @@ open, `Alt+Shift+Up` and `Alt+Shift+Down` move between its groups instead
|
|
|
1895
1915
|
([The palette](#the-palette)).
|
|
1896
1916
|
|
|
1897
1917
|
`CHORDS` also holds the Desktop's `edit-instance` (`Alt+R`, its name and
|
|
1898
|
-
colour dialog)
|
|
1899
|
-
`Alt+R`
|
|
1918
|
+
colour dialog) and `mail` (`Alt+M`, its read-only mail sheet). The TUI has no
|
|
1919
|
+
such actions, so it binds no keys for them and `Alt+R` and `Alt+M` stay the
|
|
1920
|
+
agent's.
|
|
1900
1921
|
|
|
1901
1922
|
There are three families, one choice per user for both clients
|
|
1902
1923
|
([Switch family](#switch-family)):
|
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ 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.24** ([release notes](release-notes/v0.69.24.md)).
|
|
10
|
+
The 0.69.24 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.69.
|
|
14
|
+
0.69.24,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.69.
|
|
24
|
-
npm install -g @awebai/oats@0.69.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.69.24, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.69.24 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,20 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
|
|
221
|
+
or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
|
|
222
|
+
The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0. Respawn an
|
|
223
|
+
instance of `oats-maintainer` or `oats-setup-admin` once (okf.json version
|
|
224
|
+
2), and respawn or move other instances with `oats instance upgrade` to take
|
|
225
|
+
oats.core 2.16.0. A legacy oats.aweb grant seat (1.12–1.24) fills its seat
|
|
226
|
+
record at its next start, or refuses with the respawn remedy.
|
|
227
|
+
- **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
|
|
228
|
+
oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
|
|
229
|
+
instances, or move stopped ones with `oats instance upgrade`, to take the
|
|
230
|
+
board teaching and the mail read. `--same-work` and `oats instance
|
|
231
|
+
same-work` are deprecated aliases of `--related-work` and `oats instance
|
|
232
|
+
related-work`. A team image that ran the experimental
|
|
233
|
+
bb image is rebuilt, with the bb image from oats-project/oats-bb.
|
|
220
234
|
- **[0.69.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
|
|
221
235
|
oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
|
|
222
236
|
The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
|
package/docs/workspaces.md
CHANGED
|
@@ -54,15 +54,15 @@ 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: v6.
|
|
57
|
+
oats.framework: v1.28.0 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v6.3.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
|
|
62
62
|
engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
|
|
63
63
|
reviewers: { description: Code review } # declared, not created yet (no `team` id): readiness team-unmapped
|
|
64
64
|
defaultTeam: engineering # the workspace's default team; see Teams below
|
|
65
|
-
souls: #
|
|
65
|
+
souls: # each soul's team: its default, and the others it may join
|
|
66
66
|
platform/*: { teams: [reviewers] }
|
|
67
67
|
|
|
68
68
|
defaults:
|
|
@@ -541,13 +541,21 @@ teams: # SHARED teams: the same provider team
|
|
|
541
541
|
docs: { description: Docs rota } # declared, not created yet: team-unmapped
|
|
542
542
|
defaultTeam: engineering # the workspace's fallback default team (a shared label)
|
|
543
543
|
localTeams: false # may deployments declare their own teams? (absent: false)
|
|
544
|
-
souls: #
|
|
544
|
+
souls: # the one declaration of each soul's team, per soul or pattern
|
|
545
545
|
"*": { teams: [] } # unlisted souls: default only (also what no entry means)
|
|
546
546
|
security-souls/*: { default: security, teams: [engineering] }
|
|
547
547
|
security-souls/incident-responder: { default: security, teams: [engineering, docs] }
|
|
548
548
|
oats.engineering/*: { teams: any } # any: every shared team of this file
|
|
549
549
|
```
|
|
550
550
|
|
|
551
|
+
- **`souls:` is the one declaration of which team a soul belongs to.** An entry's
|
|
552
|
+
`default` is the team that soul's instances join; its `teams` are the others they
|
|
553
|
+
may join. A pattern entry (`<member>/*`, `*`) sets them for a set of souls, and a
|
|
554
|
+
named entry overrides it for one. Nothing else assigns a soul a team: not the
|
|
555
|
+
soul's own files, and not where it runs. A deployment's local `defaultTeam` is only
|
|
556
|
+
a fallback for a soul no entry gives a default (below). The sandboxes design
|
|
557
|
+
([design record](design/2026-11-19-sandboxes.md), not built yet) places souls in
|
|
558
|
+
sandboxes without touching this declaration.
|
|
551
559
|
- **Shared teams** (`teams.<label> = { description?, team? }`): a shared team
|
|
552
560
|
without `team` is declared but not created yet (readiness `team-unmapped`):
|
|
553
561
|
its owner creates it with the messaging provider, then commits the id.
|
|
@@ -587,8 +595,8 @@ souls: # per soul pattern: its default team an
|
|
|
587
595
|
|
|
588
596
|
The default, in order:
|
|
589
597
|
|
|
590
|
-
1. the soul's `default` from `souls
|
|
591
|
-
sets one);
|
|
598
|
+
1. the soul's `default` from `souls:`, the team its instances join (the most
|
|
599
|
+
specific matching key that sets one);
|
|
592
600
|
2. else the deployment's `oats-local.yaml` `defaultTeam`, only when
|
|
593
601
|
`localTeams: true`;
|
|
594
602
|
3. else the workspace's `defaultTeam`;
|