@awebai/oats 0.69.22 → 0.69.23
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 +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +60 -17
- package/docs/implementation.md +1 -1
- 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 +117 -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 +5 -5
- 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/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +4 -3
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/deployment-data.mjs +4 -2
- package/packages/client/deployment-panel.mjs +2 -1
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +4 -3
- package/packages/client/workspace-cli.mjs +13 -2
- 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
|
@@ -91,6 +91,9 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
91
91
|
--stdio`, which the reader's hello repeats. Start a reader only where the
|
|
92
92
|
probe lists both the feature and `readerApi: 1`
|
|
93
93
|
([The warm reader](#the-warm-reader)).
|
|
94
|
+
- `boardApi` (feature `instance-board`) is the version of the agent's board:
|
|
95
|
+
the `board` on the rows, `inspect --board` and the board commands' answers
|
|
96
|
+
([The agent's board](#the-agents-board-oats-instance-board)).
|
|
94
97
|
- In text mode the command prints `@awebai/oats <version> (desktop API v1)`.
|
|
95
98
|
|
|
96
99
|
### Features
|
|
@@ -167,7 +170,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
167
170
|
| `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
171
|
| `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
172
|
| `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-
|
|
173
|
+
| `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`) | |
|
|
174
|
+
| <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
175
|
| `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
176
|
| `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
177
|
| `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,6 +187,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
183
187
|
| `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
188
|
| `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
189
|
| `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
|
+
| `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
191
|
| `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)) |
|
|
187
192
|
|
|
188
193
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
@@ -322,17 +327,21 @@ for `--no-recursive`) is never ignored.
|
|
|
322
327
|
| Command | Arguments | Flags that take a value | Switches | Refused in their own words | Its own answers |
|
|
323
328
|
|---|---|---|---|---|---|
|
|
324
329
|
| `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 |
|
|
330
|
+
| `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
331
|
| `oats sync` | none | `--dir` | `--plan`, `--json` | `--approve` | none |
|
|
327
332
|
| `oats instance stop` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--grace-ms`, `--home`, `--dir`, `--server` | `--plan`, `--apply`, `--no-recursive`, `--json` | none | none |
|
|
328
333
|
| `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
|
|
329
334
|
| `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
|
|
330
335
|
| `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
331
336
|
| `oats instance pin` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
337
|
+
| `oats instance related-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
332
338
|
| `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
|
|
333
339
|
| `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
|
|
334
340
|
| `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
|
|
335
341
|
| `oats instance attention` | none | `--message` | `--clear`, `--json` | `--home`, `--dir`, `--producer`, `--reason` | none |
|
|
342
|
+
| `oats instance board set` | `<key>` | `--label`, `--value`, `--unit`, `--link` | `--json` | `--home`, `--dir`, `--server` | none |
|
|
343
|
+
| `oats instance board unset` | `<key>` | none | `--json` | `--home`, `--dir`, `--server` | none |
|
|
344
|
+
| `oats instance board ask` | `[<question>]` | `--option`, `--id`, `--context-file`, `--clear` | `--json` | `--home`, `--dir`, `--server` | none |
|
|
336
345
|
| `oats instance suggest-name` | none | `--soul`, `--task`, `--task-file`, `--harness`, `--model`, `--launch-config`, `--dir` | `--json` | `--server` | none |
|
|
337
346
|
| `oats worktree add` | none | `--purpose`, `--branch`, `--base`, `--repo` | `--preview`, `--json` | `--server`, `--dir`, `--home` | none |
|
|
338
347
|
| `oats worktree remove` | none | `--purpose` | `--json` | `--server`, `--dir`, `--home` | none |
|
|
@@ -631,7 +640,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
631
640
|
### `oats inspect`
|
|
632
641
|
|
|
633
642
|
```text
|
|
634
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
643
|
+
oats inspect (--home <abs> [--board] | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
635
644
|
```
|
|
636
645
|
|
|
637
646
|
An instance subject, abridged:
|
|
@@ -673,7 +682,7 @@ An instance subject, abridged:
|
|
|
673
682
|
| `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
|
|
674
683
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
675
684
|
| `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)) |
|
|
685
|
+
| `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
686
|
| `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
687
|
| `problems` | below |
|
|
679
688
|
| `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
|
|
@@ -1001,6 +1010,15 @@ oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--
|
|
|
1001
1010
|
at the top level; `stderr` appears when the provider wrote any.
|
|
1002
1011
|
- A `view` operation must answer `{documents: [{label, kind?, path?, text?}]}`
|
|
1003
1012
|
(`kind` `markdown` or `text`), else `E_OPERATION_RESULT`.
|
|
1013
|
+
- **A view may carry one structured field** beside `documents`, named after
|
|
1014
|
+
its operation and versioned by its own `<name>Api` inside it: `mail` with
|
|
1015
|
+
`mailApi` for `messaging:mail` ([Mail](#mail-mailapi-1)). `documents` stays
|
|
1016
|
+
the plain rendering every view reader can show. The kernel validates
|
|
1017
|
+
`documents` only, and relays the provider's `result` unchanged, locally and
|
|
1018
|
+
through `--server`, where the routing keys (`server`, `route`) sit beside
|
|
1019
|
+
`result`, never inside it. A client reads the structured field only at a
|
|
1020
|
+
`<name>Api` it knows, and falls back to `documents` otherwise. A view carries
|
|
1021
|
+
at most one such field.
|
|
1004
1022
|
- Errors: `E_OPERATION_UNKNOWN`, `E_OPERATION_UNAVAILABLE` (empty slot, or a
|
|
1005
1023
|
home operation without `--home`), `E_CAPABILITY_REQUIRES`, `E_BAD_ARGS`
|
|
1006
1024
|
(undeclared or missing `--arg`), `E_CAPABILITY_BROKEN`. A provider's `ok:
|
|
@@ -1019,6 +1037,119 @@ advertises `operations`.
|
|
|
1019
1037
|
inspect; the provider's version owns their result shapes. For oats.okf, see
|
|
1020
1038
|
[knowledge.md](knowledge.md#knowledge-operations).
|
|
1021
1039
|
|
|
1040
|
+
**Messaging operations.** The messaging provider's operations are listed by
|
|
1041
|
+
inspect too. One of them is a contract of the messaging layer, whatever the
|
|
1042
|
+
provider: `messaging:mail`, below. oats.aweb is its first provider, from the
|
|
1043
|
+
release that adds it (its `docs/mail-read.md` says how it reads).
|
|
1044
|
+
|
|
1045
|
+
<a id="mail-mailapi-1"></a>
|
|
1046
|
+
#### Mail, `mailApi: 1`
|
|
1047
|
+
|
|
1048
|
+
`messaging:mail` is a read-only view of an instance's own mail, received and
|
|
1049
|
+
sent, newest first. It **never acknowledges** or marks anything read on the
|
|
1050
|
+
agent's behalf. Any messaging provider may answer it.
|
|
1051
|
+
|
|
1052
|
+
```text
|
|
1053
|
+
oats operation run messaging:mail --home <abs> [--arg limit=50] [--arg cursor=<nextCursor>] [--arg conversation=<id>] [--server <id>] --json
|
|
1054
|
+
```
|
|
1055
|
+
|
|
1056
|
+
The provider's manifest declares it as a home view operation with three
|
|
1057
|
+
optional args:
|
|
1058
|
+
|
|
1059
|
+
```json
|
|
1060
|
+
"mail": {"kind": "view", "command": "mail", "context": "home",
|
|
1061
|
+
"description": "Read-only: this instance's mail, received and sent, newest first. Never acknowledges.",
|
|
1062
|
+
"args": [{"name": "limit", "flag": "--limit"}, {"name": "cursor", "flag": "--cursor"}, {"name": "conversation", "flag": "--conversation"}]}
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
Its `result`:
|
|
1066
|
+
|
|
1067
|
+
```json
|
|
1068
|
+
{"documents":[{"label":"Mail","kind":"markdown","text":"…plain rendering…"}],
|
|
1069
|
+
"mail":{"mailApi":1,"acknowledges":false,"observedAt":"2026-11-19T12:00:00.000Z",
|
|
1070
|
+
"identities":[{"team":"oats","alias":"dev-1","identity":"<opaque>","primary":true,"error":null},
|
|
1071
|
+
{"team":"alpha","alias":"dev-1","identity":"<opaque>","primary":false,"error":"conversation-unreadable",
|
|
1072
|
+
"unreadableConversations":["<opaque>"]}],
|
|
1073
|
+
"messages":[{"id":"<opaque>","conversationId":"<opaque>","threadTitle":"Review","direction":"received","team":"oats",
|
|
1074
|
+
"from":{"alias":"lead","address":"oats.aweb.ai/lead","identity":"<opaque>"},
|
|
1075
|
+
"to":{"alias":"dev-1","address":"oats.aweb.ai/dev-1","identity":"<opaque>"},
|
|
1076
|
+
"subject":"Review","body":"…","truncated":false,"createdAt":"2026-11-19T11:58:00Z",
|
|
1077
|
+
"readByAgent":false,"encrypted":false,"verification":"verified","priority":"normal"}],
|
|
1078
|
+
"conversations":[{"id":"<opaque>","partial":null}],
|
|
1079
|
+
"hasMore":false,"nextCursor":null}}
|
|
1080
|
+
```
|
|
1081
|
+
|
|
1082
|
+
- **Opaque values.** `identity` ids, message and conversation ids, `team`
|
|
1083
|
+
labels and `nextCursor` are the provider's strings: a client compares them
|
|
1084
|
+
and passes them back, and never parses them. `from`/`to` `address` may be
|
|
1085
|
+
`null`; `conversationId` is `null` for mail with no conversation.
|
|
1086
|
+
- **Order.** Newest first by `createdAt`, across every identity of the
|
|
1087
|
+
instance (its primary one and each joined team's), merged, each message
|
|
1088
|
+
labelled by the `team` it was read in. `direction` is decided by the
|
|
1089
|
+
sender's identity against the identity read. `identities` lists each
|
|
1090
|
+
identity read, the primary one first.
|
|
1091
|
+
- **Read state.** `readByAgent` reports the server's read state of a received
|
|
1092
|
+
message, and is `true` for a sent one. The read never changes it, and
|
|
1093
|
+
`acknowledges` is always `false`.
|
|
1094
|
+
- **Closed sets.** `direction`: `received` or `sent`. `verification`:
|
|
1095
|
+
`verified`, `unverified`, `failed` or `unknown`. `priority`: `normal`,
|
|
1096
|
+
`high` or `unknown`. `partial`: `null` or `oldest-first-only`. A client
|
|
1097
|
+
shows any other value as unknown.
|
|
1098
|
+
- **Bounds.** Each `body` is at most 16 KiB of UTF-8, cut at a character
|
|
1099
|
+
boundary, with `truncated: true`. The whole `result` is at most 256 KiB;
|
|
1100
|
+
past it the answer stops early, with `hasMore: true` and a `nextCursor`.
|
|
1101
|
+
Where one message alone wouldn't fit, its `subject` and `threadTitle` are
|
|
1102
|
+
cut too, and `truncated: true` marks that as well: `truncated` means the
|
|
1103
|
+
provider shortened the message, whichever of its texts it cut. An answer
|
|
1104
|
+
is never sent oversized, nor as an empty page with `hasMore: true` and no
|
|
1105
|
+
`nextCursor`. `limit` is 1 to 200, default 50 (`E_BAD_ARGS` otherwise).
|
|
1106
|
+
- **Paging.** `nextCursor`, passed back as `--arg cursor=…`, gives the next
|
|
1107
|
+
messages in the same order, with no overlap. What a cursor encodes is the
|
|
1108
|
+
provider's (oats.aweb's: the last message's `createdAt`, id and team). `--arg conversation=<id>`
|
|
1109
|
+
reads one conversation, newest first; its cursor is valid only with the same
|
|
1110
|
+
conversation.
|
|
1111
|
+
- **Partial conversations.** Where the provider can read only the oldest part
|
|
1112
|
+
of a long conversation, the conversation is listed in `conversations` with
|
|
1113
|
+
`partial: "oldest-first-only"`, and its newest messages are missing, never
|
|
1114
|
+
shown as the latest. A client says "older part of a long conversation
|
|
1115
|
+
shown; the newest messages can't be read yet".
|
|
1116
|
+
- **Untrusted text.** `subject`, `threadTitle` and `body` are the sender's
|
|
1117
|
+
plain text: show them as text, attributed to their sender, never as markup.
|
|
1118
|
+
- **Encrypted mail.** End-to-end encrypted bodies are decrypted with the
|
|
1119
|
+
agent's keys, and shown to whoever can run `oats operation run` on that
|
|
1120
|
+
machine (routed reads included): the access that attaching to the agent's
|
|
1121
|
+
terminal already gives, no wider. `encrypted: true` marks them.
|
|
1122
|
+
- **Errors per identity.** In `identities[].error`, a provider's code (such
|
|
1123
|
+
as a grant without mail read). **An identity's `error` doesn't mean it has
|
|
1124
|
+
no messages:** it can come with that identity's messages beside it, and a
|
|
1125
|
+
reader shows both the mail and that some of it couldn't be read. One code
|
|
1126
|
+
is the layer's: `conversation-unreadable`, one or more of that identity's
|
|
1127
|
+
conversations couldn't be read; its other messages are shown, and the row
|
|
1128
|
+
names the missing ones in `unreadableConversations` (conversation ids,
|
|
1129
|
+
present only with that code, the list's tail dropped first if the 256 KiB
|
|
1130
|
+
bound needs it, so it may name fewer than failed, or none).
|
|
1131
|
+
- **Whole failures.** The operation fails whole, with no answer, in two
|
|
1132
|
+
cases: `E_MAIL_UNREADABLE` when no identity can be read
|
|
1133
|
+
(`details.identities` holds the rows), and `E_MAIL_TOO_LARGE` when even an
|
|
1134
|
+
answer with no messages can't fit the 256 KiB bound (its identities alone).
|
|
1135
|
+
- **Cost.** Each read calls the messaging service several times. Read on
|
|
1136
|
+
demand (opening a view, a manual refresh), never on a status poll.
|
|
1137
|
+
- **Older sides.** A home whose provider copy predates the operation answers
|
|
1138
|
+
`E_OPERATION_UNKNOWN` (inspect doesn't list `mail`): the home gets it from
|
|
1139
|
+
`oats instance upgrade` or a new spawn. A home with no messaging slot
|
|
1140
|
+
answers `E_OPERATION_UNAVAILABLE`, and a remote host without `operations`
|
|
1141
|
+
`E_REMOTE_INCOMPATIBLE`. A provider's own refusals are relayed with their
|
|
1142
|
+
code, such as oats.aweb's `E_AW_TOO_OLD` (`details: {version, needs}`) for
|
|
1143
|
+
an aw too old to read mail without acknowledging it.
|
|
1144
|
+
- **The provider's own.** How a provider maps its service's values onto the
|
|
1145
|
+
closed sets, its other identity error codes, what its cursor encodes and how
|
|
1146
|
+
much of a body its `documents` rendering shows are its own, in its docs. For
|
|
1147
|
+
oats.aweb: the "messaging:mail" section of its
|
|
1148
|
+
[README](https://github.com/awebai/oats-aweb/blob/main/README.md#messagingmail-an-instances-mail-read-without-acknowledging-it)
|
|
1149
|
+
and its [docs/mail-read.md](https://github.com/awebai/oats-aweb/blob/main/docs/mail-read.md)
|
|
1150
|
+
(the aw commands it runs, the verification and priority mappings, the
|
|
1151
|
+
cursor, every error code, a 500-character body excerpt in `documents`).
|
|
1152
|
+
|
|
1022
1153
|
<a id="workspace-model-workspaceapi-2"></a>
|
|
1023
1154
|
## Workspace
|
|
1024
1155
|
|
|
@@ -3336,7 +3467,7 @@ kernel stage raised as well.
|
|
|
3336
3467
|
|
|
3337
3468
|
| Code | Details | When |
|
|
3338
3469
|
|---|---|---|
|
|
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 ([
|
|
3470
|
+
| `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
3471
|
| `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
|
|
3341
3472
|
| `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
3473
|
| `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
|
|
@@ -3768,15 +3899,31 @@ its absence.
|
|
|
3768
3899
|
the home holds a valid pin ([Pinned instances](#pinned-instances-oats-instance-pin)),
|
|
3769
3900
|
absent otherwise; never `false`. A `pinned` in `instance.json` never
|
|
3770
3901
|
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
|
-
|
|
3902
|
+
- <a id="row-board"></a>**`board`** (feature `instance-board`): the agent's
|
|
3903
|
+
board, `{facts: [{key, label, value, unit, link, at}], questions: [{id,
|
|
3904
|
+
question, options, hasContext, since}]}`, or `null` for a home with no board
|
|
3905
|
+
file (or one whose directory can't be read) ([The agent's board](#the-agents-board-oats-instance-board)). Facts come
|
|
3906
|
+
in the order first set, questions in the order asked, and only the questions
|
|
3907
|
+
of the instance's current session. A file that can't be read as a board is an
|
|
3908
|
+
empty board, never an error. The value is at most 8 KiB as UTF-8 JSON on every
|
|
3909
|
+
row. It carries no history and no context: `oats inspect --home <h> --board`
|
|
3910
|
+
does. A `board` in `instance.json` never stands in for it, and an older
|
|
3911
|
+
kernel's rows have no key.
|
|
3912
|
+
- <a id="row-related-work"></a><a id="row-same-work"></a>**`relatedWork`**
|
|
3913
|
+
(feature `instance-related-work`): `true` when the home's related-work
|
|
3914
|
+
flag ([Related work](#related-work-oats-instance-related-work)) is bound
|
|
3915
|
+
to the parent the row's `parentInstance` names, or, on a row with no
|
|
3916
|
+
`parentInstance`, to the sibling its `siblingInstance` names. Otherwise
|
|
3917
|
+
the key is absent, never `false` or `null`: no flag, a flag bound to an
|
|
3918
|
+
earlier relation, neither relation, and a row whose `instance.json`
|
|
3919
|
+
cannot be read. A `relatedWork` or `sameWork` in `instance.json` never
|
|
3920
|
+
stands in for it. **`sameWork`** (feature `instance-same-work`), the
|
|
3921
|
+
flag's old name, stands beside it as `true` when the binding is to the
|
|
3922
|
+
parent, for a client that reads the old key; it is absent for a sibling
|
|
3923
|
+
binding and whenever `relatedWork` is, never `false` or `null`.
|
|
3924
|
+
Clients draw the line between the row and the instance it is bound to; a
|
|
3925
|
+
client that does not know the key ignores it, and an older kernel never
|
|
3926
|
+
sends it.
|
|
3780
3927
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3781
3928
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3782
3929
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -4050,11 +4197,21 @@ route target:
|
|
|
4050
4197
|
has exactly `pinned: true`; any other value (`"true"`, `1`), a host whose
|
|
4051
4198
|
kernel predates the feature and a saved route the host did not list carry
|
|
4052
4199
|
none ([`pinned`](#row-pinned)).
|
|
4053
|
-
- **`
|
|
4054
|
-
|
|
4055
|
-
|
|
4056
|
-
|
|
4057
|
-
|
|
4200
|
+
- **`board`** (feature `instance-board`) is on a row only when the host's row
|
|
4201
|
+
has the key. It is read by this kernel's own rules: each fact and question
|
|
4202
|
+
within its bounds and the whole within 8 KiB, or else an empty board.
|
|
4203
|
+
`null` stays `null` ([`board`](#row-board)).
|
|
4204
|
+
- **`relatedWork`** (feature `instance-related-work`) is on a row only when
|
|
4205
|
+
the host's row has `relatedWork: true`, and is then `true`. From a host
|
|
4206
|
+
whose features list `instance-same-work` and not `instance-related-work`
|
|
4207
|
+
(an older OATS), its row's `sameWork: true` is relayed as `relatedWork:
|
|
4208
|
+
true`. Any other value, a host whose kernel predates both features, and a
|
|
4209
|
+
saved route the host did not list carry no key
|
|
4210
|
+
([`relatedWork`](#row-related-work)). `sameWork: true` is relayed beside
|
|
4211
|
+
`relatedWork: true` when the host's row says it (a parent binding), and
|
|
4212
|
+
never on its own. `oats status --server <id> --json` relays the host's
|
|
4213
|
+
answer as it gave it, except for these two keys: each instance row carries
|
|
4214
|
+
them by the same rule (an older host's `sameWork: true` as both).
|
|
4058
4215
|
- **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
|
|
4059
4216
|
when the host's row has the key, with the host's value: a host whose kernel
|
|
4060
4217
|
predates the feature, a row the host reports without it (one that runs,
|
|
@@ -4299,7 +4456,7 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
4299
4456
|
| `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
|
|
4300
4457
|
| `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
|
|
4301
4458
|
| `oats instance pin <name> on\|off --server <id>` | none | `instance-pin` |
|
|
4302
|
-
| `oats instance
|
|
4459
|
+
| `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
4460
|
|
|
4304
4461
|
- The flags are the local command's. The instance is addressed like every
|
|
4305
4462
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -4850,7 +5007,13 @@ oats instance attention [--message=<text>] [--clear] --json
|
|
|
4850
5007
|
|
|
4851
5008
|
- **The row.** A claim is a `waiting` event, `data: {waitingOnYou: true,
|
|
4852
5009
|
reason, message?}` or `{waitingOnYou: false}`, appended to both logs, with
|
|
4853
|
-
`producer` the caller's `--producer`.
|
|
5010
|
+
`producer` the caller's `--producer`. The board's claim (producer
|
|
5011
|
+
`oats.board`, [The agent's board](#the-agents-board-oats-instance-board))
|
|
5012
|
+
also carries `session`, the id of the session it was set in. A row with a
|
|
5013
|
+
`session` counts only while that is still the current session, and only
|
|
5014
|
+
where the read proves it: a session boundary is in the rows read, or the
|
|
5015
|
+
log was read whole (not cut to its last 4 MiB). No verb sets one; a row
|
|
5016
|
+
without `session` counts as before.
|
|
4854
5017
|
- **`waiting`.** `--producer` matches `^[a-z0-9][a-z0-9._/-]{0,63}$` and is
|
|
4855
5018
|
not `kernel`. `set` needs `--reason`, one of `permission`, `question`,
|
|
4856
5019
|
`attention` (closed). `clear` refuses `--reason` and `--message`. The home
|
|
@@ -6920,87 +7083,268 @@ when the host's row says exactly `true`), and on `oats inspect --home` as
|
|
|
6920
7083
|
`instance.pinned`. Each is absent when not pinned. A client reads `pinned`
|
|
6921
7084
|
only where the probe lists `instance-pin`.
|
|
6922
7085
|
|
|
6923
|
-
##
|
|
7086
|
+
## The agent's board (`oats instance board`)
|
|
6924
7087
|
|
|
6925
|
-
Feature `instance-
|
|
7088
|
+
Feature `instance-board`, `boardApi: 1`.
|
|
6926
7089
|
|
|
6927
7090
|
```text
|
|
6928
|
-
oats instance
|
|
6929
|
-
oats
|
|
7091
|
+
oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
|
|
7092
|
+
oats instance board unset <key> [--json]
|
|
7093
|
+
oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
|
|
7094
|
+
oats instance board ask --clear <id> [--json]
|
|
6930
7095
|
```
|
|
6931
7096
|
|
|
6932
|
-
The
|
|
6933
|
-
|
|
6934
|
-
|
|
6935
|
-
|
|
7097
|
+
The board is what an agent tells its person outside its terminal: the
|
|
7098
|
+
**facts** it keeps in view (the PR, the best score, the branch) and the
|
|
7099
|
+
**questions** it needs them to answer, each with 2 to 4 options. A client
|
|
7100
|
+
shows them in the agent's view, above and below the agent's own terminal.
|
|
7101
|
+
The agent reports them, and the kernel infers nothing: it never reads a
|
|
7102
|
+
transcript, and it routes no answer. The word "pin" is never used for facts:
|
|
7103
|
+
[`oats instance pin`](#pinned-instances-oats-instance-pin) pins an instance at
|
|
7104
|
+
the top of the list, which is something else.
|
|
7105
|
+
|
|
7106
|
+
- **Who writes it.** Only the agent, from its own session, as `oats instance
|
|
7107
|
+
attention` does: the home is `$OATS_INSTANCE_HOME`. `--home`, `--dir` and
|
|
7108
|
+
`--server` are refused (`E_BAD_ARGS`), and outside an instance home every
|
|
7109
|
+
form is `E_USAGE`.
|
|
7110
|
+
- **`set`** upserts the fact `<key>`. At most 12 keys: one more is
|
|
7111
|
+
`E_BOARD_FULL`. A set with every field the same changes nothing and writes
|
|
7112
|
+
nothing. The kernel keeps a key's last 20 values with their times (a new
|
|
7113
|
+
value joins it; a new label alone doesn't). `at` is when the fact last
|
|
7114
|
+
changed. **`unset`** removes the key and its history.
|
|
7115
|
+
- **`ask`** opens a question. Its id is `--id`, or `q<n>` by default. `n` is
|
|
7116
|
+
counted per home and never reused while the home lives, so a late answer
|
|
7117
|
+
can't land on a newer question (past `q999999999999999` no default id is
|
|
7118
|
+
left: `E_BOARD_FULL`, ask with `--id`). At most 9 open at once: one more is
|
|
7119
|
+
`E_BOARD_FULL`. Asking a question that is open with the same text, options
|
|
7120
|
+
and context again changes nothing and answers its id, with or without
|
|
7121
|
+
`--id`, so a retry is safe. Anything else under an open id is
|
|
7122
|
+
`E_BAD_ARGS`. **`ask --clear <id>`** closes the
|
|
7123
|
+
question, which the agent does once it has read the answer. Clearing an id
|
|
7124
|
+
that isn't open changes nothing.
|
|
7125
|
+
- **Text.** Key and id match `^[a-z0-9][a-z0-9-]{0,15}$`. Label, value,
|
|
7126
|
+
unit, option and question are one line each, of at most 40, 80, 16, 60
|
|
7127
|
+
and 200 code points, with none of the characters a
|
|
7128
|
+
[waiting message](#waiting-on-you) refuses. A link is an absolute `https:`
|
|
7129
|
+
URL of at most 512 printable ASCII characters. The context comes from a
|
|
7130
|
+
UTF-8 file (`--context-file`), at most 2000 code points once its trailing
|
|
7131
|
+
newlines are trimmed (a file's final newline, such as a heredoc's, isn't
|
|
7132
|
+
content). Newlines (LF) are allowed in it, and every other refused
|
|
7133
|
+
character is not. Anything else is `E_BAD_ARGS`.
|
|
7134
|
+
- **The row bound.** A write that would make the row's `board` larger than
|
|
7135
|
+
8 KiB as UTF-8 JSON is `E_BOARD_FULL`, with `details.bytes` and
|
|
7136
|
+
`details.max`. Every client can rely on that bound for every row. A
|
|
7137
|
+
refused write writes nothing.
|
|
7138
|
+
- **Per session.** A question records the session it was asked in: the
|
|
7139
|
+
instance's latest kernel session boundary (`launched`, `restarted`,
|
|
7140
|
+
`stopped`: the [waiting claim's rule](#waiting-on-you)). It is live only
|
|
7141
|
+
while that is still the current session. Once a later boundary is written,
|
|
7142
|
+
no row shows it, and the next write drops it. Where the events log's bounded
|
|
7143
|
+
read (its last 4 MiB) holds no boundary, the current session can't be
|
|
7144
|
+
proved: no question is live, and `ask` is `E_BOARD_FAILED` until the next
|
|
7145
|
+
boundary. Facts persist across sessions until they are unset or the home is
|
|
7146
|
+
retired.
|
|
7147
|
+
|
|
7148
|
+
**The needs-input claim.** While any question is open, the home holds the
|
|
7149
|
+
[waiting claim](#waiting-on-you) of producer `oats.board`, reason
|
|
7150
|
+
`attention`. Its message is the oldest open question. The last `--clear`
|
|
7151
|
+
removes it. The claim's row records the session the write read
|
|
7152
|
+
(`session`), and counts only in that session, so a boundary written while a
|
|
7153
|
+
board write runs ends the claim with the question. Reason `attention` holds no scheduled wake
|
|
7154
|
+
([A held wake](schedules.md#a-held-wake)): a board question leaves the
|
|
7155
|
+
harness at its normal input line. The claim is a producer of its own, so the
|
|
7156
|
+
agent's own `attention` claim can be live beside it, and `waitingOnYou`
|
|
7157
|
+
picks between them by its usual rule. Every board write sets the claim to
|
|
7158
|
+
what the questions say after it. A write whose claim fails is
|
|
7159
|
+
`E_EVENTS_FAILED` after the board was written, with `details.id` (or
|
|
7160
|
+
`details.key`) naming what was written. Running the same command again
|
|
7161
|
+
changes nothing on the board and repairs the claim.
|
|
7162
|
+
|
|
7163
|
+
**How a person answers.** The kernel routes no answer. A client types it as
|
|
7164
|
+
the person's own keystrokes, in the agent's terminal, as `<id>: <text>`
|
|
7165
|
+
(`q2: Yes, one clean commit`), and the person's Enter sends it. An agent reads
|
|
7166
|
+
an answer by its id, then clears the question.
|
|
7167
|
+
|
|
7168
|
+
**The answer** of every form is `{boardApi, instance, home, key | id,
|
|
7169
|
+
changed, board}`, where `board` is the row's value after the write
|
|
7170
|
+
(`null` when the home has no board file and nothing was written):
|
|
7171
|
+
|
|
7172
|
+
```json
|
|
7173
|
+
{"boardApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","id":"q2","changed":true,
|
|
7174
|
+
"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"}],
|
|
7175
|
+
"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"}]}}
|
|
7176
|
+
```
|
|
7177
|
+
|
|
7178
|
+
The text answer is one line: `<instance>: fact <key> set` (or `unchanged`,
|
|
7179
|
+
`removed`, `was not set`), or `<instance>: question <id> asked: answers
|
|
7180
|
+
arrive typed as "<id>: <text>"` (or `cleared`, `was not open`).
|
|
7181
|
+
|
|
7182
|
+
| Code | When |
|
|
7183
|
+
|---|---|
|
|
7184
|
+
| `E_USAGE` | Not in an instance session: `$OATS_INSTANCE_HOME` unset, not absolute, or not an instance home under its agents root |
|
|
7185
|
+
| `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 |
|
|
7186
|
+
| `E_BOARD_FULL` | A 13th fact, a 10th open question, a row over 8 KiB, or no default id left; nothing was changed |
|
|
7187
|
+
| `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` |
|
|
7188
|
+
| `E_BOARD_BUSY` | Another process holds the board's lock past 5 seconds (`details.lock`); nothing was changed |
|
|
7189
|
+
| `E_EVENTS_FAILED` | The board was written (`details.id` or `details.key`), but its claim was not: run the same command again |
|
|
7190
|
+
|
|
7191
|
+
**Where it is read.** [`board` on status rows](#row-board), relayed on
|
|
7192
|
+
[remote roster rows](#the-remote-roster-oats-server-roster---json), and with
|
|
7193
|
+
history and context on `oats inspect --home <h> --board` as
|
|
7194
|
+
`instance.board`: each fact gains `history: [{value, at}]` (oldest first, its
|
|
7195
|
+
current value last) and each question `context` (the text, or `null`). Read
|
|
7196
|
+
it when a view is open, not on every poll. Agent text is untrusted: a client
|
|
7197
|
+
shows it as the agent's attributed words, plain text only, and opens a link
|
|
7198
|
+
only on the person's press, outside the app's window.
|
|
7199
|
+
|
|
7200
|
+
**Storage.** `<home>/.oats-board.json`, mode 0600, written atomically under
|
|
7201
|
+
the lock `<home>/.oats-board.lock`, so parallel writes of one agent lose
|
|
7202
|
+
none. The format is the kernel's own, not part of this contract. A reader
|
|
7203
|
+
takes a regular file of at most 256 KiB, without following a link. A file
|
|
7204
|
+
that isn't a valid board in every part reads as an empty board,
|
|
7205
|
+
`{facts: [], questions: []}`, never as an error. Both names are kernel-owned
|
|
7206
|
+
home files: a capability cannot declare them, and a retire counts neither as
|
|
7207
|
+
work. A start, restart or upgrade keeps them, and a retire removes them with
|
|
7208
|
+
the home.
|
|
7209
|
+
|
|
7210
|
+
## Related work (`oats instance related-work`)
|
|
7211
|
+
|
|
7212
|
+
<a id="same-work-as-the-parent-oats-instance-same-work"></a>
|
|
7213
|
+
Feature `instance-related-work`. It renames `instance-same-work`
|
|
7214
|
+
(awebai/oats#1577), which the kernel still advertises beside it for the
|
|
7215
|
+
[deprecated aliases](#the-deprecated-aliases) and the old row field.
|
|
7216
|
+
|
|
7217
|
+
```text
|
|
7218
|
+
oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]
|
|
7219
|
+
oats spawn <soul> … --related-work
|
|
7220
|
+
```
|
|
6936
7221
|
|
|
6937
|
-
|
|
6938
|
-
|
|
6939
|
-
|
|
6940
|
-
|
|
6941
|
-
|
|
7222
|
+
The flag records that an instance does related work with the instance it is
|
|
7223
|
+
bound to: its parent, or, when it has no parent, its sibling. Clients draw a
|
|
7224
|
+
line between the two for an instance that carries it. Nothing else in the
|
|
7225
|
+
kernel reads it: it is not identity, it grants nothing and it never
|
|
7226
|
+
addresses anything. The kernel never sets it on its own, for any relation:
|
|
7227
|
+
only `--related-work` and `on` do.
|
|
7228
|
+
|
|
7229
|
+
- **The binding.** The flag binds the home's recorded `parentInstance` when
|
|
7230
|
+
it has one, else its recorded `siblingInstance`. With neither, it cannot
|
|
7231
|
+
be set. A sibling binding names the sibling the home records. For a
|
|
7232
|
+
sibling of a top-level instance R, that is R. For a sibling of R's
|
|
7233
|
+
sibling S, the home records S, the anchor it was spawned beside, so the
|
|
7234
|
+
binding is to S, not R.
|
|
7235
|
+
- **The record** is `<home>/.oats-related-work.json`, either
|
|
7236
|
+
`{"relatedWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}` or
|
|
7237
|
+
`{"relatedWorkApi": 1, "sibling": "<instance>", "at": "<ISO time>"}`,
|
|
7238
|
+
exactly one of `parent` and `sibling`, mode 0600, written atomically.
|
|
7239
|
+
Present means on; `off` removes it. It is a kernel-owned home file: a
|
|
7240
|
+
capability cannot declare it as its own, a retire does not count it as
|
|
7241
|
+
work (on its own it never makes a recovery copy), and `oats instance
|
|
6942
7242
|
upgrade` does not see it as a change to the home.
|
|
6943
7243
|
- **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
|
-
|
|
7244
|
+
most 4 KiB, holding JSON with `relatedWorkApi: 1` and exactly one of a
|
|
7245
|
+
non-empty string `parent` and `sibling`. Anything else reads as off, never
|
|
7246
|
+
as an error.
|
|
7247
|
+
- **Bound to the relation.** A parent binding is on only while its `parent`
|
|
7248
|
+
is the home's current recorded `parentInstance`. A sibling binding is on
|
|
7249
|
+
only while the home records no parent and its `sibling` is the current
|
|
7250
|
+
`siblingInstance`. A relink that changes the relation leaves the record
|
|
7251
|
+
naming the old instance, so the flag reads off: a retire's lineage relink
|
|
7252
|
+
(the instances pointing at the retiree re-pointed to its parent, or their
|
|
7253
|
+
sibling link moved to its sibling) and a `--relation parent` spawn
|
|
7254
|
+
re-pointing its anchor. `on` binds it to the current relation again.
|
|
6952
7255
|
- **Lifetime.** It survives `oats session restart`, a stop and a start, a
|
|
6953
7256
|
resume (`oats session start --resume`) and `oats instance upgrade`. Only
|
|
6954
7257
|
`off` and retirement clear it.
|
|
7258
|
+
- **The old flag.** A same-work record, `<home>/.oats-same-work.json`
|
|
7259
|
+
(`{"sameWorkApi": 1, "parent": "<instance>", "at": "<ISO time>"}`), reads
|
|
7260
|
+
as a parent binding while nothing stands at the new record's name, by the
|
|
7261
|
+
same reader rules; so an instance flagged before the rename keeps its
|
|
7262
|
+
flag. When both exist, the new record wins, whatever it holds. The write
|
|
7263
|
+
that creates the new record removes the old one, and `off` removes both.
|
|
7264
|
+
`on` for a binding the old record already holds writes nothing. Both names
|
|
7265
|
+
are kernel-owned.
|
|
7266
|
+
|
|
7267
|
+
<a id="the-deprecated-aliases"></a>
|
|
7268
|
+
**The deprecated aliases.** `oats spawn … --same-work` is `--related-work`,
|
|
7269
|
+
and `oats instance same-work <instance> on|off` is `oats instance
|
|
7270
|
+
related-work`, with the same binding rule (the parent, else the sibling),
|
|
7271
|
+
the same refusals and the same answer; spawnInstance's `sameWork` option is
|
|
7272
|
+
`relatedWork`, and each call with it emits one Node `DeprecationWarning`
|
|
7273
|
+
(code `OATS_SAME_WORK`, `sameWork is renamed: use relatedWork`). Each CLI use prints one line on stderr, before the command runs
|
|
7274
|
+
or is sent with `--server`: `oats: --same-work is renamed: use
|
|
7275
|
+
--related-work`, or `oats: oats instance same-work is renamed: use oats
|
|
7276
|
+
instance related-work`. It is never in the `--json` answer: the envelope is
|
|
7277
|
+
the one the new spelling gives, with no `warnings`. The aliases, the
|
|
7278
|
+
feature `instance-same-work` and the [`sameWork`](#row-related-work) row
|
|
7279
|
+
field stay until their removal is decided on its own, with its own
|
|
7280
|
+
release-notes entry.
|
|
6955
7281
|
|
|
6956
7282
|
**The verb.** The instance is addressed as `oats instance color` addresses
|
|
6957
7283
|
it, and refused with the same answers.
|
|
6958
7284
|
|
|
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
|
-
|
|
7285
|
+
- `on` binds the flag to the instance's recorded `parentInstance`, else to
|
|
7286
|
+
its recorded `siblingInstance`; an instance with neither is refused. `on`
|
|
7287
|
+
again while the flag holds that binding writes nothing; `on` after a
|
|
7288
|
+
relink rebinds it to the current relation.
|
|
7289
|
+
- `off` removes whatever stands at either record's name (a file, a link, a
|
|
7290
|
+
directory). It succeeds whether or not the flag was on and whether or not
|
|
7291
|
+
a relation is recorded; `off` again is the same answer.
|
|
6966
7292
|
|
|
6967
|
-
The answer, the envelope's `result`, has exactly these
|
|
7293
|
+
The answer, the envelope's `result`, has exactly these three keys:
|
|
6968
7294
|
|
|
6969
7295
|
```json
|
|
6970
|
-
{"instance":"dev-a","sameWork":true}
|
|
7296
|
+
{"instance":"dev-a","relatedWork":true,"sameWork":true}
|
|
6971
7297
|
```
|
|
6972
7298
|
|
|
6973
|
-
`
|
|
6974
|
-
`false` after `off`.
|
|
7299
|
+
`relatedWork` is the binding rule read after the write: `true` after `on`,
|
|
7300
|
+
`false` after `off`. `sameWork` is the old verb's answer: `true` only when
|
|
7301
|
+
the flag holds a parent binding, so `false` for a sibling binding. The text
|
|
7302
|
+
answer is `dev-a: related work on` (or `off`).
|
|
6975
7303
|
|
|
6976
7304
|
| Code | When |
|
|
6977
7305
|
|---|---|
|
|
6978
|
-
| `E_BAD_ARGS` | Neither `on` nor `off`, or more than one word; a `--home` that is not absolute; `on` for an instance with
|
|
7306
|
+
| `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
7307
|
| *(as `oats instance color`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
|
|
6980
7308
|
| `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
7309
|
| `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
7310
|
|
|
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
|
-
|
|
7311
|
+
**At spawn.** `oats spawn … --related-work` sets the flag on the new
|
|
7312
|
+
instance. It is bound to the parent the new home records, whichever
|
|
7313
|
+
relation gave it: `--parent <instance>` or `--relation child`; `--relation
|
|
7314
|
+
sibling` of an anchor that has a parent (the new instance shares it);
|
|
7315
|
+
`--relation parent` of an anchor that had a parent (the new instance
|
|
7316
|
+
inherits it); `--work attached` (the owner of the tree). Else it is bound to
|
|
7317
|
+
the sibling the new home records: `--relation sibling` of an anchor with no
|
|
7318
|
+
parent (the anchor itself), and `--relation parent` of an anchor with a
|
|
7319
|
+
sibling link and no parent (the new instance inherits the link). The record
|
|
7320
|
+
is written inside the spawn, before the launch, so the instance's first
|
|
7321
|
+
status row carries `relatedWork: true`; a spawn rolled back removes it with
|
|
7322
|
+
the home. When the new instance would record neither (no relation,
|
|
7323
|
+
`--relation unrelated`, `--relation parent` of a top-level anchor with no
|
|
7324
|
+
sibling link), the spawn is refused with `E_BAD_ARGS` before anything is
|
|
7325
|
+
created, `--preview` included: `--related-work needs a parent or a sibling:
|
|
7326
|
+
<instance> would record no parent or sibling instance …; nothing was
|
|
7327
|
+
spawned`.
|
|
6994
7328
|
|
|
6995
7329
|
Routed with `--server <id>`, the verb runs on the host
|
|
6996
7330
|
([Routed reads and plans](#routed-reads-and-plans)) and `spawn --server …
|
|
6997
|
-
--
|
|
6998
|
-
`instance-
|
|
6999
|
-
|
|
7000
|
-
|
|
7001
|
-
|
|
7002
|
-
|
|
7003
|
-
|
|
7331
|
+
--related-work` sends the flag there. A host that advertises
|
|
7332
|
+
`instance-related-work` is sent the new spellings, the aliases included. A
|
|
7333
|
+
host that advertises only `instance-same-work` (an older OATS), and only
|
|
7334
|
+
that host, is asked by the old spellings when the binding is a parent:
|
|
7335
|
+
`--same-work` and `oats instance same-work`, its answer's `sameWork`
|
|
7336
|
+
returned with `relatedWork` beside it. The binding
|
|
7337
|
+
is read from the spawn's arguments and the host's own roster (the anchor's
|
|
7338
|
+
row for `--relation sibling|parent`, the instance's row for `on`). A sibling
|
|
7339
|
+
binding is refused there with `E_REMOTE_INCOMPATIBLE`, naming the host and
|
|
7340
|
+
the feature it lacks, and nothing is sent; it is never dropped. A host that
|
|
7341
|
+
advertises neither feature is refused with `E_REMOTE_INCOMPATIBLE` for
|
|
7342
|
+
either, and nothing is sent.
|
|
7343
|
+
|
|
7344
|
+
Where it is read: `relatedWork` (and `sameWork` beside it for a parent
|
|
7345
|
+
binding) on [status rows](#row-related-work) and on [remote roster
|
|
7346
|
+
rows](#the-remote-roster-oats-server-roster---json) (only `true` is
|
|
7347
|
+
relayed).
|
|
7004
7348
|
|
|
7005
7349
|
## Sessions and launch configurations
|
|
7006
7350
|
|