@awebai/oats 0.69.24 → 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 +56 -3
- package/docs/capabilities.md +356 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/desktop-cli-api.md +75 -2
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +20 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +12 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +298 -41
- 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/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +64 -17
- 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
|
@@ -266,6 +266,7 @@
|
|
|
266
266
|
"additionalProperties": false,
|
|
267
267
|
"properties": {
|
|
268
268
|
"description": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
|
|
269
|
+
"wire": { "type": "string", "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}$", "description": "The version of the session-provider wire this provider speaks (docs/capabilities.md, The call). A kernel calls only a provider that declares its own version: one that declares another, or none (a provider from before the key, wire 1.2), is refused E_BACKEND_WIRE, naming both." },
|
|
269
270
|
"harnesses": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$" }, "description": "The harnesses this backend runs. A spawn or a start on another is refused E_BACKEND_HARNESS before anything is created or stopped." },
|
|
270
271
|
"commands": {
|
|
271
272
|
"type": "object",
|
|
@@ -353,6 +354,34 @@
|
|
|
353
354
|
"additionalProperties": {"$ref":"#/$defs/OptionalHook"},
|
|
354
355
|
"description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
|
|
355
356
|
},
|
|
357
|
+
"sandboxDomains": {
|
|
358
|
+
"description": "Sandbox allowances (docs/capabilities.md, Sandbox allowances): the hosts a session provider may add to its harness's sandbox for an instance whose messaging, knowledge or tasks slot this capability fills. Each entry names one of this capability's settings; the kernel reads the setting's value from the deployment's configuration (never from an instance home) and takes its host: a URL's host, a bare host, or, for a map from team id to one of those, the hosts of the instance's own teams. Only a capability that declares `layer` may carry the key, and only the capability that fills the slot contributes: on any other capability a session-provider launch is refused (E_BACKEND_SANDBOX_HOST), never the line dropped. A tmux launch does not read it. A kernel from before session providers ignores the key. One rule this schema does not express: a setting is named by ONE line (two lines for the same setting, of either form, refuse the launch).",
|
|
359
|
+
"type": "array",
|
|
360
|
+
"minItems": 1,
|
|
361
|
+
"maxItems": 16,
|
|
362
|
+
"items": {
|
|
363
|
+
"oneOf": [
|
|
364
|
+
{
|
|
365
|
+
"type": "object",
|
|
366
|
+
"required": ["setting"],
|
|
367
|
+
"properties": {
|
|
368
|
+
"setting": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is a URL, a bare host, or a map from team id to one of those." },
|
|
369
|
+
"optional": { "type": "boolean", "description": "true: the session works without this host. A value the deployment does not hold is then reported and is no reason for a session provider to refuse a launch." }
|
|
370
|
+
},
|
|
371
|
+
"additionalProperties": false
|
|
372
|
+
},
|
|
373
|
+
{
|
|
374
|
+
"type": "object",
|
|
375
|
+
"required": ["settingFile", "urls"],
|
|
376
|
+
"properties": {
|
|
377
|
+
"settingFile": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is the path of a JSON file of the deployment (never inside an instance home; a regular file reached through no symbolic link, at most 64 KiB, strict JSON)." },
|
|
378
|
+
"urls": { "type": "string", "pattern": "^(/([^/~]|~[01])+){1,16}$", "not": { "pattern": "/\\*(/.*)?/\\*(/|$)" }, "maxLength": 400, "description": "A JSON pointer into that file, of which at most one segment may be `*` (every key of an object, every element of an array): each string there that is a URL or a git remote gives its host, at most 16 hosts a file." }
|
|
379
|
+
},
|
|
380
|
+
"additionalProperties": false
|
|
381
|
+
}
|
|
382
|
+
]
|
|
383
|
+
}
|
|
384
|
+
},
|
|
356
385
|
"settings": {
|
|
357
386
|
"type": "object",
|
|
358
387
|
"description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",
|
|
@@ -436,5 +465,6 @@
|
|
|
436
465
|
"additionalProperties": false
|
|
437
466
|
}
|
|
438
467
|
},
|
|
468
|
+
"dependentRequired": { "sandboxDomains": ["layer"] },
|
|
439
469
|
"additionalProperties": false
|
|
440
470
|
}
|
|
@@ -39,6 +39,7 @@ state, in what order it writes, and what happens when two things cross.
|
|
|
39
39
|
| Record | Where | Who can write it | What it holds |
|
|
40
40
|
|---|---|---|---|
|
|
41
41
|
| **Receipt** | `<instances>/.oats-retirement/baselines/<hash of the home>.json`, `runtime` | the kernel; outside the home | the authority: `launched`, `backend`, `provider`, `endpoint`, `stoppedAt`, `launchSent` |
|
|
42
|
+
| **Composition** | the same receipt, `composition`; and the kernel's own copy of the home's modules, `<instances>/.oats-retirement/modules/<hash of the home>/<store>/` | the kernel (a spawn, and an upgrade's swap); outside the home | what the kernel runs of the home: its own copy of every module, and the home's capability rows (settings, hook commands that name that copy). No verb of this page writes it; every one runs the home's hooks and its provider's commands from it, never from the home ([What the kernel trusts in a provider home](../capabilities.md#what-the-kernel-trusts-in-a-provider-home)). A retire removes the copy with the home |
|
|
42
43
|
| **Record** | `<home>/instance.json` | the kernel; inside the home, so the agent can | a copy for readers: `launched`, `backend`, `session {provider, endpoint}`, `startId` |
|
|
43
44
|
| **Stop receipt** | `<home>/.oats-stop.json` | the kernel; inside the home | which stop the last one was, for the current `startId`: an operator's, or the host's (`resume: true, reason: "host-stop"`) |
|
|
44
45
|
| **Claim** | `<instances>/.oats-retirement/claims/<name>.lock` | the kernel; outside the home | which lifecycle verb acts on the home now, and its process |
|
|
@@ -115,7 +116,7 @@ before its home can be acted on):
|
|
|
115
116
|
|
|
116
117
|
| # | Step | Record written | State after |
|
|
117
118
|
|---|---|---|---|
|
|
118
|
-
| 1 | What can refuse: the
|
|
119
|
+
| 1 | What can refuse, in this order: a module of the home the kernel holds no copy of (it runs its own copy of each, and reads their manifests there); the provider's `check` with the planned launch (the harness, yolo, the sandbox allowances, the home's trees and the launch configuration's own arguments), **before any hook runs**; then the plan and the launch hooks. A spawn or a start its backend refuses runs no hook. (Three checks run right before step 4: the home's roots, the kernel's shim, the host run's admission. One that refuses there leaves the home as it then is: stopped by step 3, or as before the verb) | none | unchanged |
|
|
119
120
|
| 2 | If unsettled: for a home launched before, the provider's `stop {endpoint: E}` (not confirmed: `E_SESSION_STOP_FAILED`); then settle | see Settling | planned or stopped |
|
|
120
121
|
| 3 | If launched before: stop the session at `E`. A restart of *running* whose session is there records `stoppedAt` and the stop receipt first (the stop rule). A start or a restart of *stopped* asks the provider's `stop {endpoint: E}` again; not confirmed is `E_SESSION_STOP_FAILED`, nothing started. (*Running* whose session is gone: step 4) | receipt, stop receipt (a restart of a session that is there) | stopped, or running-and-gone |
|
|
121
122
|
| 4 | **Mark**: receipt `launchSent: t` (and `launched: true` from planned), then the record's `launched: true` from planned. Then, for *running* whose session is gone, the provider's `stop {endpoint: E}`, and nothing is recorded of it (so a stop that is not confirmed leaves a lost home lost, not stopped as by an operator): not confirmed is `E_SESSION_STOP_FAILED`, the mark taken back (6b), nothing started. After the mark, because an input holds no claim: see the crossings | receipt, then record | sent or resent |
|
|
@@ -226,6 +227,7 @@ orders of "A launch" and of the stop rule:
|
|
|
226
227
|
| during a launch the provider refused, between the record and the receipt of its unmarking | sent | settles (there is nothing to stop) |
|
|
227
228
|
| during a spawn, after its launch's outcome and before its last write of the record | resent (the mark is kept to that write) | settles: `stop {E}`, then the launch's; the home is stopped |
|
|
228
229
|
| during a spawn's rollback, between its record and its receipt | unsettled: the launch still marked, the record already planned (not compared) | settles |
|
|
230
|
+
| during a spawn, before its record (while the provider's `check` is asked, or its hooks run) | not a home of the table yet: a receipt, where there is one, says planned, and the record is the one its files were composed with. A read answers that it is being spawned (`E_SESSION_UNAVAILABLE`), never that its records disagree | as for any spawn that ended before its record: the kernel has no verb for it yet (not this change's) |
|
|
229
231
|
| during a spawn, between the planned record and its last receipt | planned (the receipt was written before the record) | acts on it |
|
|
230
232
|
| during a resume of a home stopped with the host, after its notice | stopped with the host; its session may run again | the sweep sends the notice again; a stop or a start asks `stop {E}` |
|
|
231
233
|
| during that resume, after `stoppedAt` was cleared | running, with the host's stop receipt left | acts on a running home; a later loss of that start is a loss like any other, counted (a stop receipt says the host's stop only beside a receipt that says stopped), and a later stop removes that receipt before it records its own |
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -7458,6 +7458,8 @@ before anything is created (a preview answers them too):
|
|
|
7458
7458
|
| `E_BACKEND_AMBIGUOUS` | `{backend, capabilities}`; also from a start or a restart |
|
|
7459
7459
|
| `E_BACKEND_HARNESS` | `{backend, capability, harness, harnesses}` |
|
|
7460
7460
|
| `E_BACKEND_LAUNCH_ARG` | `{backend, launchConfig, field: "executable"}` |
|
|
7461
|
+
| `E_BACKEND_WIRE` | `{backend, capability, wire: {provider, kernel}}`: the provider's declared wire version (null: none) and this kernel's. Also from a start, a restart, a `--resume`, a stop (an operator's and the host's) and an input, before anything is read or stopped |
|
|
7462
|
+
| `E_BACKEND_SANDBOX_HOST` | `{capability, setting, host, team?, path?}`: a capability's `sandboxDomains` line that may not add a host; `setting` and `host` are null where there is none to name. With `path` (and `capability: null`): a path the kernel itself would allow the session to write that is reached through a symbolic link, or is no directory. Also from a start or a restart, before anything is stopped |
|
|
7461
7463
|
| `E_BACKEND_NOT_READY`, any other `E_BACKEND_*` | the provider's readiness, or its own refusal of the launch: `{backend, capability}`; the spawn is rolled back |
|
|
7462
7464
|
|
|
7463
7465
|
A launch that fails otherwise is `E_SESSION_START_FAILED`.
|
|
@@ -7518,7 +7520,9 @@ spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
|
|
|
7518
7520
|
stopped (nothing was sent, the provider was not called), and for a lost
|
|
7519
7521
|
session at its resume cap or with a process of its last run still in the
|
|
7520
7522
|
home; `E_SESSION_PROMPT_OPEN` and `E_SESSION_INPUT_QUEUED` from the provider
|
|
7521
|
-
(nothing was sent); `
|
|
7523
|
+
(nothing was sent); `E_BACKEND_WIRE` for a home whose provider speaks
|
|
7524
|
+
another wire than this kernel (nothing was sent, the provider was not
|
|
7525
|
+
called); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
|
|
7522
7526
|
restart that lands while an input is being sent wins, whatever the provider
|
|
7523
7527
|
answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
|
|
7524
7528
|
is accepted only on `ok: true` with `submitted: true`.
|
|
@@ -7556,7 +7560,10 @@ launched before is left stopped. The row of a never-launched home reads
|
|
|
7556
7560
|
|
|
7557
7561
|
**Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
|
|
7558
7562
|
state: "stopped"}`; `E_SESSION_STOP_FAILED` when the provider does not confirm
|
|
7559
|
-
(the home stays recorded as stopped; a second stop asks the provider again)
|
|
7563
|
+
(the home stays recorded as stopped; a second stop asks the provider again);
|
|
7564
|
+
`E_BACKEND_WIRE` for a home whose provider speaks another wire than this
|
|
7565
|
+
kernel (nothing is recorded or stopped; a retire of it goes on by the rule
|
|
7566
|
+
below, with its warning). A retire goes on
|
|
7560
7567
|
only when no process works in the home after the provider's stop, confirmed
|
|
7561
7568
|
or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
|
|
7562
7569
|
provider could not confirm the stop, the retire's answer carries a warning.
|
|
@@ -7576,6 +7583,72 @@ warnings}` relayed as given, or `result: null` with `problems` when the
|
|
|
7576
7583
|
provider could not be asked. Required for a home on that backend; not
|
|
7577
7584
|
required for a soul.
|
|
7578
7585
|
|
|
7586
|
+
**Sandbox allowances.** What a session provider may widen its harness's
|
|
7587
|
+
sandbox by for an instance ([capabilities.md](capabilities.md#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox)),
|
|
7588
|
+
as the kernel computes it from the deployment's configuration. One key,
|
|
7589
|
+
`sandbox`, only where the launch is a provider's (never for tmux):
|
|
7590
|
+
|
|
7591
|
+
- a spawn preview (`oats spawn … --backend <name> --preview --json`):
|
|
7592
|
+
`sandbox: {domains: [{host, capability, setting, team?}], write: [{path, reason}],
|
|
7593
|
+
missing: [{capability, setting, team, defaultTeam, optional?}], unread?: [{capability,
|
|
7594
|
+
setting, reason}]}`. `domains`: each host with the capability and the
|
|
7595
|
+
setting that asked for it, and `team` (a team id) on a host taken from a
|
|
7596
|
+
map: a team the instance may join, not one it is known to have joined. `write`: each path with its reason (the
|
|
7597
|
+
kernel's own). `missing`: what a capability's line names and the
|
|
7598
|
+
deployment does not hold (`team`: a team id, or null for a setting with no
|
|
7599
|
+
value; `defaultTeam`: true for the soul's default team's row and for a row
|
|
7600
|
+
with no team; `optional: true` only on a row of an optional line). `unread`, only
|
|
7601
|
+
when there is one: a `settingFile` line's file that gave no host, or
|
|
7602
|
+
values in it that were skipped.
|
|
7603
|
+
- a start's and a restart's answer: the same object, with `skipped?:
|
|
7604
|
+
[{capability, reason}]` (a slot's provider of the deployment that is not
|
|
7605
|
+
one of the home's modules: it added no host), or `sandbox: {unavailable:
|
|
7606
|
+
"<why>"}` when the deployment's configuration could not be resolved for
|
|
7607
|
+
the home's soul (a repository this host's cache does not hold, a soul the
|
|
7608
|
+
workspace no longer offers, or two souls that share the home's agent
|
|
7609
|
+
directory). That resolution reaches no remote: it reads the
|
|
7610
|
+
workspace as this host last read it and `oats-local.yaml` as it is now, so
|
|
7611
|
+
a repository this host's cache does not hold is such a cause, by name. Each `skipped` row is also a `warnings` line.
|
|
7612
|
+
- `oats readiness --home <abs> --json` of a provider home: the same, as a
|
|
7613
|
+
start would compute it now, or `sandbox: {refused: {code:
|
|
7614
|
+
"E_BACKEND_SANDBOX_HOST", message, details}}` when a start would be
|
|
7615
|
+
refused for it.
|
|
7616
|
+
|
|
7617
|
+
- **`moduleCopy`**, on a status row, a remote roster row and a start's or a
|
|
7618
|
+
restart's answer, of a provider home only (never for tmux), a top-level
|
|
7619
|
+
key beside `modules`:
|
|
7620
|
+
`moduleCopy: {runs: "kernel-copy", homeCopy: "same" | "differs", differs: [<module id>]}`.
|
|
7621
|
+
`runs` says which copy of the home's modules the kernel runs: its own,
|
|
7622
|
+
kept outside the home
|
|
7623
|
+
([capabilities.md](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
7624
|
+
**`homeCopy` covers records only**: it compares the home's own record of
|
|
7625
|
+
each module (`instance.json`, its source and commit) with the kernel's
|
|
7626
|
+
record of the copy it runs, and reads no file of either copy. `differs`
|
|
7627
|
+
names the modules whose records disagree (capability ids only, at most
|
|
7628
|
+
200; a name in the home's record that is no capability id counts in
|
|
7629
|
+
`homeCopy` and is not named), `[]` when `homeCopy` is `same`.
|
|
7630
|
+
It says `differs` after an upgrade that was interrupted between moving
|
|
7631
|
+
the home's copies and the kernel's, and when the home's record was
|
|
7632
|
+
rewritten. Whether the FILES of a home copy are the kernel's is reported
|
|
7633
|
+
by `oats readiness --home`, in `kernelCopies` (next). The key is new and
|
|
7634
|
+
optional; `modules` is unchanged, an array of drift rows on a provider
|
|
7635
|
+
home as on any other, with no key added to a row.
|
|
7636
|
+
- `oats readiness --home <abs> --json` of a provider home also carries
|
|
7637
|
+
`kernelCopies: {store, differing: [{capability, differs}]}`, an optional
|
|
7638
|
+
key that no other answer has and that changes the meaning of none: `store`
|
|
7639
|
+
is the name of the store that holds the kernel's own copies of the home's
|
|
7640
|
+
modules, and `differing` lists each module whose copy in the home is not
|
|
7641
|
+
the one the kernel runs (`differs: true`), or could not be compared
|
|
7642
|
+
(`differs: null`); `[]` when every home copy is the kernel's. It is
|
|
7643
|
+
information: the kernel runs its own copy either way
|
|
7644
|
+
([capabilities.md](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
7645
|
+
It is computed for this answer only (the files are compared), never for
|
|
7646
|
+
a status row.
|
|
7647
|
+
|
|
7648
|
+
`oats capabilities show <name> --json` carries `sandboxDomains` (the
|
|
7649
|
+
manifest's key, exactly as declared) and, only when there is one,
|
|
7650
|
+
`sandboxDomainProblems: [<message>]`.
|
|
7651
|
+
|
|
7579
7652
|
**The sweep.** A row of `oats session resume` for a provider home carries
|
|
7580
7653
|
`backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
|
|
7581
7654
|
`already-running` (a session is there), `refused` with `keeps-getting-lost`
|
|
@@ -691,7 +691,8 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
|
|
|
691
691
|
`OATS_OPERATION`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`, `OATS_KIND`,
|
|
692
692
|
`OATS_TASK`, `OATS_HARNESS`, `OATS_HARNESS_EXECUTABLE`,
|
|
693
693
|
`OATS_PREVIOUS_HARNESS`, `OATS_RUNTIME`,
|
|
694
|
-
`OATS_PREVIOUS_RUNTIME`, `
|
|
694
|
+
`OATS_PREVIOUS_RUNTIME`, `OATS_BACKEND`, `OATS_PREVIOUS_BACKEND`,
|
|
695
|
+
`OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
|
|
695
696
|
`OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
|
|
696
697
|
the login shell, honoured only for a process whose `HOME` is not your home
|
|
697
698
|
directory; a launch configuration cannot set it),
|
|
@@ -950,7 +951,9 @@ anything is created, and shown by a spawn preview:
|
|
|
950
951
|
| `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
952
|
| `E_BACKEND_HARNESS` | the provider does not run the launch's harness |
|
|
952
953
|
| `E_BACKEND_LAUNCH_ARG` | the launch configuration declares an `executable`: a provider runs the harness itself |
|
|
954
|
+
| `E_BACKEND_WIRE` | the provider speaks another version of the session-provider wire than this kernel (its manifest's `wire`), or declares none: use the release of its capability that goes with this OATS |
|
|
953
955
|
| `E_BACKEND_NOT_READY` | the provider's own readiness check, asked right before the launch, says it cannot take it |
|
|
956
|
+
| `E_BACKEND_SANDBOX_HOST` | a capability asks to add a host to the session's sandbox that it may not ask for: it declares `sandboxDomains` and fills none of the instance's messaging, knowledge or tasks slots, its line is malformed, its setting's value gives no plain host, its file is not the deployment's own, its setting was given to this one spawn (`--provider <capability> <setting>=…`: a launch's own argument is never a host source), or the directory the sandbox may write (the deployment's events directory) is reached through a symbolic link or is no directory ([Sandbox allowances](capabilities.md#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox)) |
|
|
954
957
|
|
|
955
958
|
A provider can also refuse the launch with its own `E_BACKEND_*` code (a
|
|
956
959
|
launch environment entry or an argument it cannot carry), which OATS relays;
|
|
@@ -977,6 +980,26 @@ stoppedAt}`. The two must agree as for tmux: `E_RUNTIME_AUTHORITY_MISMATCH`
|
|
|
977
980
|
otherwise, whose `details.fields` are `backend`, `session.provider` and
|
|
978
981
|
`session.endpoint`.
|
|
979
982
|
|
|
983
|
+
The receipt of a provider home also records its **composition**:
|
|
984
|
+
`composition: { version: 1, store: "<name>", modules: { "<capability>": {
|
|
985
|
+
from, commit } }, capabilityRuntime: [ <row> ], previous?: { store, modules,
|
|
986
|
+
capabilityRuntime } }`: which store holds the
|
|
987
|
+
kernel's own copies of the home's modules
|
|
988
|
+
(`<instances>/.oats-retirement/modules/<hash of the home>/<store>/`), which
|
|
989
|
+
modules the home has and where each came from, and the capability rows the
|
|
990
|
+
spawn resolved; `previous`, after an upgrade, is the pair that upgrade
|
|
991
|
+
replaced, which an undo names again. For such a home the kernel runs its own copy of a module,
|
|
992
|
+
never the home's, and reads a capability's settings and hook commands from
|
|
993
|
+
this record alone
|
|
994
|
+
([What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
995
|
+
A tmux home's receipt has no such key, and the kernel keeps no copy of its
|
|
996
|
+
modules. A kernel from before it ignores the key: one from before session
|
|
997
|
+
providers still refuses every session verb on a provider home, and one that
|
|
998
|
+
knows providers and not this record runs the home's own copies, as it
|
|
999
|
+
always did. A provider home whose receipt has no `composition` (a kernel
|
|
1000
|
+
from before it spawned the home) runs nothing on this kernel: retire it and
|
|
1001
|
+
spawn it again.
|
|
1002
|
+
|
|
980
1003
|
**The lifecycle of a provider home is one state machine**, set out in
|
|
981
1004
|
[its design record](design/2026-11-20-provider-home-lifecycle.md): the
|
|
982
1005
|
states its records spell, what each verb does in each, in what order it
|
package/docs/implementation.md
CHANGED
|
@@ -132,7 +132,8 @@ and the rules its tests pin.
|
|
|
132
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` |
|
|
133
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 |
|
|
134
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
|
|
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 per verb of the kernel's own copy of the home's module, 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
|
+
| `home-integrity.mjs` | what the kernel runs of a provider home ([capabilities](capabilities.md#what-the-kernel-trusts-in-a-provider-home)): its own copies of the home's modules, kept beside the receipt (`session-receipt.mjs`, the receipt's own primitives), the receipt's `composition`, and the capability rows read from it. A leaf: the hot reads load it. |
|
|
136
137
|
| `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
138
|
| `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. |
|
|
138
139
|
| `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 |
|
|
@@ -561,7 +562,12 @@ differs), `package-manifests` (a package's manifests), `list` (a skill
|
|
|
561
562
|
listing) and `tree-oids` (the tree ids of a set of directories). An entry is only ever a pure function of those bytes and this kernel's
|
|
562
563
|
code, never local state and never a transient error; it is written
|
|
563
564
|
atomically, a corrupt one is a miss, and `pruneStores` bounds the store
|
|
564
|
-
(`PARSED_LIMITS`, least recently used first).
|
|
565
|
+
(`PARSED_LIMITS`, least recently used first). A read session made with
|
|
566
|
+
`offline: true` never reaches a remote: a head is the one this host last
|
|
567
|
+
observed (its record, of any age), a commit and a file are read only when the
|
|
568
|
+
cache holds them, and anything else is `E_REMOTE_UNREADABLE` with reason
|
|
569
|
+
`not-cached`. The sandbox allowances of a session provider's start are
|
|
570
|
+
resolved in one (`lib/instance-resolution.mjs` `homeSandboxSource`). `--max-age` adds the observation
|
|
565
571
|
store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
|
|
566
572
|
one record per (repo key, ref args, url digest), so two spellings of one repo
|
|
567
573
|
keep a record each; the url itself is never written. Beside it,
|
|
@@ -971,7 +977,18 @@ inherits it (awebai/oats#816):
|
|
|
971
977
|
names on the real one and gives the saved one back with
|
|
972
978
|
`setProcessEnvironment` when it ends; everything else goes through
|
|
973
979
|
`fx.inEnv`. `test/fixture-real-environment.test.mjs` refuses an assignment
|
|
974
|
-
to `process.env` in any test script.
|
|
980
|
+
to `process.env` in any test script. **A test writes an executable only
|
|
981
|
+
inside its fixture** (#2042): a harness stand-in, or a home's recorded
|
|
982
|
+
`launch.executable`, is written with
|
|
983
|
+
`writeFixtureExecutable(fx.base, path, content)`, which refuses a path
|
|
984
|
+
outside the fixture's base, one reached through a link, and a symbolic or
|
|
985
|
+
hard link at the path, with nothing written. `fx.inEnv` keeps the PATH of
|
|
986
|
+
the process that runs the tests, so an in-process spawn records the
|
|
987
|
+
harness it finds there, which on a machine with the harness installed is
|
|
988
|
+
the person's own binary: a spawn whose recorded executable a test will
|
|
989
|
+
rewrite runs with the fixture's PATH (`process.env.PATH = fx.env.PATH`,
|
|
990
|
+
put back afterwards; its inert `pi`, `claude` and `codex` come first), and
|
|
991
|
+
asserts `insideFixture(fx.base, launch.executable)`. The fixture's
|
|
975
992
|
environment sets `HOME` and the XDG base directories under the base, and
|
|
976
993
|
`GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null` and
|
|
977
994
|
`GIT_TERMINAL_PROMPT=0`, so no host git
|
|
@@ -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,
|
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.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,13 @@ 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`.
|
|
220
227
|
- **[0.69.24](release-notes/v0.69.24.md#upgrade):** OATS needs Node.js 22.5
|
|
221
228
|
or later: Node 18 and 20 now refuse every command (`E_NODE_UNSUPPORTED`).
|
|
222
229
|
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.
|