@awebai/oats 0.69.23 → 0.69.24
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 -17
- package/docs/capabilities.md +353 -5
- package/docs/capability-manifest.schema.json +36 -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 +320 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +257 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +5 -1
- 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/souls-and-instances.md +45 -0
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +13 -5
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1176 -181
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +97 -8
- 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/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +28 -4
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- 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,177 @@ 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_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
|
+
|
|
7463
|
+
A launch that fails otherwise is `E_SESSION_START_FAILED`.
|
|
7464
|
+
|
|
7465
|
+
**A status row** (`oats status --json`) of a provider home:
|
|
7466
|
+
|
|
7467
|
+
```json
|
|
7468
|
+
{ "instance": "dev-a", "home": "/abs/home", "launched": true,
|
|
7469
|
+
"backend": "bb",
|
|
7470
|
+
"session": { "provider": "oats.bb", "threadId": "thr_1" },
|
|
7471
|
+
"tmux": null,
|
|
7472
|
+
"open": { "label": "Open in bb", "url": "https://…" },
|
|
7473
|
+
"running": true, "runtimeState": "unknown", "waitingOnYou": null }
|
|
7474
|
+
```
|
|
7475
|
+
|
|
7476
|
+
- `backend` is the provider's name. A tmux home's row carries `backend:
|
|
7477
|
+
"tmux"`. **A row with no `backend` key reads as tmux**: it comes from a
|
|
7478
|
+
kernel or a routed host without the feature (or is a home whose record
|
|
7479
|
+
cannot be read), never from a provider home.
|
|
7480
|
+
- `session.provider` is the capability. **`session.threadId` is on a local
|
|
7481
|
+
row only**: the thread id of the provider's endpoint, when the endpoint
|
|
7482
|
+
names one, on the host where the home lives, so a tool there can match a
|
|
7483
|
+
session to its instance. It is replaced at a start and a restart, and a
|
|
7484
|
+
home OATS stopped keeps its last. **A relayed row never has it** (`oats
|
|
7485
|
+
server roster`, `oats status --server`): a relayed row's `session` is
|
|
7486
|
+
`{provider}`. A client must not depend on `threadId` beyond the local
|
|
7487
|
+
host.
|
|
7488
|
+
- **The endpoint is never on a row.** `session.endpoint` (the provider's own
|
|
7489
|
+
locator) is on `oats session inspect --home`, a launched spawn's answer
|
|
7490
|
+
and a start's answer, on the host where the home lives; the same answers
|
|
7491
|
+
through `--server` carry `session: {provider}`. Neither the endpoint nor
|
|
7492
|
+
`open` holds a token or a secret.
|
|
7493
|
+
- `tmux` is `null`; `open` is `{label, url}` or `null`: a link a viewer may
|
|
7494
|
+
open instead of a terminal. It is relayed.
|
|
7495
|
+
- `running` is `true`, `false`, or `null` where the provider cannot tell a
|
|
7496
|
+
live idle session from a settled one. `runtimeState` is always set:
|
|
7497
|
+
`unknown` (there), `shell`, `stopped` (OATS stopped it, it was never
|
|
7498
|
+
launched, or it is gone) or `unreachable`, with `runtimeError`, when the
|
|
7499
|
+
provider failed, was slow or answered outside its contract. An unreachable
|
|
7500
|
+
row is never read as stopped.
|
|
7501
|
+
- `sessionEnd` is `stopped` for a home an operator stopped, and `lost` for
|
|
7502
|
+
one stopped with the host or whose session is gone while OATS did not
|
|
7503
|
+
stop it: the sweep resumes a lost one. Absent otherwise.
|
|
7504
|
+
- `waitingOnYou` is the producers' claim, read while the session is there
|
|
7505
|
+
and not in error (`runtimeState: "unknown"`, `running` true or null).
|
|
7506
|
+
|
|
7507
|
+
**Inspect.** `oats session inspect --home <abs> --json` answers `{home,
|
|
7508
|
+
backend, present, state, running, waitingOnYou, wakeHold, session: {provider,
|
|
7509
|
+
endpoint}, open}`: no `paneId`, no `size`. `state` is `unknown`, `shell`,
|
|
7510
|
+
`stopped` or, before the first launch, `not-launched`. For a home OATS
|
|
7511
|
+
stopped it answers `present: false, state: "stopped", running: false, open:
|
|
7512
|
+
null` without asking the provider. A provider that cannot be asked is
|
|
7513
|
+
`E_SESSION_UNAVAILABLE`.
|
|
7514
|
+
|
|
7515
|
+
**Input.** `oats session input --home <abs>` answers `{home, backend,
|
|
7516
|
+
submitted: true, verified}` (no `session`: the endpoint is inspect's, a
|
|
7517
|
+
spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
|
|
7518
|
+
stopped (nothing was sent, the provider was not called), and for a lost
|
|
7519
|
+
session at its resume cap or with a process of its last run still in the
|
|
7520
|
+
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
|
|
7522
|
+
restart that lands while an input is being sent wins, whatever the provider
|
|
7523
|
+
answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
|
|
7524
|
+
is accepted only on `ok: true` with `submitted: true`.
|
|
7525
|
+
|
|
7526
|
+
**Start and restart.** The result has every key a tmux start answers, with
|
|
7527
|
+
`backend: "<name>"`, `session: {provider, endpoint}` and `target: null`:
|
|
7528
|
+
`{instance, agent, home, harness, backend, model, launchConfig, yolo, target,
|
|
7529
|
+
session, startedAt, restartCount, reused: "new", warnings}`, and `stop:
|
|
7530
|
+
{stopped: true, waitedMs}` on a restart. A start of a home whose session is
|
|
7531
|
+
there and that OATS did not stop is `E_SESSION_RUNNING` (it reads `running:
|
|
7532
|
+
true`) or `E_SESSION_UNKNOWN`. `--resume` answers the same keys with `reused:
|
|
7533
|
+
"session"`, `startedAt: null` and `resume: {resumed: true, harness}`: the
|
|
7534
|
+
resume notice went through the provider's input and nothing was launched.
|
|
7535
|
+
Its refusals: `E_RESUME_NOT_LOST` (not a lost session), `E_SESSION_NOT_RUNNING`
|
|
7536
|
+
(the resume cap; `details.resumeCap: {limit, windowMs, nextAttemptAt}`),
|
|
7537
|
+
`E_SESSION_UNKNOWN` (a process of the last run still works in the home, or
|
|
7538
|
+
the session cannot be read), `E_SESSION_PROMPT_OPEN` (a claim or a prompt is
|
|
7539
|
+
open) and `E_SESSION_INPUT_QUEUED`.
|
|
7540
|
+
|
|
7541
|
+
**A launch with no recorded outcome** (the lifecycle's
|
|
7542
|
+
[design record](design/2026-11-20-provider-home-lifecycle.md)). From the
|
|
7543
|
+
moment a spawn or a start sends the provider's launch until its endpoint is
|
|
7544
|
+
recorded, and for good when that command died first, the home's receipt
|
|
7545
|
+
carries `launchSent` and the home is unknown, whether it was launched before
|
|
7546
|
+
or not: `oats session inspect` answers `E_SESSION_UNAVAILABLE`, its status
|
|
7547
|
+
row reads `running: null`, `runtimeState: "unreachable"` with the reason, a
|
|
7548
|
+
`--resume` is `E_SESSION_UNKNOWN`, and `oats session input` is refused with
|
|
7549
|
+
nothing sent (`E_SESSION_NOT_RUNNING` for a home never launched or recorded
|
|
7550
|
+
as stopped, else `E_SESSION_INPUT_FAILED`). A stop, a start, a restart and a
|
|
7551
|
+
retire settle it first, by asking the provider to stop whatever session that
|
|
7552
|
+
launch started: a stop then answers `stopped: true` (never `alreadyIdle`),
|
|
7553
|
+
or `E_SESSION_STOP_FAILED` when the provider does not confirm; a home
|
|
7554
|
+
launched before is left stopped. The row of a never-launched home reads
|
|
7555
|
+
`launched: true` meanwhile.
|
|
7556
|
+
|
|
7557
|
+
**Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
|
|
7558
|
+
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
|
|
7560
|
+
only when no process works in the home after the provider's stop, confirmed
|
|
7561
|
+
or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
|
|
7562
|
+
provider could not confirm the stop, the retire's answer carries a warning.
|
|
7563
|
+
|
|
7564
|
+
**Attach.** `E_SESSION_NO_TERMINAL`, `details: {backend, open}`; its message
|
|
7565
|
+
carries the `open` link when there is one. A client shows that link instead
|
|
7566
|
+
of a terminal.
|
|
7567
|
+
|
|
7568
|
+
**The authority check.** `E_RUNTIME_AUTHORITY_MISMATCH`'s `details.fields`
|
|
7569
|
+
for a provider home are `backend`, `session.provider` and `session.endpoint`
|
|
7570
|
+
(after `launched`).
|
|
7571
|
+
|
|
7572
|
+
**Readiness.** `oats readiness` carries a provider's own readiness, where it
|
|
7573
|
+
declares one, as a `providers` item: `subject: "<capability> session backend
|
|
7574
|
+
<name>"`, `producer: "session provider check"`, `result: {status, problems,
|
|
7575
|
+
warnings}` relayed as given, or `result: null` with `problems` when the
|
|
7576
|
+
provider could not be asked. Required for a home on that backend; not
|
|
7577
|
+
required for a soul.
|
|
7578
|
+
|
|
7579
|
+
**The sweep.** A row of `oats session resume` for a provider home carries
|
|
7580
|
+
`backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
|
|
7581
|
+
`already-running` (a session is there), `refused` with `keeps-getting-lost`
|
|
7582
|
+
(the home's resume cap; `code: "E_SESSION_NOT_RUNNING"`, with
|
|
7583
|
+
`nextAttemptAt`; a `--plan` reads the same count and answers the same) or `start-refused`
|
|
7584
|
+
(the notice was not sent: a prompt or a claim is open, or it was queued),
|
|
7585
|
+
`skipped` with `unknown` (not readable, or a process of the last run still
|
|
7586
|
+
works in the home). A home an operator stopped has no row. `--plan
|
|
7587
|
+
--without-provider-inspect` asks no session provider: every provider home
|
|
7588
|
+
OATS has not stopped is then `skipped`, `unknown`, with its `backend`
|
|
7589
|
+
(`E_BAD_ARGS` without `--plan`). The switch is `oats host run`'s own: it
|
|
7590
|
+
lists with it at shutdown, so that a provider going down with the host cannot
|
|
7591
|
+
hold the listing up. A client has no use for it.
|
|
7592
|
+
|
|
7593
|
+
**Launch preview.** `oats launch-config preview --home <abs> --json` of a
|
|
7594
|
+
provider home answers `command: null`, `argv: null` and `executable.path:
|
|
7595
|
+
null` (its launch is handed to the provider as data), `environment` by name,
|
|
7596
|
+
and a `backend` item in `preflight`.
|
|
7597
|
+
|
|
7351
7598
|
### Input
|
|
7352
7599
|
|
|
7353
7600
|
```text
|
|
@@ -7356,7 +7603,8 @@ oats session input --home <abs> [--text-file <path>] --json
|
|
|
7356
7603
|
|
|
7357
7604
|
Input bytes come from stdin or the named file. The existing version-1 success
|
|
7358
7605
|
answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
|
|
7359
|
-
present: true, state, paneId, submitted: true, verified}}
|
|
7606
|
+
present: true, state, paneId, submitted: true, verified}}` (a provider home's
|
|
7607
|
+
is under [Session providers](#session-providers-feature-session-providers)). Session input runs
|
|
7360
7608
|
on the execution host, including when the wake broker invokes it there;
|
|
7361
7609
|
`--server` is not supported for input. The adapter sends one literal
|
|
7362
7610
|
bracketed paste and one Enter after the existing input/authority/target checks.
|
|
@@ -7395,7 +7643,7 @@ harness receipt. See [execution targets](execution-targets.md).
|
|
|
7395
7643
|
oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
|
|
7396
7644
|
oats session start --resume --home <abs> --json
|
|
7397
7645
|
oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
|
|
7398
|
-
oats session resume [--deployment <dir>] [--plan] --json
|
|
7646
|
+
oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json
|
|
7399
7647
|
```
|
|
7400
7648
|
|
|
7401
7649
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
@@ -7563,7 +7811,7 @@ answer is the ordinary start answer plus one object:
|
|
|
7563
7811
|
|
|
7564
7812
|
### The machine sweep (`oats session resume`)
|
|
7565
7813
|
|
|
7566
|
-
`oats session resume [--deployment <dir>] [--plan] --json` (feature
|
|
7814
|
+
`oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json` (feature
|
|
7567
7815
|
`session-resume`, OATS 0.69) starts with `--resume` every home of this
|
|
7568
7816
|
machine's deployments whose session was lost. A client runs it once when it
|
|
7569
7817
|
opens. It reads this computer's list of deployments without writing it
|