@awebai/oats 0.69.22 → 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 +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -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 +151 -17
- 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 +3 -3
- 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 +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- 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/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- 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/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
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
|
|
@@ -91,6 +94,9 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
91
94
|
--stdio`, which the reader's hello repeats. Start a reader only where the
|
|
92
95
|
probe lists both the feature and `readerApi: 1`
|
|
93
96
|
([The warm reader](#the-warm-reader)).
|
|
97
|
+
- `boardApi` (feature `instance-board`) is the version of the agent's board:
|
|
98
|
+
the `board` on the rows, `inspect --board` and the board commands' answers
|
|
99
|
+
([The agent's board](#the-agents-board-oats-instance-board)).
|
|
94
100
|
- In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
|
|
95
101
|
|
|
96
102
|
### Features
|
|
@@ -167,7 +173,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
167
173
|
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
168
174
|
| `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
|
|
169
175
|
| `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
|
|
170
|
-
| `instance-
|
|
176
|
+
| `instance-related-work` | `oats instance related-work <instance> on\|off` and `oats spawn … --related-work`, local and `--server` ([Related work](#related-work-oats-instance-related-work)); `relatedWork: true` on `oats status --json` instance rows and on `oats server roster --json` rows while the instance's flag is bound to its current `parentInstance`, or, with no parent, to its current `siblingInstance`, the key absent otherwise ([`relatedWork`](#row-related-work)). It renames `instance-same-work`, still advertised beside it ([below](#feature-instance-same-work)). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows never carry `relatedWork`, and it refuses the flag and the verb (`E_BAD_ARGS`) | |
|
|
177
|
+
| <a id="feature-instance-same-work"></a>`instance-same-work` | the related-work flag by its old name, kept for a release at least ([The deprecated aliases](#the-deprecated-aliases)): `oats spawn … --same-work` and `oats instance same-work <instance> on\|off` work as the new spellings, each use saying so in one line on stderr and never in `--json`; status and roster rows carry `sameWork: true` beside `relatedWork: true` for a parent binding; `.oats-same-work.json` reads as a parent binding while `.oats-related-work.json` is absent. An older kernel advertises it alone: there the flag binds a parent only. Its removal gets its own release-notes entry | |
|
|
171
178
|
| `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
|
|
172
179
|
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
173
180
|
| `instance-suggest-name` | `oats instance suggest-name [--soul <soul>] (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
|
|
@@ -183,7 +190,9 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
183
190
|
| `workspace-tasks-payload` | oats-workspace.yaml may carry a top-level `tasks:` payload, merged for the capability that fills the tasks slot exactly as `messaging:` is for the messaging one; its leaves' `settingsOrigins` are `{kind: "workspace", at: "oats-workspace.yaml#/tasks"}` ([Provider payloads have three homes](workspaces.md#provider-payloads-have-three-homes)). A kernel without it refuses a workspace file that carries `tasks:` (unknown property) | |
|
|
184
191
|
| `settings-committed-only` | a manifest `settings.<key>.committedOnly: true` is enforced: that key in oats-local.yaml `settings.<cap>` or a `--provider <cap>` flag is refused `E_WORKSPACE_SCHEMA` reason `committed-only-key`, with `details.layer`, `details.at` and `details.allowed` ([Commands and hooks](capabilities.md#commands-and-hooks)). A kernel without it ignores the flag and merges the key | |
|
|
185
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 | |
|
|
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` |
|
|
186
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. |
|
|
187
196
|
|
|
188
197
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
189
198
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -322,23 +331,27 @@ for `--no-recursive`) is never ignored.
|
|
|
322
331
|
| Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
|
|
323
332
|
|---|---|---|---|---|---|
|
|
324
333
|
| `oats retire` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir`, `--server` | `--plan`, `--self`, `--discard-worktree`, `--keep-dir`, `--force`, `--json` | `--delete-branch` | none |
|
|
325
|
-
| `oats spawn` | `<soul>` | `--agents-root`, `--backend`, `--base`, `--branch`, `--dir`, `--expect-decision`, `--harness`, `--herdr-socket`, `--idempotency-key`, `--instance`, `--launch-config`, `--max-age`, `--model`, `--name`, `--parent`, `--provider` (2 words), `--purpose`, `--relation`, `--relative-root`, `--relative-to`, `--repo`, `--runtime`, `--server`, `--task`, `--task-file`, `--trigger-event`, `--wake-cron`, `--wake-every`, `--wake-file`, `--wake-json`, `--wake-message`, `--wake-message-file`, `--wake-tz`, `--work`, `--work-dir` | `--allow-child-spawns`, `--background`, `--json`, `--no-background`, `--no-child-spawns`, `--no-launch`, `--no-yolo`, `--preview`, `--same-work`, `--suggest-name`, `--yolo` | `--instructions-file`, `--def-file`, `--ephemeral` | an unknown flag, an argument after the last |
|
|
334
|
+
| `oats spawn` | `<soul>` | `--agents-root`, `--backend`, `--base`, `--branch`, `--dir`, `--expect-decision`, `--harness`, `--herdr-socket`, `--idempotency-key`, `--instance`, `--launch-config`, `--max-age`, `--model`, `--name`, `--parent`, `--provider` (2 words), `--purpose`, `--relation`, `--relative-root`, `--relative-to`, `--repo`, `--runtime`, `--server`, `--task`, `--task-file`, `--trigger-event`, `--wake-cron`, `--wake-every`, `--wake-file`, `--wake-json`, `--wake-message`, `--wake-message-file`, `--wake-tz`, `--work`, `--work-dir` | `--allow-child-spawns`, `--background`, `--json`, `--no-background`, `--no-child-spawns`, `--no-launch`, `--no-yolo`, `--preview`, `--related-work`, `--same-work`, `--suggest-name`, `--yolo` | `--instructions-file`, `--def-file`, `--ephemeral` | an unknown flag, an argument after the last |
|
|
326
335
|
| `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
|
|
327
336
|
| `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
|
|
328
337
|
| `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
|
|
329
338
|
| `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
|
|
330
339
|
| `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
331
340
|
| `oats instance pin` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
341
|
+
| `oats instance related-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
332
342
|
| `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
333
343
|
| `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
|
|
334
344
|
| `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
|
|
335
345
|
| `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
|
|
346
|
+
| `oats instance board set` | `<key>` | `--label`, `--value`, `--unit`, `--link` | `--json` | `--home`, `--dir`, `--server` | none |
|
|
347
|
+
| `oats instance board unset` | `<key>` | none | `--json` | `--home`, `--dir`, `--server` | none |
|
|
348
|
+
| `oats instance board ask` | `[<question>]` | `--option`, `--id`, `--context-file`, `--clear` | `--json` | `--home`, `--dir`, `--server` | none |
|
|
336
349
|
| `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
|
|
337
350
|
| `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
|
|
338
351
|
| `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
|
|
339
352
|
| `oats session start` | none | `--home`, `--instance`, `--launch-config`, `--harness`, `--runtime`, `--model`, `--server` | `--reselect-launch`, `--yolo`, `--no-yolo`, `--json`, `--resume` | `--native-record` | none |
|
|
340
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 |
|
|
341
|
-
| `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 |
|
|
342
355
|
| `oats session input` | none | `--home`, `--text-file` | `--json` | `--native-record` | none |
|
|
343
356
|
| `oats session receive` | none | `--home`, `--name` | `--json` | `--native-record` | none |
|
|
344
357
|
| `oats session upload` | none | `--file`, `--home`, `--instance`, `--server` | `--json` | `--native-record` | none |
|
|
@@ -428,6 +441,7 @@ kernel command.
|
|
|
428
441
|
|
|
429
442
|
| Code | When |
|
|
430
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 |
|
|
431
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}`) |
|
|
432
446
|
| `E_CAPABILITY_INACTIVE` | In a home: the namespace's module is not one of the home's recorded capabilities |
|
|
433
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 |
|
|
@@ -631,7 +645,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
631
645
|
### `oats inspect`
|
|
632
646
|
|
|
633
647
|
```text
|
|
634
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
648
|
+
oats inspect (--home <abs> [--board] | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
635
649
|
```
|
|
636
650
|
|
|
637
651
|
An instance subject, abridged:
|
|
@@ -673,7 +687,7 @@ An instance subject, abridged:
|
|
|
673
687
|
| `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
|
|
674
688
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
675
689
|
| `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
|
|
676
|
-
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)) |
|
|
690
|
+
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)). `board` (feature `instance-board`) is there only with `--board`, which takes `--home` (`--soul` is `E_BAD_ARGS`): the row's [`board`](#row-board) with each fact's `history` and each question's `context` ([The agent's board](#the-agents-board-oats-instance-board)). Routed with `--server`, `--board` needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) |
|
|
677
691
|
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
|
|
678
692
|
| `problems` | below |
|
|
679
693
|
| `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
|
|
@@ -1001,6 +1015,15 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
|
|
|
1001
1015
|
at the top level; `stderr` appears when the provider wrote any.
|
|
1002
1016
|
- A `view` operation must answer `{documents: [{label, kind?, path?, text?}]}`
|
|
1003
1017
|
(`kind` `markdown` or `text`), else `E_OPERATION_RESULT`.
|
|
1018
|
+
- **A view may carry one structured field** beside `documents`, named after
|
|
1019
|
+
its operation and versioned by its own `<name>Api` inside it: `mail` with
|
|
1020
|
+
`mailApi` for `messaging:mail` ([Mail](#mail-mailapi-1)). `documents` stays
|
|
1021
|
+
the plain rendering every view reader can show. The kernel validates
|
|
1022
|
+
`documents` only, and relays the provider's `result` unchanged, locally and
|
|
1023
|
+
through `--server`, where the routing keys (`server`, `route`) sit beside
|
|
1024
|
+
`result`, never inside it. A client reads the structured field only at a
|
|
1025
|
+
`<name>Api` it knows, and falls back to `documents` otherwise. A view carries
|
|
1026
|
+
at most one such field.
|
|
1004
1027
|
- Errors: `E_OPERATION_UNKNOWN`, `E_OPERATION_UNAVAILABLE` (empty slot, or a
|
|
1005
1028
|
home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
|
|
1006
1029
|
(undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
|
|
@@ -1019,6 +1042,119 @@ advertises `operations`.
|
|
|
1019
1042
|
inspect; the provider's version owns their result shapes. For oats.okf, see
|
|
1020
1043
|
[knowledge.md](knowledge.md#knowledge-operations).
|
|
1021
1044
|
|
|
1045
|
+
**Messaging operations.** The messaging provider's operations are listed by
|
|
1046
|
+
inspect too. One of them is a contract of the messaging layer, whatever the
|
|
1047
|
+
provider: `messaging:mail`, below. oats.aweb is its first provider, from the
|
|
1048
|
+
release that adds it (its `docs/mail-read.md` says how it reads).
|
|
1049
|
+
|
|
1050
|
+
<a id="mail-mailapi-1"></a>
|
|
1051
|
+
#### Mail, `mailApi: 1`
|
|
1052
|
+
|
|
1053
|
+
`messaging:mail` is a read-only view of an instance's own mail, received and
|
|
1054
|
+
sent, newest first. It **never acknowledges** or marks anything read on the
|
|
1055
|
+
agent's behalf. Any messaging provider may answer it.
|
|
1056
|
+
|
|
1057
|
+
```text
|
|
1058
|
+
oats operation run messaging:mail --home <abs> [--arg limit=50] [--arg cursor=<nextCursor>] [--arg conversation=<id>] [--server <id>] --json
|
|
1059
|
+
```
|
|
1060
|
+
|
|
1061
|
+
The provider's manifest declares it as a home view operation with three
|
|
1062
|
+
optional args:
|
|
1063
|
+
|
|
1064
|
+
```json
|
|
1065
|
+
"mail": {"kind": "view", "command": "mail", "context": "home",
|
|
1066
|
+
"description": "Read-only: this instance's mail, received and sent, newest first. Never acknowledges.",
|
|
1067
|
+
"args": [{"name": "limit", "flag": "--limit"}, {"name": "cursor", "flag": "--cursor"}, {"name": "conversation", "flag": "--conversation"}]}
|
|
1068
|
+
```
|
|
1069
|
+
|
|
1070
|
+
Its `result`:
|
|
1071
|
+
|
|
1072
|
+
```json
|
|
1073
|
+
{"documents":[{"label":"Mail","kind":"markdown","text":"…plain rendering…"}],
|
|
1074
|
+
"mail":{"mailApi":1,"acknowledges":false,"observedAt":"2026-11-19T12:00:00.000Z",
|
|
1075
|
+
"identities":[{"team":"oats","alias":"dev-1","identity":"<opaque>","primary":true,"error":null},
|
|
1076
|
+
{"team":"alpha","alias":"dev-1","identity":"<opaque>","primary":false,"error":"conversation-unreadable",
|
|
1077
|
+
"unreadableConversations":["<opaque>"]}],
|
|
1078
|
+
"messages":[{"id":"<opaque>","conversationId":"<opaque>","threadTitle":"Review","direction":"received","team":"oats",
|
|
1079
|
+
"from":{"alias":"lead","address":"oats.aweb.ai/lead","identity":"<opaque>"},
|
|
1080
|
+
"to":{"alias":"dev-1","address":"oats.aweb.ai/dev-1","identity":"<opaque>"},
|
|
1081
|
+
"subject":"Review","body":"…","truncated":false,"createdAt":"2026-11-19T11:58:00Z",
|
|
1082
|
+
"readByAgent":false,"encrypted":false,"verification":"verified","priority":"normal"}],
|
|
1083
|
+
"conversations":[{"id":"<opaque>","partial":null}],
|
|
1084
|
+
"hasMore":false,"nextCursor":null}}
|
|
1085
|
+
```
|
|
1086
|
+
|
|
1087
|
+
- **Opaque values.** `identity` ids, message and conversation ids, `team`
|
|
1088
|
+
labels and `nextCursor` are the provider's strings: a client compares them
|
|
1089
|
+
and passes them back, and never parses them. `from`/`to` `address` may be
|
|
1090
|
+
`null`; `conversationId` is `null` for mail with no conversation.
|
|
1091
|
+
- **Order.** Newest first by `createdAt`, across every identity of the
|
|
1092
|
+
instance (its primary one and each joined team's), merged, each message
|
|
1093
|
+
labelled by the `team` it was read in. `direction` is decided by the
|
|
1094
|
+
sender's identity against the identity read. `identities` lists each
|
|
1095
|
+
identity read, the primary one first.
|
|
1096
|
+
- **Read state.** `readByAgent` reports the server's read state of a received
|
|
1097
|
+
message, and is `true` for a sent one. The read never changes it, and
|
|
1098
|
+
`acknowledges` is always `false`.
|
|
1099
|
+
- **Closed sets.** `direction`: `received` or `sent`. `verification`:
|
|
1100
|
+
`verified`, `unverified`, `failed` or `unknown`. `priority`: `normal`,
|
|
1101
|
+
`high` or `unknown`. `partial`: `null` or `oldest-first-only`. A client
|
|
1102
|
+
shows any other value as unknown.
|
|
1103
|
+
- **Bounds.** Each `body` is at most 16 KiB of UTF-8, cut at a character
|
|
1104
|
+
boundary, with `truncated: true`. The whole `result` is at most 256 KiB;
|
|
1105
|
+
past it the answer stops early, with `hasMore: true` and a `nextCursor`.
|
|
1106
|
+
Where one message alone wouldn't fit, its `subject` and `threadTitle` are
|
|
1107
|
+
cut too, and `truncated: true` marks that as well: `truncated` means the
|
|
1108
|
+
provider shortened the message, whichever of its texts it cut. An answer
|
|
1109
|
+
is never sent oversized, nor as an empty page with `hasMore: true` and no
|
|
1110
|
+
`nextCursor`. `limit` is 1 to 200, default 50 (`E_BAD_ARGS` otherwise).
|
|
1111
|
+
- **Paging.** `nextCursor`, passed back as `--arg cursor=…`, gives the next
|
|
1112
|
+
messages in the same order, with no overlap. What a cursor encodes is the
|
|
1113
|
+
provider's (oats.aweb's: the last message's `createdAt`, id and team). `--arg conversation=<id>`
|
|
1114
|
+
reads one conversation, newest first; its cursor is valid only with the same
|
|
1115
|
+
conversation.
|
|
1116
|
+
- **Partial conversations.** Where the provider can read only the oldest part
|
|
1117
|
+
of a long conversation, the conversation is listed in `conversations` with
|
|
1118
|
+
`partial: "oldest-first-only"`, and its newest messages are missing, never
|
|
1119
|
+
shown as the latest. A client says "older part of a long conversation
|
|
1120
|
+
shown; the newest messages can't be read yet".
|
|
1121
|
+
- **Untrusted text.** `subject`, `threadTitle` and `body` are the sender's
|
|
1122
|
+
plain text: show them as text, attributed to their sender, never as markup.
|
|
1123
|
+
- **Encrypted mail.** End-to-end encrypted bodies are decrypted with the
|
|
1124
|
+
agent's keys, and shown to whoever can run `oats operation run` on that
|
|
1125
|
+
machine (routed reads included): the access that attaching to the agent's
|
|
1126
|
+
terminal already gives, no wider. `encrypted: true` marks them.
|
|
1127
|
+
- **Errors per identity.** In `identities[].error`, a provider's code (such
|
|
1128
|
+
as a grant without mail read). **An identity's `error` doesn't mean it has
|
|
1129
|
+
no messages:** it can come with that identity's messages beside it, and a
|
|
1130
|
+
reader shows both the mail and that some of it couldn't be read. One code
|
|
1131
|
+
is the layer's: `conversation-unreadable`, one or more of that identity's
|
|
1132
|
+
conversations couldn't be read; its other messages are shown, and the row
|
|
1133
|
+
names the missing ones in `unreadableConversations` (conversation ids,
|
|
1134
|
+
present only with that code, the list's tail dropped first if the 256 KiB
|
|
1135
|
+
bound needs it, so it may name fewer than failed, or none).
|
|
1136
|
+
- **Whole failures.** The operation fails whole, with no answer, in two
|
|
1137
|
+
cases: `E_MAIL_UNREADABLE` when no identity can be read
|
|
1138
|
+
(`details.identities` holds the rows), and `E_MAIL_TOO_LARGE` when even an
|
|
1139
|
+
answer with no messages can't fit the 256 KiB bound (its identities alone).
|
|
1140
|
+
- **Cost.** Each read calls the messaging service several times. Read on
|
|
1141
|
+
demand (opening a view, a manual refresh), never on a status poll.
|
|
1142
|
+
- **Older sides.** A home whose provider copy predates the operation answers
|
|
1143
|
+
`E_OPERATION_UNKNOWN` (inspect doesn't list `mail`): the home gets it from
|
|
1144
|
+
`oats instance upgrade` or a new spawn. A home with no messaging slot
|
|
1145
|
+
answers `E_OPERATION_UNAVAILABLE`, and a remote host without `operations`
|
|
1146
|
+
`E_REMOTE_INCOMPATIBLE`. A provider's own refusals are relayed with their
|
|
1147
|
+
code, such as oats.aweb's `E_AW_TOO_OLD` (`details: {version, needs}`) for
|
|
1148
|
+
an aw too old to read mail without acknowledging it.
|
|
1149
|
+
- **The provider's own.** How a provider maps its service's values onto the
|
|
1150
|
+
closed sets, its other identity error codes, what its cursor encodes and how
|
|
1151
|
+
much of a body its `documents` rendering shows are its own, in its docs. For
|
|
1152
|
+
oats.aweb: the "messaging:mail" section of its
|
|
1153
|
+
[README](https://github.com/awebai/oats-aweb/blob/main/README.md#messagingmail-an-instances-mail-read-without-acknowledging-it)
|
|
1154
|
+
and its [docs/mail-read.md](https://github.com/awebai/oats-aweb/blob/main/docs/mail-read.md)
|
|
1155
|
+
(the aw commands it runs, the verification and priority mappings, the
|
|
1156
|
+
cursor, every error code, a 500-character body excerpt in `documents`).
|
|
1157
|
+
|
|
1022
1158
|
<a id="workspace-model-workspaceapi-2"></a>
|
|
1023
1159
|
## Workspace
|
|
1024
1160
|
|
|
@@ -1720,6 +1856,14 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
|
|
|
1720
1856
|
empty list read as "no warning". Older kernels answer no such `warnings` key
|
|
1721
1857
|
(inspect, readiness, show, doctor) and refuse the capability instead.
|
|
1722
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
|
+
|
|
1723
1867
|
`oats doctor --json` also lists what retires left behind in `information[]`:
|
|
1724
1868
|
one `retained-recovery:` and one `retained-worktree:` line per item, after a
|
|
1725
1869
|
line that gives each kind's total, and at most 50 items per kind
|
|
@@ -3091,7 +3235,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
3091
3235
|
|
|
3092
3236
|
- Always present: `instance, agent, home, work, branch, base ({ref, oid}
|
|
3093
3237
|
the new branch started at; `null` without one), launched, warnings
|
|
3094
|
-
(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,
|
|
3095
3241
|
model, parent,
|
|
3096
3242
|
sibling, relation, spawnOrigin (operator | instance), attach, launchConfig,
|
|
3097
3243
|
launch` (the redacted recipe).
|
|
@@ -3336,7 +3482,7 @@ kernel stage raised as well.
|
|
|
3336
3482
|
|
|
3337
3483
|
| Code | Details | When |
|
|
3338
3484
|
|---|---|---|
|
|
3339
|
-
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul; `--same-work` for an instance that would record no parent ([
|
|
3485
|
+
| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul; `--related-work` (or its deprecated alias `--same-work`) for an instance that would record no parent or sibling ([Related work](#related-work-oats-instance-related-work)) |
|
|
3340
3486
|
| `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
|
|
3341
3487
|
| `E_SOUL_UNKNOWN` | `{name, members, packages, unconfirmed?}` | no such soul, or not at `--agents-root`. `unconfirmed`, only when a member could not be confirmed: `[{key, reason, detail}]`, which the message repeats with what to do |
|
|
3342
3488
|
| `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
|
|
@@ -3754,6 +3900,62 @@ its absence.
|
|
|
3754
3900
|
output, not the exit status, and nothing is printed, whether or not it can
|
|
3755
3901
|
be read or written. A status routed with `--server` records nothing on this
|
|
3756
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.
|
|
3757
3959
|
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3758
3960
|
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3759
3961
|
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
@@ -3768,15 +3970,31 @@ its absence.
|
|
|
3768
3970
|
the home holds a valid pin ([Pinned instances](#pinned-instances-oats-instance-pin)),
|
|
3769
3971
|
absent otherwise; never `false`. A `pinned` in `instance.json` never
|
|
3770
3972
|
stands in for it. Clients list a pinned row first in its machine's list.
|
|
3771
|
-
- <a id="row-
|
|
3772
|
-
`
|
|
3773
|
-
|
|
3774
|
-
|
|
3775
|
-
|
|
3776
|
-
|
|
3777
|
-
|
|
3778
|
-
|
|
3779
|
-
|
|
3973
|
+
- <a id="row-board"></a>**`board`** (feature `instance-board`): the agent's
|
|
3974
|
+
board, `{facts: [{key, label, value, unit, link, at}], questions: [{id,
|
|
3975
|
+
question, options, hasContext, since}]}`, or `null` for a home with no board
|
|
3976
|
+
file (or one whose directory can't be read) ([The agent's board](#the-agents-board-oats-instance-board)). Facts come
|
|
3977
|
+
in the order first set, questions in the order asked, and only the questions
|
|
3978
|
+
of the instance's current session. A file that can't be read as a board is an
|
|
3979
|
+
empty board, never an error. The value is at most 8 KiB as UTF-8 JSON on every
|
|
3980
|
+
row. It carries no history and no context: `oats inspect --home <h> --board`
|
|
3981
|
+
does. A `board` in `instance.json` never stands in for it, and an older
|
|
3982
|
+
kernel's rows have no key.
|
|
3983
|
+
- <a id="row-related-work"></a><a id="row-same-work"></a>**`relatedWork`**
|
|
3984
|
+
(feature `instance-related-work`): `true` when the home's related-work
|
|
3985
|
+
flag ([Related work](#related-work-oats-instance-related-work)) is bound
|
|
3986
|
+
to the parent the row's `parentInstance` names, or, on a row with no
|
|
3987
|
+
`parentInstance`, to the sibling its `siblingInstance` names. Otherwise
|
|
3988
|
+
the key is absent, never `false` or `null`: no flag, a flag bound to an
|
|
3989
|
+
earlier relation, neither relation, and a row whose `instance.json`
|
|
3990
|
+
cannot be read. A `relatedWork` or `sameWork` in `instance.json` never
|
|
3991
|
+
stands in for it. **`sameWork`** (feature `instance-same-work`), the
|
|
3992
|
+
flag's old name, stands beside it as `true` when the binding is to the
|
|
3993
|
+
parent, for a client that reads the old key; it is absent for a sibling
|
|
3994
|
+
binding and whenever `relatedWork` is, never `false` or `null`.
|
|
3995
|
+
Clients draw the line between the row and the instance it is bound to; a
|
|
3996
|
+
client that does not know the key ignores it, and an older kernel never
|
|
3997
|
+
sends it.
|
|
3780
3998
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3781
3999
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3782
4000
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -4050,11 +4268,21 @@ route target:
|
|
|
4050
4268
|
has exactly `pinned: true`; any other value (`"true"`, `1`), a host whose
|
|
4051
4269
|
kernel predates the feature and a saved route the host did not list carry
|
|
4052
4270
|
none ([`pinned`](#row-pinned)).
|
|
4053
|
-
- **`
|
|
4054
|
-
|
|
4055
|
-
|
|
4056
|
-
|
|
4057
|
-
|
|
4271
|
+
- **`board`** (feature `instance-board`) is on a row only when the host's row
|
|
4272
|
+
has the key. It is read by this kernel's own rules: each fact and question
|
|
4273
|
+
within its bounds and the whole within 8 KiB, or else an empty board.
|
|
4274
|
+
`null` stays `null` ([`board`](#row-board)).
|
|
4275
|
+
- **`relatedWork`** (feature `instance-related-work`) is on a row only when
|
|
4276
|
+
the host's row has `relatedWork: true`, and is then `true`. From a host
|
|
4277
|
+
whose features list `instance-same-work` and not `instance-related-work`
|
|
4278
|
+
(an older OATS), its row's `sameWork: true` is relayed as `relatedWork:
|
|
4279
|
+
true`. Any other value, a host whose kernel predates both features, and a
|
|
4280
|
+
saved route the host did not list carry no key
|
|
4281
|
+
([`relatedWork`](#row-related-work)). `sameWork: true` is relayed beside
|
|
4282
|
+
`relatedWork: true` when the host's row says it (a parent binding), and
|
|
4283
|
+
never on its own. `oats status --server <id> --json` relays the host's
|
|
4284
|
+
answer as it gave it, except for these two keys: each instance row carries
|
|
4285
|
+
them by the same rule (an older host's `sameWork: true` as both).
|
|
4058
4286
|
- **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
|
|
4059
4287
|
when the host's row has the key, with the host's value: a host whose kernel
|
|
4060
4288
|
predates the feature, a row the host reports without it (one that runs,
|
|
@@ -4299,7 +4527,7 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
4299
4527
|
| `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
|
|
4300
4528
|
| `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
|
|
4301
4529
|
| `oats instance pin <name> on\|off --server <id>` | none | `instance-pin` |
|
|
4302
|
-
| `oats instance
|
|
4530
|
+
| `oats instance related-work <name> on\|off --server <id>` | none | `instance-related-work`; a host with only `instance-same-work` is asked by the old name for a parent binding ([Related work](#related-work-oats-instance-related-work)) |
|
|
4303
4531
|
|
|
4304
4532
|
- The flags are the local command's. The instance is addressed like every
|
|
4305
4533
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -4850,7 +5078,13 @@ oats instance attention [--message=<text>] [--clear] --json
|
|
|
4850
5078
|
|
|
4851
5079
|
- **The row.** A claim is a `waiting` event, `data: {waitingOnYou: true,
|
|
4852
5080
|
reason, message?}` or `{waitingOnYou: false}`, appended to both logs, with
|
|
4853
|
-
`producer` the caller's `--producer`.
|
|
5081
|
+
`producer` the caller's `--producer`. The board's claim (producer
|
|
5082
|
+
`oats.board`, [The agent's board](#the-agents-board-oats-instance-board))
|
|
5083
|
+
also carries `session`, the id of the session it was set in. A row with a
|
|
5084
|
+
`session` counts only while that is still the current session, and only
|
|
5085
|
+
where the read proves it: a session boundary is in the rows read, or the
|
|
5086
|
+
log was read whole (not cut to its last 4 MiB). No verb sets one; a row
|
|
5087
|
+
without `session` counts as before.
|
|
4854
5088
|
- **`waiting`.** `--producer` matches `^[a-z0-9][a-z0-9._/-]{0,63}$` and is
|
|
4855
5089
|
not `kernel`. `set` needs `--reason`, one of `permission`, `question`,
|
|
4856
5090
|
`attention` (closed). `clear` refuses `--reason` and `--message`. The home
|
|
@@ -5116,7 +5350,12 @@ oats instance stop <instance> --plan [--no-recursive] [--home <abs>] [--dir <d>]
|
|
|
5116
5350
|
`E_GIT_FAILED` for an error that has none; `E_WORK_INSPECTION_FAILED` for
|
|
5117
5351
|
a home the kernel cannot look into, where whether it has a `work/` cannot
|
|
5118
5352
|
be told; OATS 0.52.0).
|
|
5119
|
-
- `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`.
|
|
5120
5359
|
- `retiring` and `stopPending`, booleans on every target, say who holds the
|
|
5121
5360
|
target's home when the plan is read (OATS 0.52.0, feature
|
|
5122
5361
|
`lifecycle-claim-stop`). `retiring`: a self-retire is scheduled for it
|
|
@@ -6920,90 +7159,442 @@ when the host's row says exactly `true`), and on `oats inspect --home` as
|
|
|
6920
7159
|
`instance.pinned`. Each is absent when not pinned. A client reads `pinned`
|
|
6921
7160
|
only where the probe lists `instance-pin`.
|
|
6922
7161
|
|
|
6923
|
-
##
|
|
7162
|
+
## The agent's board (`oats instance board`)
|
|
6924
7163
|
|
|
6925
|
-
Feature `instance-
|
|
7164
|
+
Feature `instance-board`, `boardApi: 1`.
|
|
6926
7165
|
|
|
6927
7166
|
```text
|
|
6928
|
-
oats instance
|
|
6929
|
-
oats
|
|
7167
|
+
oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
|
|
7168
|
+
oats instance board unset <key> [--json]
|
|
7169
|
+
oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
|
|
7170
|
+
oats instance board ask --clear <id> [--json]
|
|
6930
7171
|
```
|
|
6931
7172
|
|
|
6932
|
-
The
|
|
6933
|
-
|
|
6934
|
-
|
|
6935
|
-
|
|
7173
|
+
The board is what an agent tells its person outside its terminal: the
|
|
7174
|
+
**facts** it keeps in view (the PR, the best score, the branch) and the
|
|
7175
|
+
**questions** it needs them to answer, each with 2 to 4 options. A client
|
|
7176
|
+
shows them in the agent's view, above and below the agent's own terminal.
|
|
7177
|
+
The agent reports them, and the kernel infers nothing: it never reads a
|
|
7178
|
+
transcript, and it routes no answer. The word "pin" is never used for facts:
|
|
7179
|
+
[`oats instance pin`](#pinned-instances-oats-instance-pin) pins an instance at
|
|
7180
|
+
the top of the list, which is something else.
|
|
7181
|
+
|
|
7182
|
+
- **Who writes it.** Only the agent, from its own session, as `oats instance
|
|
7183
|
+
attention` does: the home is `$OATS_INSTANCE_HOME`. `--home`, `--dir` and
|
|
7184
|
+
`--server` are refused (`E_BAD_ARGS`), and outside an instance home every
|
|
7185
|
+
form is `E_USAGE`.
|
|
7186
|
+
- **`set`** upserts the fact `<key>`. At most 12 keys: one more is
|
|
7187
|
+
`E_BOARD_FULL`. A set with every field the same changes nothing and writes
|
|
7188
|
+
nothing. The kernel keeps a key's last 20 values with their times (a new
|
|
7189
|
+
value joins it; a new label alone doesn't). `at` is when the fact last
|
|
7190
|
+
changed. **`unset`** removes the key and its history.
|
|
7191
|
+
- **`ask`** opens a question. Its id is `--id`, or `q<n>` by default. `n` is
|
|
7192
|
+
counted per home and never reused while the home lives, so a late answer
|
|
7193
|
+
can't land on a newer question (past `q999999999999999` no default id is
|
|
7194
|
+
left: `E_BOARD_FULL`, ask with `--id`). At most 9 open at once: one more is
|
|
7195
|
+
`E_BOARD_FULL`. Asking a question that is open with the same text, options
|
|
7196
|
+
and context again changes nothing and answers its id, with or without
|
|
7197
|
+
`--id`, so a retry is safe. Anything else under an open id is
|
|
7198
|
+
`E_BAD_ARGS`. **`ask --clear <id>`** closes the
|
|
7199
|
+
question, which the agent does once it has read the answer. Clearing an id
|
|
7200
|
+
that isn't open changes nothing.
|
|
7201
|
+
- **Text.** Key and id match `^[a-z0-9][a-z0-9-]{0,15}$`. Label, value,
|
|
7202
|
+
unit, option and question are one line each, of at most 40, 80, 16, 60
|
|
7203
|
+
and 200 code points, with none of the characters a
|
|
7204
|
+
[waiting message](#waiting-on-you) refuses. A link is an absolute `https:`
|
|
7205
|
+
URL of at most 512 printable ASCII characters. The context comes from a
|
|
7206
|
+
UTF-8 file (`--context-file`), at most 2000 code points once its trailing
|
|
7207
|
+
newlines are trimmed (a file's final newline, such as a heredoc's, isn't
|
|
7208
|
+
content). Newlines (LF) are allowed in it, and every other refused
|
|
7209
|
+
character is not. Anything else is `E_BAD_ARGS`.
|
|
7210
|
+
- **The row bound.** A write that would make the row's `board` larger than
|
|
7211
|
+
8 KiB as UTF-8 JSON is `E_BOARD_FULL`, with `details.bytes` and
|
|
7212
|
+
`details.max`. Every client can rely on that bound for every row. A
|
|
7213
|
+
refused write writes nothing.
|
|
7214
|
+
- **Per session.** A question records the session it was asked in: the
|
|
7215
|
+
instance's latest kernel session boundary (`launched`, `restarted`,
|
|
7216
|
+
`stopped`: the [waiting claim's rule](#waiting-on-you)). It is live only
|
|
7217
|
+
while that is still the current session. Once a later boundary is written,
|
|
7218
|
+
no row shows it, and the next write drops it. Where the events log's bounded
|
|
7219
|
+
read (its last 4 MiB) holds no boundary, the current session can't be
|
|
7220
|
+
proved: no question is live, and `ask` is `E_BOARD_FAILED` until the next
|
|
7221
|
+
boundary. Facts persist across sessions until they are unset or the home is
|
|
7222
|
+
retired.
|
|
7223
|
+
|
|
7224
|
+
**The needs-input claim.** While any question is open, the home holds the
|
|
7225
|
+
[waiting claim](#waiting-on-you) of producer `oats.board`, reason
|
|
7226
|
+
`attention`. Its message is the oldest open question. The last `--clear`
|
|
7227
|
+
removes it. The claim's row records the session the write read
|
|
7228
|
+
(`session`), and counts only in that session, so a boundary written while a
|
|
7229
|
+
board write runs ends the claim with the question. Reason `attention` holds no scheduled wake
|
|
7230
|
+
([A held wake](schedules.md#a-held-wake)): a board question leaves the
|
|
7231
|
+
harness at its normal input line. The claim is a producer of its own, so the
|
|
7232
|
+
agent's own `attention` claim can be live beside it, and `waitingOnYou`
|
|
7233
|
+
picks between them by its usual rule. Every board write sets the claim to
|
|
7234
|
+
what the questions say after it. A write whose claim fails is
|
|
7235
|
+
`E_EVENTS_FAILED` after the board was written, with `details.id` (or
|
|
7236
|
+
`details.key`) naming what was written. Running the same command again
|
|
7237
|
+
changes nothing on the board and repairs the claim.
|
|
7238
|
+
|
|
7239
|
+
**How a person answers.** The kernel routes no answer. A client types it as
|
|
7240
|
+
the person's own keystrokes, in the agent's terminal, as `<id>: <text>`
|
|
7241
|
+
(`q2: Yes, one clean commit`), and the person's Enter sends it. An agent reads
|
|
7242
|
+
an answer by its id, then clears the question.
|
|
7243
|
+
|
|
7244
|
+
**The answer** of every form is `{boardApi, instance, home, key | id,
|
|
7245
|
+
changed, board}`, where `board` is the row's value after the write
|
|
7246
|
+
(`null` when the home has no board file and nothing was written):
|
|
7247
|
+
|
|
7248
|
+
```json
|
|
7249
|
+
{"boardApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","id":"q2","changed":true,
|
|
7250
|
+
"board":{"facts":[{"key":"pr","label":"Pull request","value":"#1990","unit":null,"link":"https://github.com/oats-project/oats/pull/1990","at":"2026-11-19T21:00:00.000Z"}],
|
|
7251
|
+
"questions":[{"id":"q2","question":"Squash before merging?","options":["Yes, one clean commit","No, keep the history"],"hasContext":true,"since":"2026-11-19T21:01:00.000Z"}]}}
|
|
7252
|
+
```
|
|
6936
7253
|
|
|
6937
|
-
|
|
6938
|
-
|
|
6939
|
-
|
|
6940
|
-
|
|
6941
|
-
|
|
7254
|
+
The text answer is one line: `<instance>: fact <key> set` (or `unchanged`,
|
|
7255
|
+
`removed`, `was not set`), or `<instance>: question <id> asked: answers
|
|
7256
|
+
arrive typed as "<id>: <text>"` (or `cleared`, `was not open`).
|
|
7257
|
+
|
|
7258
|
+
| Code | When |
|
|
7259
|
+
|---|---|
|
|
7260
|
+
| `E_USAGE` | Not in an instance session: `$OATS_INSTANCE_HOME` unset, not absolute, or not an instance home under its agents root |
|
|
7261
|
+
| `E_BAD_ARGS` | `--home`, `--dir` or `--server`; a field out of its rules; fewer than 2 or more than 4 options; another question under an open id; a flag given twice (`--option` repeats); `--clear` beside anything else |
|
|
7262
|
+
| `E_BOARD_FULL` | A 13th fact, a 10th open question, a row over 8 KiB, or no default id left; nothing was changed |
|
|
7263
|
+
| `E_BOARD_FAILED` | `ask` where the current session can't be read from the events log (no boundary in its last 4 MiB); nothing was changed. Use `oats instance attention --message` |
|
|
7264
|
+
| `E_BOARD_BUSY` | Another process holds the board's lock past 5 seconds (`details.lock`); nothing was changed |
|
|
7265
|
+
| `E_EVENTS_FAILED` | The board was written (`details.id` or `details.key`), but its claim was not: run the same command again |
|
|
7266
|
+
|
|
7267
|
+
**Where it is read.** [`board` on status rows](#row-board), relayed on
|
|
7268
|
+
[remote roster rows](#the-remote-roster-oats-server-roster---json), and with
|
|
7269
|
+
history and context on `oats inspect --home <h> --board` as
|
|
7270
|
+
`instance.board`: each fact gains `history: [{value, at}]` (oldest first, its
|
|
7271
|
+
current value last) and each question `context` (the text, or `null`). Read
|
|
7272
|
+
it when a view is open, not on every poll. Agent text is untrusted: a client
|
|
7273
|
+
shows it as the agent's attributed words, plain text only, and opens a link
|
|
7274
|
+
only on the person's press, outside the app's window.
|
|
7275
|
+
|
|
7276
|
+
**Storage.** `<home>/.oats-board.json`, mode 0600, written atomically under
|
|
7277
|
+
the lock `<home>/.oats-board.lock`, so parallel writes of one agent lose
|
|
7278
|
+
none. The format is the kernel's own, not part of this contract. A reader
|
|
7279
|
+
takes a regular file of at most 256 KiB, without following a link. A file
|
|
7280
|
+
that isn't a valid board in every part reads as an empty board,
|
|
7281
|
+
`{facts: [], questions: []}`, never as an error. Both names are kernel-owned
|
|
7282
|
+
home files: a capability cannot declare them, and a retire counts neither as
|
|
7283
|
+
work. A start, restart or upgrade keeps them, and a retire removes them with
|
|
7284
|
+
the home.
|
|
7285
|
+
|
|
7286
|
+
## Related work (`oats instance related-work`)
|
|
7287
|
+
|
|
7288
|
+
<a id="same-work-as-the-parent-oats-instance-same-work"></a>
|
|
7289
|
+
Feature `instance-related-work`. It renames `instance-same-work`
|
|
7290
|
+
(awebai/oats#1577), which the kernel still advertises beside it for the
|
|
7291
|
+
[deprecated aliases](#the-deprecated-aliases) and the old row field.
|
|
7292
|
+
|
|
7293
|
+
```text
|
|
7294
|
+
oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
|
|
7295
|
+
oats spawn <soul> … --related-work
|
|
7296
|
+
```
|
|
7297
|
+
|
|
7298
|
+
The flag records that an instance does related work with the instance it is
|
|
7299
|
+
bound to: its parent, or, when it has no parent, its sibling. Clients draw a
|
|
7300
|
+
line between the two for an instance that carries it. Nothing else in the
|
|
7301
|
+
kernel reads it: it is not identity, it grants nothing and it never
|
|
7302
|
+
addresses anything. The kernel never sets it on its own, for any relation:
|
|
7303
|
+
only `--related-work` and `on` do.
|
|
7304
|
+
|
|
7305
|
+
- **The binding.** The flag binds the home's recorded `parentInstance` when
|
|
7306
|
+
it has one, else its recorded `siblingInstance`. With neither, it cannot
|
|
7307
|
+
be set. A sibling binding names the sibling the home records. For a
|
|
7308
|
+
sibling of a top-level instance R, that is R. For a sibling of R's
|
|
7309
|
+
sibling S, the home records S, the anchor it was spawned beside, so the
|
|
7310
|
+
binding is to S, not R.
|
|
7311
|
+
- **The record** is `<home>/.oats-related-work.json`, either
|
|
7312
|
+
`{"relatedWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}` or
|
|
7313
|
+
`{"relatedWorkApi": 1, "sibling": "<instance>", "at": "<ISO time>"}`,
|
|
7314
|
+
exactly one of `parent` and `sibling`, mode 0600, written atomically.
|
|
7315
|
+
Present means on; `off` removes it. It is a kernel-owned home file: a
|
|
7316
|
+
capability cannot declare it as its own, a retire does not count it as
|
|
7317
|
+
work (on its own it never makes a recovery copy), and `oats instance
|
|
6942
7318
|
upgrade` does not see it as a change to the home.
|
|
6943
7319
|
- **A reader** takes a regular file only, without following a link, of at
|
|
6944
|
-
most 4 KiB, holding JSON with `
|
|
6945
|
-
`parent`. Anything else reads as off, never
|
|
6946
|
-
|
|
6947
|
-
|
|
6948
|
-
|
|
6949
|
-
|
|
6950
|
-
|
|
6951
|
-
|
|
7320
|
+
most 4 KiB, holding JSON with `relatedWorkApi: 1` and exactly one of a
|
|
7321
|
+
non-empty string `parent` and `sibling`. Anything else reads as off, never
|
|
7322
|
+
as an error.
|
|
7323
|
+
- **Bound to the relation.** A parent binding is on only while its `parent`
|
|
7324
|
+
is the home's current recorded `parentInstance`. A sibling binding is on
|
|
7325
|
+
only while the home records no parent and its `sibling` is the current
|
|
7326
|
+
`siblingInstance`. A relink that changes the relation leaves the record
|
|
7327
|
+
naming the old instance, so the flag reads off: a retire's lineage relink
|
|
7328
|
+
(the instances pointing at the retiree re-pointed to its parent, or their
|
|
7329
|
+
sibling link moved to its sibling) and a `--relation parent` spawn
|
|
7330
|
+
re-pointing its anchor. `on` binds it to the current relation again.
|
|
6952
7331
|
- **Lifetime.** It survives `oats session restart`, a stop and a start, a
|
|
6953
7332
|
resume (`oats session start --resume`) and `oats instance upgrade`. Only
|
|
6954
7333
|
`off` and retirement clear it.
|
|
7334
|
+
- **The old flag.** A same-work record, `<home>/.oats-same-work.json`
|
|
7335
|
+
(`{"sameWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}`), reads
|
|
7336
|
+
as a parent binding while nothing stands at the new record's name, by the
|
|
7337
|
+
same reader rules; so an instance flagged before the rename keeps its
|
|
7338
|
+
flag. When both exist, the new record wins, whatever it holds. The write
|
|
7339
|
+
that creates the new record removes the old one, and `off` removes both.
|
|
7340
|
+
`on` for a binding the old record already holds writes nothing. Both names
|
|
7341
|
+
are kernel-owned.
|
|
7342
|
+
|
|
7343
|
+
<a id="the-deprecated-aliases"></a>
|
|
7344
|
+
**The deprecated aliases.** `oats spawn … --same-work` is `--related-work`,
|
|
7345
|
+
and `oats instance same-work <instance> on|off` is `oats instance
|
|
7346
|
+
related-work`, with the same binding rule (the parent, else the sibling),
|
|
7347
|
+
the same refusals and the same answer; spawnInstance's `sameWork` option is
|
|
7348
|
+
`relatedWork`, and each call with it emits one Node `DeprecationWarning`
|
|
7349
|
+
(code `OATS_SAME_WORK`, `sameWork is renamed: use relatedWork`). Each CLI use prints one line on stderr, before the command runs
|
|
7350
|
+
or is sent with `--server`: `oats: --same-work is renamed: use
|
|
7351
|
+
--related-work`, or `oats: oats instance same-work is renamed: use oats
|
|
7352
|
+
instance related-work`. It is never in the `--json` answer: the envelope is
|
|
7353
|
+
the one the new spelling gives, with no `warnings`. The aliases, the
|
|
7354
|
+
feature `instance-same-work` and the [`sameWork`](#row-related-work) row
|
|
7355
|
+
field stay until their removal is decided on its own, with its own
|
|
7356
|
+
release-notes entry.
|
|
6955
7357
|
|
|
6956
7358
|
**The verb.** The instance is addressed as `oats instance color` addresses
|
|
6957
7359
|
it, and refused with the same answers.
|
|
6958
7360
|
|
|
6959
|
-
- `on` binds the flag to the instance's recorded `parentInstance
|
|
6960
|
-
instance with
|
|
6961
|
-
|
|
6962
|
-
|
|
6963
|
-
- `off` removes whatever stands at
|
|
6964
|
-
directory). It succeeds whether or not the flag was on and whether or not
|
|
6965
|
-
|
|
7361
|
+
- `on` binds the flag to the instance's recorded `parentInstance`, else to
|
|
7362
|
+
its recorded `siblingInstance`; an instance with neither is refused. `on`
|
|
7363
|
+
again while the flag holds that binding writes nothing; `on` after a
|
|
7364
|
+
relink rebinds it to the current relation.
|
|
7365
|
+
- `off` removes whatever stands at either record's name (a file, a link, a
|
|
7366
|
+
directory). It succeeds whether or not the flag was on and whether or not
|
|
7367
|
+
a relation is recorded; `off` again is the same answer.
|
|
6966
7368
|
|
|
6967
|
-
The answer, the envelope's `result`, has exactly these
|
|
7369
|
+
The answer, the envelope's `result`, has exactly these three keys:
|
|
6968
7370
|
|
|
6969
7371
|
```json
|
|
6970
|
-
{"instance":"dev-a","sameWork":true}
|
|
7372
|
+
{"instance":"dev-a","relatedWork":true,"sameWork":true}
|
|
6971
7373
|
```
|
|
6972
7374
|
|
|
6973
|
-
`
|
|
6974
|
-
`false` after `off`.
|
|
7375
|
+
`relatedWork` is the binding rule read after the write: `true` after `on`,
|
|
7376
|
+
`false` after `off`. `sameWork` is the old verb's answer: `true` only when
|
|
7377
|
+
the flag holds a parent binding, so `false` for a sibling binding. The text
|
|
7378
|
+
answer is `dev-a: related work on` (or `off`).
|
|
6975
7379
|
|
|
6976
7380
|
| Code | When |
|
|
6977
7381
|
|---|---|
|
|
6978
|
-
| `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with
|
|
7382
|
+
| `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with neither a recorded parent nor a recorded sibling: `<instance> would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed` |
|
|
6979
7383
|
| *(as `oats instance color`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
|
|
6980
7384
|
| `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes), or the home is quarantined. Nothing was written |
|
|
6981
7385
|
| `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
|
|
6982
7386
|
|
|
6983
|
-
**At spawn.** `oats spawn … --
|
|
6984
|
-
bound to the parent
|
|
6985
|
-
<instance>` or `--relation child`; `--relation
|
|
6986
|
-
a parent (the new instance shares it);
|
|
6987
|
-
|
|
6988
|
-
|
|
6989
|
-
|
|
6990
|
-
|
|
6991
|
-
|
|
6992
|
-
|
|
6993
|
-
|
|
7387
|
+
**At spawn.** `oats spawn … --related-work` sets the flag on the new
|
|
7388
|
+
instance. It is bound to the parent the new home records, whichever
|
|
7389
|
+
relation gave it: `--parent <instance>` or `--relation child`; `--relation
|
|
7390
|
+
sibling` of an anchor that has a parent (the new instance shares it);
|
|
7391
|
+
`--relation parent` of an anchor that had a parent (the new instance
|
|
7392
|
+
inherits it); `--work attached` (the owner of the tree). Else it is bound to
|
|
7393
|
+
the sibling the new home records: `--relation sibling` of an anchor with no
|
|
7394
|
+
parent (the anchor itself), and `--relation parent` of an anchor with a
|
|
7395
|
+
sibling link and no parent (the new instance inherits the link). The record
|
|
7396
|
+
is written inside the spawn, before the launch, so the instance's first
|
|
7397
|
+
status row carries `relatedWork: true`; a spawn rolled back removes it with
|
|
7398
|
+
the home. When the new instance would record neither (no relation,
|
|
7399
|
+
`--relation unrelated`, `--relation parent` of a top-level anchor with no
|
|
7400
|
+
sibling link), the spawn is refused with `E_BAD_ARGS` before anything is
|
|
7401
|
+
created, `--preview` included: `--related-work needs a parent or a sibling:
|
|
7402
|
+
<instance> would record no parent or sibling instance …; nothing was
|
|
7403
|
+
spawned`.
|
|
6994
7404
|
|
|
6995
7405
|
Routed with `--server <id>`, the verb runs on the host
|
|
6996
7406
|
([Routed reads and plans](#routed-reads-and-plans)) and `spawn --server …
|
|
6997
|
-
--
|
|
6998
|
-
`instance-
|
|
6999
|
-
|
|
7000
|
-
|
|
7001
|
-
|
|
7002
|
-
|
|
7003
|
-
|
|
7407
|
+
--related-work` sends the flag there. A host that advertises
|
|
7408
|
+
`instance-related-work` is sent the new spellings, the aliases included. A
|
|
7409
|
+
host that advertises only `instance-same-work` (an older OATS), and only
|
|
7410
|
+
that host, is asked by the old spellings when the binding is a parent:
|
|
7411
|
+
`--same-work` and `oats instance same-work`, its answer's `sameWork`
|
|
7412
|
+
returned with `relatedWork` beside it. The binding
|
|
7413
|
+
is read from the spawn's arguments and the host's own roster (the anchor's
|
|
7414
|
+
row for `--relation sibling|parent`, the instance's row for `on`). A sibling
|
|
7415
|
+
binding is refused there with `E_REMOTE_INCOMPATIBLE`, naming the host and
|
|
7416
|
+
the feature it lacks, and nothing is sent; it is never dropped. A host that
|
|
7417
|
+
advertises neither feature is refused with `E_REMOTE_INCOMPATIBLE` for
|
|
7418
|
+
either, and nothing is sent.
|
|
7419
|
+
|
|
7420
|
+
Where it is read: `relatedWork` (and `sameWork` beside it for a parent
|
|
7421
|
+
binding) on [status rows](#row-related-work) and on [remote roster
|
|
7422
|
+
rows](#the-remote-roster-oats-server-roster---json) (only `true` is
|
|
7423
|
+
relayed).
|
|
7004
7424
|
|
|
7005
7425
|
## Sessions and launch configurations
|
|
7006
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
|
+
|
|
7007
7598
|
### Input
|
|
7008
7599
|
|
|
7009
7600
|
```text
|
|
@@ -7012,7 +7603,8 @@ oats session input --home <abs> [--text-file <path>] --json
|
|
|
7012
7603
|
|
|
7013
7604
|
Input bytes come from stdin or the named file. The existing version-1 success
|
|
7014
7605
|
answer is `{schemaVersion: 1, ok: true, result: {home, backend: "tmux",
|
|
7015
|
-
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
|
|
7016
7608
|
on the execution host, including when the wake broker invokes it there;
|
|
7017
7609
|
`--server` is not supported for input. The adapter sends one literal
|
|
7018
7610
|
bracketed paste and one Enter after the existing input/authority/target checks.
|
|
@@ -7051,7 +7643,7 @@ harness receipt. See [execution targets](execution-targets.md).
|
|
|
7051
7643
|
oats session start --home <abs> [--launch-config <name>|none] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--server <id>] --json
|
|
7052
7644
|
oats session start --resume --home <abs> --json
|
|
7053
7645
|
oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --json
|
|
7054
|
-
oats session resume [--deployment <dir>] [--plan] --json
|
|
7646
|
+
oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json
|
|
7055
7647
|
```
|
|
7056
7648
|
|
|
7057
7649
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
@@ -7219,7 +7811,7 @@ answer is the ordinary start answer plus one object:
|
|
|
7219
7811
|
|
|
7220
7812
|
### The machine sweep (`oats session resume`)
|
|
7221
7813
|
|
|
7222
|
-
`oats session resume [--deployment <dir>] [--plan] --json` (feature
|
|
7814
|
+
`oats session resume [--deployment <dir>] [--plan [--without-provider-inspect]] --json` (feature
|
|
7223
7815
|
`session-resume`, OATS 0.69) starts with `--resume` every home of this
|
|
7224
7816
|
machine's deployments whose session was lost. A client runs it once when it
|
|
7225
7817
|
opens. It reads this computer's list of deployments without writing it
|