@awebai/oats 0.69.23 → 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 +56 -17
- package/docs/capabilities.md +353 -5
- package/docs/capability-manifest.schema.json +36 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +257 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +5 -1
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/souls-and-instances.md +45 -0
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +13 -5
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1176 -181
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +97 -8
- package/lib/kernel-features.mjs +10 -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 +28 -4
- 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 +2 -2
- 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 +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- 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/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- 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/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
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
|
|
@@ -1072,6 +1115,96 @@ the operation says so, with what to do: stop it and upgrade it (`oats instance
|
|
|
1072
1115
|
upgrade`), or start a new agent of its soul. The details are in
|
|
1073
1116
|
[packages/desktop/docs/desktop-mail-sheet.md](../packages/desktop/docs/desktop-mail-sheet.md).
|
|
1074
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
|
+
|
|
1075
1208
|
## Copy from a terminal
|
|
1076
1209
|
|
|
1077
1210
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -1493,7 +1626,7 @@ then requires that launch to reactivate the retained tab with exactly
|
|
|
1493
1626
|
one viewer and no terminal focus event. CDP sends a key to the window;
|
|
1494
1627
|
independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
|
|
1495
1628
|
only, with no tab or Start dialog, on Home (its row current and its view
|
|
1496
|
-
shown
|
|
1629
|
+
shown). The smoke also
|
|
1497
1630
|
asserts that viewer cleanup restores its private tmux baseline. The fixture's
|
|
1498
1631
|
workspace/member source, soul definition and inert harness executable are authored by the test-only
|
|
1499
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)). |
|
package/docs/first-team.md
CHANGED
|
@@ -25,6 +25,17 @@ with read access to the repositories below (your own credential helpers; the
|
|
|
25
25
|
kernel never prompts), tmux, and an authenticated harness (Pi, Claude or
|
|
26
26
|
Codex).
|
|
27
27
|
|
|
28
|
+
Node 18 and 20 get
|
|
29
|
+
`E_NODE_UNSUPPORTED` before any command runs, including `version` and
|
|
30
|
+
capability commands. With `--json` the refusal is one failure envelope on
|
|
31
|
+
stdout and exit 1; without it the message is on stderr. A Node too old to
|
|
32
|
+
parse the entry (for example Node 12) can fail with a SyntaxError first.
|
|
33
|
+
The npm package declares `engines.node: ">=22.5.0"` so npm warns at install time.
|
|
34
|
+
|
|
35
|
+
Git 2.45 or later recommended (partial caches); an older Git works, with
|
|
36
|
+
whole-tree fetches. `oats doctor` reports the version and cache support as
|
|
37
|
+
information, without refusing an older Git.
|
|
38
|
+
|
|
28
39
|
```bash
|
|
29
40
|
npm install -g @awebai/oats@latest
|
|
30
41
|
node --version && tmux -V && oats version --json # features must list workspace-v2
|
package/docs/implementation.md
CHANGED
|
@@ -80,7 +80,7 @@ and the rules its tests pin.
|
|
|
80
80
|
|
|
81
81
|
| path | contents |
|
|
82
82
|
|---|---|
|
|
83
|
-
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its
|
|
83
|
+
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its static imports are Node built-ins and dependency-free startup helpers (`node-version`, `compile-cache`, `hot-reads`, `install-stamp`): its first statement checks the Node 22 floor, before the install stamp or compile cache; then it imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
|
|
84
84
|
| `lib/` | the kernel (below) |
|
|
85
85
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
86
86
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
@@ -105,6 +105,7 @@ and the rules its tests pin.
|
|
|
105
105
|
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
|
|
106
106
|
| `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
|
|
107
107
|
| `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
|
|
108
|
+
| `node-version.mjs` | the CLI startup check and `E_NODE_UNSUPPORTED` envelope for Node before 22, shared with unit tests. No imports or effects; loads on Node 18 and 20 before the install stamp, compile cache or kernel. CI runs the actual CLI on Node 20 (`scripts/check-unsupported-node.mjs`) to prove the refusal precedes every dispatch path |
|
|
108
109
|
| `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
|
|
109
110
|
| `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630), and the warm reader's start (`oats reader --stdio`, whose reads `reader.mjs` imports itself): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
|
|
110
111
|
| `roster-read.mjs`, `workspace-read.mjs`, `read-call.mjs` | the deployment reads (awebai/oats#1630): `oats status` (`roster-read.mjs`: the roster, its drift and its workspace identity) and `oats workspace status` (`workspace-read.mjs`: members, packages, automations, the desktop facts, and the rows `oats sync` reports too), one implementation behind the CLI and a process that answers them many times. Each has an answer function (`statusAnswer`, `workspaceStatusAnswer`: `{ exit, answer, stderr }`, `answer` the JSON the CLI prints, a refusal included) and a data function (`statusView`, `workspaceStatusView`) bin's text renderer reads. `read-call.mjs` is one call's scope: it takes an explicit context (the absolute `dir`, `maxAge`, the caller's read session, the cache, an optional deployments observer), resets at its start every piece of module-level state the reads can reach (`READ_STATE`; `test/read-call-state.test.mjs` scans the reads' import closure and fails on a binding with no row), answers refusals as envelopes, and drains the session's notices. Within one call, two pieces of work are not repeated: `listInstances` hands the records it read to the rest of the read (`records`: `legacyCapturedHomes` and the waiting read take them instead of parsing them again), and `workspace status` asks git for each member clone's remotes once (`remotes`, shared by the automation scope and the desktop facts); both are maps the read makes and drops, never module state. A call registers no process listener, closes no session and reads no argv or cwd: the CLI passes `commandSession` (created at the first remote read, with its exit and signal listeners) and closes it at the end of the command, as for every verb. The read part of the dispatch is there too (`parseMaxAge`, `readBudget`, `callSession`); `test/read-call-equivalence.test.mjs` answers both reads many times in one process and compares each answer with a fresh CLI run's. Leaves: never `core.mjs`. Kernel-private, not in `./core` |
|
|
@@ -131,6 +132,9 @@ and the rules its tests pin.
|
|
|
131
132
|
| `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
|
|
132
133
|
| `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
|
|
133
134
|
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
135
|
+
| `session-providers.mjs` | a capability's `sessionProviders` (feature `session-providers`): the use-time validator (per provider, never from the manifest contract or discovery), `--backend`'s selection among an instance's capabilities, the wire (one call of the home's own module copy per verb, with the hook environment) and the rules of each verb's answer, the receipt's `runtime` for a provider home. A leaf: `session-inspect.mjs` and `instance-listing.mjs` call a provider on the hot reads; `core.mjs` holds the launch, stop, start and retire of a provider home. |
|
|
136
|
+
| `hook-env.mjs` | the environment a capability's code runs with in an instance home (`lifecycleHookEnv`, `teamEnv`, `stableSoulId`, `instanceSoulDir`, `kernelBin`): every lifecycle hook's and a session provider's commands'. A leaf, re-exported by `core.mjs`. |
|
|
137
|
+
| `provider-resume.mjs` | the resume cap of a home on a session provider: at most `RESUME_LIMIT` resumes of one home in `RESUME_WINDOW_MS`, in one boot, counted before the provider's input is called (the sweep's notice, `session start --resume`, any input to a lost session). One kernel-private file per home under `OATS_HOME_DIR`. A leaf. |
|
|
134
138
|
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
135
139
|
| `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep at the start, then the tick and the sweep each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
|
|
136
140
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
package/docs/integrations.md
CHANGED
|
@@ -41,7 +41,7 @@ arrives from.
|
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
43
|
oats.okf: v6.3.0
|
|
44
|
-
oats.aweb: v1.
|
|
44
|
+
oats.aweb: v1.47.0
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
47
47
|
defaults:
|
|
@@ -97,7 +97,7 @@ operations in full.
|
|
|
97
97
|
- **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
|
|
98
98
|
tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
|
|
99
99
|
identity in its default team. **An existing workspace opts in** by pinning
|
|
100
|
-
`oats.aweb: v1.
|
|
100
|
+
`oats.aweb: v1.47.0` (the feature needs 1.31.0 or later), adding
|
|
101
101
|
`tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
|
|
102
102
|
`oats sync`. Only new spawns get it. A soul that names its own tasks
|
|
103
103
|
provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
|