@awebai/oats 0.66.0 → 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.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
package/docs/desktop.md
CHANGED
|
@@ -112,6 +112,23 @@ PATH, not the Desktop's. A tmux server that was already running keeps its own
|
|
|
112
112
|
environment; restart it if its sessions should get the new PATH, which ends
|
|
113
113
|
its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
|
|
114
114
|
|
|
115
|
+
## Updating
|
|
116
|
+
|
|
117
|
+
Installing a new version doesn't change a Desktop that is already running: an
|
|
118
|
+
AppImage runs from its own mount, and a DEB or another copy of the app hands
|
|
119
|
+
its launch to the running app, which opens or focuses a window and carries on
|
|
120
|
+
in the old version. To switch, quit Desktop (close every window) and open it
|
|
121
|
+
again.
|
|
122
|
+
|
|
123
|
+
From this version on, a launch of a different version says so: the running
|
|
124
|
+
Desktop opens or focuses the window as usual, then asks whether to **Restart
|
|
125
|
+
into** the version you opened, naming the file it starts, or **Keep** the
|
|
126
|
+
running one. Restarting closes Desktop's windows and starts the version you
|
|
127
|
+
opened; your agents keep running in their sessions. When the copy you opened can't be found again (its file was
|
|
128
|
+
moved or removed), the message only tells you to quit and open it again. Both
|
|
129
|
+
copies must be this version or later: a running Desktop older than this one
|
|
130
|
+
can't tell you, and neither can a launch of one.
|
|
131
|
+
|
|
115
132
|
## Opening a workspace
|
|
116
133
|
|
|
117
134
|
The app opens the workspaces you had open, plus the directory it was
|
|
@@ -119,17 +136,12 @@ launched with (`--dir`, or the folder it was started from) when that is an
|
|
|
119
136
|
OATS deployment — the directory (the operator's choice) holding
|
|
120
137
|
`oats-local.yaml` and `agents/`. A folder that is not a deployment is never
|
|
121
138
|
opened: started from Finder, with nothing open to restore, the window shows
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
(`oats deployments`, see
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
beside a row takes it off the list (Right Arrow, then Enter, from the
|
|
129
|
-
keyboard); nothing on disk changes. With an oats that has no such list, the
|
|
130
|
-
switcher shows the saved deployments and says "This oats can't list this
|
|
131
|
-
computer's deployments. Update oats." **Add local workspace… → Browse**
|
|
132
|
-
points it at any other deployment.
|
|
139
|
+
"Choose a workspace" and opens **Add local workspace…** (the **+** at the top
|
|
140
|
+
of the sidebar). The dialog lists the deployments on this computer that are
|
|
141
|
+
not open: those on this computer's deployments list (`oats deployments`, see
|
|
142
|
+
[Workspaces](workspaces.md)) and a saved one. Click one, or press Enter on it,
|
|
143
|
+
to add it and open it in this window. **Browse…** points it at any other
|
|
144
|
+
deployment.
|
|
133
145
|
A picked folder without `oats-local.yaml` is offered onboarding instead. The
|
|
134
146
|
Desktop never parses the deployment: its members, lock state and header come
|
|
135
147
|
from `oats workspace status`, and its instances from the deployment's one
|
|
@@ -148,17 +160,19 @@ Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
|
|
|
148
160
|
Each workspace has at most one window, titled with the workspace's name (a
|
|
149
161
|
workspace on a server: `name — server`).
|
|
150
162
|
|
|
151
|
-
- **Switching.**
|
|
152
|
-
window. If
|
|
153
|
-
|
|
154
|
-
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
163
|
+
- **Switching.** Picking a workspace in the sidebar's list shows it in the
|
|
164
|
+
current window. If another window shows it, it moves to this window, and the
|
|
165
|
+
other window shows another workspace ([A workspace another window
|
|
166
|
+
shows](#a-workspace-another-window-shows)). No other window comes to the
|
|
167
|
+
front.
|
|
168
|
+
- **Open in new window.** A workspace's row in the list opens it in its own
|
|
169
|
+
window from its context menu (a right-click, or Shift+F10 or the Menu key),
|
|
170
|
+
or with ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A workspace that
|
|
171
|
+
already has a window is brought to the front.
|
|
158
172
|
- **New Window.** On macOS, **File → New Window** (⌘⇧N); everywhere,
|
|
159
173
|
**Window: new window** in the command palette. The new window has no
|
|
160
|
-
workspace yet: it
|
|
161
|
-
you pick one. It reads nothing until then.
|
|
174
|
+
workspace yet: it shows "Choose a workspace" and focuses the list of
|
|
175
|
+
workspaces until you pick one. It reads nothing until then.
|
|
162
176
|
- **Moving between windows.** On macOS, ⌘\` cycles the app's windows, and the
|
|
163
177
|
**Window** menu lists them.
|
|
164
178
|
- **Restore.** Quitting and relaunching brings every window back with its
|
|
@@ -169,12 +183,14 @@ workspace on a server: `name — server`).
|
|
|
169
183
|
- **Launching again.** Running the app again (`open -a "OATS Desktop" --args
|
|
170
184
|
--dir <deployment>`, or from inside a deployment) adds that deployment if
|
|
171
185
|
needed and brings its window to the front, opening one if it has none. Any
|
|
172
|
-
other launch brings the most recently used window to the front.
|
|
186
|
+
other launch brings the most recently used window to the front. A launch of
|
|
187
|
+
another version also offers to restart into it ([Updating](#updating)).
|
|
173
188
|
- **Closing.** Closing a window leaves the other windows, and their
|
|
174
189
|
terminals, running. Closing the last window quits the app.
|
|
175
190
|
- Tabs belong to their window: a workspace's terminals and tabs stay in the
|
|
176
191
|
window they were opened in, and switching that window back to the
|
|
177
|
-
workspace brings them back.
|
|
192
|
+
workspace brings them back. A window whose workspace another window takes
|
|
193
|
+
over closes its tabs of that workspace.
|
|
178
194
|
- A tab's terminal ends ("session ended") when its instance's tmux window
|
|
179
195
|
goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
|
|
180
196
|
another instance's terminal. Stopping an instance leaves its tab open.
|
|
@@ -186,10 +202,139 @@ workspace on a server: `name — server`).
|
|
|
186
202
|
An instance respawned under the same name is a new instance: opening it
|
|
187
203
|
opens a new tab.
|
|
188
204
|
|
|
205
|
+
## Workspaces
|
|
206
|
+
|
|
207
|
+
The sidebar, top to bottom: the **Workspace** heading, with **Show only the
|
|
208
|
+
current workspace** and **Add local workspace…** at its end, over the list of
|
|
209
|
+
workspaces; a thin line; the two main views, **Workspace overview** and
|
|
210
|
+
**Automations**, one under the other; another line; **Instances**, a heading
|
|
211
|
+
with the running count over the list of instances; and, over a line, the
|
|
212
|
+
foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
|
|
213
|
+
after it, and at the bar's right **Spawn instance**, its words alone (a ground
|
|
214
|
+
only on hover), which
|
|
215
|
+
opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
|
|
216
|
+
the spawn dialog, and the settings cog, whose menu holds **Theme…** and **Keyboard
|
|
217
|
+
shortcuts…**, each with its shortcut. A window opens on the **Workspace
|
|
218
|
+
overview** page, on its **Souls** tab: at launch, and after you choose a
|
|
219
|
+
workspace for it. Connections is in the command palette
|
|
220
|
+
(**Settings: Connections…**), and the palette opens with its shortcut or
|
|
221
|
+
Ctrl+X then `k`.
|
|
222
|
+
The instances have no search field: to find one by name, type it in the
|
|
223
|
+
command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
|
|
224
|
+
instance roster**) and `/` in the sidebar go to the roster's current row;
|
|
225
|
+
on an empty roster, to its one action, the foot's **Spawn instance**, where
|
|
226
|
+
F6 lands too (a failed read's **Retry** comes first).
|
|
227
|
+
|
|
228
|
+
The list of workspaces is always shown. Its heading holds **Add local
|
|
229
|
+
workspace…** (the **+**). The list has one row per workspace this window can show, whatever
|
|
230
|
+
machine it is on: every workspace the Desktop serves, those only on servers
|
|
231
|
+
included, and the deployments no workspace matched ([One workspace, several
|
|
232
|
+
machines](#one-workspace-several-machines)), after them in the same list.
|
|
233
|
+
|
|
234
|
+
With one workspace the list is one compact row. With many it scrolls within
|
|
235
|
+
about six rows, the current row stays in view, and while rows are cut off
|
|
236
|
+
below, a line under the list says how many ("2 more below"), with the
|
|
237
|
+
needs-input mark at its right when one of them has an instance that needs
|
|
238
|
+
input.
|
|
239
|
+
|
|
240
|
+
**Show only the current workspace** is the toggle before the **+** in the
|
|
241
|
+
heading, for working in one workspace at a time. Pressed (its icon in the
|
|
242
|
+
accent colour), the list shows the current workspace's row alone. Nothing
|
|
243
|
+
stands for the others: no "N more" line, and no needs-input mark for one of
|
|
244
|
+
them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
|
|
245
|
+
Linux and Windows (the same in every chord family, and from a terminal) or the
|
|
246
|
+
palette's **Show only the current workspace**, to see every workspace again.
|
|
247
|
+
Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
|
|
248
|
+
shows alone. A window choosing a workspace shows them all. The choice is remembered on this
|
|
249
|
+
computer.
|
|
250
|
+
|
|
251
|
+
- **A row is one line: a circle and the workspace's name.** No icon, no
|
|
252
|
+
machine, no state: a workspace's own pages show its machines and
|
|
253
|
+
deployments. The circle is the one an instance row has, in the same place.
|
|
254
|
+
A long name ends in an ellipsis, and the row's tooltip is the whole name.
|
|
255
|
+
- **The current workspace** has its circle filled, like a running
|
|
256
|
+
instance's, and its name in bold; the others have the ring a stopped
|
|
257
|
+
instance has. It has no background of its own: the selection's background
|
|
258
|
+
marks the current page (Workspace overview or Automations), so the
|
|
259
|
+
sidebar fills one "you are here" row. A screen reader hears it as current,
|
|
260
|
+
and the list's description names it, by the same name as its row.
|
|
261
|
+
- **The needs-input mark.** A row has an exclamation mark (a small amber
|
|
262
|
+
disc with a "!") at its right end when an instance of that workspace needs
|
|
263
|
+
input, the same mark an instance's **Needs input** pill starts with: the claim the instance roster shows
|
|
264
|
+
for that instance, from a running session (OATS with the `waiting-on-you`
|
|
265
|
+
feature), as the Desktop already reads it for the workspaces it serves.
|
|
266
|
+
Every row can have it, the current one included. The row's name then ends
|
|
267
|
+
in ", needs input" for a screen reader, and its tooltip says "An instance
|
|
268
|
+
here needs input". What isn't known shows no mark, never a guess: a
|
|
269
|
+
deployment that isn't live (stale, not reached, its last read failed) and
|
|
270
|
+
an oats without `waiting-on-you`. The mark never moves a row: the order
|
|
271
|
+
stays the same whoever waits.
|
|
272
|
+
- **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+X then ↑ /
|
|
273
|
+
↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
|
|
274
|
+
in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
|
|
275
|
+
selection; one another window shows moves here ([A workspace another window
|
|
276
|
+
shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
|
|
277
|
+
previous / next row, and stop at the ends ("No workspace above this one." /
|
|
278
|
+
"No workspace below this one."). Each is a pick, so walking the list with
|
|
279
|
+
them moves every workspace it passes that another window shows into this
|
|
280
|
+
window.
|
|
281
|
+
- **Open in new window** is in a row's context menu (a right-click, or
|
|
282
|
+
Shift+F10 or the Menu key), and ⌘Enter on macOS / Ctrl+Enter on Linux and
|
|
283
|
+
Windows does it from the keyboard. It opens the workspace in its own window,
|
|
284
|
+
or brings the window that shows it to the front.
|
|
285
|
+
- **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
|
|
286
|
+
`w` in the sidebar, Ctrl+X then `o`, ⌥⌘O / Alt+O and the palette's
|
|
287
|
+
**Workspace: switch…** focus it. The full keys are in [the keyboard
|
|
288
|
+
reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
|
|
289
|
+
|
|
290
|
+
**Add local workspace…** lists the deployments on this computer that are not
|
|
291
|
+
open: those on this computer's deployments list and a saved one. Each is one
|
|
292
|
+
button: a click, or Enter on it, adds it (checked first) and opens it in this
|
|
293
|
+
window; a failure says why in the dialog, with focus back on it. The dialog
|
|
294
|
+
counts these alone ("2 workspaces to add"). After them, under **Can't be
|
|
295
|
+
opened**, come the rows of this computer's list that can't be opened, each
|
|
296
|
+
saying why in a word, and they open nothing: **Missing** (the folder is gone, or its volume
|
|
297
|
+
isn't mounted), **Not a deployment** (no `oats-local.yaml` any more), or
|
|
298
|
+
**Can't be checked** (OATS couldn't read the folder). The full sentence is the
|
|
299
|
+
row's tooltip and what a screen reader hears. **Remove** beside such a row
|
|
300
|
+
takes it off the list (Right Arrow, then Enter, from the keyboard); nothing on
|
|
301
|
+
disk changes. With an oats that has no deployments list, the dialog offers the
|
|
302
|
+
saved deployments alone and says "This oats can't list this computer's
|
|
303
|
+
deployments. Update oats."; a list read that failed says "Couldn't read this
|
|
304
|
+
computer's deployments:" and why. **Browse…** chooses any other folder, and one without
|
|
305
|
+
`oats-local.yaml` is offered onboarding.
|
|
306
|
+
|
|
307
|
+
A window with no workspace (a New Window, or one whose workspace moved to
|
|
308
|
+
another window) shows "Choose a workspace" and focuses the list. When the
|
|
309
|
+
Desktop serves no workspace at all, so the list is empty, it opens **Add local
|
|
310
|
+
workspace…** instead. Closing the dialog leaves "Choose a workspace", whose
|
|
311
|
+
button opens it again.
|
|
312
|
+
|
|
313
|
+
### A workspace another window shows
|
|
314
|
+
|
|
315
|
+
Picking a workspace another window shows moves it to this window: a pick from
|
|
316
|
+
the list, the workspace select of
|
|
317
|
+
the Workspace page, and a spawn whose new instance is in that workspace.
|
|
318
|
+
Nothing else comes to the front. The other window lets the workspace go: it
|
|
319
|
+
shows the workspace it showed most recently before that one among those the
|
|
320
|
+
Desktop still serves and no other window shows, else no workspace ("Choose a
|
|
321
|
+
workspace"). It closes every tab it had of the workspace that moved. The
|
|
322
|
+
Desktop waits at most 2 seconds for the other window; one that answers late
|
|
323
|
+
ends the same way, and so does one that was still opening or reloading:
|
|
324
|
+
once it comes up it shows no workspace, never the one that moved. **Open in
|
|
325
|
+
new window** still brings the other window to the front instead.
|
|
326
|
+
|
|
327
|
+
Only the terminals and the split move with the workspace: this window opens
|
|
328
|
+
the same terminal tabs in the same split, each with a fresh viewer, and the
|
|
329
|
+
agents keep running. File, brain and view tabs do not move: they close in the
|
|
330
|
+
other window.
|
|
331
|
+
|
|
189
332
|
## Capabilities and spawning
|
|
190
333
|
|
|
191
|
-
**Workspace › Capabilities**
|
|
192
|
-
|
|
334
|
+
**Workspace › Capabilities** is in two parts, each with its title:
|
|
335
|
+
**Workspace defaults** (below), then **All capabilities**, what the
|
|
336
|
+
workspace offers. Under the **All capabilities** title, a row of segments
|
|
337
|
+
jumps to its three sections: **Workspace owned** (from the member repos, for every soul),
|
|
193
338
|
**Repo owned** (only for souls of the same repo) and **Packages** (pinned
|
|
194
339
|
versions). Workspace owned and Repo owned are grouped by the repository
|
|
195
340
|
that defines each capability. The groups are headed like the Souls tab:
|
|
@@ -200,29 +345,83 @@ pills (**All**, then one per repository, each with its count) show one
|
|
|
200
345
|
repository at a time; "N of M shown" appears while a pill or the search
|
|
201
346
|
narrows the list.
|
|
202
347
|
|
|
348
|
+
Above All capabilities, **Workspace defaults** shows what every soul of the
|
|
349
|
+
workspace starts with, unless it turns one off. It is one panel with two
|
|
350
|
+
groups. **Core capabilities** (at most one of each per soul) is always
|
|
351
|
+
**Knowledge**, **Messaging** and **Tasks**. **Additional capabilities** (any
|
|
352
|
+
number per soul) lists the other capabilities the workspace gives every soul,
|
|
353
|
+
or says there are none. Each default is shown the same way: its tile, the
|
|
354
|
+
capability and its source (a package and its pinned version, or a repository
|
|
355
|
+
and "latest"). Click it to open the capability's page. An empty core slot
|
|
356
|
+
shows **None**: there is no workspace default, and each soul chooses its
|
|
357
|
+
own. A core capability the workspace names among its other defaults, rather
|
|
358
|
+
than in its slot, is shown under Core, in that slot, as the kernel fills the
|
|
359
|
+
slot with it. An additional default the workspace turned off is struck through and
|
|
360
|
+
says "turned off by the workspace". A workspace that sets no defaults, a
|
|
361
|
+
standalone deployment for example, shows one line saying so. The search and
|
|
362
|
+
the repository pills never narrow or hide this section. It is read from
|
|
363
|
+
`oats workspace status --json`: an OATS that does not report the defaults
|
|
364
|
+
shows no such part, and the Desktop does not guess them from the souls. The
|
|
365
|
+
defaults have no segment of their own: the segments are All capabilities'.
|
|
366
|
+
Teams add no capabilities (removed in 0.30), so there are no team defaults
|
|
367
|
+
to show.
|
|
368
|
+
|
|
369
|
+
The round **i** button in the toolbar, beside the search (**About capabilities**), opens
|
|
370
|
+
**What capabilities are**: what a capability gives a soul's instances (skills,
|
|
371
|
+
commands and instructions, the instructions injected into each instance's
|
|
372
|
+
composed `AGENTS.md` after the soul's own), the three places one comes from
|
|
373
|
+
(Workspace owned, Repo owned, Packages), which three capabilities are core
|
|
374
|
+
(knowledge, messaging and tasks, at most one of each per soul) and that every
|
|
375
|
+
other one is additional, and what workspace defaults are and why they
|
|
376
|
+
matter: every soul gets them, they give an organisation's agents one shared
|
|
377
|
+
way of working, and a knowledge default keeps what agents learn and the
|
|
378
|
+
procedures the organisation writes down for later instances; a soul can turn
|
|
379
|
+
one off and name its own in its place.
|
|
380
|
+
**Close** or Esc closes it and returns the focus to the button; leaving the
|
|
381
|
+
tab or the workspace closes it too. **Workspace › Souls** has the same button
|
|
382
|
+
at the end of its toolbar, **About souls**, which explains what a soul is.
|
|
383
|
+
|
|
203
384
|
A soul's page (open a soul from **Workspace › Souls**) ends with
|
|
204
|
-
**Instructions**, what its instances are told
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
385
|
+
**Instructions**, what its instances are told, read like a capability's
|
|
386
|
+
injected instructions (a navigation tree on the left, the file on the right).
|
|
387
|
+
The tree has two sections, a rule between them:
|
|
388
|
+
|
|
389
|
+
- **Defined in this soul**: its own `AGENTS.md`, at its path in the soul's
|
|
390
|
+
repository, and, with an OATS that reports a soul's skills, its **Skills**.
|
|
391
|
+
Open a skill to list its files; a file opens in the reader under its
|
|
392
|
+
repository path.
|
|
393
|
+
- **Composed for an instance**: what an instance of this soul gets. Its
|
|
394
|
+
**AGENTS.md**, *after spawn, with injects*, and its **Skills**, each saying
|
|
395
|
+
where it comes from. With an OATS that lists every skill a spawn gives the
|
|
396
|
+
instance (0.67.0 and later), the Skills are that list: the soul's own, each
|
|
397
|
+
**From this soul**, and the ones its capabilities add, each **From** the
|
|
398
|
+
capability. A capability's skill file opens under its place in the instance
|
|
399
|
+
home (`.oats/modules/<capability>/…`), with **Open capability** above it. With
|
|
400
|
+
an older OATS the skills listed are the soul's own, and a note says that the
|
|
401
|
+
skills capabilities add are listed by a newer OATS. For a soul on another
|
|
402
|
+
machine, the server's OATS must list them too, as for the composed
|
|
403
|
+
AGENTS.md below.
|
|
404
|
+
|
|
405
|
+
Both come from the same inspection as the rest of the page, so **Refresh**
|
|
406
|
+
re-reads them and keeps what you had open, and your place in it. A file over
|
|
407
|
+
200,000 characters is shown cut, and says so.
|
|
408
|
+
|
|
409
|
+
The composed **AGENTS.md** needs an OATS that composes a soul's instructions
|
|
410
|
+
(0.46.0 and later). It is the file a spawn of this soul on this computer would
|
|
411
|
+
write, with one entry per part (the soul's own text, then each block OATS and
|
|
412
|
+
the soul's capabilities add, in order). Open it to read the whole document;
|
|
413
|
+
choose a part to go to it. Each part's header says where it comes from
|
|
414
|
+
(**From this soul** or **Injected by …**) and names its file; a capability's
|
|
415
|
+
part has **Open capability**, and **Copy composed AGENTS.md** copies the exact
|
|
416
|
+
file. When the soul can't be composed here, the section says so and the problem
|
|
417
|
+
shows at the top of the page. For a soul on another machine (a server
|
|
418
|
+
workspace), the page shows the composed file when that machine supports it:
|
|
419
|
+
this computer's OATS must be 0.49.0 or later, to pass on what each server
|
|
420
|
+
reports about itself, and the server's OATS must say it composes a soul's
|
|
421
|
+
instructions (0.49.0 and later report this). Until a server reports it (an
|
|
422
|
+
older server, or one whose last read failed), its soul pages show no composed
|
|
423
|
+
**AGENTS.md**. A soul's skills follow the same rule, with the server's OATS
|
|
424
|
+
saying it reports them.
|
|
226
425
|
|
|
227
426
|
The **Spawn** dialog's left column, **What will be created**, starts with the
|
|
228
427
|
new instance's name and its home. Then come where it works, its harness and
|
|
@@ -230,6 +429,63 @@ model (with where that choice came from), its default team and the teams it may
|
|
|
230
429
|
also join, and its relationship when it has one. Under them are its core
|
|
231
430
|
capabilities and its other capabilities.
|
|
232
431
|
|
|
432
|
+
The dialog's first field is the **Opening instruction**, and the dialog opens
|
|
433
|
+
with the cursor in it (after a restored instruction's text). In a narrow window,
|
|
434
|
+
**What will be created** comes after the form's last field, above **Spawn**:
|
|
435
|
+
scroll down with the fields to read it.
|
|
436
|
+
|
|
437
|
+
The dialog's last field before **Developer settings** is **Name · optional**.
|
|
438
|
+
Left empty, the kernel numbers the new instance (`<soul>-<n>`). A name you type
|
|
439
|
+
is used in lowercase and gets the soul's role, the last word of the soul's
|
|
440
|
+
name, as its suffix:
|
|
441
|
+
`desktop-improvements` for `oats-desktop-expert` becomes
|
|
442
|
+
`desktop-improvements-expert`. A name that already ends in the role, or is
|
|
443
|
+
the role, stays as typed. The line under the field shows the final name, and a
|
|
444
|
+
name that is too long, invalid or already taken is explained there. A spawn
|
|
445
|
+
on a server takes the exact name the same way when that machine's OATS can
|
|
446
|
+
take one (feature `spawn-name`, read from its last roster answer), and its
|
|
447
|
+
name is explained there too when that machine refuses it. With an OATS older
|
|
448
|
+
than 0.26.0 on either side, which can't take an exact name, or a server whose
|
|
449
|
+
OATS this computer has not heard from, what you type is a purpose instead: the
|
|
450
|
+
instance is named `<soul>-<purpose>`, and the field shows that prefix.
|
|
451
|
+
|
|
452
|
+
**Named from its task.** When the installed OATS can suggest names (feature
|
|
453
|
+
`spawn-suggest-name`), the help under an empty Name reads "Left empty, the
|
|
454
|
+
instance is named from its task." Once the Opening instruction holds at
|
|
455
|
+
least seven words, the Desktop asks OATS for a name as you type. The soul's
|
|
456
|
+
own harness reads the instruction and replies with a short name for the work,
|
|
457
|
+
and the role is added as its suffix. The name shows as the field's
|
|
458
|
+
placeholder ("release-notes-manager"), on the line under the field ("(from
|
|
459
|
+
the task)") and in **What will be created**. It belongs to the instruction it
|
|
460
|
+
was made for: when you change the instruction it goes, and the Desktop asks
|
|
461
|
+
again for the new instruction while it holds seven words or more. Typing in
|
|
462
|
+
Name replaces it and stops suggestions for the rest of the dialog, even if
|
|
463
|
+
you empty the field again. Press **Spawn** with Name empty and no name yet, and the
|
|
464
|
+
dialog says **Naming…** and asks once, however short the instruction. When OATS
|
|
465
|
+
can't name it, the instance is numbered and a notification says why, for
|
|
466
|
+
example "Named oats-desktop-expert-3: naming took longer than 20 seconds."
|
|
467
|
+
That happens when there is no instruction, when the harness doesn't suggest
|
|
468
|
+
names (Codex), when there is no answer within 20 seconds, when the harness
|
|
469
|
+
couldn't be asked, and when its reply wasn't a name. Each request is a call
|
|
470
|
+
to the harness's model: nothing is asked before you type, and nothing runs on
|
|
471
|
+
a timer.
|
|
472
|
+
|
|
473
|
+
A spawn on a server whose OATS takes an exact name is named from its task the
|
|
474
|
+
same way, with one difference: the name is chosen on this computer. The
|
|
475
|
+
Opening instruction is sent to this computer's harness and model, as for a
|
|
476
|
+
spawn here: the Harness you chose, else the soul's default on that server,
|
|
477
|
+
else Claude Code, with this computer's launch configuration for it. That needs
|
|
478
|
+
an OATS here that can name a spawn for another machine (feature
|
|
479
|
+
`instance-suggest-name`). When it can't, or the name couldn't be chosen here,
|
|
480
|
+
the server names the instance itself from its task if its OATS can (feature
|
|
481
|
+
`spawn-apply-suggest-name`): the help reads "Left empty, the instance is named
|
|
482
|
+
from its task on <server>." Otherwise the server numbers it, and the help reads
|
|
483
|
+
"Named by <server> when it spawns." Naming never stops a spawn on a server.
|
|
484
|
+
When the instance is numbered where it would have been named, a notification
|
|
485
|
+
says why, as for a spawn here. A name chosen here is not checked on the server
|
|
486
|
+
until the spawn: one that is already taken there is refused, and explained
|
|
487
|
+
under the field.
|
|
488
|
+
|
|
233
489
|
When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
|
|
234
490
|
names them, in the order they run, and says this can take several minutes. Such
|
|
235
491
|
a spawn may run for a long time: its roster row reads **Setting up worktree…**
|
|
@@ -295,21 +551,34 @@ When the retire has ended without finishing, the row says so and offers only
|
|
|
295
551
|
|
|
296
552
|
## One workspace, several machines
|
|
297
553
|
|
|
298
|
-
The
|
|
554
|
+
The list of workspaces has each workspace once, however many deployments it has: the
|
|
299
555
|
deployments you opened on this Mac and those your registered servers report,
|
|
300
556
|
matched by the workspace each one reports (its repository key and default
|
|
301
557
|
team, by the kernel's rules). It needs a CLI with the `workspace-identity`
|
|
302
558
|
feature (OATS 0.36.0); without it each deployment has its own entry.
|
|
303
559
|
|
|
304
|
-
- **
|
|
305
|
-
shows the workspace's overview trees.
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
560
|
+
- **Machines.** **Workspace › Machines** (once the Deployments page, and
|
|
561
|
+
the Active overview before that) shows the workspace's overview trees.
|
|
562
|
+
One sentence above them says what a machine is: "Each machine runs this
|
|
563
|
+
workspace in a folder of its own. The instances under a machine run on
|
|
564
|
+
that machine." **All** stacks one section per deployment, each headed by
|
|
565
|
+
its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
|
|
566
|
+
with "Instances on this machine" or "Instances on altair" under it. Then
|
|
567
|
+
each deployment has a tab of its own, named by its machine ("altair";
|
|
568
|
+
"This Mac · oats-v2" when this Mac holds two). A workspace with one
|
|
569
|
+
deployment shows just that deployment's tab, its tree under the same
|
|
570
|
+
heading. The tab you chose is
|
|
571
|
+
remembered per workspace. With two or more deployments, the sidebar's
|
|
572
|
+
instance list is grouped under one heading per machine; with one, it has
|
|
573
|
+
no headings.
|
|
574
|
+
- **An instance's card.** Clicking an instance on the Machines tab shows
|
|
575
|
+
what it reports and two buttons. **Go to instance** opens its terminal tab;
|
|
576
|
+
for a stopped instance it reads **Start…** and opens the Start dialog.
|
|
577
|
+
**Go to soul** opens the soul it was spawned from on the Workspace page. It
|
|
578
|
+
is disabled, and says why, when that soul can't be told or shown exactly:
|
|
579
|
+
the instance records none, it is no longer among the deployment's souls,
|
|
580
|
+
several match, another soul of the deployment has the same name, or the
|
|
581
|
+
instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the instance's menu and its panel.
|
|
313
582
|
- **Not shown live.** A deployment that can't be shown live says why in a few
|
|
314
583
|
words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
|
|
315
584
|
report its workspace"), and **How to fix** under it gives the full sentence
|
|
@@ -318,19 +587,22 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
|
|
|
318
587
|
needs `oats sync` or fixing in `oats-local.yaml`, or this computer's OATS
|
|
319
588
|
can't read other machines. A server that can't be reached stays under the
|
|
320
589
|
workspace it last reported, marked "remembered".
|
|
321
|
-
- **The
|
|
590
|
+
- **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
|
|
322
591
|
altair"), with a mark when one of them isn't live.
|
|
323
592
|
- **Not matched to a workspace.** A deployment that can't be matched is
|
|
324
|
-
listed on its own under that heading in the
|
|
325
|
-
a short reason; choosing it opens its tab on the
|
|
593
|
+
listed on its own under that heading in the list, with its machine and
|
|
594
|
+
a short reason; choosing it opens its tab on the Machines tab. When this
|
|
326
595
|
computer's OATS is too old to report workspaces, nothing can be matched:
|
|
327
596
|
each deployment is listed on its own, as before, and its heading says to
|
|
328
597
|
update OATS.
|
|
329
598
|
- **Actions.** Everything you do to an instance goes to that instance's own
|
|
330
599
|
deployment. Workspace-wide pages (Setup, Capabilities, Sync, Automations,
|
|
331
600
|
Schedules, Teams configuration) act on the workspace's first deployment on
|
|
332
|
-
this Mac, else its first
|
|
333
|
-
|
|
601
|
+
this Mac, else its first. None of them names it: not Souls,
|
|
602
|
+
Capabilities, Teams or Setup, nor the Automations page, nor a soul's, a
|
|
603
|
+
capability's or a team's page. The side panel names it ("On This Mac ·
|
|
604
|
+
~/acme", under a soul's name) when there are two or more, as do Brain and
|
|
605
|
+
the Sync sheet, and the Machines tab shows each deployment on its own tab.
|
|
334
606
|
- **Spawn.** With two or more deployments, the Spawn dialog asks first which
|
|
335
607
|
one to spawn in (and says "Runs on" in its summary), starting on the one you last used in that workspace when it
|
|
336
608
|
offers the soul, else the first that does (this Mac first). With one, it
|
|
@@ -342,7 +614,8 @@ deployment. Details are in
|
|
|
342
614
|
|
|
343
615
|
## Scheduling agents and wake messages
|
|
344
616
|
|
|
345
|
-
Open **Schedules** in the selected workspace
|
|
617
|
+
Open **Automations › Schedules** in the selected workspace (the sidebar's
|
|
618
|
+
**Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
|
|
346
619
|
wake an existing agent with a message, or harvest its knowledge. **Schedule…**
|
|
347
620
|
on a Soul roster card preselects that soul. Choose the task or message, repeat
|
|
348
621
|
pattern and time zone; new agent jobs also offer harness, model, permissions
|
|
@@ -409,7 +682,7 @@ member and what each member state means. Then **Shared through Git** lists
|
|
|
409
682
|
what the workspace declares (Members, with the host first and tagged
|
|
410
683
|
**Host**, Packages and Defaults). **This computer** lists what is not shared:
|
|
411
684
|
this deployment's settings, lock, CLI and instances, the member clones, and
|
|
412
|
-
the machines that run the workspace.
|
|
685
|
+
the machines that run the workspace (**Registered machines**).
|
|
413
686
|
|
|
414
687
|
## A workspace's machines
|
|
415
688
|
|
|
@@ -417,7 +690,7 @@ A window offers only the machines that run its workspace: those whose
|
|
|
417
690
|
registration reports the same workspace key as the window's deployment on this
|
|
418
691
|
computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
|
|
419
692
|
spawn dialog's **Where to run** lists "This computer" and those machines; the
|
|
420
|
-
Workspace › Setup tab lists them with their OATS version and whether they can
|
|
693
|
+
Workspace › Setup tab's **Registered machines** lists them with their OATS version and whether they can
|
|
421
694
|
be reached, with **Check** and **Remove**. Registrations whose key is not known
|
|
422
695
|
yet are checked once in the background after the Desktop starts.
|
|
423
696
|
|
|
@@ -438,8 +711,8 @@ saved route. A machine registered for a workspace no window shows is not
|
|
|
438
711
|
contacted, so a machine that is switched off no longer slows every window's
|
|
439
712
|
roster. Opening a window on another workspace reads its machines at once. Until
|
|
440
713
|
it does, that workspace's machines are shown as they were last read, marked
|
|
441
|
-
stale, and the
|
|
442
|
-
|
|
714
|
+
stale, and the list of workspaces still lists them, not counted live. The read covers every machine again while a window
|
|
715
|
+
has no workspace, and on the first read after the Desktop starts. With an
|
|
443
716
|
older CLI, every registered machine is read, as before.
|
|
444
717
|
|
|
445
718
|
## Instances on servers
|
|
@@ -545,6 +818,29 @@ right of its parent, and related instances are grouped together. Siblings are
|
|
|
545
818
|
joined by a dotted line through their dots. A parent's line to its children
|
|
546
819
|
runs just to the right of the dotted line, so the two never merge.
|
|
547
820
|
|
|
821
|
+
## An instance's colour
|
|
822
|
+
|
|
823
|
+
An instance can have a colour, one of the soul palette's six (Sand, Sage,
|
|
824
|
+
Slate, Mauve, Clay, Olive). Its dot shows it wherever the instance is listed:
|
|
825
|
+
the sidebar, its terminal tab, the command palette and the overview. A running
|
|
826
|
+
instance's dot is filled with the colour, a stopped one's is a ring in it. An
|
|
827
|
+
instance whose state is unknown keeps the warning dot, and one without a colour
|
|
828
|
+
looks as before. The shape says the state, never the colour alone.
|
|
829
|
+
|
|
830
|
+
To set it, open **Instance: name and colour…** from the command palette, or
|
|
831
|
+
press Alt+R (⌥⌘R on macOS; Ctrl+Alt+R in the Ctrl+Alt family). It acts on the instance of the terminal you
|
|
832
|
+
are in, else the focused sidebar row, else the active terminal tab's instance.
|
|
833
|
+
The dialog shows the instance's name, which can't be changed yet, and the
|
|
834
|
+
colours as buttons: **None** and the six. Arrow keys move between them; Enter,
|
|
835
|
+
Space or a click sets the colour at once, and **Saved.** or OATS's refusal
|
|
836
|
+
appears under the title. The dialog stays open until you close it.
|
|
837
|
+
|
|
838
|
+
The colour is the instance's own, kept in its home by OATS
|
|
839
|
+
(`oats instance color`). Setting one needs OATS 0.67.0 or later on this
|
|
840
|
+
computer, and for an instance on a server, on that server too; until then the
|
|
841
|
+
buttons are disabled and the dialog says which is missing. An instance whose
|
|
842
|
+
home is being spawned or retired can't be given a colour meanwhile.
|
|
843
|
+
|
|
548
844
|
## Identity marks and harness badges
|
|
549
845
|
|
|
550
846
|
Souls, capabilities and workspaces carry a coloured two-letter mark beside
|
|
@@ -597,7 +893,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
597
893
|
| Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
|
|
598
894
|
| macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
|
|
599
895
|
| Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
|
|
600
|
-
| Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use
|
|
896
|
+
| Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
|
|
601
897
|
|
|
602
898
|
For bugs, attach the terminal output of the app (`OATS Desktop` prints
|
|
603
899
|
server and CLI-discovery logs to stdout) and your platform/arch.
|
package/docs/first-team.md
CHANGED
|
@@ -163,9 +163,11 @@ in section 2). The instance home is
|
|
|
163
163
|
`agents/<soul>/instances/<instance>/`; `work/` is its repository view;
|
|
164
164
|
`.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
|
|
165
165
|
`instance.json` records `modules` (from, commit, digest), `providers` and
|
|
166
|
-
`workspace`. A running instance never changes under itself
|
|
167
|
-
|
|
168
|
-
|
|
166
|
+
`workspace`. A running instance never changes under itself; a stopped one can
|
|
167
|
+
be moved to the locked package versions with `oats instance upgrade`. Member
|
|
168
|
+
modules and the soul body still require a new spawn. `oats status` shows the
|
|
169
|
+
drift (`member moved since (now @ …)` / `capability no longer present`). See
|
|
170
|
+
[upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
|
|
169
171
|
|
|
170
172
|
Instance-specific provider values belong to the spawn:
|
|
171
173
|
`oats spawn <soul> --provider <cap> key=value` (repeatable; dotted keys nest),
|