@awebai/oats 0.69.24 → 0.70.1
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 +62 -6
- package/docs/capabilities.md +374 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/design/2026-11-21-human-ids-contract.md +342 -0
- package/docs/design/README.md +2 -0
- package/docs/desktop-cli-api.md +111 -4
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +26 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/release-notes/v0.70.1.md +70 -0
- package/docs/schedules.md +42 -3
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +16 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +408 -66
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +2 -1
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +64 -10
- package/lib/instance-listing.mjs +5 -1
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/remote.mjs +33 -1
- package/lib/retire-admission.mjs +7 -0
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +6 -4
- package/lib/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +68 -19
- package/lib/session-receipt.mjs +93 -0
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package.json +1 -1
|
@@ -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.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# OATS 0.70.1
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
A preview on a session provider now asks the provider's own readiness check,
|
|
6
|
+
so it no longer reads clean for a launch the provider then refuses. A
|
|
7
|
+
schedule's save asks the same, with the job's own `yolo`. tmux homes and their
|
|
8
|
+
previews are unchanged.
|
|
9
|
+
|
|
10
|
+
## Upgrade
|
|
11
|
+
|
|
12
|
+
- **The Desktop and the CLI** can be upgraded in either order.
|
|
13
|
+
- **A scheduled or triggered spawn on a provider that launches only in full
|
|
14
|
+
mode (bb's)** needs `yolo: true` in its definition, or a launch
|
|
15
|
+
configuration that sets it. A job without it is now refused when saved, where
|
|
16
|
+
it used to fail at each run.
|
|
17
|
+
|
|
18
|
+
## Changed
|
|
19
|
+
|
|
20
|
+
- **A spawn job on a session provider is checked by the provider when it is
|
|
21
|
+
saved.** A spawn's preview now asks a session provider's `check` with the
|
|
22
|
+
launch that is planned, and `oats schedule add`, `update` and `test` ask
|
|
23
|
+
that preview with the job's own launch selection, its `yolo` included
|
|
24
|
+
([spawn](../schedules.md#kinds)). On a provider that launches only in full
|
|
25
|
+
mode:
|
|
26
|
+
- a job with `yolo: true` is saved and launches, as one whose launch
|
|
27
|
+
configuration sets yolo does (a build with the preview's new check and
|
|
28
|
+
without this change refused the job's own `yolo: true` on `add` and
|
|
29
|
+
`update`, and `oats schedule test` said its soul did not resolve: the
|
|
30
|
+
schedule's preview did not carry it);
|
|
31
|
+
- a job with no `yolo` is refused when saved (`E_SCHEDULE_INVALID`,
|
|
32
|
+
`details.code: "E_BACKEND_SANDBOXED_MODE"`), and `oats schedule test`
|
|
33
|
+
reports it, where it used to fail only at its run. One the
|
|
34
|
+
save did not ask the provider about (its soul was already spawned in
|
|
35
|
+
the deployment, or the provider comes from a member module, which a
|
|
36
|
+
preview does not ask) fails at each run, `launch-failed` with `errorCode:
|
|
37
|
+
"E_BACKEND_SANDBOXED_MODE"`, and leaves no home.
|
|
38
|
+
|
|
39
|
+
## Fixed
|
|
40
|
+
|
|
41
|
+
- **A preview on a session provider no longer reads clean for a launch the
|
|
42
|
+
provider will refuse.** `oats spawn --preview` of a spawn on a session
|
|
43
|
+
provider read complete, with no problem and no warning, and the spawn was
|
|
44
|
+
then refused by the provider's readiness check and undone (with a provider
|
|
45
|
+
that launches only in full mode and no full-mode choice:
|
|
46
|
+
`E_BACKEND_SANDBOXED_MODE`). A preview now asks the provider's `check` with
|
|
47
|
+
the launch that is planned, as the spawn does before any hook runs
|
|
48
|
+
([spawn preview](../desktop-cli-api.md), [check](../capabilities.md#check-optional)):
|
|
49
|
+
- a launch the provider would refuse fails the preview with the spawn's own
|
|
50
|
+
code and creates nothing; a provider that cannot be asked is
|
|
51
|
+
`E_BACKEND_NOT_READY`; one that outlasts the preview's budget leaves
|
|
52
|
+
`preflight.status: "timeout"`;
|
|
53
|
+
- `oats launch-config preview --home` of a provider home asks it too, and
|
|
54
|
+
shows a refusal as a failed `backend` item, with `ok: false`;
|
|
55
|
+
- a provider in a member module, which runs only from a spawned home, is
|
|
56
|
+
not asked: the preview says so in `warnings`.
|
|
57
|
+
|
|
58
|
+
For a provider's author: `check` may now be handed a home that does not
|
|
59
|
+
exist yet (a spawn's preview hands its planned path). It must only read,
|
|
60
|
+
and treat an absent home as absent.
|
|
61
|
+
|
|
62
|
+
## Documentation
|
|
63
|
+
|
|
64
|
+
- **Schedules and triggers on a session provider**
|
|
65
|
+
([Kinds](../schedules.md#kinds), [Triggers](../schedules.md#triggers)): a
|
|
66
|
+
scheduled or triggered spawn on a provider that launches only in full mode
|
|
67
|
+
needs `yolo: true` in its definition, or a launch configuration that sets
|
|
68
|
+
it; a wake is the input of a provider home's session, and never starts a
|
|
69
|
+
stopped provider home. Tests now cover a wake, a scheduled spawn and a
|
|
70
|
+
triggered spawn on a session provider.
|
package/docs/schedules.md
CHANGED
|
@@ -171,11 +171,13 @@ refuses the key on a trigger.
|
|
|
171
171
|
package soul the workspace offers, see `oats souls`), whether or not this
|
|
172
172
|
deployment has spawned it before. `add` and `update` refuse a job whose
|
|
173
173
|
`oats spawn <agent> --preview`, with the job's `launchConfig`, `harness`,
|
|
174
|
-
`model`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
|
|
174
|
+
`model`, `yolo`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
|
|
175
175
|
with spawn's own message and its code in `details.code`), or whose preview
|
|
176
176
|
answer cannot be confirmed; a soul this deployment has already spawned is
|
|
177
177
|
accepted without the preview. `agentsRoot`, when given, must be the deployment's `agents/` root; `repo`
|
|
178
|
-
is the work repository, as `--repo`. `backend` is `tmux
|
|
178
|
+
is the work repository, as `--repo`. `backend` is `tmux`, or the name of a
|
|
179
|
+
[session provider](execution-targets.md#session-providers) of the soul's
|
|
180
|
+
capabilities; `backend: herdr`
|
|
179
181
|
is refused (`E_HERDR_REMOVED`, naming the file and key: Herdr was removed in
|
|
180
182
|
0.31.0), and a stored job that names it is reported invalid and never runs.
|
|
181
183
|
`model` is a model id (a letter or
|
|
@@ -189,6 +191,23 @@ refuses the key on a trigger.
|
|
|
189
191
|
trailing block naming the job and the minute and ending with `oats retire
|
|
190
192
|
--self`. `wake` (`{cron, tz, message}`) attaches a wake schedule to each
|
|
191
193
|
launched instance.
|
|
194
|
+
|
|
195
|
+
**On a session provider** the run's spawn launches through the provider
|
|
196
|
+
`backend` names. A provider that launches only in full mode (bb's does)
|
|
197
|
+
refuses every other launch at its
|
|
198
|
+
[check](capabilities.md#check-optional), `E_BACKEND_SANDBOXED_MODE`. A job
|
|
199
|
+
on such a provider needs `yolo: true` in its definition, or a launch
|
|
200
|
+
configuration that sets it: the job's `launchConfig`, or the deployment's
|
|
201
|
+
[default for the harness](configuration.md#the-harness-default). Without
|
|
202
|
+
it `add` and `update` refuse the job where they ask the preview
|
|
203
|
+
(`E_SCHEDULE_INVALID`, with `details.code: "E_BACKEND_SANDBOXED_MODE"`),
|
|
204
|
+
and `oats schedule test` reports it. A job the save did not ask the
|
|
205
|
+
provider about (its soul was already spawned here, so `add` and `update`
|
|
206
|
+
ask no preview; or the provider comes from a member module, which a
|
|
207
|
+
preview does not ask) fails at each run: the run is recorded
|
|
208
|
+
`launch-failed` with `errorCode: "E_BACKEND_SANDBOXED_MODE"` and the
|
|
209
|
+
provider's message, its spawn is undone and no home is left; the job tries
|
|
210
|
+
again at its next due minute.
|
|
192
211
|
- **command** `{…, cwd, argv}` — runs an oats-only argv (`argv[0]` is `oats`,
|
|
193
212
|
no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
|
|
194
213
|
inside the deployment. The runner tracks any instance the command's
|
|
@@ -221,6 +240,21 @@ refuses the key on a trigger.
|
|
|
221
240
|
again only at due minutes, so a harness that keeps exiting is not restarted
|
|
222
241
|
in a loop. Unobservable or still starting: skipped, delivery kept pending.
|
|
223
242
|
Word wake messages so that receiving one again is harmless.
|
|
243
|
+
|
|
244
|
+
A home on a [session provider](execution-targets.md#session-providers) has
|
|
245
|
+
no terminal: the message is its session's input, sent once through the
|
|
246
|
+
provider, and a live claim holds it the same way. **A wake never starts a
|
|
247
|
+
provider home OATS stopped.** Its input is refused before any provider
|
|
248
|
+
call: the run is `skipped` with `errorCode: "E_SESSION_NOT_RUNNING"`, and
|
|
249
|
+
the delivery stays pending until the home is started (`oats session
|
|
250
|
+
start`). To a session that is lost (gone, and not stopped by OATS) the
|
|
251
|
+
input is a resume, on which the provider restarts the session, counted
|
|
252
|
+
against the home's cap
|
|
253
|
+
([lost sessions](execution-targets.md#session-providers)). An input the provider itself refuses
|
|
254
|
+
(`E_SESSION_PROMPT_OPEN` while its session shows a prompt,
|
|
255
|
+
`E_SESSION_INPUT_QUEUED`) is `skipped` with that `errorCode`: nothing was
|
|
256
|
+
sent, and the pending delivery is tried again at every tick, then delivered
|
|
257
|
+
once.
|
|
224
258
|
- **operation** `{…, operation, home}` — runs a provider operation
|
|
225
259
|
(`<layer>:<name>`, one the capability filling that layer declares) in the
|
|
226
260
|
instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
|
|
@@ -299,7 +333,12 @@ when the timer cannot reach it.
|
|
|
299
333
|
request's title and body are untrusted and never reach the task. `teams` (optional) becomes the messaging capability's `join=`
|
|
300
334
|
setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
|
|
301
335
|
`launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
|
|
302
|
-
schedules.
|
|
336
|
+
schedules. On a session provider that launches only in full mode (bb's
|
|
337
|
+
does) the spawn needs `yolo: true`, or a launch configuration that sets
|
|
338
|
+
it, as [a schedule's spawn](#kinds) does. Without it each event's spawn
|
|
339
|
+
fails (`spawn-failed`, `E_BACKEND_SANDBOXED_MODE`, kept as the trigger's
|
|
340
|
+
`lastError`), no home is created, and the event stays pending and is tried
|
|
341
|
+
again at each poll.
|
|
303
342
|
- **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
|
|
304
343
|
the slug of the soul's agent name (a package soul's is
|
|
305
344
|
`<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
|
|
@@ -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,
|
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/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.1** ([release notes](release-notes/v0.70.1.md)).
|
|
10
|
+
The 0.70.1 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.1,** 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.1, in either order
|
|
24
|
+
npm install -g @awebai/oats@0.70.1 # 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,17 @@ 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.1](release-notes/v0.70.1.md#upgrade):** a scheduled or triggered
|
|
221
|
+
spawn on a provider that launches only in full mode (bb's) needs `yolo:
|
|
222
|
+
true`, or a launch configuration that sets it; a job without it is now
|
|
223
|
+
refused when saved.
|
|
224
|
+
- **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
|
|
225
|
+
the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
|
|
226
|
+
reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
|
|
227
|
+
0.69.17 or older refuses it until then. A session-provider home spawned by
|
|
228
|
+
an earlier kernel is retired with `--force` and spawned again (no released
|
|
229
|
+
provider exists). Capability authors: in a provider home, hooks run from
|
|
230
|
+
the kernel's copy of the capability; find the home by `OATS_INSTANCE_HOME`.
|
|
220
231
|
- **[0.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
|
|
221
232
|
or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
|
|
222
233
|
The catalog pins oats.framework 1.28.0 and oats.aweb 1.47.0. Respawn an
|
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
|
@@ -33,6 +33,7 @@ import { memberRowByKey } from "./workspace.mjs";
|
|
|
33
33
|
import { sameRepo } from "./repo-moves.mjs";
|
|
34
34
|
import { triggerSourcesOf } from "./trigger-sources.mjs";
|
|
35
35
|
import { sessionProvidersOf } from "./session-providers.mjs";
|
|
36
|
+
import { sandboxDomainsOf } from "./sandbox-allowances.mjs";
|
|
36
37
|
|
|
37
38
|
export const CAPABILITY_SHOW_API = 1;
|
|
38
39
|
/** A text is cut to at most this many UTF-8 bytes; binary detection examines this many + 3. */
|
|
@@ -195,6 +196,14 @@ function triggerSourceKeys(manifest) {
|
|
|
195
196
|
return { triggerSources: manifest.triggerSources, ...(problems.length ? { triggerSourceProblems: problems } : {}) };
|
|
196
197
|
}
|
|
197
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
|
+
}
|
|
198
207
|
/** The session providers a manifest declares (lib/session-providers.mjs), as declared, and the problems a
|
|
199
208
|
* `--backend` naming them would get: added keys, each only when there is something to say. A malformed
|
|
200
209
|
* declaration is shown, never refused. */
|
|
@@ -230,7 +239,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
|
|
|
230
239
|
skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
|
|
231
240
|
}
|
|
232
241
|
}
|
|
233
|
-
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) };
|
|
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) };
|
|
234
243
|
}
|
|
235
244
|
|
|
236
245
|
/** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
|