@awebai/oats 0.69.23 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -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 +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- 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/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- 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/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- 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
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# OATS 0.70.0
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
The kernel side of session providers is complete. A provider that sandboxes
|
|
6
|
+
its harness is handed the sandbox allowances the instance needs, its trees and
|
|
7
|
+
the kernel's own state to protect. For a provider home, the kernel runs only
|
|
8
|
+
its own copy of the home's modules, kept outside the home, so nothing the
|
|
9
|
+
agent writes in its home changes what the kernel runs. The session-provider
|
|
10
|
+
wire is version 1.3. tmux homes are unchanged, except that every event-log
|
|
11
|
+
write now refuses a log that is a link or a FIFO.
|
|
12
|
+
|
|
13
|
+
## Upgrade
|
|
14
|
+
|
|
15
|
+
- **The Desktop and the CLI:** a Desktop of 0.69.18 to 0.69.24 accepts the
|
|
16
|
+
0.70.0 CLI as above its tested bound. It then runs only its reads,
|
|
17
|
+
terminals, Spawn, Start, Restart, the colour and the background, and says
|
|
18
|
+
so, until Desktop 0.70.0 is installed. A Desktop of 0.69.17 or older
|
|
19
|
+
refuses the 0.70.0 CLI until then. Upgrade both.
|
|
20
|
+
- **A provider home spawned by an earlier kernel must be respawned.** Its
|
|
21
|
+
receipt has no `composition`, so this kernel runs none of its
|
|
22
|
+
capabilities: its session reads unavailable, and every verb's message
|
|
23
|
+
says to retire it and spawn it again. `oats retire <name> --force` removes
|
|
24
|
+
it (its retire hooks are not run, and the retire says which). The
|
|
25
|
+
session-provider wire has been experimental so far, and no released
|
|
26
|
+
provider exists; tmux homes are not affected.
|
|
27
|
+
- **For a capability's author:** in a provider home your hooks and commands
|
|
28
|
+
run from the kernel's copy of your capability, not from
|
|
29
|
+
`<home>/.oats/modules/<capability>/`. Find the home by
|
|
30
|
+
`OATS_INSTANCE_HOME`, never by your own location, and never write beside
|
|
31
|
+
your own code.
|
|
32
|
+
- **For a provider's author:** if your provider sandboxes its harness, keep
|
|
33
|
+
`<instances>/.oats-retirement/` unwritable from the session (the kernel's
|
|
34
|
+
copies of the modules and the receipts are there) and leave it readable,
|
|
35
|
+
and its `modules/` executable, at the same path (a hook hands the harness
|
|
36
|
+
scripts there); the launch input names it in `protected`, and deny writes to the Git pointer, configuration and hooks
|
|
37
|
+
of each path in `trees`. Nothing in this release makes a provider's
|
|
38
|
+
sandboxed mode a security boundary between an agent and the operator's
|
|
39
|
+
account.
|
|
40
|
+
|
|
41
|
+
## Added
|
|
42
|
+
|
|
43
|
+
- **The kernel runs its own copy of a provider home's modules, never the
|
|
44
|
+
home's.** A session provider may run its harness in a sandbox that still
|
|
45
|
+
lets the agent write its own home, and the kernel that runs the home's
|
|
46
|
+
hooks and the provider's commands runs outside any sandbox, while that
|
|
47
|
+
agent runs. For a home on a session provider the kernel now runs nothing
|
|
48
|
+
that is in the home
|
|
49
|
+
([What the kernel trusts in a provider home](../capabilities.md#what-the-kernel-trusts-in-a-provider-home)):
|
|
50
|
+
- The kernel keeps its own copy of the home's modules outside the home,
|
|
51
|
+
at `<instances>/.oats-retirement/modules/<hash of the home>/<store>/`,
|
|
52
|
+
made once by the spawn, before the provider is asked anything and
|
|
53
|
+
before any hook of the spawn runs. Every
|
|
54
|
+
lifecycle hook and worktree hook, every command of the provider, every
|
|
55
|
+
capability's readiness check and every command or operation dispatched
|
|
56
|
+
in the home runs from it, and the home's manifests are read there. The
|
|
57
|
+
copies in the home stay, for the agent and its harness.
|
|
58
|
+
- The home's receipt records its `composition`: which store holds those
|
|
59
|
+
copies, which modules the home has and where each came from, and the
|
|
60
|
+
capability rows the spawn resolved (settings, their origins, hook
|
|
61
|
+
commands, levels). `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS` and the hook
|
|
62
|
+
commands of such a home come from the receipt, never from
|
|
63
|
+
`instance.json`.
|
|
64
|
+
- A retire removes the kernel's copy with the home. `oats instance
|
|
65
|
+
upgrade` makes the copies for the upgraded home in a new store and then
|
|
66
|
+
writes the receipt once, naming the new store and the new rows together:
|
|
67
|
+
an upgrade that fails or is killed before that write leaves the old copy
|
|
68
|
+
and the old rows, and `--undo` names them again.
|
|
69
|
+
- A provider home's status row, its remote roster row and a start's
|
|
70
|
+
answer gain an optional key beside `modules`, `moduleCopy: {runs:
|
|
71
|
+
"kernel-copy", homeCopy: "same" | "differs", differs}`: which copy the
|
|
72
|
+
kernel runs, and whether the home's own record of its modules is the
|
|
73
|
+
kernel's (records only, nothing hashed). `oats readiness --home` of a
|
|
74
|
+
provider home gains `kernelCopies: {store, differing}`, which compares
|
|
75
|
+
the files. `modules` is unchanged.
|
|
76
|
+
- Nothing is hashed at a call, so a read of a provider home costs no more
|
|
77
|
+
than before. The cost is disk: a provider home's modules are kept twice
|
|
78
|
+
(about 1.3 MB for a home with the usual capabilities).
|
|
79
|
+
- **The launch input and the check's planned launch carry `trees`**: the
|
|
80
|
+
home's `work/`, then every extra tree Git itself lists for the home, as
|
|
81
|
+
absolute paths. A provider that sandboxes keeps each tree's Git pointer,
|
|
82
|
+
configuration and hooks unwritable. Additive; the wire stays 1.3.
|
|
83
|
+
- **The launch input and the check's planned launch carry `protected`**:
|
|
84
|
+
the kernel's own state for the home, today `<instances>/.oats-retirement/`:
|
|
85
|
+
paths a sandboxed agent must never write, and that a provider must not
|
|
86
|
+
block reading or executing. The kernel makes each directory before the
|
|
87
|
+
launch. Additive; the wire stays 1.3.
|
|
88
|
+
- **`OATS_PREVIOUS_BACKEND`** for launch hooks: the backend the home was
|
|
89
|
+
last launched on, as its receipt records it (`tmux` or a provider's
|
|
90
|
+
name); absent at a first launch. A capability that keeps files of its own
|
|
91
|
+
in a home for one backend removes them only when this names that backend.
|
|
92
|
+
|
|
93
|
+
- **Sandbox allowances for session providers.** A session provider that runs
|
|
94
|
+
its harness in a sandbox is handed, with every launch, what the instance
|
|
95
|
+
needs from outside it: `sandbox: {domains, write, missing}` in the launch
|
|
96
|
+
input. The kernel builds the list from the deployment's configuration and
|
|
97
|
+
nothing else adds to it.
|
|
98
|
+
- A capability that fills an instance's messaging, knowledge or tasks slot
|
|
99
|
+
may declare `sandboxDomains` in its manifest: `{"setting": "<key>"}`
|
|
100
|
+
(the setting's value is a URL, a bare host, or a map from team id to
|
|
101
|
+
one, of which the instance's own teams' entries are taken; `"optional":
|
|
102
|
+
true` where the session works without the host) or `{"settingFile":
|
|
103
|
+
"<key>", "urls": "<JSON pointer>"}` (the hosts in a JSON file of the
|
|
104
|
+
deployment). On any other capability a provider launch is refused,
|
|
105
|
+
`E_BACKEND_SANDBOX_HOST`; so is a value that gives no plain host, and a
|
|
106
|
+
file that is not the deployment's own.
|
|
107
|
+
- `write` is the deployment's events directory, which the kernel creates
|
|
108
|
+
before the launch.
|
|
109
|
+
- Values come from the deployment's configuration as a spawn preview
|
|
110
|
+
resolves it, never from an instance home. A start and a restart resolve
|
|
111
|
+
it again, for the deployment and the soul the home's path names (its
|
|
112
|
+
`instance.json` decides neither), without reaching any remote: the
|
|
113
|
+
workspace as this host last read it, and `oats-local.yaml` as it is now; when that cannot be done the launch input says `sandbox:
|
|
114
|
+
{unavailable}`, and the provider refuses a launch it would sandbox.
|
|
115
|
+
- A provider's `check` is handed the planned launch (`launch: {harness,
|
|
116
|
+
yolo, args, sandbox}`) before every launch, and before any hook runs:
|
|
117
|
+
a spawn its backend refuses runs no hook and leaves no home, and a
|
|
118
|
+
refused start runs no hook and stops nothing. `args` are the launch
|
|
119
|
+
configuration's own; a hook's arguments reach the launch input only.
|
|
120
|
+
- A read of a home while it is being spawned (`oats session inspect`, a
|
|
121
|
+
status row) answers `E_SESSION_UNAVAILABLE`, "is being spawned", where
|
|
122
|
+
it answered that the home's records disagree. For a tmux home too.
|
|
123
|
+
- `oats spawn --preview`, a start's answer and `oats readiness --home`
|
|
124
|
+
list each host with who asked for it and each path with its reason;
|
|
125
|
+
`oats capabilities show` lists `sandboxDomains` and its problems.
|
|
126
|
+
- **One wire version.** A session provider declares the wire it speaks
|
|
127
|
+
(`sessionProviders.<name>.wire`, `"1.3"`), and every request carries the
|
|
128
|
+
kernel's. A provider that declares another, or none, is refused
|
|
129
|
+
`E_BACKEND_WIRE`, naming both.
|
|
130
|
+
- What the kernel runs of a provider home is its own copy of the home's
|
|
131
|
+
modules, kept outside the home: see "The kernel runs its own copy of a
|
|
132
|
+
provider home's modules" in these notes.
|
|
133
|
+
- tmux launches are unchanged: no `sandbox`, and `sandboxDomains` is not
|
|
134
|
+
read. A kernel from before session providers ignores the key.
|
|
135
|
+
|
|
136
|
+
## Changed
|
|
137
|
+
|
|
138
|
+
- **Every Git the kernel runs over a provider home's trees runs with the
|
|
139
|
+
repository's hooks and its file monitor off**: now also a spawn's `git
|
|
140
|
+
worktree add` and its rollback, and `oats worktree add` and `remove` (the
|
|
141
|
+
reads and a retire already did, for every home). A tmux home's Git is
|
|
142
|
+
unchanged.
|
|
143
|
+
- **An append to an instance's event log never writes through a link.** The
|
|
144
|
+
home's log and the deployment's are opened without following a symbolic
|
|
145
|
+
link, and written only when they are a regular file with one name: a
|
|
146
|
+
symbolic link, a hard link and a FIFO at a log's name are refused, as the
|
|
147
|
+
reader already refuses them. The other log still gets its row.
|
|
148
|
+
- **`oats instance upgrade` of a provider home** takes its module set and
|
|
149
|
+
each module's source from the receipt (a module only the home's record
|
|
150
|
+
names refuses it), runs each upgrade hook from the kernel's copy, and
|
|
151
|
+
keeps the pair it replaced, so that `--undo` names the kernel's previous
|
|
152
|
+
copies and rows again in one write. It is not resumed after an
|
|
153
|
+
interruption (`E_UPGRADE_PARTIAL`): the journal it would resume from is
|
|
154
|
+
in the home. The kernel's side is whole either way; such a home is
|
|
155
|
+
retired and spawned again.
|
|
@@ -209,6 +209,18 @@ the locked package versions with `oats instance upgrade`. Member modules and
|
|
|
209
209
|
the soul body still require a new spawn. See
|
|
210
210
|
[upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
|
|
211
211
|
|
|
212
|
+
For a home on a session provider the kernel keeps its own copy of the
|
|
213
|
+
home's modules outside the home, beside the home's receipt, and the receipt
|
|
214
|
+
records the home's capability rows (its `composition`). The kernel runs such
|
|
215
|
+
a home's hooks and commands from its own copy and reads their settings from
|
|
216
|
+
the receipt, never from the home's copies or its `instance.json`. A retire
|
|
217
|
+
removes that copy with the home, and `oats instance upgrade` exchanges it
|
|
218
|
+
and rewrites the rows in one write of the receipt, so that a failed upgrade
|
|
219
|
+
leaves the old copy and the old rows together, and `--undo` names the
|
|
220
|
+
previous pair again. An interrupted upgrade of such a home is not resumed:
|
|
221
|
+
its journal is in the home. See
|
|
222
|
+
[What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home).
|
|
223
|
+
|
|
212
224
|
### The harness starts normally
|
|
213
225
|
|
|
214
226
|
OATS is a skill contributor, not a skill sandbox. The harness (pi, Claude Code,
|
|
@@ -1550,6 +1562,51 @@ still name the old path. A child attached to one of the home's extra trees
|
|
|
1550
1562
|
is handled the same way, tree by tree
|
|
1551
1563
|
([extra trees at retire](#extra-trees-at-retire)).
|
|
1552
1564
|
|
|
1565
|
+
#### Retiring a home on a session provider
|
|
1566
|
+
|
|
1567
|
+
A home whose session runs on a
|
|
1568
|
+
[session provider](execution-targets.md#session-providers) (its
|
|
1569
|
+
`instance.json` records `backend` and `session`) is retired by a kernel that
|
|
1570
|
+
lists the feature `session-providers`, in this order:
|
|
1571
|
+
|
|
1572
|
+
1. **The stop is recorded** (`stoppedAt` in the home's receipt): from then on
|
|
1573
|
+
inspect answers stopped and every input to the home is refused
|
|
1574
|
+
`E_SESSION_NOT_RUNNING`, so nothing restarts its session.
|
|
1575
|
+
2. **Inputs that were being sent are waited for.** An input already on its
|
|
1576
|
+
way when the stop was recorded can have the provider restart the session,
|
|
1577
|
+
and once the home is gone nothing could stop it. The retire waits for
|
|
1578
|
+
those inputs to end (at most an input's timeout and 5 s). An input still
|
|
1579
|
+
being sent after that does not hold the retire: its provider command is
|
|
1580
|
+
ended, and the retire goes on, with a warning that names that input's
|
|
1581
|
+
process. An input whose `oats` command was killed is not waited for: its
|
|
1582
|
+
provider command is ended at once. (Every stop of a provider home waits
|
|
1583
|
+
so, a plain `oats instance stop` too.)
|
|
1584
|
+
3. **The provider is asked to stop the session**, with the usual grace,
|
|
1585
|
+
never escalated. A launch that was sent and never recorded (a command
|
|
1586
|
+
killed while it launched) is settled the same way: the provider is asked
|
|
1587
|
+
to stop whatever it runs for the home.
|
|
1588
|
+
4. **No process may work in the home**, whatever the provider answered: a
|
|
1589
|
+
stop it confirms can still leave one behind (a harness that outlives its
|
|
1590
|
+
server for a while), and there is no window whose absence would say
|
|
1591
|
+
otherwise. With a process working in the home, or when that cannot be
|
|
1592
|
+
told, the retire refuses `E_RUNTIME_QUIESCE_FAILED` at once, names the
|
|
1593
|
+
processes and keeps the home; its stop stays recorded. A shell whose
|
|
1594
|
+
working directory is in the home counts too, and one named in the
|
|
1595
|
+
refusal may be your own: leaving the home's directory clears it.
|
|
1596
|
+
5. The retire hooks run (the provider's own archives its session there), the
|
|
1597
|
+
work is preserved as for any home, and the home is removed.
|
|
1598
|
+
|
|
1599
|
+
**When the provider cannot confirm the stop** (it fails, it does not answer,
|
|
1600
|
+
or its capability is no longer among the home's modules after an upgrade),
|
|
1601
|
+
the retire does not strand the home. It goes on when step 4 finds no
|
|
1602
|
+
process in the home, and its answer then carries a warning that the session
|
|
1603
|
+
was not stopped through its backend: archive or remove that session with the
|
|
1604
|
+
provider's own tooling.
|
|
1605
|
+
|
|
1606
|
+
A retire's plan (`oats retire <instance> --plan`) reads the session through
|
|
1607
|
+
the provider, as `oats session inspect` does. A kernel without the feature
|
|
1608
|
+
refuses to retire such a home (`E_RUNTIME_ENDPOINT_UNKNOWN`) and keeps it.
|
|
1609
|
+
|
|
1553
1610
|
#### What `work/` is at retire
|
|
1554
1611
|
|
|
1555
1612
|
The retire and its plan read what is at `<home>/work` once, by one rule
|
package/docs/trust-model.md
CHANGED
|
@@ -74,7 +74,14 @@ Inside one trust group, none of these hold:
|
|
|
74
74
|
[Trust is the workspace's declaration](capabilities.md#mental-model) of a
|
|
75
75
|
member repo or a package. The kernel then checks that what it is about to
|
|
76
76
|
run is the copy made at spawn. That copy is in the agent's home, so the
|
|
77
|
-
check is no defence against the agent.
|
|
77
|
+
check is no defence against the agent. For a home on a session provider
|
|
78
|
+
the kernel does not run the home's copy at all: it runs its own copy of
|
|
79
|
+
the home's modules, kept outside the home and made at the spawn, and
|
|
80
|
+
takes the capability settings and hook commands from the home's receipt,
|
|
81
|
+
kept there too
|
|
82
|
+
([What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
83
|
+
That holds against an agent that cannot write outside its home, which is
|
|
84
|
+
the provider's sandbox to ensure, not OATS's.
|
|
78
85
|
- That a harness's sandbox is a boundary. OATS counts none as one and relies
|
|
79
86
|
on none. Where a harness restricts what its agent can write, that is the
|
|
80
87
|
harness's property and not a promise of OATS.
|
package/docs/tui.md
CHANGED
|
@@ -267,6 +267,25 @@ while a terminal is open); under 80 columns it has the whole width.
|
|
|
267
267
|
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
268
268
|
beside the sidebar, where the detail was, as a tab: see
|
|
269
269
|
[Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
|
|
270
|
+
- **An agent that runs on a session provider** (a capability's session
|
|
271
|
+
backend, such as bb) has no terminal. The list shows it in the state OATS
|
|
272
|
+
reports (the detail says `running` or `stopped` when OATS says which, else
|
|
273
|
+
the provider's own word), and `S`, `R`, `X` and `D` act on it as on any agent. `Enter` opens
|
|
274
|
+
nothing: the line says where it runs ("Runs in a bb thread; open it in
|
|
275
|
+
bb.") and, when the provider offers a link, prints it under that
|
|
276
|
+
(`"Open in bb: http://…"`) for you to open. The palette does not
|
|
277
|
+
list it among the agents to open, the agent steps pass over it, and a
|
|
278
|
+
workspace's remembered tabs never open it. Its `!` mark shows whenever
|
|
279
|
+
OATS reports that it waits on you and it is not stopped
|
|
280
|
+
([how the clients read `backend`](desktop-cli-api.md#row-backend-clients)).
|
|
281
|
+
Start the TUI outside an agent's home: OATS refuses to retire a home while
|
|
282
|
+
a process works in it, the TUI's own included, and names that process.
|
|
283
|
+
A known limit: when another machine's agent moves to a session provider
|
|
284
|
+
while the TUI is opening it, a check of its terminal that fails says
|
|
285
|
+
OATS's failure ("The session is no longer running on …") and not where
|
|
286
|
+
it runs, and an agent OATS holds by then (a retire that began) may have a
|
|
287
|
+
viewer started for it, which OATS refuses (`E_SESSION_NO_TERMINAL`).
|
|
288
|
+
Neither reaches another agent.
|
|
270
289
|
|
|
271
290
|
**A view of more than one deployment** (this machine and another, or two
|
|
272
291
|
deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
@@ -704,7 +723,8 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
704
723
|
as the workspace was left. The shown tab is the most recent for
|
|
705
724
|
[the palette](#the-palette).
|
|
706
725
|
- A tab whose instance is gone or cannot be opened now (retired,
|
|
707
|
-
stopped
|
|
726
|
+
stopped, or now running on a session provider, which has no terminal)
|
|
727
|
+
is dropped, and nothing is said of it. A group the drops
|
|
708
728
|
leave with no tab goes, as when its last tab is closed; a group that
|
|
709
729
|
was empty when the workspace was left is empty again. A shown tab
|
|
710
730
|
dropped gives its place to the next, else the one before.
|
package/docs/upgrading.md
CHANGED
|
@@ -6,12 +6,12 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.
|
|
10
|
-
The 0.
|
|
9
|
+
The latest version is **OATS 0.70.0** ([release notes](release-notes/v0.70.0.md)).
|
|
10
|
+
The 0.70.0 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
|
|
11
11
|
Desktop and the CLI can be upgraded [in either order](#either-order-works).
|
|
12
12
|
|
|
13
13
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
14
|
-
0.
|
|
14
|
+
0.70.0,** in the [release notes](release-notes/): it says what to do before
|
|
15
15
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
16
16
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
17
17
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -20,8 +20,8 @@ prints the version you have.
|
|
|
20
20
|
Then, on each host:
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
# 0. where the Desktop is installed: Desktop 0.
|
|
24
|
-
npm install -g @awebai/oats@0.
|
|
23
|
+
# 0. where the Desktop is installed: Desktop 0.70.0, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.70.0 # 1. the CLI
|
|
25
25
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
26
26
|
oats doctor # 3. in the same deployment
|
|
27
27
|
```
|
|
@@ -217,6 +217,20 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
217
217
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
218
218
|
here.
|
|
219
219
|
|
|
220
|
+
- **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
|
|
221
|
+
the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
|
|
222
|
+
reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
|
|
223
|
+
0.69.17 or older refuses it until then. A session-provider home spawned by
|
|
224
|
+
an earlier kernel is retired with `--force` and spawned again (no released
|
|
225
|
+
provider exists). Capability authors: in a provider home, hooks run from
|
|
226
|
+
the kernel's copy of the capability; find the home by `OATS_INSTANCE_HOME`.
|
|
227
|
+
- **[0.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
|
|
228
|
+
or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
|
|
229
|
+
The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0. Respawn an
|
|
230
|
+
instance of `oats-maintainer` or `oats-setup-admin` once (okf.json version
|
|
231
|
+
2), and respawn or move other instances with `oats instance upgrade` to take
|
|
232
|
+
oats.core 2.16.0. A legacy oats.aweb grant seat (1.12–1.24) fills its seat
|
|
233
|
+
record at its next start, or refuses with the respawn remedy.
|
|
220
234
|
- **[0.69.23](release-notes/v0.69.23.md#upgrade):** the catalog pins
|
|
221
235
|
oats.framework 1.27.0, oats.aweb 1.46.0 and oats.okf 6.3.0. Respawn
|
|
222
236
|
instances, or move stopped ones with `oats instance upgrade`, to take the
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.28.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v6.3.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -62,7 +62,7 @@ teams: # SHARED teams: the same provider tea
|
|
|
62
62
|
engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
|
|
63
63
|
reviewers: { description: Code review } # declared, not created yet (no `team` id): readiness team-unmapped
|
|
64
64
|
defaultTeam: engineering # the workspace's default team; see Teams below
|
|
65
|
-
souls: #
|
|
65
|
+
souls: # each soul's team: its default, and the others it may join
|
|
66
66
|
platform/*: { teams: [reviewers] }
|
|
67
67
|
|
|
68
68
|
defaults:
|
|
@@ -541,13 +541,21 @@ teams: # SHARED teams: the same provider team
|
|
|
541
541
|
docs: { description: Docs rota } # declared, not created yet: team-unmapped
|
|
542
542
|
defaultTeam: engineering # the workspace's fallback default team (a shared label)
|
|
543
543
|
localTeams: false # may deployments declare their own teams? (absent: false)
|
|
544
|
-
souls: #
|
|
544
|
+
souls: # the one declaration of each soul's team, per soul or pattern
|
|
545
545
|
"*": { teams: [] } # unlisted souls: default only (also what no entry means)
|
|
546
546
|
security-souls/*: { default: security, teams: [engineering] }
|
|
547
547
|
security-souls/incident-responder: { default: security, teams: [engineering, docs] }
|
|
548
548
|
oats.engineering/*: { teams: any } # any: every shared team of this file
|
|
549
549
|
```
|
|
550
550
|
|
|
551
|
+
- **`souls:` is the one declaration of which team a soul belongs to.** An entry's
|
|
552
|
+
`default` is the team that soul's instances join; its `teams` are the others they
|
|
553
|
+
may join. A pattern entry (`<member>/*`, `*`) sets them for a set of souls, and a
|
|
554
|
+
named entry overrides it for one. Nothing else assigns a soul a team: not the
|
|
555
|
+
soul's own files, and not where it runs. A deployment's local `defaultTeam` is only
|
|
556
|
+
a fallback for a soul no entry gives a default (below). The sandboxes design
|
|
557
|
+
([design record](design/2026-11-19-sandboxes.md), not built yet) places souls in
|
|
558
|
+
sandboxes without touching this declaration.
|
|
551
559
|
- **Shared teams** (`teams.<label> = { description?, team? }`): a shared team
|
|
552
560
|
without `team` is declared but not created yet (readiness `team-unmapped`):
|
|
553
561
|
its owner creates it with the messaging provider, then commits the id.
|
|
@@ -587,8 +595,8 @@ souls: # per soul pattern: its default team an
|
|
|
587
595
|
|
|
588
596
|
The default, in order:
|
|
589
597
|
|
|
590
|
-
1. the soul's `default` from `souls
|
|
591
|
-
sets one);
|
|
598
|
+
1. the soul's `default` from `souls:`, the team its instances join (the most
|
|
599
|
+
specific matching key that sets one);
|
|
592
600
|
2. else the deployment's `oats-local.yaml` `defaultTeam`, only when
|
|
593
601
|
`localTeams: true`;
|
|
594
602
|
3. else the workspace's `defaultTeam`;
|
package/lib/automation-scope.mjs
CHANGED
|
@@ -17,7 +17,7 @@ export function childEnv() {
|
|
|
17
17
|
for (const key of [...RESERVED_LAUNCH_ENV,
|
|
18
18
|
"OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
|
|
19
19
|
"OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
|
|
20
|
-
"OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
|
|
20
|
+
"OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_BACKEND", "OATS_PREVIOUS_BACKEND", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
|
|
21
21
|
"OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
|
|
22
22
|
"OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
|
|
23
23
|
]) delete env[key];
|
package/lib/capability-show.mjs
CHANGED
|
@@ -32,6 +32,8 @@ import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifest
|
|
|
32
32
|
import { memberRowByKey } from "./workspace.mjs";
|
|
33
33
|
import { sameRepo } from "./repo-moves.mjs";
|
|
34
34
|
import { triggerSourcesOf } from "./trigger-sources.mjs";
|
|
35
|
+
import { sessionProvidersOf } from "./session-providers.mjs";
|
|
36
|
+
import { sandboxDomainsOf } from "./sandbox-allowances.mjs";
|
|
35
37
|
|
|
36
38
|
export const CAPABILITY_SHOW_API = 1;
|
|
37
39
|
/** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
|
|
@@ -194,6 +196,23 @@ function triggerSourceKeys(manifest) {
|
|
|
194
196
|
return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
|
|
195
197
|
}
|
|
196
198
|
|
|
199
|
+
/** `sandboxDomains` (lib/sandbox-allowances.mjs), as declared, and what is wrong with it: added keys,
|
|
200
|
+
* each only when there is something to say. A malformed declaration is shown here, and refuses a
|
|
201
|
+
* session-provider launch of an instance that composes the capability. */
|
|
202
|
+
function sandboxDomainKeys(manifest) {
|
|
203
|
+
if (manifest?.sandboxDomains === undefined) return {};
|
|
204
|
+
const { problems } = sandboxDomainsOf(manifest);
|
|
205
|
+
return { sandboxDomains: manifest.sandboxDomains, ...(problems.length ? { sandboxDomainProblems: problems } : {}) };
|
|
206
|
+
}
|
|
207
|
+
/** The session providers a manifest declares (lib/session-providers.mjs), as declared, and the problems a
|
|
208
|
+
* `--backend` naming them would get: added keys, each only when there is something to say. A malformed
|
|
209
|
+
* declaration is shown, never refused. */
|
|
210
|
+
function sessionProviderKeys(manifest) {
|
|
211
|
+
if (manifest?.sessionProviders === undefined) return {};
|
|
212
|
+
const { problems } = sessionProvidersOf(manifest);
|
|
213
|
+
return { sessionProviders: manifest.sessionProviders, ...(problems.length ? { sessionProviderProblems: problems } : {}) };
|
|
214
|
+
}
|
|
215
|
+
|
|
197
216
|
/** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
|
|
198
217
|
export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
199
218
|
const r = bindRemote(remote, remoteOptions);
|
|
@@ -220,7 +239,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
|
220
239
|
skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
|
|
221
240
|
}
|
|
222
241
|
}
|
|
223
|
-
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest) };
|
|
242
|
+
return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source), ...triggerSourceKeys(source.manifest), ...sessionProviderKeys(source.manifest), ...sandboxDomainKeys(source.manifest) };
|
|
224
243
|
}
|
|
225
244
|
|
|
226
245
|
/** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
|
package/lib/command-flags.mjs
CHANGED
|
@@ -27,7 +27,7 @@ export function sameWorkDeprecation(argv) {
|
|
|
27
27
|
return undefined;
|
|
28
28
|
}
|
|
29
29
|
export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
|
|
30
|
-
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
30
|
+
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--related-work|--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux|<session provider>] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
31
31
|
export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
32
32
|
export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
|
|
33
33
|
export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
|
|
@@ -158,7 +158,7 @@ export const COMMAND_FLAGS = Object.freeze([
|
|
|
158
158
|
refused: { ...NATIVE_RECORD_GONE, "--resume": "--resume exists on session start only: it brings back a session that was lost" },
|
|
159
159
|
usage: "usage: oats session restart (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--stop-grace <seconds>] [--json]" },
|
|
160
160
|
{ command: "session resume", operands: [], values: ["--deployment"],
|
|
161
|
-
refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan] [--json]" },
|
|
161
|
+
refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--without-provider-inspect", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] [--json]" },
|
|
162
162
|
{ command: "session input", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--text-file"], switches: ["--json"], usage: "usage: oats session input --home <abs> [--text-file <path>] [--json]" },
|
|
163
163
|
{ command: "session receive", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--name"], switches: ["--json"], usage: "usage: oats session receive --home <abs> --name <file name> [--json]" },
|
|
164
164
|
{ command: "session upload", operands: [], refused: NATIVE_RECORD_GONE, values: ["--file", ...SESSION_ADDRESS], switches: ["--json"],
|
package/lib/compile-cache.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** Node's compile cache for the CLI (awebai/oats#1630): V8 keeps the code it compiled for the
|
|
2
2
|
* kernel's modules, so a command does not recompile them all on every run. Kernel-private, not
|
|
3
3
|
* exported from `./core` and not a contract: `bin/oats.mjs` calls enableCliCompileCache before it
|
|
4
|
-
* imports the kernel (only
|
|
4
|
+
* imports the kernel (only dependency-free startup helpers are parsed before), and in-process
|
|
5
5
|
* consumers never call it (they run in their own processes).
|
|
6
6
|
*
|
|
7
7
|
* - The cache is `$OATS_HOME_DIR/compile-cache` (`~/.oats/compile-cache`), made 0700 here: Node's
|