@awebai/oats 0.69.22 → 0.69.24
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +151 -17
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
package/docs/desktop.md
CHANGED
|
@@ -270,7 +270,7 @@ workspace on a server: `name — server`).
|
|
|
270
270
|
|
|
271
271
|
The sidebar, top to bottom: the **Workspace** heading, with **Add local
|
|
272
272
|
workspace…** (the **+**) at its end, over the list of workspaces; a thin line;
|
|
273
|
-
|
|
273
|
+
three pinned rows, **Home**, **Workspace** and **Automations**, drawn like the
|
|
274
274
|
instance rows (Automations shows a red dot, and says "a run failed", while a
|
|
275
275
|
schedule's last run failed: see [Scheduling agents](#scheduling-agents-and-wake-messages));
|
|
276
276
|
another line; **Agents**, a heading with the running count over the list of
|
|
@@ -288,42 +288,63 @@ for the keys. A window opens on **Home**: at launch, and after you choose a work
|
|
|
288
288
|
for it. Connections is in the
|
|
289
289
|
command palette (**Connections**, among its sections), and the palette opens with its
|
|
290
290
|
shortcut or the leader (Ctrl+Space) then `k`.
|
|
291
|
-
**Home** answers two questions on one
|
|
292
|
-
have.
|
|
293
|
-
|
|
294
|
-
- **
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
291
|
+
**Home** answers two questions on one screen: what needs you, and what you
|
|
292
|
+
have. It is one centred column. Top to bottom:
|
|
293
|
+
|
|
294
|
+
- **Needs you.** The agents waiting on you, newest first: each with the
|
|
295
|
+
needs-input mark, its name, its soul and machine, and its message. Enter (or
|
|
296
|
+
a click) opens one as it does in the roster. Eight show at most, then **Show
|
|
297
|
+
all N**, which shows the rest in place. With none, one quiet line says
|
|
298
|
+
"Nothing needs you."
|
|
299
|
+
- **One summary line**, such as "24 agents · 21 running · 3 need you · 0
|
|
300
|
+
stopped" (and how many have no known state, when some don't). A live agent
|
|
301
|
+
is "running": OATS doesn't report working or idle yet, and the Desktop
|
|
302
|
+
doesn't guess it.
|
|
303
|
+
- **The workspace, as one row of tiles**, each a button with its count:
|
|
304
|
+
**Agents**, **Souls**, **Capabilities**, **Teams**, **Machines** and
|
|
305
|
+
**Automations** (with the sidebar row's red dot while a run failed). A count
|
|
306
|
+
still being read says "Counting…", and one that couldn't be read says so;
|
|
307
|
+
nothing is guessed. Enter opens that part of the Workspace page on its tab
|
|
308
|
+
(Machines on its List), and Esc there comes back to Home; Automations opens
|
|
309
|
+
its page. Agents opens **Home › Agents**: every agent, running or stopped, in
|
|
310
|
+
the sidebar's order (pinned ones first), with its soul and machine, its
|
|
311
|
+
state, and who started it (the person it's attributed to, or the agent that
|
|
312
|
+
spawned it). An agent waiting on you wears the needs-input mark there too,
|
|
313
|
+
and says "needs you". Esc or the **‹ Home** button returns.
|
|
314
|
+
- **Running**, under the tiles: the first five running agents, in the
|
|
315
|
+
sidebar's order, then **Show all N running**, which shows the rest in place
|
|
316
|
+
(and **Show fewer** folds them back). The heading says they run; no row
|
|
317
|
+
repeats it.
|
|
310
318
|
- **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
|
|
312
|
-
|
|
313
|
-
Home has no key of its own yet: the palette's **Home** (among its
|
|
314
|
-
opens it
|
|
315
|
-
|
|
319
|
+
three keys (New agent, the command palette, Home), then the tiles.
|
|
320
|
+
|
|
321
|
+
Home has no key of its own yet: its row, or the palette's **Home** (among its
|
|
322
|
+
sections), opens it, and always on its board, also from **Home › Agents**. Home never changes the roster's order: urgency is sorted
|
|
323
|
+
on Home only.
|
|
324
|
+
|
|
325
|
+
**The Workspace page** has its own row, under Home's, and ⌘2 / Ctrl+2. Its
|
|
326
|
+
head says where you are and how to get back, **Home › Workspace › Souls**,
|
|
327
|
+
above its tabs (Souls, Capabilities, Teams, Machines, Setup): Home and
|
|
328
|
+
Workspace are links (Workspace opens the page on Souls). A soul's, a
|
|
329
|
+
capability's or a team's page carries the same trail in its bar, one level
|
|
330
|
+
deeper (**Home › Workspace › Souls › dev**, and a skill one more), each part
|
|
331
|
+
above the page a link. Esc goes up one level: from a soul's page to Souls,
|
|
332
|
+
then to Home. Every way onto the page (its row, a Home tile, the palette, the
|
|
333
|
+
key, a soul's or a capability's page) marks the Workspace row, never Home's.
|
|
316
334
|
|
|
317
335
|
**The command palette** (⌘K / Alt+K) is the one place to reach everything.
|
|
318
336
|
It lists, in order: the agents that need you (the newest first), your recent
|
|
319
337
|
agents (the sidebar's tree, the one you used last on top), the sections
|
|
320
|
-
(Home, Workspace
|
|
338
|
+
(Home, Workspace and its tabs, Automations, Connections), the commands,
|
|
321
339
|
and one **New agent: <soul>** row per soul. Type to narrow it; `>` keeps only
|
|
322
340
|
the commands and `+` only the souls.
|
|
323
341
|
|
|
324
342
|
**The status line** runs along the bottom of the window. It shows the three
|
|
325
343
|
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)
|
|
344
|
+
in a terminal: the leader, close tab and the palette); on the Workspace pages,
|
|
345
|
+
their own keys: **↑↓ move · Enter open · v table · Esc Home** on Souls (**v
|
|
346
|
+
grid** in the table), the same without **v** on Capabilities, and **↑↓ move ·
|
|
347
|
+
Enter open · Esc back** on a soul's, a capability's or a team's page. It says in one line why a
|
|
327
348
|
key could not act (the leader's line is drawn there), says what was just done
|
|
328
349
|
("Workspace onboarded. The lock is written."), says when the terminal in front
|
|
329
350
|
loses its server and when it is back (the pane keeps its countdown and its
|
|
@@ -355,7 +376,8 @@ hear the new size once, when you let go.
|
|
|
355
376
|
|
|
356
377
|
**Appearance.** The palette's **Appearance…** and ⇧⌘Space / Ctrl+Shift+Space
|
|
357
378
|
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
|
|
379
|
+
the system's light or dark setting; it was "This computer"), Dark (Tokyo Night's
|
|
380
|
+
blues and greys in the window; the terminals keep their own colours), Light, and
|
|
359
381
|
More themes… (Solarized). **Font**, the terminals' font (the window's own
|
|
360
382
|
text is always the system's interface font):
|
|
361
383
|
|
|
@@ -428,8 +450,8 @@ a choice saved for it is ignored.)
|
|
|
428
450
|
- **The current workspace** has its circle filled, like a running
|
|
429
451
|
instance's, and its name in bold; the others have the ring a stopped
|
|
430
452
|
instance has. It has no background of its own: the selection's background
|
|
431
|
-
marks the current page (Home,
|
|
432
|
-
|
|
453
|
+
marks the current page (Home, Workspace, whichever of its tabs or pages
|
|
454
|
+
shows, or Automations), so the
|
|
433
455
|
sidebar fills one "you are here" row. A screen reader hears it as current,
|
|
434
456
|
and the list's description names it, by the same name as its row.
|
|
435
457
|
- **The needs-input mark.** A row has an exclamation mark (a small amber
|
|
@@ -507,18 +529,24 @@ other window.
|
|
|
507
529
|
## Capabilities and spawning
|
|
508
530
|
|
|
509
531
|
**Workspace › Capabilities** lists every capability of the workspace as one
|
|
510
|
-
list of rows.
|
|
532
|
+
list of rows. Its first line says what a capability is, how many the workspace
|
|
533
|
+
has and how many are official, and what the ✓, **core** and **default** say
|
|
534
|
+
(**default** only where the workspace reports its defaults). Core capabilities
|
|
535
|
+
(knowledge, messaging and tasks) come first,
|
|
511
536
|
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.
|
|
537
|
+
name. There are no sections, repository groups or colour marks. The rows sit
|
|
538
|
+
on the page, a thin rule under each, with no box around them; a row lightens
|
|
539
|
+
under the pointer and takes the selection tint when focused. Each row
|
|
513
540
|
shows:
|
|
514
541
|
|
|
515
542
|
- the capability's name;
|
|
516
|
-
- who made it: a small ✓ in a circle for an official one (its tooltip says
|
|
543
|
+
- who made it, right after the name: a small ✓ in a circle for an official one (its tooltip says
|
|
517
544
|
which fact made it official: **Official: in the OATS catalog** or **Official:
|
|
518
545
|
from the OATS repository**), or **by** its source (a member repository's
|
|
519
546
|
name, or a git package's repository);
|
|
520
547
|
- one line of what it does (the manifest's description, cut to one line);
|
|
521
|
-
- its tags
|
|
548
|
+
- its tags, as small pills (**core** in a thin frame, **default** on a quiet
|
|
549
|
+
fill): **core**, **default** for one the workspace gives every soul,
|
|
522
550
|
**default · off** for one the workspace turns off, and **repo only** for one
|
|
523
551
|
only its own repository's souls can use.
|
|
524
552
|
|
|
@@ -535,12 +563,18 @@ A kernel fact for "official" is
|
|
|
535
563
|
name and version are not on this list: **Setup**'s Packages box shows them,
|
|
536
564
|
and so does the capability's page.
|
|
537
565
|
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
566
|
+
Above the list, **Workspace defaults** shows what the workspace gives every
|
|
567
|
+
soul, so its agents share one way of working. Its title and **All
|
|
568
|
+
capabilities**' are in small capitals, as the Souls groups' are. One sentence says what defaults
|
|
569
|
+
are (a soul can turn a default off and choose its own instead); then **Core**,
|
|
570
|
+
one line each for Knowledge, Messaging and Tasks with the capability that fills
|
|
571
|
+
it (its name alone when the list doesn't hold it, or "No default"), and **Additional**, every other default, a turned-off one
|
|
572
|
+
tagged so. Each default is the list's own row, with its one line and where it
|
|
573
|
+
comes from, and opens its page; ↑ and ↓ move across them. The list follows,
|
|
574
|
+
under **All capabilities**. The sentence also names a declared default the
|
|
575
|
+
list can't show as a row. A workspace that sets no defaults (a standalone
|
|
576
|
+
deployment, for example) says so. The search narrows only the list, never the
|
|
577
|
+
defaults. It is read
|
|
544
578
|
from `oats workspace status --json`: an OATS that doesn't report the defaults
|
|
545
579
|
shows no sentence and no tag, and the Desktop doesn't guess them from the
|
|
546
580
|
souls. The defaults are declared in the workspace file; the page only shows
|
|
@@ -577,7 +611,12 @@ one off and name its own in its place.
|
|
|
577
611
|
tab or the workspace closes it too.
|
|
578
612
|
|
|
579
613
|
**Workspace › Souls** lists the souls the workspace offers. Its first line says
|
|
580
|
-
what a soul is
|
|
614
|
+
what a soul is, how many the workspace has and how many have agents running,
|
|
615
|
+
and how the page is ordered ("You have 10 souls, 4 with agents running, grouped
|
|
616
|
+
by where they come from; maintainers first, then experts, developers,
|
|
617
|
+
operations. Enter opens one.").
|
|
618
|
+
Each group's heading is its name in small capitals and its count
|
|
619
|
+
("AGENTS · member repo · host · 6 souls"). The souls are grouped by where they come from: the workspace's
|
|
581
620
|
own repository first, then its other member repositories, then each package,
|
|
582
621
|
then the external souls. Inside a group they are in kind order: maintainers,
|
|
583
622
|
experts, developers, operations, then the rest, each by name. The kind is read
|
|
@@ -588,10 +627,12 @@ reports no role for a soul yet, so the name is the rule until it does
|
|
|
588
627
|
([#1980](https://github.com/oats-project/oats/issues/1980)).
|
|
589
628
|
|
|
590
629
|
The souls show as a grid of cards or as a table: **v** (or **Grid** | **Table**
|
|
591
|
-
|
|
592
|
-
also after a restart.
|
|
593
|
-
|
|
594
|
-
|
|
630
|
+
beside the page's title) switches between them, and each window remembers its choice,
|
|
631
|
+
also after a restart. The grid has three columns at most, fewer in a narrow
|
|
632
|
+
window. A card shows the soul's name, larger and bold, what it
|
|
633
|
+
does, in muted text on two lines at most, and a smaller line with how many of its agents run
|
|
634
|
+
and its kind; a soul a spawn here would refuse also says why, in one quiet
|
|
635
|
+
line above its count, the whole sentence on its page. The table has the same souls as rows: name, what it does, kind,
|
|
595
636
|
agents running, harness · model, and **Ready** (or why a spawn here would be
|
|
596
637
|
refused; **—** when this OATS does not report it). A card or a row's name
|
|
597
638
|
opens the soul's page. A new agent of a soul starts from **New agent** on its
|
|
@@ -599,8 +640,10 @@ page, from Quick Open, or from the palette. Souls of a member repository that
|
|
|
599
640
|
has not confirmed its membership are listed last, under **Not available**,
|
|
600
641
|
with the reason; they open nothing.
|
|
601
642
|
|
|
602
|
-
A soul's page (open a soul from **Workspace › Souls**) is one column
|
|
603
|
-
|
|
643
|
+
A soul's page (open a soul from **Workspace › Souls**) is one column, in the
|
|
644
|
+
same type and spacing as the lists: its name as the page's one large line, the
|
|
645
|
+
section titles in small capitals, the capability rows as Capabilities' rows.
|
|
646
|
+
Under its name and what it does, a block of facts: **Harness · model** (what a spawn here
|
|
604
647
|
runs, and where that choice came from), **Teams** (the teams its agents may
|
|
605
648
|
join, the default marked; with team model v2, **Teams on this computer** folds
|
|
606
649
|
out the editable list), **Knowledge** (the nodes it owns and reads, when it
|
|
@@ -1054,6 +1097,114 @@ starts, ends or its text changes, never as the age ticks over. In a split,
|
|
|
1054
1097
|
each group's row follows its own tab. The row goes as soon as the wait ends,
|
|
1055
1098
|
and it never shows for a stopped instance or a roster that is out of date.
|
|
1056
1099
|
|
|
1100
|
+
## An agent's mail
|
|
1101
|
+
|
|
1102
|
+
**Alt+M** (⌥⌘M on macOS), the palette's **Agent: mail** or **Mail** in
|
|
1103
|
+
Details' Messaging & Teams section opens the agent's own mail, received and
|
|
1104
|
+
sent, newest first, in a read-only sheet from the right. Each message says who
|
|
1105
|
+
it is from or to, its team when the agent is in more than one, its subject and
|
|
1106
|
+
its body as plain text attributed to its sender, and whether it was encrypted,
|
|
1107
|
+
is not read by the agent yet, is high priority, or its sender is not verified.
|
|
1108
|
+
**r** reads it again and **Older mail** reads further back; Esc closes it.
|
|
1109
|
+
|
|
1110
|
+
Reading it never acknowledges anything or marks anything read: the Desktop
|
|
1111
|
+
runs only the messaging layer's `messaging:mail` operation, when the sheet
|
|
1112
|
+
opens or you ask it to read again, never on its own. Nothing else on the screen
|
|
1113
|
+
says anything about an agent's mail. An agent whose messaging layer predates
|
|
1114
|
+
the operation says so, with what to do: stop it and upgrade it (`oats instance
|
|
1115
|
+
upgrade`), or start a new agent of its soul. The details are in
|
|
1116
|
+
[packages/desktop/docs/desktop-mail-sheet.md](../packages/desktop/docs/desktop-mail-sheet.md).
|
|
1117
|
+
|
|
1118
|
+
## The agent view: facts and questions
|
|
1119
|
+
|
|
1120
|
+
With an OATS that reports the agent's board (feature `instance-board`; the
|
|
1121
|
+
agent writes it with `oats instance board set` and `oats instance board ask`,
|
|
1122
|
+
[docs/desktop-cli-api.md](desktop-cli-api.md)), an agent's terminal tab is its
|
|
1123
|
+
**agent view**. Top to bottom:
|
|
1124
|
+
|
|
1125
|
+
1. **Facts**: what the agent keeps in your view, one compact row each,
|
|
1126
|
+
`label · value unit`, with "updated 4 min ago". At most three show; **N
|
|
1127
|
+
more** unfolds the rest. While the view is open the Desktop reads each
|
|
1128
|
+
fact's history once, and a number that changed draws a small sparkline.
|
|
1129
|
+
A link shows as the agent's, with its host (`dev-a says: github.com…`). A
|
|
1130
|
+
press shows its whole address over the top of the terminal, wrapped, the
|
|
1131
|
+
host in bold, with **Open in browser** beside it: only that press opens it,
|
|
1132
|
+
in your browser. Esc closes it. An address that looks like it carries a
|
|
1133
|
+
secret (a token in it) is never shown: the fact shows without its link. **×**, or
|
|
1134
|
+
**u** on a focused fact, hides it on this computer only: the agent's board
|
|
1135
|
+
is unchanged, and the fact shows again when its value changes. **N hidden ·
|
|
1136
|
+
show** brings them all back.
|
|
1137
|
+
2. **The agent's own terminal**, unchanged: the same viewer, the same cell
|
|
1138
|
+
geometry, the only part that scrolls (a long context scrolls inside its
|
|
1139
|
+
own open fold, at most twelve lines tall). The board leaves it at least
|
|
1140
|
+
120 px, or 40% of the pane: in a short pane the facts give way to one (the
|
|
1141
|
+
rest stay behind **N more**), then the questions drop their key hint, then
|
|
1142
|
+
an open context shortens to three lines. A pane too short even for that
|
|
1143
|
+
keeps its terminal smaller, and a number types only while at least two of
|
|
1144
|
+
its lines show. It gives up exactly the rows the
|
|
1145
|
+
facts and the questions take.
|
|
1146
|
+
3. **Questions**: one at a time, under the terminal, so they sit right by the
|
|
1147
|
+
agent's input line at the bottom of its screen. "question 2 of 3", ‹ › and
|
|
1148
|
+
the dots turn them, and so do Tab / Shift+Tab and ← / → while the questions
|
|
1149
|
+
have the focus. A question with context has a **Context** fold, attributed
|
|
1150
|
+
to the agent, as plain text: **c** opens or closes it and moves the focus
|
|
1151
|
+
there, where Tab moves into its text. With no open question there is no zone.
|
|
1152
|
+
|
|
1153
|
+
**What the view says when it can't show something.** History and context come
|
|
1154
|
+
from a second read while the view is open (`oats inspect --home <h> --board`,
|
|
1155
|
+
sent only when this computer's OATS, and for an agent on another machine that
|
|
1156
|
+
machine's OATS too, has the feature). The view reads it when it opens, when a
|
|
1157
|
+
fact changes and when a question with context is asked, never on the roster's
|
|
1158
|
+
poll. When that read fails, comes back in a shape the Desktop can't read, or
|
|
1159
|
+
comes from an OATS without the feature, the facts strip and the context fold
|
|
1160
|
+
say which. A board the Desktop can't read, or one with entries it had to leave
|
|
1161
|
+
out, says so too. None of these hides a question or reads as "no questions".
|
|
1162
|
+
|
|
1163
|
+
**Answering.** The questions and the facts are focus regions: from the
|
|
1164
|
+
terminal, **Ctrl+Shift+F6** moves to the questions, and F6 / Shift+F6 move on
|
|
1165
|
+
from there (the facts come before the terminal, the questions after it). The
|
|
1166
|
+
palette's **Agent: questions and facts (focus)** moves through the questions,
|
|
1167
|
+
the facts and back to the terminal. Esc goes back to the terminal. A number, or a press on an
|
|
1168
|
+
option, puts `<id>: <option>` on the agent's input line, for example
|
|
1169
|
+
`q2: Yes, one clean commit`, and gives the terminal the focus. Nothing is sent:
|
|
1170
|
+
your Enter in the terminal sends it, as if you had typed it, so you see what
|
|
1171
|
+
goes. No bare digit is ever typed, and nothing is typed into a terminal that
|
|
1172
|
+
isn't on screen: a press whose terminal left the screen while the Desktop read
|
|
1173
|
+
the agent's claims types nothing. After a press the card says, quietly, "Typed
|
|
1174
|
+
on the input line: press Enter in the terminal to send it." until your next
|
|
1175
|
+
input in the terminal or a change on the board. The Desktop doesn't guess what
|
|
1176
|
+
the input line holds: the card stays until the agent clears the question once
|
|
1177
|
+
it has read your answer, and a second press types again, as typing would.
|
|
1178
|
+
|
|
1179
|
+
While the terminal is in its scrollback (you scrolled up with the
|
|
1180
|
+
wheel or Shift+PgUp), nothing is typed either, because the scrollback would
|
|
1181
|
+
read the answer's first letter as its own key: the zone says "The terminal is
|
|
1182
|
+
in its scrollback: press q or scroll to the bottom, then press the number
|
|
1183
|
+
again." The Desktop checks the terminal just before it types, and types only
|
|
1184
|
+
when the check says it isn't in its scrollback: when it can't tell (the check
|
|
1185
|
+
failed), nothing is typed and the zone says "The answer wasn't typed: the Desktop
|
|
1186
|
+
couldn't check the terminal's scrollback. Type it there yourself, or press the
|
|
1187
|
+
number again." On an agent on another machine the numbers are disabled from the
|
|
1188
|
+
start, since its terminal can't be checked from this computer, and the zone says
|
|
1189
|
+
"This agent runs on another machine: type the answer in its terminal (for
|
|
1190
|
+
example q1: Yes)." (follow-up: #2029). The check and the typing are two steps a few milliseconds apart:
|
|
1191
|
+
if you enter the scrollback in exactly that moment, tmux can still read the
|
|
1192
|
+
answer's first letter as a scrollback key. That window is not closed.
|
|
1193
|
+
|
|
1194
|
+
**While a dialog is open** (the agent has a live `permission` or `question`
|
|
1195
|
+
claim, from its harness or any other producer), the numbers are disabled and
|
|
1196
|
+
the zone says "The agent's terminal is showing a prompt: answer it there
|
|
1197
|
+
first." The Desktop reads the agent's claims for this when the view opens and
|
|
1198
|
+
when they change, because the roster row shows only the newest one.
|
|
1199
|
+
|
|
1200
|
+
The board's own question is the agent's needs-input claim (reason
|
|
1201
|
+
`attention`), so the sidebar mark, the tab's mark and Home's "needs you" read
|
|
1202
|
+
it as before. In the agent view it shows in the question zone, not in the
|
|
1203
|
+
waiting row. Any other claim keeps the waiting row described above. Without
|
|
1204
|
+
the feature (an older OATS), the tab is the terminal and its waiting row, as
|
|
1205
|
+
before. A tab on another machine shows the board when that machine's OATS has
|
|
1206
|
+
the feature.
|
|
1207
|
+
|
|
1057
1208
|
## Copy from a terminal
|
|
1058
1209
|
|
|
1059
1210
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -1113,12 +1264,43 @@ error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
|
1113
1264
|
|
|
1114
1265
|
The sidebar lists a workspace's instances as a tree: a child sits one step
|
|
1115
1266
|
right of its parent, and related instances are grouped together, with a little
|
|
1116
|
-
space before the next group. The
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1267
|
+
space before the next group. The indent and that space show the tree.
|
|
1268
|
+
|
|
1269
|
+
The sidebar draws a line only for related work: an instance its host reports
|
|
1270
|
+
doing work related to its parent's, or to a sibling's. No flag, no line, on
|
|
1271
|
+
every host. Where it draws one, it looks as it did before the Desktop's
|
|
1272
|
+
redesign:
|
|
1273
|
+
|
|
1274
|
+
- **A solid line** joins a parent to a child whose work is related to its
|
|
1275
|
+
parent's: the parent's line leaves its dot and ends in a rounded elbow at
|
|
1276
|
+
the child's. Any other child keeps its indent with no line, and its
|
|
1277
|
+
parent's line doesn't reach it.
|
|
1278
|
+
- **A dotted line** joins the dots of two top-level instances of one group
|
|
1279
|
+
when the one linked as a sibling of the other reports related work. The
|
|
1280
|
+
links are pairs: S may be linked to R and T to S, and the line then runs
|
|
1281
|
+
through all three dots, passing beside the children between them. A
|
|
1282
|
+
top-level instance whose work isn't related breaks the dotted line: its
|
|
1283
|
+
row, and its children's, carry none, so nothing touches its dot. The order
|
|
1284
|
+
doesn't change for the lines.
|
|
1285
|
+
|
|
1286
|
+
The same lines show whether a group is open or closed: closed, the dotted
|
|
1287
|
+
line joins the top-level dots; open, it runs on beside the children, whose
|
|
1288
|
+
own lines are drawn. Both lines hold 3:1 contrast on every row fill.
|
|
1289
|
+
|
|
1290
|
+
The flag comes from the instances' OATS ([Related work](desktop-cli-api.md#related-work-oats-instance-related-work)).
|
|
1291
|
+
An OATS with `instance-related-work` reports it for a child and for a
|
|
1292
|
+
sibling. An older OATS, with `instance-same-work` only, reports it for a
|
|
1293
|
+
child only (set with `--same-work`), so its siblings get no dotted line. An
|
|
1294
|
+
OATS with neither reports none, and no line is drawn. For another machine's
|
|
1295
|
+
instances, its host must report the feature too, through an installed OATS
|
|
1296
|
+
with `server-probe-features`; a host whose features are not known (its last
|
|
1297
|
+
read failed) gets no line. A spawn from the Desktop never sets the flag.
|
|
1298
|
+
|
|
1299
|
+
A screen reader hears each row's state ("running", "stopped" or "status
|
|
1300
|
+
unknown") after its two lines, then each child "under" its parent, with
|
|
1301
|
+
"related work" when the line joins them, and each instance linked as a
|
|
1302
|
+
sibling "sibling of" the other, with "related work" at both ends of a joined
|
|
1303
|
+
pair. The lines themselves are hidden from assistive technology.
|
|
1122
1304
|
|
|
1123
1305
|
The sidebar shows the top-level instances only until you open one. An
|
|
1124
1306
|
instance with children has a chevron right after its name, with the number
|
|
@@ -1149,17 +1331,11 @@ are in name order, and an instance whose spawn time can't be read comes after
|
|
|
1149
1331
|
every one whose time can. Pinned instances come before all of these, at every
|
|
1150
1332
|
level ([Pinned instances](#pinned-instances)).
|
|
1151
1333
|
|
|
1152
|
-
Children
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
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.
|
|
1334
|
+
Children whose work is related to their parent's come first under it, each
|
|
1335
|
+
part newest first, so a parent's line ends at its last joined child and never
|
|
1336
|
+
passes one it doesn't join. Top-level instances keep their order whatever
|
|
1337
|
+
their flag. The command palette draws the same lines by the same rule, in its
|
|
1338
|
+
own recency order inside each part.
|
|
1163
1339
|
|
|
1164
1340
|
A row shows the instance's name as words: each `-` is a space, and the first
|
|
1165
1341
|
letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
|
|
@@ -1450,7 +1626,7 @@ then requires that launch to reactivate the retained tab with exactly
|
|
|
1450
1626
|
one viewer and no terminal focus event. CDP sends a key to the window;
|
|
1451
1627
|
independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
|
|
1452
1628
|
only, with no tab or Start dialog, on Home (its row current and its view
|
|
1453
|
-
shown
|
|
1629
|
+
shown). The smoke also
|
|
1454
1630
|
asserts that viewer cleanup restores its private tmux baseline. The fixture's
|
|
1455
1631
|
workspace/member source, soul definition and inert harness executable are authored by the test-only
|
|
1456
1632
|
[`launch-fixture.mjs`](../packages/desktop/test/helpers/launch-fixture.mjs).
|
|
@@ -37,8 +37,12 @@ variables point at are described in
|
|
|
37
37
|
|
|
38
38
|
## Backends
|
|
39
39
|
|
|
40
|
-
tmux is the
|
|
41
|
-
is
|
|
40
|
+
tmux is the kernel's own session backend, and the default: `oats spawn
|
|
41
|
+
--backend tmux` is accepted, and `tmux` must be installed on the execution
|
|
42
|
+
host. A capability can supply another backend, a
|
|
43
|
+
[session provider](#session-providers), which `--backend <name>` selects.
|
|
44
|
+
`sessionBackends` in `oats version --json` lists the kernel's own (`["tmux"]`),
|
|
45
|
+
never a provider. The rest of this section is tmux. A launched
|
|
42
46
|
home keeps the session it recorded: `session start` and `restart` never
|
|
43
47
|
re-read the defaults. The session target is recorded twice: in
|
|
44
48
|
`instance.json` and in an independent lifecycle receipt. Every session command
|
|
@@ -923,6 +927,185 @@ other instance whose window is in that session, not only the one you are
|
|
|
923
927
|
moving. And a window that a viewer still links would live on in that viewer,
|
|
924
928
|
so the next start would create a second window for the same home.
|
|
925
929
|
|
|
930
|
+
### Session providers
|
|
931
|
+
|
|
932
|
+
A kernel that lists the feature `session-providers` (`oats version --json`)
|
|
933
|
+
can run an instance on a session backend that a capability supplies: the
|
|
934
|
+
agent runs where the provider runs it, and OATS keeps the instance's home,
|
|
935
|
+
its records, its lifecycle and its answers. What a capability declares and
|
|
936
|
+
answers is in
|
|
937
|
+
[capabilities.md](capabilities.md#session-providers-sessionproviders). tmux
|
|
938
|
+
homes are unchanged.
|
|
939
|
+
|
|
940
|
+
**Selecting one.** `oats spawn <soul> --backend <name>`, a schedule's
|
|
941
|
+
`backend` and a trigger's `spawn.backend` take a provider's name. The
|
|
942
|
+
provider is one that a capability of that instance declares:
|
|
943
|
+
`oats inspect --soul <soul> --json` lists them under `sessionProviders`
|
|
944
|
+
(`[{name, capability}]`), and so does `oats inspect --home`. Refused before
|
|
945
|
+
anything is created, and shown by a spawn preview:
|
|
946
|
+
|
|
947
|
+
| Code | When |
|
|
948
|
+
|---|---|
|
|
949
|
+
| `E_BACKEND_UNKNOWN` | no capability of the instance declares the name, or declares it malformed; the message names the backends available |
|
|
950
|
+
| `E_BACKEND_AMBIGUOUS` | two capabilities of the instance declare the name (a spawn, and a start or restart of a home whose modules now do) |
|
|
951
|
+
| `E_BACKEND_HARNESS` | the provider does not run the launch's harness |
|
|
952
|
+
| `E_BACKEND_LAUNCH_ARG` | the launch configuration declares an `executable`: a provider runs the harness itself |
|
|
953
|
+
| `E_BACKEND_NOT_READY` | the provider's own readiness check, asked right before the launch, says it cannot take it |
|
|
954
|
+
|
|
955
|
+
A provider can also refuse the launch with its own `E_BACKEND_*` code (a
|
|
956
|
+
launch environment entry or an argument it cannot carry), which OATS relays;
|
|
957
|
+
the spawn is then rolled back.
|
|
958
|
+
|
|
959
|
+
**What OATS checks for a provider launch, and what it does not.** The launch
|
|
960
|
+
configuration, the harness, the model, yolo, the capabilities' hooks and the
|
|
961
|
+
launch environment are decided as for tmux and handed to the provider. The
|
|
962
|
+
checks about a terminal pane are skipped, because no pane runs the harness:
|
|
963
|
+
the harness executable on the pane's `PATH`, folder trust, the Claude login
|
|
964
|
+
credential, the development-channel prompt, the native-record wrapper. The
|
|
965
|
+
provider's readiness covers what they covered. One check stays: a
|
|
966
|
+
capability's harness-package requirement (`requires`) is probed for a
|
|
967
|
+
provider launch too, on this host, unless the row says which backends it is
|
|
968
|
+
for (`backends: ["tmux"]` leaves it out of a provider launch;
|
|
969
|
+
`["session-provider"]` makes it one of provider launches only).
|
|
970
|
+
|
|
971
|
+
**Records.** A provider home's `instance.json` carries `backend: "<name>"`
|
|
972
|
+
and `session: {provider, endpoint}` (`provider`: the capability; `endpoint`:
|
|
973
|
+
the provider's own locator, at most 4 KiB, `null` before the first launch),
|
|
974
|
+
and no `tmux` and no `command`; its launch recipe's `executable` is `null`.
|
|
975
|
+
Its receipt records `runtime: {launched, backend, provider, endpoint,
|
|
976
|
+
stoppedAt}`. The two must agree as for tmux: `E_RUNTIME_AUTHORITY_MISMATCH`
|
|
977
|
+
otherwise, whose `details.fields` are `backend`, `session.provider` and
|
|
978
|
+
`session.endpoint`.
|
|
979
|
+
|
|
980
|
+
**The lifecycle of a provider home is one state machine**, set out in
|
|
981
|
+
[its design record](design/2026-11-20-provider-home-lifecycle.md): the
|
|
982
|
+
states its records spell, what each verb does in each, in what order it
|
|
983
|
+
writes, and what happens when two things cross. In short:
|
|
984
|
+
|
|
985
|
+
- The receipt's `runtime` carries `launchSent` (an instant) **while a launch
|
|
986
|
+
that was sent to the provider has no recorded outcome**: written right
|
|
987
|
+
before the provider's launch is called, by a spawn and by a start, kept
|
|
988
|
+
until the launch's endpoint is in the receipt *and* in the record, and
|
|
989
|
+
removed last. A launch that is killed leaves it there.
|
|
990
|
+
- Such a home is **unsettled**: a session may run that no record names. It
|
|
991
|
+
reads as unknown (`oats session inspect` answers `E_SESSION_UNAVAILABLE`,
|
|
992
|
+
its status row `running: null`, `runtimeState: "unreachable"`), during a
|
|
993
|
+
launch as after one that died; its record is not compared with its receipt
|
|
994
|
+
meanwhile; input to it is refused, nothing sent.
|
|
995
|
+
- A stop, a start, a restart and a retire **settle** it first: the provider
|
|
996
|
+
is asked to stop whatever session rooted at the home was created since
|
|
997
|
+
that instant (`stop` with `endpoint: null` and `launchSent`). Confirmed, a
|
|
998
|
+
home that was never launched is as it was, and one launched before is
|
|
999
|
+
stopped; not confirmed is `E_SESSION_STOP_FAILED`, and the next verb asks
|
|
1000
|
+
again.
|
|
1001
|
+
- For a home that was **never launched**, the receipt reads `runtime:
|
|
1002
|
+
{launched: true, backend, provider, launchSent}` meanwhile and
|
|
1003
|
+
`instance.json` `launched: true`, both without an endpoint. A kernel from
|
|
1004
|
+
before session providers reads that as a launch it cannot address and
|
|
1005
|
+
refuses every verb on the home, a retire included, where it would have
|
|
1006
|
+
retired a home it read as never launched.
|
|
1007
|
+
|
|
1008
|
+
**The verbs.**
|
|
1009
|
+
|
|
1010
|
+
| Verb | On a provider home |
|
|
1011
|
+
|---|---|
|
|
1012
|
+
| `session inspect` | the provider's `present`, `state` and `running`, with `backend`, `session` and `open` (`{label, url}` or `null`: what to show instead of a terminal); no `paneId`, no `size`. A provider that fails, is slow or answers outside the contract is `E_SESSION_UNAVAILABLE`, never "stopped" |
|
|
1013
|
+
| `session input` | the provider sends the text. `submitted: true` only when it was dispatched; `E_SESSION_PROMPT_OPEN` (a prompt is open in the session: nothing was sent) and `E_SESSION_INPUT_QUEUED` (the provider queued it and withdrew it) are the provider's refusals; anything else is `E_SESSION_INPUT_FAILED`. An input to a lost session is a resume ([below](#provider-homes-lost-sessions)) |
|
|
1014
|
+
| `instance stop` | records the stop, then asks the provider to stop the session (`E_SESSION_STOP_FAILED` when it does not confirm; the home stays recorded as stopped). A stop of a home that is already stopped asks the provider once more: run it again to finish a stop the provider did not confirm |
|
|
1015
|
+
| `session start` | launches a new session, a fresh conversation on `TASK.md`, and records its endpoint. Refused when a session is there that OATS did not stop: `E_SESSION_RUNNING` when it reads `running: true`, else `E_SESSION_UNKNOWN`. For a home OATS stopped it first asks the provider to stop once more, and refuses `E_SESSION_STOP_FAILED` when that is not confirmed |
|
|
1016
|
+
| `session restart` | stop, then start, under one lifecycle claim |
|
|
1017
|
+
| `session start --resume` | sends the resume notice through the provider's input; nothing is launched ([below](#provider-homes-lost-sessions)) |
|
|
1018
|
+
| `session attach` | `E_SESSION_NO_TERMINAL`; the message carries inspect's `open` link when there is one |
|
|
1019
|
+
| `oats retire` | records the stop, asks the provider to stop, checks that no process works in the home, then runs the retire hooks and removes the home ([souls-and-instances.md](souls-and-instances.md#retiring-a-home-on-a-session-provider)) |
|
|
1020
|
+
|
|
1021
|
+
**Stop stays stopped.** OATS records `stoppedAt` in the receipt at every stop
|
|
1022
|
+
it makes (`oats instance stop`, a restart's stop, a retire, the host's
|
|
1023
|
+
shutdown), before it calls the provider, and a start clears it. While it is
|
|
1024
|
+
set, inspect answers stopped (`present: false`, `running: false`) without
|
|
1025
|
+
calling the provider, and every input is refused `E_SESSION_NOT_RUNNING`
|
|
1026
|
+
before any call: `oats session input`, a scheduled wake (which never starts
|
|
1027
|
+
a provider home), a client's input, the messaging broker's delivery. A stop
|
|
1028
|
+
that lands while an input is being sent still wins: OATS asks the provider
|
|
1029
|
+
to stop the session again and answers the input `E_SESSION_NOT_RUNNING`, so
|
|
1030
|
+
a mail stays unread and comes again. A
|
|
1031
|
+
session stopped in the provider's own interface sets nothing in OATS, and
|
|
1032
|
+
the provider may restart it on the next input: **stop an OATS agent with
|
|
1033
|
+
OATS**.
|
|
1034
|
+
|
|
1035
|
+
**Status.** A provider home's row of `oats status --json` carries `backend`,
|
|
1036
|
+
`session: {provider}`, `tmux: null`, `open`, `running` (`true`, `false`, or
|
|
1037
|
+
`null` where the provider cannot tell) and `runtimeState`, always set:
|
|
1038
|
+
`unknown`, `shell`, `stopped` or `unreachable` (with `runtimeError`). On the
|
|
1039
|
+
host where the home lives the row's `session` also carries `threadId`, when
|
|
1040
|
+
the provider's endpoint names one, so a tool on that host can match a session
|
|
1041
|
+
to its instance. The endpoint itself is on `oats session inspect --home` and
|
|
1042
|
+
on a spawn's and a start's answer, on that host only: **nothing of it is
|
|
1043
|
+
relayed** by `oats server roster` or `--server`, whose rows and answers carry
|
|
1044
|
+
`session: {provider}`. A tmux row carries `backend: "tmux"`; a row with no
|
|
1045
|
+
`backend` (an older kernel, an older routed host) is a tmux row. Status asks
|
|
1046
|
+
each provider once per group of homes where it can (`inspectMany`), falls
|
|
1047
|
+
back to one `inspect` per home when a batch is bad (never after one that
|
|
1048
|
+
timed out), gives all its providers 30 s together, and asks nothing about a
|
|
1049
|
+
home OATS stopped, which keeps its last endpoint until its next start.
|
|
1050
|
+
`waitingOnYou` is the producers' claim, as for tmux, read while the session
|
|
1051
|
+
is there and not in error.
|
|
1052
|
+
|
|
1053
|
+
<a id="provider-homes-lost-sessions"></a>
|
|
1054
|
+
|
|
1055
|
+
**Lost sessions, and the resume.** An OATS stop is the intent that keeps a
|
|
1056
|
+
home down; only a lost session is resumed, in its own conversation, on the
|
|
1057
|
+
host where the home lives. Two provider homes read `sessionEnd: "lost"`:
|
|
1058
|
+
|
|
1059
|
+
- one stopped by **`oats host run`'s shutdown**. That stop records
|
|
1060
|
+
`stoppedAt` like any other, so input stays refused while the host or the
|
|
1061
|
+
container goes down, and the home's stop receipt says the host's shutdown
|
|
1062
|
+
wrote it. An operator's stop after it withdraws that. The shutdown stops
|
|
1063
|
+
every provider home OATS has not stopped, whatever its session reads, and
|
|
1064
|
+
asks no provider to find them (`oats session resume --plan
|
|
1065
|
+
--without-provider-inspect`), so a provider that goes down with the host
|
|
1066
|
+
cannot hold it up.
|
|
1067
|
+
- one whose session is **gone while OATS did not stop it**: the provider
|
|
1068
|
+
answers `present: false`. A provider reads a session in error this way.
|
|
1069
|
+
|
|
1070
|
+
The sweep (`oats session resume`: the Desktop and the TUI when they open,
|
|
1071
|
+
`oats host run` at its start and each minute) resumes both with `oats session
|
|
1072
|
+
start --resume --home <home>`, which you can also run for one home: it clears
|
|
1073
|
+
the stop, if there is one, and sends one resume notice through the
|
|
1074
|
+
provider's input. Nothing is launched, and a home an operator stopped stays
|
|
1075
|
+
stopped. The rules of that resume:
|
|
1076
|
+
|
|
1077
|
+
- **The cap.** A lost session's resume is counted against the home, at most
|
|
1078
|
+
3 in an hour within one boot, as the sweep bounds a tmux home's starts. The
|
|
1079
|
+
kernel counts before it calls the provider, and **any input to a lost
|
|
1080
|
+
session is a resume** (a mail the broker delivers, a scheduled wake): the
|
|
1081
|
+
provider would restart the session on it. At the cap the resume and the
|
|
1082
|
+
input are refused `E_SESSION_NOT_RUNNING`, nothing is sent, a mail stays
|
|
1083
|
+
unread, and the sweep's row is `refused`, `keeps-getting-lost`. A stop with
|
|
1084
|
+
the host is no crash and is not counted. A resume the provider itself
|
|
1085
|
+
refuses is not counted either (nothing was sent); one whose call fails is,
|
|
1086
|
+
since the provider may have restarted the session.
|
|
1087
|
+
- **The last run's processes.** A resume of a lost session waits until no
|
|
1088
|
+
process works in the home (a harness can outlive its server's crash), for
|
|
1089
|
+
at most 150 s. Past that it refuses `E_SESSION_UNKNOWN`, names the
|
|
1090
|
+
processes and never kills them; it is not counted, and the next sweep tries
|
|
1091
|
+
again. An input does not wait: it is refused at once.
|
|
1092
|
+
- **The notice is input.** It is not sent while a claim is open that holds a
|
|
1093
|
+
scheduled wake (a permission prompt, a question) or while the provider
|
|
1094
|
+
says a prompt is open: `E_SESSION_PROMPT_OPEN`. A notice the provider
|
|
1095
|
+
queued is no resume: `E_SESSION_INPUT_QUEUED`. In both cases the home stays
|
|
1096
|
+
as it was, and a later sweep tries again.
|
|
1097
|
+
|
|
1098
|
+
The sweep's rows for provider homes carry `backend`.
|
|
1099
|
+
|
|
1100
|
+
**Other machines and older kernels.** A routed `--backend <provider>`
|
|
1101
|
+
(`--server`) is sent only to a host that lists `session-providers`; another
|
|
1102
|
+
host is refused `E_REMOTE_INCOMPATIBLE` before anything is sent. A kernel
|
|
1103
|
+
without the feature that meets a provider home on the same machine (the
|
|
1104
|
+
Desktop bundles its own kernel) only refuses: every session verb answers
|
|
1105
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN` before any tmux call, a start of a home that
|
|
1106
|
+
was never launched answers `E_LAUNCH_RECIPE_UNSUPPORTED`, and its stop and
|
|
1107
|
+
its retire are refused. Use a kernel that lists the feature for such a home.
|
|
1108
|
+
|
|
926
1109
|
### Herdr (removed in 0.31.0)
|
|
927
1110
|
|
|
928
1111
|
OATS no longer supports Herdr. Everything that meets it refuses with
|
|
@@ -955,7 +1138,7 @@ saved route that records `herdrPath` still loads; the field is ignored.
|
|
|
955
1138
|
| `oats spawn <soul> [--no-launch]` | Creates the home and launches the harness. `--no-launch` creates the home only. |
|
|
956
1139
|
| `oats session start --home <abs>` | Starts a stopped or never-launched instance again in its existing home. |
|
|
957
1140
|
| `oats session start --resume --home <abs>` | Starts an instance whose session was lost again, in its own last conversation ([Resume after a shutdown](#resume-after-a-shutdown)). |
|
|
958
|
-
| `oats session resume [--deployment <dir>] [--plan]` | Resumes every lost session of this machine's deployments ([Resume after a shutdown](#resume-after-a-shutdown)). |
|
|
1141
|
+
| `oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]]` | Resumes every lost session of this machine's deployments ([Resume after a shutdown](#resume-after-a-shutdown)). |
|
|
959
1142
|
| `oats session restart --home <abs>` | Stops the running harness and starts it again in place. |
|
|
960
1143
|
| `oats instance stop <instance> --plan` / `--apply` | Stops the harness and keeps home, work and launch recipe. |
|
|
961
1144
|
| `oats retire <instance>` | Ends the session and retires the instance ([souls-and-instances.md](souls-and-instances.md#retire)). |
|