@awebai/oats 0.69.23 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/desktop-cli-api.md
CHANGED
|
@@ -66,9 +66,12 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
66
66
|
with against that kernel's own version, so never finds it above. A
|
|
67
67
|
`desktopApi` other than 1 is refused (`newerApi` on the candidate when it is
|
|
68
68
|
a higher one).
|
|
69
|
-
- `harnesses` is what `--harness` accepts; `sessionBackends`
|
|
70
|
-
|
|
71
|
-
is refused with `E_HERDR_REMOVED`).
|
|
69
|
+
- `harnesses` is what `--harness` accepts; `sessionBackends` the kernel's own
|
|
70
|
+
session backends: `["tmux"]` since 0.31.0, when Herdr was removed (`--backend
|
|
71
|
+
herdr` is refused with `E_HERDR_REMOVED`). With the feature
|
|
72
|
+
`session-providers`, `--backend` also takes a session provider's name: a
|
|
73
|
+
backend a capability supplies, never listed here
|
|
74
|
+
([Session providers](#session-providers-feature-session-providers)). A host without the `harness` feature
|
|
72
75
|
lists `runtimes` instead.
|
|
73
76
|
- `remote` is the routed surface: the commands `--server <id>` sends to a
|
|
74
77
|
registered server, plus `roster`. The Desktop checks the execution host's
|
|
@@ -189,6 +192,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
189
192
|
| `schedule-host-register-only` | `oats schedule host install --register-only`: the scope is recorded in the host schedule registry and no timer is installed ([`oats schedule`](#oats-schedule)). Routed with `--server`, the option is sent only to a host that lists this and `schedule`; otherwise it is refused here with `E_REMOTE_INCOMPATIBLE` before anything is sent, since a host without it ignores the option and installs a timer | |
|
|
190
193
|
| `instance-board` | the agent's board: `oats instance board set\|unset\|ask\|ask --clear`, run by the agent in its own home; `board` on `oats status --json` instance rows and `oats server roster --json` rows; `oats inspect --home <h> --board` for each fact's history and each question's context; the `oats.board` needs-input claim, reason `attention` ([The agent's board](#the-agents-board-oats-instance-board)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses `oats instance board` (`E_BAD_ARGS`) and its rows have no `board` | `boardApi: 1` |
|
|
191
194
|
| `spawn-task-stdin` | `oats spawn <soul> --task-file -` reads the task from standard input. A spawn routed with `--server` sends its `--task` or `--task-file` text that way, to the preview and to the apply, to a host that lists this, and not as an argument; a host that does not list it gets the text as an argument, and the answer's `warnings` gains one line that says it was readable in both machines' process lists ([servers.md](servers.md#a-routed-spawns-task)) |
|
|
195
|
+
| `session-providers` | session backends a capability supplies ([Session providers](#session-providers-feature-session-providers)): `--backend <provider>` on `oats spawn` (a schedule's `backend`, a trigger's `spawn.backend`); a provider home's `backend`, `session` and `open` on its status row (the endpoint only on its local inspect, spawn and start answers; nothing of it relayed); `backend: "tmux"` on a tmux home's status row; `sessionProviders` in `oats inspect` and `oats capabilities show`; a provider's readiness in `oats readiness`; `backends` on a capability's `requires` row; the codes `E_BACKEND_UNKNOWN`, `E_BACKEND_AMBIGUOUS`, `E_BACKEND_HARNESS`, `E_BACKEND_LAUNCH_ARG`, `E_BACKEND_NOT_READY`, `E_SESSION_NO_TERMINAL`, `E_SESSION_PROMPT_OPEN`, `E_SESSION_INPUT_QUEUED`; `backend` on the sweep's rows of provider homes; `oats session resume --plan --without-provider-inspect`, which is `oats host run`'s own switch for its shutdown listing, not a client's. A routed `--backend <provider>` is sent only to a host that lists it. |
|
|
192
196
|
|
|
193
197
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
194
198
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -347,7 +351,7 @@ for `--no-recursive`) is never ignored.
|
|
|
347
351
|
| `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
|
|
348
352
|
| `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
|
|
349
353
|
| `oats session restart` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server`, `--stop-grace` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json` | `--native-record`, `--resume` | none |
|
|
350
|
-
| `oats session resume` | none | `--deployment` | `--plan`, `--json` | `--native-record`, `--server` | none |
|
|
354
|
+
| `oats session resume` | none | `--deployment` | `--plan`, `--without-provider-inspect`, `--json` | `--native-record`, `--server` | none |
|
|
351
355
|
| `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
|
|
352
356
|
| `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
|
|
353
357
|
| `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
|
|
@@ -437,6 +441,7 @@ kernel command.
|
|
|
437
441
|
|
|
438
442
|
| Code | When |
|
|
439
443
|
|---|---|
|
|
444
|
+
| `E_NODE_UNSUPPORTED` | Node.js is older than 22: before every command, exit 1 with `details: {found: "<process.versions.node>", minimum: "22"}` and message `oats needs Node.js 22 or later; this is Node.js <found>`. With `--json` anywhere in argv, stdout is one failure envelope; otherwise the message is on stderr. This includes the `version --json` probe, whose success shape is not the envelope: on unsupported Node it answers this failure envelope with exit 1. Node 18 and 20 get this refusal; a Node too old to parse the entry can fail with a SyntaxError first |
|
|
440
445
|
| `E_UNKNOWN_COMMAND` | No kernel command or capability namespace matches; an unknown capability subcommand; a [removed verb](#removed-verbs-and-flags) (`details: {removed, replacement}`) |
|
|
441
446
|
| `E_CAPABILITY_INACTIVE` | In a home: the namespace's module is not one of the home's recorded capabilities |
|
|
442
447
|
| `E_CAPABILITY_BLOCKED` | In a home: the manifest claiming the namespace is not a workspace module copy of that home. There is no package trust gate |
|
|
@@ -1851,6 +1856,14 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
|
|
|
1851
1856
|
empty list read as "no warning". Older kernels answer no such `warnings` key
|
|
1852
1857
|
(inspect, readiness, show, doctor) and refuse the capability instead.
|
|
1853
1858
|
|
|
1859
|
+
`oats doctor --json` reports the Git version and whether it supports partial
|
|
1860
|
+
caches in an existing `information[]` line starting `git-version:` (text:
|
|
1861
|
+
`INFO: git-version: …`). Git before 2.45 uses the whole-tree fallback; this
|
|
1862
|
+
is information, never a warning or a refusal. A failed version probe reports
|
|
1863
|
+
unknown support. A newer Git supports partial caches, but a remote can
|
|
1864
|
+
require whole-tree fetches and an existing whole-tree cache keeps its mode
|
|
1865
|
+
([Git version failures](workspaces.md#membership-and-trust)).
|
|
1866
|
+
|
|
1854
1867
|
`oats doctor --json` also lists what retires left behind in `information[]`:
|
|
1855
1868
|
one `retained-recovery:` and one `retained-worktree:` line per item, after a
|
|
1856
1869
|
line that gives each kind's total, and at most 50 items per kind
|
|
@@ -3222,7 +3235,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
3222
3235
|
|
|
3223
3236
|
- Always present: `instance, agent, home, work, branch, base ({ref, oid}
|
|
3224
3237
|
the new branch started at; `null` without one), launched, warnings
|
|
3225
|
-
(array), tmux ({session, window, socket?} | null), backend ("tmux"
|
|
3238
|
+
(array), tmux ({session, window, socket?} | null), backend ("tmux", or a
|
|
3239
|
+
session provider's name with `session: {provider, endpoint}` after it and
|
|
3240
|
+
`tmux: null`, `attach: null`: [Session providers](#session-providers-feature-session-providers)), repo, harness,
|
|
3226
3241
|
model, parent,
|
|
3227
3242
|
sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
|
|
3228
3243
|
launch` (the redacted recipe).
|
|
@@ -3885,6 +3900,62 @@ its absence.
|
|
|
3885
3900
|
output, not the exit status, and nothing is printed, whether or not it can
|
|
3886
3901
|
be read or written. A status routed with `--server` records nothing on this
|
|
3887
3902
|
machine ([execution-targets.md](execution-targets.md#which-losses-come-back)).
|
|
3903
|
+
- <a id="row-backend-clients"></a>**How the clients read `backend`** (the
|
|
3904
|
+
Desktop and the TUI, `packages/client`). A row whose `backend` is text that
|
|
3905
|
+
is not empty and not `tmux` runs on a session provider, in no terminal (an
|
|
3906
|
+
empty `backend` names none: the kernel never sends one, and the row reads
|
|
3907
|
+
as one with no `backend`):
|
|
3908
|
+
- Its `running`, `runtimeState` and `runtimeError` are shown as the kernel
|
|
3909
|
+
reports them. No client asks tmux about it: with an older kernel, whose
|
|
3910
|
+
rows a client's own terminal check refines, such a row is never passed
|
|
3911
|
+
to that check.
|
|
3912
|
+
- Its acts are the ones of its state: Restart, Stop and Retire while it
|
|
3913
|
+
runs; Start, Stop and Retire stopped; Stop and Retire when the kernel
|
|
3914
|
+
answers `running: null`.
|
|
3915
|
+
- Open is never offered. The clients say where the agent runs ("Runs in a
|
|
3916
|
+
bb thread; open it in bb.") and, when the row carries `open`
|
|
3917
|
+
(`{label, url}`), show it as a link: the Desktop opens it in the system
|
|
3918
|
+
browser from the row's menu, the TUI prints the url. Only an `http` or
|
|
3919
|
+
`https` url with no credentials in it is shown, and only on a row of
|
|
3920
|
+
this machine: another machine's url is that machine's own loopback. No
|
|
3921
|
+
client attaches, splits or restores a terminal for the row.
|
|
3922
|
+
- Its `waitingOnYou` claim is shown unless the row is stopped
|
|
3923
|
+
(`running: false`): while it runs and when the kernel answers
|
|
3924
|
+
`running: null`, since an agent that waits on a person is idle in its
|
|
3925
|
+
provider. A tmux row's claim still needs `running: true` and no
|
|
3926
|
+
`runtimeState` but `running`. A row whose last read failed, or whose
|
|
3927
|
+
server was not reached, shows none, as for any row.
|
|
3928
|
+
- It counts as running (the Desktop's Home, the counts) on `running: true`
|
|
3929
|
+
alone: its `runtimeState` is the provider's word (`unknown` while it
|
|
3930
|
+
runs), never `running`.
|
|
3931
|
+
- A start's or a restart's answer for it carries the provider's name as
|
|
3932
|
+
`backend`, `session: {provider, endpoint?}` and no terminal `target`
|
|
3933
|
+
(the endpoint on a start on this machine, never on a routed one); the
|
|
3934
|
+
clients open no terminal after it.
|
|
3935
|
+
- Its stop and its retire run from the deployment's directory, never from
|
|
3936
|
+
its home. The retire of such a home is refused while any process works in
|
|
3937
|
+
it, the client's own included: start the Desktop or the TUI outside an
|
|
3938
|
+
agent's home.
|
|
3939
|
+
- The Desktop shows the backend and `session.threadId`, when it is text,
|
|
3940
|
+
as `bb · thread thr_…`. Only a status row of this machine carries the
|
|
3941
|
+
thread id: a row relayed from another host (`oats server roster`,
|
|
3942
|
+
`--server`) never does, so a client shows the backend alone there and
|
|
3943
|
+
depends on the id for nothing. The id addresses nothing.
|
|
3944
|
+
|
|
3945
|
+
A row with no `backend` (an older kernel's, or an older routed host's)
|
|
3946
|
+
reads as tmux, as one with `tmux` does: both are read as before. A row recorded
|
|
3947
|
+
on Herdr keeps its own reason (`E_HERDR_REMOVED`) before any of this. On a
|
|
3948
|
+
row of this machine `herdr` is not read as a backend: such a row is known
|
|
3949
|
+
by its `sessionTarget` or its `unsupported` state, and one that only names
|
|
3950
|
+
`herdr` reads as before. A
|
|
3951
|
+
`backend` that is no provider's name (1 to 40 lowercase letters, digits
|
|
3952
|
+
and dashes, the first a letter or a digit; not `tmux` or
|
|
3953
|
+
`session-provider`) still makes the row a provider's, never asked of tmux:
|
|
3954
|
+
the clients then say "Runs outside tmux; it has no terminal to open." and
|
|
3955
|
+
show the value only as display text. `--backend` on a
|
|
3956
|
+
client's spawn is held to the names the kernel lists: `sessionBackends` of
|
|
3957
|
+
`oats version --json` and the session providers `oats inspect --json`
|
|
3958
|
+
reports.
|
|
3888
3959
|
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3889
3960
|
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3890
3961
|
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
@@ -5279,7 +5350,12 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
|
|
|
5279
5350
|
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
5280
5351
|
a home the kernel cannot look into, where whether it has a `work/` cannot
|
|
5281
5352
|
be told; OATS 0.52.0).
|
|
5282
|
-
- `midTask`: `true`, `false` or `"unknown"`.
|
|
5353
|
+
- `midTask`: `true`, `false` or `"unknown"`. A home on a
|
|
5354
|
+
[session provider](execution-targets.md#session-providers) whose session
|
|
5355
|
+
is there reads what its provider reports of it (the `running` of
|
|
5356
|
+
`oats session inspect`, see [Session providers](#session-providers-feature-session-providers)): `true` when it runs a turn,
|
|
5357
|
+
and `"unknown"` when the provider reports no activity (`running: null`),
|
|
5358
|
+
unless its work has changes, which is `true`.
|
|
5283
5359
|
- `retiring` and `stopPending`, booleans on every target, say who holds the
|
|
5284
5360
|
target's home when the plan is read (OATS 0.52.0, feature
|
|
5285
5361
|
`lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
|
|
@@ -7348,6 +7424,250 @@ relayed).
|
|
|
7348
7424
|
|
|
7349
7425
|
## Sessions and launch configurations
|
|
7350
7426
|
|
|
7427
|
+
### Session providers (feature `session-providers`)
|
|
7428
|
+
|
|
7429
|
+
A capability can supply a session backend beside the kernel's tmux
|
|
7430
|
+
([execution-targets.md](execution-targets.md#session-providers); the
|
|
7431
|
+
capability's side is
|
|
7432
|
+
[capabilities.md](capabilities.md#session-providers-sessionproviders)). A
|
|
7433
|
+
home on one is a **provider home**. Everything below is added by the
|
|
7434
|
+
feature; a tmux home's answers are as they were, except its status row's
|
|
7435
|
+
`backend`.
|
|
7436
|
+
|
|
7437
|
+
**Reading the offer.** `oats inspect --soul <soul> --json` and `oats inspect
|
|
7438
|
+
--home <abs> --json` carry `sessionProviders: [{name, capability}]`, the
|
|
7439
|
+
backends `--backend` takes there beside `tmux`, sorted by name (`[]` when the
|
|
7440
|
+
soul has none; a malformed declaration is none). `oats capabilities show
|
|
7441
|
+
<name> --json` carries `sessionProviders` (the manifest's key, exactly as
|
|
7442
|
+
declared) and, only when there is one, `sessionProviderProblems: [{provider,
|
|
7443
|
+
pointer, message}]`.
|
|
7444
|
+
|
|
7445
|
+
**Spawn.** `oats spawn <soul> --backend <name>` (after `--preview`, as for
|
|
7446
|
+
tmux). A preview carries `backend: "<name>"`, `backendStatus: {name,
|
|
7447
|
+
installed: true, started: false}` and `executable: null`. A launched spawn's
|
|
7448
|
+
answer carries `backend: "<name>"`, `session: {provider, endpoint}`, `tmux:
|
|
7449
|
+
null`, `attach: null`, and its `launch.executable` is `null`. While the
|
|
7450
|
+
provider launches, the spawn holds the new home's lifecycle claim: a stop's
|
|
7451
|
+
apply, a start and a retire of it are refused as busy (`E_LIFECYCLE_BUSY`,
|
|
7452
|
+
`E_SESSION_START_BUSY`) until the launch is recorded or undone. Refusals,
|
|
7453
|
+
before anything is created (a preview answers them too):
|
|
7454
|
+
|
|
7455
|
+
| Code | `details` |
|
|
7456
|
+
|---|---|
|
|
7457
|
+
| `E_BACKEND_UNKNOWN` | `{backend, available}`: the names `--backend` takes for this instance, `tmux` first |
|
|
7458
|
+
| `E_BACKEND_AMBIGUOUS` | `{backend, capabilities}`; also from a start or a restart |
|
|
7459
|
+
| `E_BACKEND_HARNESS` | `{backend, capability, harness, harnesses}` |
|
|
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 |
|
|
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 |
|
|
7464
|
+
|
|
7465
|
+
A launch that fails otherwise is `E_SESSION_START_FAILED`.
|
|
7466
|
+
|
|
7467
|
+
**A status row** (`oats status --json`) of a provider home:
|
|
7468
|
+
|
|
7469
|
+
```json
|
|
7470
|
+
{ "instance": "dev-a", "home": "/abs/home", "launched": true,
|
|
7471
|
+
"backend": "bb",
|
|
7472
|
+
"session": { "provider": "oats.bb", "threadId": "thr_1" },
|
|
7473
|
+
"tmux": null,
|
|
7474
|
+
"open": { "label": "Open in bb", "url": "https://…" },
|
|
7475
|
+
"running": true, "runtimeState": "unknown", "waitingOnYou": null }
|
|
7476
|
+
```
|
|
7477
|
+
|
|
7478
|
+
- `backend` is the provider's name. A tmux home's row carries `backend:
|
|
7479
|
+
"tmux"`. **A row with no `backend` key reads as tmux**: it comes from a
|
|
7480
|
+
kernel or a routed host without the feature (or is a home whose record
|
|
7481
|
+
cannot be read), never from a provider home.
|
|
7482
|
+
- `session.provider` is the capability. **`session.threadId` is on a local
|
|
7483
|
+
row only**: the thread id of the provider's endpoint, when the endpoint
|
|
7484
|
+
names one, on the host where the home lives, so a tool there can match a
|
|
7485
|
+
session to its instance. It is replaced at a start and a restart, and a
|
|
7486
|
+
home OATS stopped keeps its last. **A relayed row never has it** (`oats
|
|
7487
|
+
server roster`, `oats status --server`): a relayed row's `session` is
|
|
7488
|
+
`{provider}`. A client must not depend on `threadId` beyond the local
|
|
7489
|
+
host.
|
|
7490
|
+
- **The endpoint is never on a row.** `session.endpoint` (the provider's own
|
|
7491
|
+
locator) is on `oats session inspect --home`, a launched spawn's answer
|
|
7492
|
+
and a start's answer, on the host where the home lives; the same answers
|
|
7493
|
+
through `--server` carry `session: {provider}`. Neither the endpoint nor
|
|
7494
|
+
`open` holds a token or a secret.
|
|
7495
|
+
- `tmux` is `null`; `open` is `{label, url}` or `null`: a link a viewer may
|
|
7496
|
+
open instead of a terminal. It is relayed.
|
|
7497
|
+
- `running` is `true`, `false`, or `null` where the provider cannot tell a
|
|
7498
|
+
live idle session from a settled one. `runtimeState` is always set:
|
|
7499
|
+
`unknown` (there), `shell`, `stopped` (OATS stopped it, it was never
|
|
7500
|
+
launched, or it is gone) or `unreachable`, with `runtimeError`, when the
|
|
7501
|
+
provider failed, was slow or answered outside its contract. An unreachable
|
|
7502
|
+
row is never read as stopped.
|
|
7503
|
+
- `sessionEnd` is `stopped` for a home an operator stopped, and `lost` for
|
|
7504
|
+
one stopped with the host or whose session is gone while OATS did not
|
|
7505
|
+
stop it: the sweep resumes a lost one. Absent otherwise.
|
|
7506
|
+
- `waitingOnYou` is the producers' claim, read while the session is there
|
|
7507
|
+
and not in error (`runtimeState: "unknown"`, `running` true or null).
|
|
7508
|
+
|
|
7509
|
+
**Inspect.** `oats session inspect --home <abs> --json` answers `{home,
|
|
7510
|
+
backend, present, state, running, waitingOnYou, wakeHold, session: {provider,
|
|
7511
|
+
endpoint}, open}`: no `paneId`, no `size`. `state` is `unknown`, `shell`,
|
|
7512
|
+
`stopped` or, before the first launch, `not-launched`. For a home OATS
|
|
7513
|
+
stopped it answers `present: false, state: "stopped", running: false, open:
|
|
7514
|
+
null` without asking the provider. A provider that cannot be asked is
|
|
7515
|
+
`E_SESSION_UNAVAILABLE`.
|
|
7516
|
+
|
|
7517
|
+
**Input.** `oats session input --home <abs>` answers `{home, backend,
|
|
7518
|
+
submitted: true, verified}` (no `session`: the endpoint is inspect's, a
|
|
7519
|
+
spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
|
|
7520
|
+
stopped (nothing was sent, the provider was not called), and for a lost
|
|
7521
|
+
session at its resume cap or with a process of its last run still in the
|
|
7522
|
+
home; `E_SESSION_PROMPT_OPEN` and `E_SESSION_INPUT_QUEUED` from the provider
|
|
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
|
|
7526
|
+
restart that lands while an input is being sent wins, whatever the provider
|
|
7527
|
+
answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
|
|
7528
|
+
is accepted only on `ok: true` with `submitted: true`.
|
|
7529
|
+
|
|
7530
|
+
**Start and restart.** The result has every key a tmux start answers, with
|
|
7531
|
+
`backend: "<name>"`, `session: {provider, endpoint}` and `target: null`:
|
|
7532
|
+
`{instance, agent, home, harness, backend, model, launchConfig, yolo, target,
|
|
7533
|
+
session, startedAt, restartCount, reused: "new", warnings}`, and `stop:
|
|
7534
|
+
{stopped: true, waitedMs}` on a restart. A start of a home whose session is
|
|
7535
|
+
there and that OATS did not stop is `E_SESSION_RUNNING` (it reads `running:
|
|
7536
|
+
true`) or `E_SESSION_UNKNOWN`. `--resume` answers the same keys with `reused:
|
|
7537
|
+
"session"`, `startedAt: null` and `resume: {resumed: true, harness}`: the
|
|
7538
|
+
resume notice went through the provider's input and nothing was launched.
|
|
7539
|
+
Its refusals: `E_RESUME_NOT_LOST` (not a lost session), `E_SESSION_NOT_RUNNING`
|
|
7540
|
+
(the resume cap; `details.resumeCap: {limit, windowMs, nextAttemptAt}`),
|
|
7541
|
+
`E_SESSION_UNKNOWN` (a process of the last run still works in the home, or
|
|
7542
|
+
the session cannot be read), `E_SESSION_PROMPT_OPEN` (a claim or a prompt is
|
|
7543
|
+
open) and `E_SESSION_INPUT_QUEUED`.
|
|
7544
|
+
|
|
7545
|
+
**A launch with no recorded outcome** (the lifecycle's
|
|
7546
|
+
[design record](design/2026-11-20-provider-home-lifecycle.md)). From the
|
|
7547
|
+
moment a spawn or a start sends the provider's launch until its endpoint is
|
|
7548
|
+
recorded, and for good when that command died first, the home's receipt
|
|
7549
|
+
carries `launchSent` and the home is unknown, whether it was launched before
|
|
7550
|
+
or not: `oats session inspect` answers `E_SESSION_UNAVAILABLE`, its status
|
|
7551
|
+
row reads `running: null`, `runtimeState: "unreachable"` with the reason, a
|
|
7552
|
+
`--resume` is `E_SESSION_UNKNOWN`, and `oats session input` is refused with
|
|
7553
|
+
nothing sent (`E_SESSION_NOT_RUNNING` for a home never launched or recorded
|
|
7554
|
+
as stopped, else `E_SESSION_INPUT_FAILED`). A stop, a start, a restart and a
|
|
7555
|
+
retire settle it first, by asking the provider to stop whatever session that
|
|
7556
|
+
launch started: a stop then answers `stopped: true` (never `alreadyIdle`),
|
|
7557
|
+
or `E_SESSION_STOP_FAILED` when the provider does not confirm; a home
|
|
7558
|
+
launched before is left stopped. The row of a never-launched home reads
|
|
7559
|
+
`launched: true` meanwhile.
|
|
7560
|
+
|
|
7561
|
+
**Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
|
|
7562
|
+
state: "stopped"}`; `E_SESSION_STOP_FAILED` when the provider does not confirm
|
|
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
|
|
7567
|
+
only when no process works in the home after the provider's stop, confirmed
|
|
7568
|
+
or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
|
|
7569
|
+
provider could not confirm the stop, the retire's answer carries a warning.
|
|
7570
|
+
|
|
7571
|
+
**Attach.** `E_SESSION_NO_TERMINAL`, `details: {backend, open}`; its message
|
|
7572
|
+
carries the `open` link when there is one. A client shows that link instead
|
|
7573
|
+
of a terminal.
|
|
7574
|
+
|
|
7575
|
+
**The authority check.** `E_RUNTIME_AUTHORITY_MISMATCH`'s `details.fields`
|
|
7576
|
+
for a provider home are `backend`, `session.provider` and `session.endpoint`
|
|
7577
|
+
(after `launched`).
|
|
7578
|
+
|
|
7579
|
+
**Readiness.** `oats readiness` carries a provider's own readiness, where it
|
|
7580
|
+
declares one, as a `providers` item: `subject: "<capability> session backend
|
|
7581
|
+
<name>"`, `producer: "session provider check"`, `result: {status, problems,
|
|
7582
|
+
warnings}` relayed as given, or `result: null` with `problems` when the
|
|
7583
|
+
provider could not be asked. Required for a home on that backend; not
|
|
7584
|
+
required for a soul.
|
|
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
|
+
|
|
7652
|
+
**The sweep.** A row of `oats session resume` for a provider home carries
|
|
7653
|
+
`backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
|
|
7654
|
+
`already-running` (a session is there), `refused` with `keeps-getting-lost`
|
|
7655
|
+
(the home's resume cap; `code: "E_SESSION_NOT_RUNNING"`, with
|
|
7656
|
+
`nextAttemptAt`; a `--plan` reads the same count and answers the same) or `start-refused`
|
|
7657
|
+
(the notice was not sent: a prompt or a claim is open, or it was queued),
|
|
7658
|
+
`skipped` with `unknown` (not readable, or a process of the last run still
|
|
7659
|
+
works in the home). A home an operator stopped has no row. `--plan
|
|
7660
|
+
--without-provider-inspect` asks no session provider: every provider home
|
|
7661
|
+
OATS has not stopped is then `skipped`, `unknown`, with its `backend`
|
|
7662
|
+
(`E_BAD_ARGS` without `--plan`). The switch is `oats host run`'s own: it
|
|
7663
|
+
lists with it at shutdown, so that a provider going down with the host cannot
|
|
7664
|
+
hold the listing up. A client has no use for it.
|
|
7665
|
+
|
|
7666
|
+
**Launch preview.** `oats launch-config preview --home <abs> --json` of a
|
|
7667
|
+
provider home answers `command: null`, `argv: null` and `executable.path:
|
|
7668
|
+
null` (its launch is handed to the provider as data), `environment` by name,
|
|
7669
|
+
and a `backend` item in `preflight`.
|
|
7670
|
+
|
|
7351
7671
|
### Input
|
|
7352
7672
|
|
|
7353
7673
|
```text
|
|
@@ -7356,7 +7676,8 @@ oats session input --home <abs> [--text-file <path>] --json
|
|
|
7356
7676
|
|
|
7357
7677
|
Input bytes come from stdin or the named file. The existing version-1 success
|
|
7358
7678
|
answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
|
|
7359
|
-
present: true, state, paneId, submitted: true, verified}}
|
|
7679
|
+
present: true, state, paneId, submitted: true, verified}}` (a provider home's
|
|
7680
|
+
is under [Session providers](#session-providers-feature-session-providers)). Session input runs
|
|
7360
7681
|
on the execution host, including when the wake broker invokes it there;
|
|
7361
7682
|
`--server` is not supported for input. The adapter sends one literal
|
|
7362
7683
|
bracketed paste and one Enter after the existing input/authority/target checks.
|
|
@@ -7395,7 +7716,7 @@ harness receipt. See [execution targets](execution-targets.md).
|
|
|
7395
7716
|
oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
|
|
7396
7717
|
oats session start --resume --home <abs> --json
|
|
7397
7718
|
oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
|
|
7398
|
-
oats session resume [--deployment <dir>] [--plan] --json
|
|
7719
|
+
oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json
|
|
7399
7720
|
```
|
|
7400
7721
|
|
|
7401
7722
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
@@ -7563,7 +7884,7 @@ answer is the ordinary start answer plus one object:
|
|
|
7563
7884
|
|
|
7564
7885
|
### The machine sweep (`oats session resume`)
|
|
7565
7886
|
|
|
7566
|
-
`oats session resume [--deployment <dir>] [--plan] --json` (feature
|
|
7887
|
+
`oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json` (feature
|
|
7567
7888
|
`session-resume`, OATS 0.69) starts with `--resume` every home of this
|
|
7568
7889
|
machine's deployments whose session was lost. A client runs it once when it
|
|
7569
7890
|
opens. It reads this computer's list of deployments without writing it
|