@awebai/oats 0.69.20 → 0.69.22
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 +26 -3
- package/docs/capabilities.md +1 -1
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +311 -4
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +404 -177
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/official-catalog.md +44 -1
- package/docs/packages.md +2 -2
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/tui.md +44 -4
- package/docs/upgrading.md +16 -5
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +5 -3
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +16 -0
- package/lib/instance-listing.mjs +8 -4
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/servers.mjs +8 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +3 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +62 -20
- package/packages/client/keymap.mjs +11 -3
- package/packages/client/remote-roster.mjs +8 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +283 -30
package/docs/desktop.md
CHANGED
|
@@ -268,31 +268,84 @@ workspace on a server: `name — server`).
|
|
|
268
268
|
|
|
269
269
|
## Workspaces
|
|
270
270
|
|
|
271
|
-
The sidebar, top to bottom: the **Workspace** heading, with **
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
**
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
271
|
+
The sidebar, top to bottom: the **Workspace** heading, with **Add local
|
|
272
|
+
workspace…** (the **+**) at its end, over the list of workspaces; a thin line;
|
|
273
|
+
two pinned rows, **Home** and **Automations**, drawn like the
|
|
274
|
+
instance rows (Automations shows a red dot, and says "a run failed", while a
|
|
275
|
+
schedule's last run failed: see [Scheduling agents](#scheduling-agents-and-wake-messages));
|
|
276
|
+
another line; **Agents**, a heading with the running count over the list of
|
|
277
|
+
agents; and, over a line, the foot, one bar: at its left **N need you**, the
|
|
278
|
+
number of this workspace's agents that need input (hidden when none does;
|
|
279
|
+
it takes you to the first of them, in the roster's order, expanding a collapsed
|
|
280
|
+
parent or opening the Background section to show it), and at its right
|
|
281
|
+
**New agent**, which opens the command palette on its souls (⌘P / Alt+P,
|
|
282
|
+
named in its tooltip) to pick a soul and then the spawn dialog, and **?**,
|
|
283
|
+
which opens the keyboard shortcuts. The foot has no mark, no Hide sidebar
|
|
284
|
+
button and no settings menu: ⌘B / Ctrl+Shift+B and the palette's **Sidebar:
|
|
285
|
+
toggle (hide/show)** hide the sidebar, and the palette's **Appearance…** and
|
|
286
|
+
**Keyboard shortcuts…** open the two sheets for the theme and the fonts, and
|
|
287
|
+
for the keys. A window opens on **Home**: at launch, and after you choose a workspace
|
|
288
|
+
for it. Connections is in the
|
|
289
|
+
command palette (**Connections**, among its sections), and the palette opens with its
|
|
290
|
+
shortcut or the leader (Ctrl+Space) then `k`.
|
|
291
|
+
**Home** answers two questions on one page: what needs you, and what you
|
|
292
|
+
have.
|
|
293
|
+
|
|
294
|
+
- **The board.** **Needs you** lists the agents waiting on you, each with its
|
|
295
|
+
message, newest first; **Running** lists the live ones, newest first. A
|
|
296
|
+
group with nobody in it isn't shown. Stopped agents aren't on the board, and
|
|
297
|
+
a live agent is "running": OATS doesn't report working or idle yet, and the
|
|
298
|
+
Desktop doesn't guess it. There is no "New" group yet either, since nothing
|
|
299
|
+
records which agents stopped or finished since you last looked. Enter (or a
|
|
300
|
+
click) on a row opens it as it does in the roster: a running agent's
|
|
301
|
+
terminal, a stopped one's Start.
|
|
302
|
+
- **The overview.** Agents, Souls, Capabilities, Teams, Machines and Graph,
|
|
303
|
+
each with what you have ("You have 4 souls"). Enter opens that part of the
|
|
304
|
+
Workspace page on its tab (the Machines canvas stands in for the Graph for
|
|
305
|
+
now), and Esc there comes back to Home. Agents opens **Home › Agents**: every
|
|
306
|
+
agent, running or stopped, with its soul and machine, its state, and who
|
|
307
|
+
started it (the person it's attributed to, or the agent that spawned it).
|
|
308
|
+
An agent waiting on you wears the needs-input mark there too, and says
|
|
309
|
+
"needs you". Esc or the **‹ Home** button returns.
|
|
310
|
+
- **A workspace with no agents yet** shows what OATS does in two lines and
|
|
311
|
+
three keys (New agent, the command palette, Home), then the overview.
|
|
312
|
+
|
|
313
|
+
Home has no key of its own yet: the palette's **Home** (among its sections)
|
|
314
|
+
opens it. The
|
|
315
|
+
board never changes the roster's order: urgency is sorted on Home only.
|
|
316
|
+
|
|
317
|
+
**The command palette** (⌘K / Alt+K) is the one place to reach everything.
|
|
318
|
+
It lists, in order: the agents that need you (the newest first), your recent
|
|
319
|
+
agents (the sidebar's tree, the one you used last on top), the sections
|
|
320
|
+
(Home, Workspace overview and its tabs, Automations, Connections), the commands,
|
|
321
|
+
and one **New agent: <soul>** row per soul. Type to narrow it; `>` keeps only
|
|
322
|
+
the commands and `+` only the souls.
|
|
323
|
+
|
|
324
|
+
**The status line** runs along the bottom of the window. It shows the three
|
|
325
|
+
keys most useful where you are (in the roster: Enter, Stop and the palette;
|
|
326
|
+
in a terminal: the leader, close tab and the palette), says in one line why a
|
|
327
|
+
key could not act (the leader's line is drawn there), says what was just done
|
|
328
|
+
("Workspace onboarded. The lock is written."), says when the terminal in front
|
|
329
|
+
loses its server and when it is back (the pane keeps its countdown and its
|
|
330
|
+
**Reconnect now**). It asks nothing: Stop, Start and Restart keep their
|
|
331
|
+
dialogs.
|
|
332
|
+
|
|
333
|
+
**The help sheet.** Press the leader (Ctrl+Space; Ctrl+X if you chose it) and a small sheet at the
|
|
334
|
+
bottom right lists the keys it takes where you are; the next key does its job
|
|
335
|
+
and the sheet goes. The leader then `?` keeps it open until Esc. To turn the
|
|
336
|
+
sheet off, untick **Show the help sheet when the leader is pressed** on the
|
|
337
|
+
Keyboard shortcuts sheet.
|
|
286
338
|
The instances have no search field: to find one by name, type it in the
|
|
287
339
|
command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
|
|
288
340
|
instance roster**) and `/` in the sidebar go to the roster's current row;
|
|
289
|
-
on an empty roster,
|
|
290
|
-
|
|
341
|
+
on an empty roster, which says "No agents yet · ⌘P starts one" (New
|
|
342
|
+
agent's key, Alt+P off macOS, as you bound it), to its one action, the foot's **New
|
|
343
|
+
agent**, where F6 lands too (a failed read's **Retry** comes first).
|
|
291
344
|
|
|
292
345
|
The sidebar is 288px wide, and you can make it wider or narrower: drag its
|
|
293
346
|
right edge, between 240px and 480px (or 45% of the window, when that is
|
|
294
347
|
less, so the terminals keep the rest). With the keyboard, Tab to that edge
|
|
295
|
-
(after the
|
|
348
|
+
(after the foot's **?**) and use ← and → (8px a step, 32px with Shift), Home
|
|
296
349
|
and End for the narrowest and the widest. A double-click on the edge, Enter
|
|
297
350
|
on it, or the command palette's **Sidebar: reset width** put it back to 288px.
|
|
298
351
|
The width is remembered on this computer, and kept while the sidebar is
|
|
@@ -300,45 +353,49 @@ hidden; a window too narrow for it shows it narrower, and gives it back when
|
|
|
300
353
|
the window grows again. The terminals refit as it moves, and their programs
|
|
301
354
|
hear the new size once, when you let go.
|
|
302
355
|
|
|
303
|
-
**
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
- **
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
Linux)
|
|
313
|
-
latest. On Windows it is the system's
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
names in the sidebar and on tabs are a little smaller in it (12px, from
|
|
318
|
-
12.5px), since a monospace face runs wider.
|
|
319
|
-
- **System font**, the faces Desktop had before: the system's interface font
|
|
320
|
-
for the window and Inconsolata in the terminals. It is the default on every
|
|
356
|
+
**Appearance.** The palette's **Appearance…** and ⇧⌘Space / Ctrl+Shift+Space
|
|
357
|
+
open the Appearance sheet, with three parts. **Theme**: System (Omarchy's theme on a computer that runs Omarchy, else
|
|
358
|
+
the system's light or dark setting; it was "This computer"), Dark, Light, and
|
|
359
|
+
More themes… (Solarized). **Font**, the terminals' font (the window's own
|
|
360
|
+
text is always the system's interface font):
|
|
361
|
+
|
|
362
|
+
- **This computer's monospace**, the default on a computer that runs Omarchy
|
|
363
|
+
(it was "Omarchy's font"). On Linux the terminals use the computer's
|
|
364
|
+
monospace font, the one `omarchy font current` names and `omarchy font set`
|
|
365
|
+
changes (fontconfig's `monospace`, on any Linux); a font changed that way
|
|
366
|
+
shows when Desktop next starts, at the latest. On Windows it is the system's
|
|
367
|
+
monospace font. It is not offered on macOS, where the terminals keep
|
|
368
|
+
Inconsolata.
|
|
369
|
+
- **System**: Inconsolata in the terminals. It is the default on every
|
|
321
370
|
computer that doesn't run Omarchy (other Linux, macOS and Windows).
|
|
371
|
+
- **Choose…**: a font family by name, as the palette's **Terminal: set font
|
|
372
|
+
family…**.
|
|
373
|
+
|
|
374
|
+
And **Terminal font size**, the same size as ⌘= / Ctrl+= change. A choice
|
|
375
|
+
applies at once and the sheet stays open; Esc closes it.
|
|
376
|
+
|
|
377
|
+
Changed in the next release: the window's own text no longer follows the font
|
|
378
|
+
choice. Before, Omarchy's font made the whole window monospace; now only the
|
|
379
|
+
terminals use it (D2 of the Desktop UI rework).
|
|
322
380
|
|
|
323
381
|
Desktop knows a computer runs Omarchy when Omarchy's theme directory
|
|
324
|
-
(`~/.local/state/omarchy/current`) is there, the same one the **
|
|
382
|
+
(`~/.local/state/omarchy/current`) is there, the same one the **System**
|
|
325
383
|
theme reads. A font you chose always wins over the default.
|
|
326
384
|
|
|
327
385
|
The terminal's size belongs to the face its terminals are in, since the same
|
|
328
|
-
size looks larger in a wider face.
|
|
386
|
+
size looks larger in a wider face. The computer's monospace in the terminals defaults to
|
|
329
387
|
13px (JetBrains Mono, Omarchy's default face, at 13px), and Inconsolata, with
|
|
330
|
-
System
|
|
388
|
+
System, on macOS or when the monospace shows Inconsolata, to
|
|
331
389
|
15px, on every computer. A size you set is kept for that face only, and a
|
|
332
390
|
font change never carries it to the other. Resetting the size or the zoom
|
|
333
391
|
goes back to the default of the face in use.
|
|
334
392
|
|
|
335
393
|
The computer's monospace font is used only once it draws at a fixed width.
|
|
336
|
-
Desktop checks it at start and on each choice in the
|
|
394
|
+
Desktop checks it at start and on each choice in the sheet. Where the
|
|
337
395
|
computer has no monospace font, or `monospace` names a bitmap font (which the
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
it draws.
|
|
396
|
+
terminals cannot draw), **This computer's monospace** shows Inconsolata, and its row
|
|
397
|
+
says **No monospace font on this computer: showing System**. The choice stays,
|
|
398
|
+
so the computer's font is used once it draws.
|
|
342
399
|
|
|
343
400
|
The choice is kept on this computer, like the theme, and applies at once:
|
|
344
401
|
open terminals switch font and take that face's size in place, and keep what
|
|
@@ -359,16 +416,10 @@ below, a line under the list says how many ("2 more below"), with the
|
|
|
359
416
|
needs-input mark at its right when one of them has an instance that needs
|
|
360
417
|
input.
|
|
361
418
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
|
|
367
|
-
Linux and Windows (the same in every chord family, and from a terminal) or the
|
|
368
|
-
palette's **Show only the current workspace**, to see every workspace again.
|
|
369
|
-
Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
|
|
370
|
-
shows alone. A window choosing a workspace shows them all. The choice is remembered on this
|
|
371
|
-
computer.
|
|
419
|
+
The list always shows every workspace: one is shown at a time by construction,
|
|
420
|
+
and everything under the list belongs to it. (**Show only the current
|
|
421
|
+
workspace** is gone, with its ⌥⇧⌘O / Ctrl+Alt+Shift+O and its palette command;
|
|
422
|
+
a choice saved for it is ignored.)
|
|
372
423
|
|
|
373
424
|
- **A row is one line: a circle and the workspace's name.** No icon, no
|
|
374
425
|
machine, no state: a workspace's own pages show its machines and
|
|
@@ -377,7 +428,8 @@ computer.
|
|
|
377
428
|
- **The current workspace** has its circle filled, like a running
|
|
378
429
|
instance's, and its name in bold; the others have the ring a stopped
|
|
379
430
|
instance has. It has no background of its own: the selection's background
|
|
380
|
-
marks the current page (
|
|
431
|
+
marks the current page (Home, whose row also stands for the Workspace page it
|
|
432
|
+
opens, or Automations), so the
|
|
381
433
|
sidebar fills one "you are here" row. A screen reader hears it as current,
|
|
382
434
|
and the list's description names it, by the same name as its row.
|
|
383
435
|
- **The needs-input mark.** A row has an exclamation mark (a small amber
|
|
@@ -391,7 +443,7 @@ computer.
|
|
|
391
443
|
deployment that isn't live (stale, not reached, its last read failed) and
|
|
392
444
|
an oats without `waiting-on-you`. The mark never moves a row: the order
|
|
393
445
|
stays the same whoever waits.
|
|
394
|
-
- **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+
|
|
446
|
+
- **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+Space then ↑ /
|
|
395
447
|
↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
|
|
396
448
|
in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
|
|
397
449
|
selection; one another window shows moves here ([A workspace another window
|
|
@@ -406,7 +458,7 @@ computer.
|
|
|
406
458
|
Windows does it from the keyboard. It opens the workspace in its own window,
|
|
407
459
|
or brings the window that shows it to the front.
|
|
408
460
|
- **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
|
|
409
|
-
`w` in the sidebar, Ctrl+
|
|
461
|
+
`w` in the sidebar, Ctrl+Space then `o`, ⌥⌘O / Alt+O and the palette's
|
|
410
462
|
**Workspace: switch…** focus it. The full keys are in [the keyboard
|
|
411
463
|
reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
|
|
412
464
|
|
|
@@ -454,40 +506,61 @@ other window.
|
|
|
454
506
|
|
|
455
507
|
## Capabilities and spawning
|
|
456
508
|
|
|
457
|
-
**Workspace › Capabilities**
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
509
|
+
**Workspace › Capabilities** lists every capability of the workspace as one
|
|
510
|
+
list of rows. Core capabilities (knowledge, messaging and tasks) come first,
|
|
511
|
+
in that order, each with a dim **core** tag; every other capability follows by
|
|
512
|
+
name. There are no sections, repository groups or colour marks. Each row
|
|
513
|
+
shows:
|
|
514
|
+
|
|
515
|
+
- the capability's name;
|
|
516
|
+
- who made it: a small ✓ in a circle for an official one (its tooltip says
|
|
517
|
+
which fact made it official: **Official: in the OATS catalog** or **Official:
|
|
518
|
+
from the OATS repository**), or **by** its source (a member repository's
|
|
519
|
+
name, or a git package's repository);
|
|
520
|
+
- one line of what it does (the manifest's description, cut to one line);
|
|
521
|
+
- its tags: **core**, **default** for one the workspace gives every soul,
|
|
522
|
+
**default · off** for one the workspace turns off, and **repo only** for one
|
|
523
|
+
only its own repository's souls can use.
|
|
524
|
+
|
|
525
|
+
A capability is official by a rule of the Desktop over what the kernel
|
|
526
|
+
already reports: a package the workspace pins from the catalog
|
|
527
|
+
(`oats workspace status` reports its source as `catalog:<id>`), or a
|
|
528
|
+
capability of the OATS repository itself. Its name proves nothing. The mark
|
|
529
|
+
says only that: it is not a trust claim, since being listed is not being
|
|
530
|
+
trusted. Its limit: `OATS_PACKAGE_CATALOG` can point the kernel at another
|
|
531
|
+
catalog file, and workspace status doesn't say which catalog was read, so an
|
|
532
|
+
operator who points it elsewhere sees that catalog's packages marked official.
|
|
533
|
+
A kernel fact for "official" is
|
|
534
|
+
[oats-project/oats#1981](https://github.com/oats-project/oats/issues/1981). A package's
|
|
535
|
+
name and version are not on this list: **Setup**'s Packages box shows them,
|
|
536
|
+
and so does the capability's page.
|
|
537
|
+
|
|
538
|
+
One sentence above the list says what defaults are: the capabilities the
|
|
539
|
+
workspace gives every soul, so its agents share one way of working. A soul
|
|
540
|
+
can turn a default off and choose its own instead. The sentence also says
|
|
541
|
+
which core slot no default fills, and names a declared default the list can't
|
|
542
|
+
show as a row. A workspace that sets no defaults (a standalone deployment, for
|
|
543
|
+
example) says so in that sentence. The search never narrows it. It is read
|
|
544
|
+
from `oats workspace status --json`: an OATS that doesn't report the defaults
|
|
545
|
+
shows no sentence and no tag, and the Desktop doesn't guess them from the
|
|
546
|
+
souls. The defaults are declared in the workspace file; the page only shows
|
|
547
|
+
them. Teams add no capabilities (removed in 0.30).
|
|
548
|
+
|
|
549
|
+
↑ and ↓ move along the rows, and Enter opens a capability's page. The page
|
|
550
|
+
reads top to bottom:
|
|
551
|
+
|
|
552
|
+
- its name, its tags, and one line on where it comes from (who made it, then
|
|
553
|
+
the package and its pinned version, or the repository at its latest);
|
|
554
|
+
- **what it does**, as one paragraph;
|
|
555
|
+
- **Skills**: each skill's name and one line. Enter opens the whole skill in
|
|
556
|
+
the pane, read-only: its front matter as a table, then its text, with its
|
|
557
|
+
other files a press away. Esc returns to the capability;
|
|
558
|
+
- then, folded, each only when there is something to show: **Commands**,
|
|
559
|
+
**Settings** and the soul's **As <soul> resolves it** (opened from a soul),
|
|
560
|
+
**Triggers**, **Hooks**, **Used by**, **Comes from** (the commit,
|
|
561
|
+
fingerprint, path and manifest file) and **Files** (the injected
|
|
562
|
+
instructions and every skill file, in a tree with a reader). Enter or Space
|
|
563
|
+
unfolds one, and a fold stays open while the page refreshes.
|
|
491
564
|
|
|
492
565
|
The round **i** button in the toolbar, beside the search (**About capabilities**), opens
|
|
493
566
|
**What capabilities are**: what a capability gives a soul's instances (skills,
|
|
@@ -501,43 +574,86 @@ way of working, and a knowledge default keeps what agents learn and the
|
|
|
501
574
|
procedures the organisation writes down for later instances; a soul can turn
|
|
502
575
|
one off and name its own in its place.
|
|
503
576
|
**Close** or Esc closes it and returns the focus to the button; leaving the
|
|
504
|
-
tab or the workspace closes it too.
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
577
|
+
tab or the workspace closes it too.
|
|
578
|
+
|
|
579
|
+
**Workspace › Souls** lists the souls the workspace offers. Its first line says
|
|
580
|
+
what a soul is. The souls are grouped by where they come from: the workspace's
|
|
581
|
+
own repository first, then its other member repositories, then each package,
|
|
582
|
+
then the external souls. Inside a group they are in kind order: maintainers,
|
|
583
|
+
experts, developers, operations, then the rest, each by name. The kind is read
|
|
584
|
+
from the soul's name (`packages/client/soul-role.mjs`): a name with a word
|
|
585
|
+
`setup`, `operator`, `admin`, `ops` or `operations` is operations; else a name
|
|
586
|
+
ending in `-maintainer`, `-expert` or `-developer` is that; else other. OATS
|
|
587
|
+
reports no role for a soul yet, so the name is the rule until it does
|
|
588
|
+
([#1980](https://github.com/oats-project/oats/issues/1980)).
|
|
589
|
+
|
|
590
|
+
The souls show as a grid of cards or as a table: **v** (or **Grid** | **Table**
|
|
591
|
+
in the toolbar) switches between them, and each window remembers its choice,
|
|
592
|
+
also after a restart. A card shows the soul's name, what it does, how many of
|
|
593
|
+
its agents run, and its kind; a soul a spawn here would refuse also says why,
|
|
594
|
+
above its count. The table has the same souls as rows: name, what it does, kind,
|
|
595
|
+
agents running, harness · model, and **Ready** (or why a spawn here would be
|
|
596
|
+
refused; **—** when this OATS does not report it). A card or a row's name
|
|
597
|
+
opens the soul's page. A new agent of a soul starts from **New agent** on its
|
|
598
|
+
page, from Quick Open, or from the palette. Souls of a member repository that
|
|
599
|
+
has not confirmed its membership are listed last, under **Not available**,
|
|
600
|
+
with the reason; they open nothing.
|
|
601
|
+
|
|
602
|
+
A soul's page (open a soul from **Workspace › Souls**) is one column. Under its
|
|
603
|
+
name and what it does, a block of facts: **Harness · model** (what a spawn here
|
|
604
|
+
runs, and where that choice came from), **Teams** (the teams its agents may
|
|
605
|
+
join, the default marked; with team model v2, **Teams on this computer** folds
|
|
606
|
+
out the editable list), **Knowledge** (the nodes it owns and reads, when it
|
|
607
|
+
declares any) and **Ready**: the word, or the one thing that stops a spawn here
|
|
608
|
+
in one sentence, with **Details** folded under it (the problem in full and its
|
|
609
|
+
code, and the soul's readiness checks, read when you open it). Its capability
|
|
610
|
+
warnings follow. Its agents are not listed: the Souls grid and table count
|
|
611
|
+
them, and the roster lists them.
|
|
612
|
+
|
|
613
|
+
Then **Capabilities**, one list of rows: the core capabilities first (knowledge,
|
|
614
|
+
messaging, tasks), each with a dim **core** tag, then the others in the order
|
|
615
|
+
the workspace composes them. Each row has the capability's name, **by** where it
|
|
616
|
+
comes from, and one line of what it does (its description in the workspace's
|
|
617
|
+
catalog). Enter or a click opens the capability's page; ↑ and ↓ move between
|
|
618
|
+
the rows. What the soul turns off, and a core slot left empty, are one line
|
|
619
|
+
under the list.
|
|
620
|
+
|
|
621
|
+
Then its two prompts, as two tabs: **Soul instructions** (the soul's own
|
|
622
|
+
`AGENTS.md`, at its path in the soul's repository) and **Composed
|
|
623
|
+
instructions** (what its agents are actually told). The tabs are one stop for
|
|
624
|
+
Tab; ← and → (or Home and End) switch them. Each tab is a reader at a readable
|
|
625
|
+
width, with its sections listed on its left when the page is wide enough: the
|
|
626
|
+
own file's headings, the composed document's parts.
|
|
627
|
+
|
|
628
|
+
Under the tabs, **Skills** folds out the soul's skills, with an OATS that
|
|
629
|
+
reports them, in two sections:
|
|
630
|
+
|
|
631
|
+
- **Defined in this soul**: its own skills. Open a skill to list its files; a
|
|
632
|
+
file opens in the reader beside the list, under its repository path.
|
|
633
|
+
- **Every skill an agent gets**: each saying where it comes from. With an OATS
|
|
634
|
+
that lists every skill a spawn gives the agent (0.67.0 and later), that list:
|
|
635
|
+
the soul's own, each **From this soul**, and the ones its capabilities add,
|
|
636
|
+
each **From** the capability. A capability's skill file opens under its place
|
|
637
|
+
in the agent's home (`.oats/modules/<capability>/…`), with **Open
|
|
638
|
+
capability** above it. With an older OATS the skills listed are the soul's
|
|
639
|
+
own, and a note says that the skills capabilities add are listed by a newer
|
|
640
|
+
OATS. For a soul on another machine, the server's OATS must list them too, as
|
|
641
|
+
for the composed instructions below.
|
|
642
|
+
|
|
643
|
+
A link in either document to a listed skill file opens it there. Everything on
|
|
644
|
+
the page comes from the same inspection, so **Refresh** re-reads it and keeps
|
|
645
|
+
what you had open, and your place in it. A file over 200,000 characters is
|
|
646
|
+
shown cut, and says so.
|
|
647
|
+
|
|
648
|
+
The composed instructions need an OATS that composes a soul's instructions
|
|
649
|
+
(0.46.0 and later); without one, the tab says so. They are the `AGENTS.md` a
|
|
650
|
+
spawn of this soul on this computer would write, one section per part (the
|
|
651
|
+
soul's own text, then each block OATS and the soul's capabilities add, in
|
|
652
|
+
order). Each part's header says where it comes from (**From this soul** or
|
|
653
|
+
**Injected by …**) and names its file; a capability's part has **Open
|
|
654
|
+
capability**, and **Copy composed AGENTS.md** copies the exact file. When the
|
|
655
|
+
soul can't be composed here, the tab says so and the problem is the page's
|
|
656
|
+
**Ready** line. For a soul on another machine (a server
|
|
541
657
|
workspace), the page shows the composed file when that machine supports it:
|
|
542
658
|
this computer's OATS must be 0.49.0 or later, to pass on what each server
|
|
543
659
|
reports about itself, and the server's OATS must say it composes a soul's
|
|
@@ -623,6 +739,13 @@ same themed look, and its open list follows the light or dark theme.
|
|
|
623
739
|
|
|
624
740
|
## Stopping and retiring
|
|
625
741
|
|
|
742
|
+
Stop and Retire open a centred sheet with what Desktop has read they will
|
|
743
|
+
do: Stop's children, and for Retire what goes (the home, the worktree and its
|
|
744
|
+
uncommitted work, the branch and pull request it leaves alone). After you
|
|
745
|
+
confirm a retire, the row reads Retiring…, then a dim "✕ name · retired" row
|
|
746
|
+
stays in its place for ten seconds. Start and Restart open their dialog, with
|
|
747
|
+
the harness, permissions and model.
|
|
748
|
+
|
|
626
749
|
The Desktop runs one stop or retire at a time for its own requests. Another
|
|
627
750
|
program using OATS at the same time, such as the `oats` command or the
|
|
628
751
|
terminal client, is held off by OATS itself: from OATS 0.52.0, a stop and a
|
|
@@ -746,7 +869,12 @@ pattern and time zone; new agent jobs also offer harness, model, permissions
|
|
|
746
869
|
and session backend. The list shows the next run, last observed outcome and
|
|
747
870
|
whether the host scheduler is enabled. Pause, edit, run now and delete operate
|
|
748
871
|
on that workspace's saved jobs. Launching an agent is reported separately from
|
|
749
|
-
the end of its run; neither means its task succeeded.
|
|
872
|
+
the end of its run; neither means its task succeeded. While a schedule's last
|
|
873
|
+
run is **launch failed** or **invalid**, the sidebar's **Automations** shows a
|
|
874
|
+
red dot, and a screen reader hears "Automations, a run failed"; it clears once
|
|
875
|
+
no last run has failed. The sidebar reads both lists when the workspace opens
|
|
876
|
+
and then at most once a minute. A trigger's last run carries no outcome, so a
|
|
877
|
+
trigger never marks it.
|
|
750
878
|
|
|
751
879
|
Each schedule and trigger can carry a one-line **summary** (up to 200
|
|
752
880
|
characters), shown under its name in the list. Without one, the list shows the
|
|
@@ -789,14 +917,21 @@ the CLI, cron semantics, observed outcomes and recovery commands.
|
|
|
789
917
|
|
|
790
918
|
## A workspace's teams and setup
|
|
791
919
|
|
|
792
|
-
The Workspace › **Teams** tab has
|
|
920
|
+
The Workspace › **Teams** tab has two sections. **Workspace teams** are the
|
|
921
|
+
teams the workspace declares in `oats-workspace.yaml`: everyone who opens the
|
|
922
|
+
workspace sees them. **This computer's teams** are the teams declared only on
|
|
923
|
+
this computer, in its `oats-local.yaml` (the kernel's local teams), not
|
|
924
|
+
shared with the workspace. Each section says so in one sentence, and a team's
|
|
925
|
+
page lists **your agents** on it, on this computer and the machines added to
|
|
926
|
+
this workspace, never the team's whole membership. The Teams tab has one card per team. Under its description,
|
|
793
927
|
**Default for** says whose default the team is: all souls of a repository, a
|
|
794
928
|
single soul, or every soul without its own default for the default team. **May
|
|
795
929
|
join** says who else may join it. Both are read from the workspace's committed
|
|
796
930
|
`souls:`; a team nobody may join yet says so. The address (the team on the
|
|
797
931
|
messaging provider) and the members running in it follow.
|
|
798
932
|
|
|
799
|
-
The **Setup** tab
|
|
933
|
+
The **Setup** tab is one list, in one column (its graph view went in the
|
|
934
|
+
Desktop UI rework). Under the workspace's name, one
|
|
800
935
|
line counts its members (and those that need attention), its packages and the
|
|
801
936
|
state of the lock. The next line says where the workspace is declared. An
|
|
802
937
|
**Overview** says that the workspace's **host**, the repository that holds
|
|
@@ -804,9 +939,12 @@ state of the lock. The next line says where the workspace is declared. An
|
|
|
804
939
|
packages. **For developers** (folded) explains how a repository becomes a
|
|
805
940
|
member and what each member state means. Then **Shared through Git** lists
|
|
806
941
|
what the workspace declares (Members, with the host first and tagged
|
|
807
|
-
**Host**, Packages and Defaults).
|
|
808
|
-
|
|
809
|
-
the
|
|
942
|
+
**Host**, Packages and Defaults). Each member's **Details** (or **Why?**, when
|
|
943
|
+
its handshake needs attention) opens its panel under its row: both sides of
|
|
944
|
+
the handshake, what it means now, its capabilities by name and the kernel's
|
|
945
|
+
own detail. **This computer** lists what is not shared: this deployment's
|
|
946
|
+
settings, lock, CLI and agents, and the member clones. The machines that run
|
|
947
|
+
the workspace are the **Machines** tab's.
|
|
810
948
|
|
|
811
949
|
## A workspace's machines
|
|
812
950
|
|
|
@@ -814,12 +952,17 @@ A window offers only the machines that run its workspace: those whose
|
|
|
814
952
|
registration reports the same workspace key as the window's deployment on this
|
|
815
953
|
computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
|
|
816
954
|
spawn dialog's **Where to run** lists "This computer" and those machines; the
|
|
817
|
-
Workspace ›
|
|
818
|
-
|
|
819
|
-
|
|
955
|
+
Workspace › **Machines** tab lists the computers the workspace runs on: this
|
|
956
|
+
computer first (where the view has a deployment here: "reading…" or "not read"
|
|
957
|
+
until it is read), then each of those machines, with whether it can be reached
|
|
958
|
+
and its OATS version. A remote-only view lists its machines' deployments
|
|
959
|
+
instead. The Map and the roster show where agents run; the list counts none.
|
|
960
|
+
Enter on a machine opens it: its name, ssh host and folder,
|
|
961
|
+
**Check** and **Remove**. Registrations whose key is not known yet are checked
|
|
962
|
+
once in the background after the Desktop starts.
|
|
820
963
|
|
|
821
964
|
**Add a machine to this workspace…** (the last entry of Where to run, and a
|
|
822
|
-
button
|
|
965
|
+
button on the Machines tab) takes an ssh host alias, a name, the folder on that machine
|
|
823
966
|
and whether to install OATS there, and runs `oats server connect` from this
|
|
824
967
|
deployment; when the workspace uses oats.aweb for messaging, it then runs `oats
|
|
825
968
|
aweb connect` to join that machine to the workspace's team. Each step shows as
|
|
@@ -969,39 +1112,72 @@ error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
|
969
1112
|
## The sidebar's instance tree
|
|
970
1113
|
|
|
971
1114
|
The sidebar lists a workspace's instances as a tree: a child sits one step
|
|
972
|
-
right of its parent, and related instances are grouped together
|
|
973
|
-
|
|
974
|
-
|
|
1115
|
+
right of its parent, and related instances are grouped together, with a little
|
|
1116
|
+
space before the next group. The sidebar draws no lines between them: the
|
|
1117
|
+
indent and that space show the tree. A screen reader hears each row's state ("running", "stopped" or "status
|
|
1118
|
+
unknown") after its two lines, then each child "under"
|
|
1119
|
+
its parent, with "same work" when its host reports it doing its parent's work,
|
|
1120
|
+
and each instance linked as a sibling "sibling of" the other, after the row's
|
|
1121
|
+
two lines.
|
|
1122
|
+
|
|
1123
|
+
The sidebar shows the top-level instances only until you open one. An
|
|
1124
|
+
instance with children has a chevron right after its name, with the number
|
|
1125
|
+
of instances under it at every depth, so every name at a level starts at the
|
|
1126
|
+
same place. Click the chevron to show its group as
|
|
1127
|
+
it was drawn before, and click it again to hide the group. A click anywhere
|
|
1128
|
+
else on the row still opens its terminal. From the keyboard, Right opens the
|
|
1129
|
+
focused row and Left closes it. Every instance at the top of the tree, the
|
|
1130
|
+
[Background section](#background-instances)'s included, starts collapsed in
|
|
1131
|
+
each new window, except one still being set up or retired, or whose retire
|
|
1132
|
+
failed: while its row shows that state, it has no chevron and its group
|
|
1133
|
+
stays open, so an instance under it that needs input is never hidden. A
|
|
1134
|
+
group that holds a pinned instance, its top instance included, starts open
|
|
1135
|
+
too, so the pin is seen with its group ([Pinned instances](#pinned-instances));
|
|
1136
|
+
close it and it stays closed. An instance inside a group starts open, and each one with
|
|
1137
|
+
children has its own chevron. What you open or close stays as you left it
|
|
1138
|
+
until the window closes. **Show in roster**, `--instance` and a spawn from
|
|
1139
|
+
the Desktop open the rows above the instance they show. The TUI's list still
|
|
1140
|
+
shows every instance open.
|
|
975
1141
|
|
|
976
1142
|
The newest instance is on top: the tree is in spawn order, newest first, at
|
|
977
|
-
every level. A
|
|
1143
|
+
every level. A little space separates each top-level group (an instance with
|
|
1144
|
+
its children and the siblings joined to it) from the next; the order never
|
|
1145
|
+
changes for it. A group of related instances sits where its first instance's
|
|
978
1146
|
spawn time puts it, so spawning a child doesn't move the group, and starting
|
|
979
1147
|
or stopping an instance moves nothing. Instances spawned at the same moment
|
|
980
1148
|
are in name order, and an instance whose spawn time can't be read comes after
|
|
981
|
-
every one whose time can.
|
|
1149
|
+
every one whose time can. Pinned instances come before all of these, at every
|
|
1150
|
+
level ([Pinned instances](#pinned-instances)).
|
|
982
1151
|
|
|
983
|
-
|
|
1152
|
+
Children that do their parent's work come first under it. When the instances'
|
|
984
1153
|
OATS has the `instance-same-work` feature, a child the kernel reports as doing
|
|
985
1154
|
its parent's work (`sameWork: true` in its row, set with `oats spawn …
|
|
986
|
-
--same-work` or `oats instance same-work <instance> on`) is
|
|
987
|
-
parent
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
its
|
|
994
|
-
host must report the feature too, through an installed OATS with
|
|
995
|
-
`server-probe-features`. A host without the feature, or one whose features are
|
|
996
|
-
not known (its last read failed), keeps a line to every child. A spawn from the
|
|
997
|
-
Desktop never sets the flag.
|
|
1155
|
+
--same-work` or `oats instance same-work <instance> on`) is listed before its
|
|
1156
|
+
parent's other children, each part newest first. The command palette still
|
|
1157
|
+
draws lines: there a parent's line joins only those children (siblings by a
|
|
1158
|
+
dotted line through their dots), in its own recency order inside each part.
|
|
1159
|
+
For another machine's instances, its host must report the feature too, through
|
|
1160
|
+
an installed OATS with `server-probe-features`. A host without the feature, or
|
|
1161
|
+
one whose features are not known (its last read failed), lists every child as
|
|
1162
|
+
doing its parent's work. A spawn from the Desktop never sets the flag.
|
|
998
1163
|
|
|
999
1164
|
A row shows the instance's name as words: each `-` is a space, and the first
|
|
1000
1165
|
letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
|
|
1001
|
-
maintainer lanes". Only the row's label changes. The
|
|
1002
|
-
palette (which still finds the instance by its name), its terminal tab,
|
|
1003
|
-
screen reader and the `oats` CLI all use the instance's real name. The TUI's
|
|
1004
|
-
sidebar shows the same words.
|
|
1166
|
+
maintainer lanes". Only the row's label changes. The instance panel, the
|
|
1167
|
+
command palette (which still finds the instance by its name), its terminal tab,
|
|
1168
|
+
a screen reader and the `oats` CLI all use the instance's real name. The TUI's
|
|
1169
|
+
sidebar shows the same words. A long name is cut at its end with "…".
|
|
1170
|
+
|
|
1171
|
+
A row's second line says its soul and the machine it runs on, "oats-expert ·
|
|
1172
|
+
falcon", or the machine alone when its soul isn't known. This computer's rows
|
|
1173
|
+
name it by the host name OATS records for it (`host.name` in its
|
|
1174
|
+
`oats-local.yaml`); with none recorded, they say "This Mac". A limit for now:
|
|
1175
|
+
the Desktop learns that name from its Automations read, so these rows say
|
|
1176
|
+
"This Mac" until that read answers, and keep saying it where the installed
|
|
1177
|
+
OATS serves no automations ([#1972](https://github.com/oats-project/oats/issues/1972)
|
|
1178
|
+
tracks reading it from the status answer instead). That's all a row
|
|
1179
|
+
says: its repository, branch, pull request and harness are in the instance
|
|
1180
|
+
panel. Rows are 44px tall, the dot centred on the row.
|
|
1005
1181
|
|
|
1006
1182
|
A row's dot says the instance's state: filled while it runs, a ring when it is
|
|
1007
1183
|
stopped, a grey ring with a small grey centre when its state is unknown (the
|
|
@@ -1011,18 +1187,26 @@ instance that needs input (a running session's claim, from OATS with the
|
|
|
1011
1187
|
slightly larger amber disc with a "!" cut out of it, the mark its terminal tab
|
|
1012
1188
|
and the workspace list show. Amber means needs input and nothing else.
|
|
1013
1189
|
Elsewhere, a dot that flags a problem is red: a keyboard shortcut that clashes
|
|
1014
|
-
with another (on the
|
|
1015
|
-
Workspace page's tabs),
|
|
1016
|
-
scheduler that is off.
|
|
1017
|
-
The row keeps its soul and
|
|
1018
|
-
hears "Needs input" after the name,
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1190
|
+
with another (on the foot's **?**), Setup or Teams needing attention (on the
|
|
1191
|
+
Workspace page's tabs), the sidebar's **Automations** while a last run failed,
|
|
1192
|
+
and an automation that doesn't run here or a scheduler that is off.
|
|
1193
|
+
The row keeps its soul and machine on its second line. A screen reader
|
|
1194
|
+
hears "Needs input" after the name, then the reason and when it started
|
|
1195
|
+
waiting; the instance panel's **Needs input** section gives the reason, how
|
|
1196
|
+
long it has waited and the agent's message. A collapsed parent shows "! N
|
|
1197
|
+
below" on its second line for the rows it hides that need input, beside its
|
|
1198
|
+
own mark when it waits too. Rows never move or grow, and nothing animates. The
|
|
1199
|
+
row has no hover card: its facts are the instance panel's, and a row's error
|
|
1200
|
+
("OATS says: the last start failed") is its tooltip and its description. Until
|
|
1201
|
+
the panel serves a row with no terminal open, the row's tooltip also says its
|
|
1202
|
+
repository, branch, harness and model; a screen reader doesn't hear these on
|
|
1203
|
+
the row, so with the keyboard alone they show once the row's terminal is
|
|
1204
|
+
open.
|
|
1022
1205
|
|
|
1023
1206
|
A row has no ⋯ button. Its actions (Open in split, Open pull request…,
|
|
1024
1207
|
Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…,
|
|
1025
|
-
Move to background or out of it ([Background instances](#background-instances)),
|
|
1208
|
+
Move to background or out of it ([Background instances](#background-instances)),
|
|
1209
|
+
Pin to top or Unpin ([Pinned instances](#pinned-instances)), and
|
|
1026
1210
|
Forget… for an instance its server no longer lists) are in the row's context
|
|
1027
1211
|
menu (right-click, Shift+F10 or the ContextMenu key), as a workspace row's are.
|
|
1028
1212
|
It opens where you right-click, or on the row from the keyboard; the arrow keys,
|
|
@@ -1030,8 +1214,9 @@ Home and End move in it, and Esc or Tab close it with the focus back on the
|
|
|
1030
1214
|
row. A right-click never opens the row's terminal. While the menu can't be used
|
|
1031
1215
|
(the roster is out of date, one of its actions is still running, or the row
|
|
1032
1216
|
can't be used from this computer), it opens nothing, and one line at the
|
|
1033
|
-
bottom of the main area says why, as a leader key that can't act does.
|
|
1034
|
-
|
|
1217
|
+
bottom of the main area says why, as a leader key that can't act does. A row
|
|
1218
|
+
draws no tools of its own: its pull request opens with **Open pull request…**,
|
|
1219
|
+
and a stopped row starts with **Start…**, both in its menu.
|
|
1035
1220
|
|
|
1036
1221
|
## Background instances
|
|
1037
1222
|
|
|
@@ -1077,6 +1262,47 @@ and for an instance on a server, on that server too. With an older OATS the
|
|
|
1077
1262
|
sidebar lists every instance in the main tree, and the switch and the menu
|
|
1078
1263
|
items are not shown.
|
|
1079
1264
|
|
|
1265
|
+
## Pinned instances
|
|
1266
|
+
|
|
1267
|
+
A pinned instance is listed at the top of its machine's list, so the agents
|
|
1268
|
+
you come back to stay in reach. A pin changes only the order. The instance
|
|
1269
|
+
starts, opens, takes input and retires as any other.
|
|
1270
|
+
|
|
1271
|
+
- **The order.** Pinned instances come first at every level of the tree: the
|
|
1272
|
+
groups of a machine's list, the instances of a group, and the children of
|
|
1273
|
+
one parent. An instance counts as pinned when it or any instance below it
|
|
1274
|
+
is pinned. Pinning a child lifts its whole group to the top of its
|
|
1275
|
+
machine's list, and the path down to it rises among its siblings. A group
|
|
1276
|
+
that holds a pinned instance, its top instance included, doesn't start
|
|
1277
|
+
collapsed, so the pin is seen with its group; closed by hand, it stays
|
|
1278
|
+
closed until you open it. Among
|
|
1279
|
+
pinned instances the usual order stands: spawn time, newest first. There
|
|
1280
|
+
is no manual order. Under one parent, the children joined by the parent's
|
|
1281
|
+
line still come first ([the tree](#the-sidebars-instance-tree)). A pinned instance
|
|
1282
|
+
in the Background section is first in that section's own tree. A pinned
|
|
1283
|
+
child whose parent is on another machine is first only in its own
|
|
1284
|
+
machine's list. A filter never reorders the list. The command palette
|
|
1285
|
+
lists the instances you have focused by recency, as before, and every
|
|
1286
|
+
other instance in this order.
|
|
1287
|
+
- **The mark.** A pinned row shows a small pin after its name. A screen
|
|
1288
|
+
reader hears "Pinned" with the row's name. An instance that is listed
|
|
1289
|
+
first only because one below it is pinned carries no pin.
|
|
1290
|
+
- **Pinning.** A row's context menu offers **Pin to top**, or **Unpin** on a
|
|
1291
|
+
pinned instance, which runs `oats instance pin <name> on|off`. Each is an
|
|
1292
|
+
act at once, with no dialog. The row moves when the roster is next read,
|
|
1293
|
+
right after the change. The command palette offers **Agent: Pin to
|
|
1294
|
+
top** or **Agent: Unpin** for the instance the leader keys act on. An
|
|
1295
|
+
instance that is held (spawning, or being retired) offers neither.
|
|
1296
|
+
- **Shared.** The pin is kept in the instance's home, so everyone who views
|
|
1297
|
+
that machine sees the same pins, in the Desktop, the TUI and another
|
|
1298
|
+
machine's view. There is no pin of your own. Retiring a pinned instance
|
|
1299
|
+
removes its pin with it.
|
|
1300
|
+
|
|
1301
|
+
This needs OATS with the `instance-pin` feature on this computer, and for an
|
|
1302
|
+
instance on a server, on that server too. With an older OATS the list keeps
|
|
1303
|
+
its usual order, no row shows a pin, and the menu items and palette commands
|
|
1304
|
+
are not shown.
|
|
1305
|
+
|
|
1080
1306
|
## An instance's colour
|
|
1081
1307
|
|
|
1082
1308
|
An instance can have a colour, one of the soul palette's six (Sand, Sage,
|
|
@@ -1128,9 +1354,9 @@ letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-maintainer` KM and
|
|
|
1128
1354
|
`oats.aweb` OA. Two names can share a mark (`oats-expert` and
|
|
1129
1355
|
`oats-operator-expert` are both OE); the name and the colour tell them apart.
|
|
1130
1356
|
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1357
|
+
Soul cards, the soul page, the context panel and the spawn dialog show each
|
|
1358
|
+
instance's or soul's harness as a small badge, next to its name (a roster row
|
|
1359
|
+
doesn't: its second line is its soul and machine). The badge names the harness the CLI reports; it says nothing about
|
|
1134
1360
|
whether that harness is installed or signed in. Pi's badge is the official
|
|
1135
1361
|
pi.dev press-kit mark (MIT), and Claude Code's is Anthropic's Claude spark
|
|
1136
1362
|
in the theme's colours. The Codex badge is OATS's own drawing, not OpenAI's
|
|
@@ -1219,11 +1445,12 @@ and adds fresh AppImage probes with `--dir <fixture> --instance smoke-probe`,
|
|
|
1219
1445
|
asserting main's selection-request diagnostic. Repeated launches of the same
|
|
1220
1446
|
arguments reach the running app. Both launches of the running fixture must
|
|
1221
1447
|
open its terminal tab in the main area while keeping keyboard focus on its
|
|
1222
|
-
roster row. Before the repeated running launch, the smoke switches to
|
|
1223
|
-
|
|
1448
|
+
roster row. Before the repeated running launch, the smoke switches to Home,
|
|
1449
|
+
then requires that launch to reactivate the retained tab with exactly
|
|
1224
1450
|
one viewer and no terminal focus event. CDP sends a key to the window;
|
|
1225
1451
|
independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
|
|
1226
|
-
only, with no tab or Start dialog, on
|
|
1452
|
+
only, with no tab or Start dialog, on Home (its row current and its view
|
|
1453
|
+
shown, since Home's row also stands for the Workspace page). The smoke also
|
|
1227
1454
|
asserts that viewer cleanup restores its private tmux baseline. The fixture's
|
|
1228
1455
|
workspace/member source, soul definition and inert harness executable are authored by the test-only
|
|
1229
1456
|
[`launch-fixture.mjs`](../packages/desktop/test/helpers/launch-fixture.mjs).
|