@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.
@@ -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 plan, the launch hooks, the provider's `check` with the planned launch. (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
+ | 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 |
@@ -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); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
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). A retire goes on
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`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
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
@@ -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 home's own module copy per verb, with the hook environment) and the rules of each verb's answer, the receipt's `runtime` for a provider home. A leaf: `session-inspect.mjs` and `instance-listing.mjs` call a provider on the hot reads; `core.mjs` holds the launch, stop, start and retire of a provider home. |
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). `--max-age` adds the observation
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. The fixture's
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,
@@ -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.69.24** ([release notes](release-notes/v0.69.24.md)).
10
- The 0.69.24 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
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.69.24,** in the [release notes](release-notes/): it says what to do before
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.69.24, in either order
24
- npm install -g @awebai/oats@0.69.24 # 1. the CLI
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
@@ -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];
@@ -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.