@awebai/oats 0.66.0 → 0.68.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
package/docs/desktop-cli-api.md
CHANGED
|
@@ -89,6 +89,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
89
89
|
| `schedule-history`, `schedule-read-2` | run history with identity and provenance (gate on `schedule-read-2`) | `scheduleHistoryApi: 3` |
|
|
90
90
|
| `workspace-v2` | `onboard`, `sync`, `package`, `workspace status`, `capabilities`, `souls` | `workspaceApi: 2` |
|
|
91
91
|
| `instance-modules` | `instance.json` `modules`/`providers`/`workspace`; module drift in status; preview `modules[]` | |
|
|
92
|
+
| `instance-upgrade` | `oats instance upgrade` plan/apply/undo for stopped local homes; optional `upgrade` hook; `modules.<cap>.previous`; `modules-upgraded` event; start/restart package `drift` | |
|
|
92
93
|
| `spawn-provider-payload` | `oats spawn … --provider <cap> <key>=<value>` | |
|
|
93
94
|
| `served-identity` | `decision.effective.providers`; the served `identity` in inspect and status | |
|
|
94
95
|
| `packages-no-approval` | no package approval anywhere | |
|
|
@@ -119,6 +120,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
119
120
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
120
121
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
121
122
|
| `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
123
|
+
| `soul-composed-skills` | `oats inspect --soul <soul> --composed-skills` and its `souls[].composedSkills`: every skill a spawn of the soul gives its instance, its own and its capabilities', each with its `source` and each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)). The same kernels name each capability skill of `spawn --preview`'s `skills[]` as the spawn does ([The preview](#the-preview)) | |
|
|
124
|
+
| `spawn-suggest-name` | `oats spawn <soul> --preview --suggest-name`: the preview also chooses the name, from the task, through the soul's own harness, and says how in `naming` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)). Suggested names work on claude and pi; codex is numbered (`unsupported-harness`). Routed, the host needs the feature | |
|
|
122
125
|
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
123
126
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
124
127
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
@@ -135,8 +138,11 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
135
138
|
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
136
139
|
| `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 | |
|
|
137
140
|
| `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`) | |
|
|
141
|
+
| `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) |
|
|
138
142
|
| `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` |
|
|
139
143
|
| `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 | |
|
|
144
|
+
| `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 of `<soul>` 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) | |
|
|
145
|
+
| `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
|
|
140
146
|
|
|
141
147
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
142
148
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -437,7 +443,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
437
443
|
### `oats inspect`
|
|
438
444
|
|
|
439
445
|
```text
|
|
440
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
|
|
446
|
+
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
441
447
|
```
|
|
442
448
|
|
|
443
449
|
An instance subject, abridged:
|
|
@@ -463,7 +469,7 @@ An instance subject, abridged:
|
|
|
463
469
|
"recordedDefaultTeam":{"label":"eng","team":null,"from":"soul"},
|
|
464
470
|
"knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"status","kind":"view","available":true,"reason":null}]},
|
|
465
471
|
"instance":{"home":"/w/agents/rm/instances/rm-1","instance":"rm-1","agent":"rm","harness":"pi","model":null,"yolo":null,"launched":false,
|
|
466
|
-
"createdAt":"2026-09-28T10:08:01.281Z","resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
|
|
472
|
+
"createdAt":"2026-09-28T10:08:01.281Z","color":null,"resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
|
|
467
473
|
"instructions":{"file":"/w/agents/rm/instances/rm-1/AGENTS.md","text":"…","truncated":false,
|
|
468
474
|
"sources":[{"source":"capability:oats.okf","file":"/w/agents/rm/instances/rm-1/.oats/modules/oats.okf/injects/okf.md"}]}},
|
|
469
475
|
"identity":null,
|
|
@@ -479,7 +485,7 @@ An instance subject, abridged:
|
|
|
479
485
|
| `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
|
|
480
486
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
481
487
|
| `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
|
|
482
|
-
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
|
|
488
|
+
| `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)) |
|
|
483
489
|
| `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 |
|
|
484
490
|
| `problems` | below |
|
|
485
491
|
| `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
|
|
@@ -588,6 +594,48 @@ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
|
|
|
588
594
|
and nothing is sent. Every text is untrusted repository content: render it as
|
|
589
595
|
plain text or through a sanitising renderer.
|
|
590
596
|
|
|
597
|
+
`composedSkills` (feature `soul-composed-skills`) is present only with
|
|
598
|
+
`--composed-skills`, which takes a soul subject (`--home` is `E_BAD_ARGS`) and
|
|
599
|
+
combines with `--instructions` and `--skills`; without the flag the key is
|
|
600
|
+
absent and nothing extra is composed. It lists every skill an instance of this
|
|
601
|
+
soul gets: the soul's own and each capability's.
|
|
602
|
+
|
|
603
|
+
```json
|
|
604
|
+
"composedSkills":[{"name":"oats-operate","source":"module:oats.core","path":".oats/modules/oats.core/skills/oats-operate",
|
|
605
|
+
"description":"…","files":[{"path":".oats/modules/oats.core/skills/oats-operate/SKILL.md","bytes":1234,"text":"…","binary":false,"truncated":false}],
|
|
606
|
+
"filesTruncated":false},
|
|
607
|
+
{"name":"release-checklist","source":"soul","path":"skills/release-checklist","description":"Cutting a release.",
|
|
608
|
+
"files":[…],"filesTruncated":false}]
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
- One row per skill, sorted by `name` in codepoint order. `source` is
|
|
612
|
+
`"soul"` or `"module:<capability id>"`, the vocabulary of `instance.json`
|
|
613
|
+
`skills` and of the spawn preview.
|
|
614
|
+
- `path` is POSIX. A soul skill's is relative to the soul directory, as in
|
|
615
|
+
`skills`; a capability skill's is relative to the instance home, where the
|
|
616
|
+
instance carries the capability's copy (`.oats/modules/<id>/…`). Each
|
|
617
|
+
file's `path` starts with its skill's.
|
|
618
|
+
- The rest of a row, and every rule for its files, is `skills`' above, with
|
|
619
|
+
one difference: the whole field carries at most 2 MiB (2,097,152 bytes) of
|
|
620
|
+
`text`, summed over every file in answer order, whichever source it comes
|
|
621
|
+
from. Problems name `composedSkills: ` instead of `skills: `.
|
|
622
|
+
- It is computed by the same scratch materialization as `--instructions`
|
|
623
|
+
(one serves both when both are given): the soul's skills by the
|
|
624
|
+
enumerator spawn uses, read from the soul copy, and the capability skills
|
|
625
|
+
materialize placed, read from the scratch copy before it is removed. It
|
|
626
|
+
runs no hooks and writes nothing in the deployment.
|
|
627
|
+
- It is `null` when a spawn would refuse a collision between a soul skill and
|
|
628
|
+
a capability skill (names compare case-insensitively), with the problem
|
|
629
|
+
`{code: "E_SKILL_DUPLICATE", message: "composedSkills: skill \"<name>\"
|
|
630
|
+
from soul collides with module <id>'s skill"}`, the sentence spawn refuses
|
|
631
|
+
with. It is `null` when the soul resolves but cannot be composed here, with
|
|
632
|
+
the composition's code and sentence, naming `composedSkills`. It is `null`
|
|
633
|
+
with `soul-skills-unreadable` when the soul's own skills cannot be listed.
|
|
634
|
+
|
|
635
|
+
Routed with `--server <id>`, `--composed-skills` travels to the host; a host
|
|
636
|
+
whose probe does not advertise `soul-composed-skills` is refused with
|
|
637
|
+
`E_REMOTE_INCOMPATIBLE`, and nothing is sent.
|
|
638
|
+
|
|
591
639
|
**Layers.** `id` is the capability filling the slot or `null`. `from`
|
|
592
640
|
(feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
|
|
593
641
|
or a home spawned before it was recorded.
|
|
@@ -2430,7 +2478,13 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2430
2478
|
- `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
|
|
2431
2479
|
`member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
|
|
2432
2480
|
strings, module skills as `{name, source: "module:<cap>"}`) are display
|
|
2433
|
-
only: bind to `modules[]` and `decision`.
|
|
2481
|
+
only: bind to `modules[]` and `decision`. A module skill's `name` is a
|
|
2482
|
+
skill the spawn copies, by the rule it copies by: a manifest entry that
|
|
2483
|
+
holds skill directories lists each of them, and a manifest with no
|
|
2484
|
+
`skills` lists each `skills/<dir>/` holding a `SKILL.md`, read at the
|
|
2485
|
+
module's commit (feature `soul-composed-skills`; earlier kernels named such
|
|
2486
|
+
an entry by its own directory, `skills`, and listed nothing for a manifest
|
|
2487
|
+
with no `skills`).
|
|
2434
2488
|
- `resolution` (24 hex) hashes `declRevision` (the declarations) and
|
|
2435
2489
|
`payloadRevision` (the merged payloads). `workspace` is the host key;
|
|
2436
2490
|
`standalone` marks a standalone view. `task` is the task text or `null`.
|
|
@@ -2450,6 +2504,137 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2450
2504
|
new head and revision. An apply with `--expect-decision` may reuse heads
|
|
2451
2505
|
too (feature `spawn-apply-max-age`, [Apply](#apply)).
|
|
2452
2506
|
|
|
2507
|
+
#### The suggested name (feature `spawn-suggest-name`)
|
|
2508
|
+
|
|
2509
|
+
```text
|
|
2510
|
+
oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real spawn] [--json]
|
|
2511
|
+
```
|
|
2512
|
+
|
|
2513
|
+
A preview that also chooses the instance's name, from the task (`--task-file`,
|
|
2514
|
+
or `--task <text>`). Like every preview it writes nothing and runs no hooks.
|
|
2515
|
+
- `--suggest-name` with `--name`, `--purpose` or `--expect-decision` is
|
|
2516
|
+
`E_BAD_ARGS`. Without `--preview` it names an apply
|
|
2517
|
+
([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
|
|
2518
|
+
- **The call.** The kernel makes one non-interactive call through the
|
|
2519
|
+
harness, executable and environment the spawn would launch (the launch
|
|
2520
|
+
configuration's `env`, not its `args`), with this prompt on stdin, never in
|
|
2521
|
+
argv:
|
|
2522
|
+
|
|
2523
|
+
> Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
|
|
2524
|
+
>
|
|
2525
|
+
> Task:
|
|
2526
|
+
> <the task text, at most 4000 characters>
|
|
2527
|
+
|
|
2528
|
+
It runs from a fresh empty temporary directory, removed afterwards, with no
|
|
2529
|
+
`OATS_INSTANCE*` variable, without a shell, in its own process group. It is
|
|
2530
|
+
made after the preview's harness checks (the executable's lookup and the
|
|
2531
|
+
harness package probes, from where the home will be) and before anything
|
|
2532
|
+
that depends on the name (placement, branch, home). It takes what those
|
|
2533
|
+
checks leave of the preview's one 20 s preflight budget, which is not
|
|
2534
|
+
raised for it: the group is killed after 20 s, or when the budget runs out
|
|
2535
|
+
first. Its time counts in `preflight.elapsedMs`; `preflight.status` stays
|
|
2536
|
+
that of the checks, so a numbered preview after a `timeout` is confirmed
|
|
2537
|
+
like any other. At most 4 KiB of its output is read.
|
|
2538
|
+
- **It starts none of the user's code: no MCP server, hook, plugin,
|
|
2539
|
+
extension or project setting, and no tool on either harness.** Three
|
|
2540
|
+
exceptions are stated:
|
|
2541
|
+
- Claude Code's own built-in plugins (`cc-plugin-*@builtin`) load as
|
|
2542
|
+
they always do, `--bare` included.
|
|
2543
|
+
- Hooks in the host's managed policy (`managed-settings.json`) still
|
|
2544
|
+
apply: they are the host admin's.
|
|
2545
|
+
- pi runs its own credential commands (`!command` keys and headers in
|
|
2546
|
+
models.json), as every pi launch does: they are its login.
|
|
2547
|
+
|
|
2548
|
+
A claude login through `apiKeyHelper` is not read (`--setting-sources
|
|
2549
|
+
""`): such a user gets `harness-failed` and a numbered name.
|
|
2550
|
+
|
|
2551
|
+
Each harness's argv is proven to start nothing else
|
|
2552
|
+
(`scripts/naming-isolation-proof.mjs`, a recorded run against fixtures,
|
|
2553
|
+
rerun by an operator after a harness upgrade). The proof covers claude
|
|
2554
|
+
2.1.288 and pi 1.3.0, on Linux; macOS is not proven.
|
|
2555
|
+
- **claude**, model `haiku`: `-p --tools "" --strict-mcp-config
|
|
2556
|
+
--setting-sources "" --disable-slash-commands --no-session-persistence
|
|
2557
|
+
--output-format text --model haiku`. Its native login is kept, which
|
|
2558
|
+
`--bare` would not keep.
|
|
2559
|
+
- **pi**, the instance's model: `-p --no-session --no-tools
|
|
2560
|
+
--no-extensions --no-mcp --no-skills --no-prompt-templates --no-themes
|
|
2561
|
+
--no-context-files --no-approve [--model <m>]`.
|
|
2562
|
+
- **codex** is not supported. Its naming call is not proven to start
|
|
2563
|
+
nothing, so a codex soul is numbered with `unsupported-harness`.
|
|
2564
|
+
- **The name.**
|
|
2565
|
+
1. The reply's first non-empty line, as a slug.
|
|
2566
|
+
2. Without one or more trailing `-<role>`. The role is the last word of the
|
|
2567
|
+
soul's name, after any package qualifier.
|
|
2568
|
+
3. At most 4 words, cut at a word boundary to fit
|
|
2569
|
+
`64 − 1 − len(role)`.
|
|
2570
|
+
4. Nothing left, or only the role, is `invalid-reply`.
|
|
2571
|
+
5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
|
|
2572
|
+
a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
|
|
2573
|
+
- **The answer** is the full preview, plus `naming`:
|
|
2574
|
+
|
|
2575
|
+
```json
|
|
2576
|
+
"naming": { "source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku" }
|
|
2577
|
+
```
|
|
2578
|
+
|
|
2579
|
+
```json
|
|
2580
|
+
"naming": { "source": "numbered", "reason": "timeout", "message": "claude gave no name within 20 s", "ms": 20000 }
|
|
2581
|
+
```
|
|
2582
|
+
|
|
2583
|
+
- With `source: "suggested"`, `instance`, `home`, `branch` and `decision`
|
|
2584
|
+
are those of a preview with `--name <instance>`: an apply with `--name
|
|
2585
|
+
<instance> --expect-decision <revision>` matches it.
|
|
2586
|
+
- With `source: "numbered"`, they are today's numbered name, and the apply
|
|
2587
|
+
goes without `--name`.
|
|
2588
|
+
- `reason` is one of a closed set:
|
|
2589
|
+
- `no-task`: no task, or a blank one; no call is made.
|
|
2590
|
+
- `unsupported-harness`: no call is made.
|
|
2591
|
+
- `timeout`.
|
|
2592
|
+
- `harness-failed`: a nonzero exit, a signal, or no executable. `message`
|
|
2593
|
+
gives the exit or the signal, never the output.
|
|
2594
|
+
- `invalid-reply`.
|
|
2595
|
+
- `model` is `null` when the harness runs its own default.
|
|
2596
|
+
- A failure is never an error: the preview answers.
|
|
2597
|
+
- The text preview prints `name: suggested by claude (haiku) in 2310 ms` or
|
|
2598
|
+
`name: numbered (<reason>: <message>)`.
|
|
2599
|
+
- **`--server`:** the call runs on the target machine, through the routed
|
|
2600
|
+
preview, and the task travels as a routed spawn's does. A host that does
|
|
2601
|
+
not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
|
|
2602
|
+
before the spawn is sent.
|
|
2603
|
+
|
|
2604
|
+
#### On an apply (feature `spawn-apply-suggest-name`)
|
|
2605
|
+
|
|
2606
|
+
```text
|
|
2607
|
+
oats spawn <soul> --suggest-name --task-file <f> [the flags of a real spawn] [--json]
|
|
2608
|
+
```
|
|
2609
|
+
|
|
2610
|
+
An apply with `--suggest-name` and no `--name`, `--purpose` or
|
|
2611
|
+
`--expect-decision` names the instance on the machine that spawns, by the
|
|
2612
|
+
preview's call and rules above, through the soul's harness.
|
|
2613
|
+
- The name is `<descriptive>-<role>`, made unique as a preview's is, and it is
|
|
2614
|
+
placed exactly as `--name <name>` would be.
|
|
2615
|
+
- On any failure the instance is numbered as it is today, and `naming` says
|
|
2616
|
+
why. A failed call is never an error: the spawn goes on.
|
|
2617
|
+
- The call is made before anything is placed, after the executable is
|
|
2618
|
+
resolved and the harness packages probed. An apply has no preflight
|
|
2619
|
+
budget: the call has its own 20 s. Every later bound of the apply (the
|
|
2620
|
+
hooks, the launch) starts after it, so the apply can take up to 20 s longer
|
|
2621
|
+
than without the flag. A caller with its own deadline on the apply allows
|
|
2622
|
+
for that.
|
|
2623
|
+
- The result carries `naming`, in the preview's shape and with its closed
|
|
2624
|
+
`reason` set, whenever `--suggest-name` was given
|
|
2625
|
+
([Apply](#apply), its result). The text answer prints a
|
|
2626
|
+
`name: suggested by …` or `name: numbered (…)` line.
|
|
2627
|
+
- **A race.** Another soul's spawn that takes the name between the naming
|
|
2628
|
+
and the placement makes this apply `E_INSTANCE_NAME_TAKEN`, as for `--name`
|
|
2629
|
+
(nothing was created by this call; spawn again for another name). The same
|
|
2630
|
+
soul's is `E_PLACEMENT_TAKEN`, as for any name.
|
|
2631
|
+
- Without `--suggest-name`, an apply is unchanged: numbered, with no call.
|
|
2632
|
+
- **`--server`:** the call runs on the host, through the routed apply. A host
|
|
2633
|
+
that does not advertise `spawn-apply-suggest-name` is refused
|
|
2634
|
+
(`E_REMOTE_INCOMPATIBLE`) before the spawn is sent; the route never drops
|
|
2635
|
+
the flag. A caller that would rather have the host number the instance
|
|
2636
|
+
checks the host's `probe.features` and does not send the flag.
|
|
2637
|
+
|
|
2453
2638
|
**Provider settings.**
|
|
2454
2639
|
- `providers` is the `--provider` map as typed.
|
|
2455
2640
|
- `settings.<cap>`: the merged payload (manifest defaults, then workspace,
|
|
@@ -2489,7 +2674,8 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
|
|
|
2489
2674
|
- The home is reserved with a non-recursive `mkdir`. A concurrent loser
|
|
2490
2675
|
refuses `E_PLACEMENT_TAKEN {instance, home}` having touched nothing. Names
|
|
2491
2676
|
are deployment-wide: a same-name race with another soul ends in
|
|
2492
|
-
`E_INSTANCE_NAME_TAKEN` (for `--name`) or
|
|
2677
|
+
`E_INSTANCE_NAME_TAKEN` (for `--name` and a suggested name) or
|
|
2678
|
+
`E_PLACEMENT_TAKEN`.
|
|
2493
2679
|
- A refused child spawn appends `child-spawn-refused` to the parent's log (on
|
|
2494
2680
|
apply only).
|
|
2495
2681
|
- `--max-age <s>` with `--expect-decision <revision>` (feature
|
|
@@ -2566,7 +2752,9 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
2566
2752
|
`wakeScheduleError` (a requested wake), `worktreeHooks` (feature
|
|
2567
2753
|
`worktree-event`: only when the spawn ran `worktree` hooks, the receipt
|
|
2568
2754
|
`[{capability, ok, required, log, exitCode, signal?, timedOut?,
|
|
2569
|
-
contract?}]`, `log` being the hook's log file)
|
|
2755
|
+
contract?}]`, `log` being the hook's log file), `naming` (feature
|
|
2756
|
+
`spawn-apply-suggest-name`: only with `--suggest-name`, `{source, reason?,
|
|
2757
|
+
message?, ms, harness?, model?}` as on the preview).
|
|
2570
2758
|
- A spawn that runs `worktree` hooks can take up to 30 minutes per hook
|
|
2571
2759
|
([the worktree event](capabilities.md#the-worktree-event)).
|
|
2572
2760
|
|
|
@@ -2583,6 +2771,90 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2583
2771
|
`E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
|
|
2584
2772
|
a silent `-2`.
|
|
2585
2773
|
- The name is part of the decision.
|
|
2774
|
+
- Routed (`--server`), `--name` needs a host that advertises `spawn-name`:
|
|
2775
|
+
`E_REMOTE_INCOMPATIBLE` otherwise, with nothing sent. A saved route here
|
|
2776
|
+
under that name is `E_ROUTE_EXISTS`, before the spawn is sent.
|
|
2777
|
+
- `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
|
|
2778
|
+
descriptive name for the task, `<descriptive>-<role>`, which the apply then
|
|
2779
|
+
passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
|
|
2780
|
+
An apply with `--suggest-name` (feature `spawn-apply-suggest-name`) chooses
|
|
2781
|
+
it itself ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)).
|
|
2782
|
+
- `oats instance suggest-name` (feature `instance-suggest-name`) chooses one on
|
|
2783
|
+
this machine for a spawn on another
|
|
2784
|
+
([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
|
|
2785
|
+
|
|
2786
|
+
### A name for a spawn elsewhere (`oats instance suggest-name`)
|
|
2787
|
+
|
|
2788
|
+
Feature `instance-suggest-name`.
|
|
2789
|
+
|
|
2790
|
+
```text
|
|
2791
|
+
oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] --json
|
|
2792
|
+
```
|
|
2793
|
+
|
|
2794
|
+
The name a spawn of `<soul>` would get by `--suggest-name`, chosen on the
|
|
2795
|
+
machine that asks (a Desktop's, with the spawn dialog open) for a spawn that
|
|
2796
|
+
may land on another.
|
|
2797
|
+
|
|
2798
|
+
- **What it touches.** It resolves no workspace, writes nothing, records
|
|
2799
|
+
nothing and reserves no name. It reads only this machine's launch
|
|
2800
|
+
configurations (the `oats-local.yaml` in reach of `--dir`, else the working
|
|
2801
|
+
directory) and the OATS tmux server's environment, as a spawn's pane would
|
|
2802
|
+
have it; it resolves no souls, members, lock or remote. The deployment it
|
|
2803
|
+
reads is not added to this computer's deployments list.
|
|
2804
|
+
- **The soul is only a name.** It gives the role (the last word of the name,
|
|
2805
|
+
after any package qualifier) and needn't exist on this machine. It is
|
|
2806
|
+
checked as a soul name's shape (`<soul>`, `<package>/<soul>`,
|
|
2807
|
+
`<package>--<soul>`), never resolved.
|
|
2808
|
+
- **Not made unique.** The words, role and length rules are the preview's
|
|
2809
|
+
([The suggested name](#the-suggested-name-feature-spawn-suggest-name)), but no
|
|
2810
|
+
`-2` is added: the machine the spawn lands on owns uniqueness, and a name
|
|
2811
|
+
taken there is its `E_INSTANCE_NAME_TAKEN` at the apply.
|
|
2812
|
+
- **The harness and model.** The harness is `--harness`, else the
|
|
2813
|
+
configuration's, else claude. Its executable and environment are what a
|
|
2814
|
+
spawn on this machine would launch it with: `--launch-config` if given
|
|
2815
|
+
(`none` for the bare harness), else this machine's default configuration
|
|
2816
|
+
for that harness, else the harness's own executable. The model is
|
|
2817
|
+
`--model`, else the configuration's: `@native-default` is the harness's
|
|
2818
|
+
own, and a preference list names its first entry (no catalogue is
|
|
2819
|
+
probed: the naming call is the only process the command starts). It
|
|
2820
|
+
matters for pi; claude always names with `haiku`. The task text goes to this machine's harness and model, as the
|
|
2821
|
+
preview's naming does.
|
|
2822
|
+
- **The call** is the preview's, with the same prompt, argv and isolation,
|
|
2823
|
+
and its model call is bounded as the preview's is: at most 20 s and 4 KiB
|
|
2824
|
+
of output.
|
|
2825
|
+
- **The answer** is the usual envelope, `ok: true` whether the name was
|
|
2826
|
+
suggested or numbered:
|
|
2827
|
+
|
|
2828
|
+
```json
|
|
2829
|
+
{"schemaVersion": 1, "ok": true, "result": {"name": "fix-flaky-login-developer", "naming": {"source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku"}}}
|
|
2830
|
+
```
|
|
2831
|
+
|
|
2832
|
+
```json
|
|
2833
|
+
{"schemaVersion": 1, "ok": true, "result": {"naming": {"source": "numbered", "reason": "harness-failed", "message": "claude could not be run: claude is not installed on this machine (claude binary not found on PATH)", "ms": 0}}}
|
|
2834
|
+
```
|
|
2835
|
+
|
|
2836
|
+
- `name` is present only when `naming.source` is `"suggested"`.
|
|
2837
|
+
- `naming` has the preview's shape, and `naming.reason` its closed set:
|
|
2838
|
+
`no-task` (`--task ""`, or a blank task file; no call is made),
|
|
2839
|
+
`unsupported-harness` (codex; no call is made), `timeout`,
|
|
2840
|
+
`harness-failed` (a nonzero exit, a signal, or no executable here: no
|
|
2841
|
+
such executable, or a configuration's `{fromEnv}` reference not set
|
|
2842
|
+
here; `message` names the cause, never a value), `invalid-reply`.
|
|
2843
|
+
- A naming failure is not an error: `ok: true` with
|
|
2844
|
+
`naming.source: "numbered"`.
|
|
2845
|
+
- The text answer is the name, or `numbered (<reason>: <message>)`.
|
|
2846
|
+
- **Refusals** (`E_BAD_ARGS` unless named): no `--soul`, or one that is not
|
|
2847
|
+
a soul name's shape; neither or both of `--task` and `--task-file`, or one
|
|
2848
|
+
that cannot be read; a `--harness` other than pi, claude or codex; a
|
|
2849
|
+
`--harness` that is not the named configuration's; a flag or argument it
|
|
2850
|
+
does not take; `--server`. An unknown `--launch-config` is
|
|
2851
|
+
`E_LAUNCH_CONFIG_UNKNOWN`.
|
|
2852
|
+
- **Never routed.** `oats instance` commands route through `--server`, but
|
|
2853
|
+
this one runs where it is asked: a name for another machine is decided
|
|
2854
|
+
here. `--server` is refused before anything is sent.
|
|
2855
|
+
- **When the feature is missing** (an older local kernel), a client spawns
|
|
2856
|
+
without a name: the host numbers the instance, or names it itself if it
|
|
2857
|
+
advertises `spawn-apply-suggest-name` and the client sends `--suggest-name`.
|
|
2586
2858
|
|
|
2587
2859
|
### Spawn origin
|
|
2588
2860
|
|
|
@@ -2832,9 +3104,9 @@ A failed `add` reports the same facts about its rollback in `details`:
|
|
|
2832
3104
|
| `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
|
|
2833
3105
|
| `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
|
|
2834
3106
|
| `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
|
|
2835
|
-
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message)
|
|
3107
|
+
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message), or an unregistered residue differs from the recorded branch (the message and `details.git` list the modified or nonignored untracked paths). The record is kept. Save the changes, or discard, then retry |
|
|
2836
3108
|
| `E_CHILDREN_RUNNING` | `remove`: an instance attached to the tree has a session that is running, or that cannot be read. Answered under the purpose's claim, before Git is asked anything: nothing is removed and the record is kept. `details: {purpose, path, children: [{instance, home, session}]}`, `session` being `"running"` or `"unknown"`; only the instances that refuse are listed. The message names each one and what was seen, and the step: `oats instance stop <instance>`, or retire it, then remove again. No flag removes anyway. It is the code [a retire](#retire-children-running) answers, with other `details`: a retire answers it for a child it asked to stop and that did not; `remove` for an attached instance it found running or unread, and it asks nobody to stop, so there is no `childrenStopped` |
|
|
2837
|
-
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or
|
|
3109
|
+
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, removal could not be verified, or an unregistered residue could not be checked against its recorded branch or deleted; the record is kept. A failure after Git started removal reports possible partial deletion and the retry, never that nothing was removed. A missing or invalid `.git` marker names the manual step: save any work, remove the directory by hand, then run `remove` again to drop the record. See [extra-tree removal recovery](souls-and-instances.md#extra-trees) |
|
|
2838
3110
|
| `E_LIFECYCLE_FAILED` | an error that is not the kernel's; with [`details.cause`](#kernel-codes) when it has a code of its own or is a defect, and without it when it is a refusal without a code. When it is the purpose's claim that could not be taken (`<home>/.oats/trees` cannot be made, the claim's file cannot be written), the message is `the claim <path> could not be taken (…); nothing was done`. Also a command that was refused the claim after its takeover had ended a dead command's git step: the message names the group it ended first, then the refusal, and `details` are that refusal's (a refusal of the kernel's has no `details.cause`; anything else has it by the same rule) |
|
|
2839
3111
|
|
|
2840
3112
|
A rollback that cannot finish keeps the record and says so in the message
|
|
@@ -2879,6 +3151,11 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
|
|
|
2879
3151
|
the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
|
|
2880
3152
|
`<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
|
|
2881
3153
|
`<home>/.agents/skills/<cap>/<skill>/`).
|
|
3154
|
+
After a package upgrade, the moved row also carries
|
|
3155
|
+
`previous: {from, commit, digest, materializedAt, receipt}`: one level, for
|
|
3156
|
+
its latest move. Readers tolerate this additive field. The verified copy
|
|
3157
|
+
for undo lives at `<home>/.oats/previous/<receipt>/`; each move replaces the
|
|
3158
|
+
previous state, and retirement preserves it in recovery.
|
|
2882
3159
|
- `branch`: for a worktree instance, the branch its worktree was created on.
|
|
2883
3160
|
For an attached or checkout instance, the branch the tree's HEAD named at
|
|
2884
3161
|
the spawn, or `null` when HEAD was detached or named a ref OATS carries no
|
|
@@ -3006,6 +3283,12 @@ its absence.
|
|
|
3006
3283
|
An older kernel's `running` is the window's presence, and it checks a row
|
|
3007
3284
|
with a claim against its session (as `oats session inspect` observes it),
|
|
3008
3285
|
reading `null` unless a harness runs there.
|
|
3286
|
+
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3287
|
+
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3288
|
+
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
3289
|
+
a `color` in `instance.json` never stands in for it. Every row has it,
|
|
3290
|
+
an unreadable record's row included (`null`). Presentation only: it is not
|
|
3291
|
+
identity and never addresses anything.
|
|
3009
3292
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3010
3293
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3011
3294
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -3166,7 +3449,7 @@ route target:
|
|
|
3166
3449
|
"soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
|
|
3167
3450
|
"modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
|
|
3168
3451
|
"commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
|
|
3169
|
-
"retirePending":false,"rollbackIncomplete":false,
|
|
3452
|
+
"color":"sage","retirePending":false,"rollbackIncomplete":false,
|
|
3170
3453
|
"savedRoute":false,"addressable":true,"missingRemotely":false}],
|
|
3171
3454
|
"retireFailures":[]}
|
|
3172
3455
|
```
|
|
@@ -3461,6 +3744,7 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
3461
3744
|
| `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
|
|
3462
3745
|
| `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3463
3746
|
| `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3747
|
+
| `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
|
|
3464
3748
|
|
|
3465
3749
|
- The flags are the local command's. The instance is addressed like every
|
|
3466
3750
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -3594,6 +3878,10 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
3594
3878
|
bytes}`. Only a regular file is opened (no symlinks, same device and inode
|
|
3595
3879
|
after open), and at most its last 4 MiB is read (`"tail"`).
|
|
3596
3880
|
- **Kinds:** `spawned`, `launched`, `restarted`, `stopped`, `stop-refused`,
|
|
3881
|
+
`modules-upgraded` (`data: {receipt, modules:[{capability, from, to}]}`,
|
|
3882
|
+
written after the module swap and retirement baseline complete),
|
|
3883
|
+
`upgrade-refused` (a failure with no successful or uncertain apply-hook outcome,
|
|
3884
|
+
naming the failed step or module; older clients tolerate the unknown kind),
|
|
3597
3885
|
`retire-planned`, `retired`, `retire-refused` (0.53.0,
|
|
3598
3886
|
[below](#retire-refused-event)), `worktree-retained`, `worktree-removed`,
|
|
3599
3887
|
`branch-deleted` (not written since 0.41.0: no retire deletes a branch;
|
|
@@ -3731,7 +4019,7 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
3731
4019
|
|
|
3732
4020
|
### Waiting on you
|
|
3733
4021
|
|
|
3734
|
-
Feature `waiting-on-you` (OATS 0.40.0): an instance
|
|
4022
|
+
Feature `waiting-on-you` (OATS 0.40.0): an instance waiting on a human (a
|
|
3735
4023
|
permission prompt, a question, an agent asking for an answer) says so through
|
|
3736
4024
|
a producer's claim. **Claims are display-only:** nothing in the kernel acts
|
|
3737
4025
|
on `waitingOnYou`. In particular `oats session input` behaves exactly as
|
|
@@ -3826,6 +4114,84 @@ oats instance attention [--message <text>] [--clear] --json
|
|
|
3826
4114
|
readable `instance.json`), `E_HOME_MISMATCH`, `E_EVENTS_FAILED` (the write
|
|
3827
4115
|
failed; nothing else is affected).
|
|
3828
4116
|
|
|
4117
|
+
## Upgrading an instance's package modules
|
|
4118
|
+
|
|
4119
|
+
Requires the `instance-upgrade` feature in `oats version --json` or `oats status --json`.
|
|
4120
|
+
|
|
4121
|
+
```text
|
|
4122
|
+
oats instance upgrade <instance> --plan [--json]
|
|
4123
|
+
oats instance upgrade <instance> --plan-revision <revision> --idempotency-key <key> [--json]
|
|
4124
|
+
oats instance upgrade <instance> --undo --plan [--json]
|
|
4125
|
+
oats instance upgrade <instance> --undo --plan-revision <revision> --idempotency-key <key> [--json]
|
|
4126
|
+
```
|
|
4127
|
+
|
|
4128
|
+
This local act resolves an instance like `oats retire`, from its deployment
|
|
4129
|
+
or a parent's home. It uses the lifecycle claim and requires a stopped,
|
|
4130
|
+
readable session. A running or unreadable session is `E_SESSION_RUNNING`,
|
|
4131
|
+
naming `oats instance stop <instance>`, upgrade, then session start. It does
|
|
4132
|
+
not support `--server` or several homes in one call.
|
|
4133
|
+
|
|
4134
|
+
A read-only plan stages package copies outside the home, verifies the locked
|
|
4135
|
+
commit and integrity as spawn does, then removes that staging. Its revision
|
|
4136
|
+
hashes the facts. Each moving module reports `{capability,
|
|
4137
|
+
from:{version,commit,digest}, to:{version,commit,integrity},
|
|
4138
|
+
skills:{added,removed,changed}, inject, hooks, provider:{decision,reason}}`.
|
|
4139
|
+
`inject` and `hooks` indicate changes. The plan also lists kept modules and
|
|
4140
|
+
member drift and `homeChangedSinceSpawn` (both excluded from `planRevision`).
|
|
4141
|
+
A package no longer in the lock is kept. Member modules and
|
|
4142
|
+
the soul body never move. A provider refusal refuses the whole act.
|
|
4143
|
+
|
|
4144
|
+
Apply rechecks the revision under the lifecycle claim (`E_PLAN_STALE` with
|
|
4145
|
+
a fresh plan on mismatch) and records an idempotency receipt. It stages the
|
|
4146
|
+
whole modules, skills, inject and hook composition through spawn's composer,
|
|
4147
|
+
using the soul at its recorded commit. It saves and verifies the previous
|
|
4148
|
+
state before provider hooks run, swaps the composition, updates only a clean
|
|
4149
|
+
home's retirement `homeFingerprint`, commits the receipt, then appends
|
|
4150
|
+
`modules-upgraded`. A dirty home keeps its baseline file byte-identical, so
|
|
4151
|
+
older kernels also preserve its pre-upgrade edits at retirement. Work-tree
|
|
4152
|
+
fingerprints and digest versions always remain as recorded. The moved module record's `previous`
|
|
4153
|
+
is described under [`instance.json`](#instancejson).
|
|
4154
|
+
Upgrade runs no launch hooks. When a moved module's new manifest has no launch
|
|
4155
|
+
hook, apply removes its recorded launch/environment contribution in the same
|
|
4156
|
+
journaled metadata swap. When it still declares a launch hook, the existing
|
|
4157
|
+
contribution stays with settings and trust refreshed, until the next start
|
|
4158
|
+
replaces it wholesale. Undo restores the recorded contribution from the
|
|
4159
|
+
backed-up `instance.json`. There is no pending dropped-hook state to resolve
|
|
4160
|
+
at start, so consecutive upgrades need no intervening start.
|
|
4161
|
+
Receipts live at `<home>/.oats/upgrade-receipt.<key>.json`. Retirement's baseline
|
|
4162
|
+
excludes only that exact receipt filename pattern and `.oats/.staging-upgrade-*`;
|
|
4163
|
+
`.oats/previous/` is ordinary home content covered by the baseline.
|
|
4164
|
+
|
|
4165
|
+
Before the commit boundary, failure restores composed home bytes and removes
|
|
4166
|
+
staging and the saved previous state only when no provider hook succeeded or
|
|
4167
|
+
has an uncertain outcome. A non-zero hook result must be explicitly observed
|
|
4168
|
+
and recorded in the same invocation to permit this rollback. A hook reporting
|
|
4169
|
+
failure must leave no effects of its own; provider host effects are its
|
|
4170
|
+
responsibility.
|
|
4171
|
+
|
|
4172
|
+
Before spawning a hook, the receipt records `step: "hook <capability>"` and
|
|
4173
|
+
`hooks.inFlight: <capability>`. Resuming an unknown in-flight outcome durably
|
|
4174
|
+
records `uncertain: [<capability>]` before retry work. Even a kill before spawn
|
|
4175
|
+
counts as uncertain if not-started cannot be proved. After any success or
|
|
4176
|
+
uncertainty, failure records `partial`: the error names pending work and asks
|
|
4177
|
+
for the same `--idempotency-key` to finish forward. Retry re-runs pending
|
|
4178
|
+
idempotent hooks, including an uncertain one. A subsequent hook failure stays
|
|
4179
|
+
partial; it cannot authorize rollback. Start refuses with `E_UPGRADE_PARTIAL`
|
|
4180
|
+
while the receipt is partial. If completion is impossible, the remedy is respawn.
|
|
4181
|
+
|
|
4182
|
+
The commit boundary is after swap and baseline: the receipt becomes
|
|
4183
|
+
`status: "complete"` with `steps.cleaned: false` before the success event and staging cleanup.
|
|
4184
|
+
Successful cleanup sets `steps.cleaned: true`. A failure after that boundary
|
|
4185
|
+
leaves the upgrade committed. The same-key retry finishes event publication
|
|
4186
|
+
and cleanup, without
|
|
4187
|
+
hooks or copies. Start is allowed with one warning naming that retry; a new
|
|
4188
|
+
upgrade or undo plan refuses until cleanup finishes. `E_UPGRADE_PARTIAL`
|
|
4189
|
+
applies only before commit. Retirement adds no special cleanup behavior.
|
|
4190
|
+
|
|
4191
|
+
`--undo` uses the latest verified previous state and the restored version's
|
|
4192
|
+
`upgrade` hook, under the same adoption and failure protocol. A version
|
|
4193
|
+
without that hook cannot be restored through this act; respawn instead.
|
|
4194
|
+
|
|
3829
4195
|
## Lifecycle: stop and retire
|
|
3830
4196
|
|
|
3831
4197
|
Feature `lifecycle-plans` (and `retire-retention`), `lifecycleApi: 1`. A
|
|
@@ -4202,6 +4568,7 @@ in flight.
|
|
|
4202
4568
|
|
|
4203
4569
|
Feature `lifecycle-claim-stop`, OATS 0.52.0 (#866). A retire and a stop apply
|
|
4204
4570
|
hold the home's claim for their whole run, and `oats worktree add` reads it.
|
|
4571
|
+
This table covers those three commands; the upgrade pairs follow separately.
|
|
4205
4572
|
Each cell is the answer of the command that **arrives**. It is given at once
|
|
4206
4573
|
and before any effect: that command stopped, ran, copied, made and removed
|
|
4207
4574
|
nothing, and the command already on the home is not disturbed.
|
|
@@ -4216,6 +4583,25 @@ nothing, and the command already on the home is not disturbed.
|
|
|
4216
4583
|
| the claim file is no readable claim | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` | `E_LIFECYCLE_BUSY` |
|
|
4217
4584
|
| the holder of the claim is gone | not refused | not refused | not refused | not refused |
|
|
4218
4585
|
|
|
4586
|
+
<a id="upgrade-lifecycle-pairs"></a>
|
|
4587
|
+
The `instance-upgrade` pairs use the same home's lifecycle claim:
|
|
4588
|
+
|
|
4589
|
+
| On the home | Arriving command | Answer |
|
|
4590
|
+
|---|---|---|
|
|
4591
|
+
| a retire is running | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4592
|
+
| a self-retire is scheduled | `oats instance upgrade` apply | `E_INSTANCE_RETIRING` |
|
|
4593
|
+
| a stop or upgrade apply is running | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4594
|
+
| a holder's verb is unknown, its liveness cannot be read, or the claim is unreadable | `oats instance upgrade` apply | `E_LIFECYCLE_BUSY` |
|
|
4595
|
+
| the holder of the claim is gone | `oats instance upgrade` apply | not refused after claim takeover checks |
|
|
4596
|
+
| an upgrade apply is running | `oats retire` or `oats instance stop --apply` | `E_LIFECYCLE_BUSY` |
|
|
4597
|
+
| an upgrade apply is running | `oats worktree add` | not refused |
|
|
4598
|
+
|
|
4599
|
+
Upgrade requires a stopped session. Start and restart do not take or read the
|
|
4600
|
+
lifecycle claim: upgrade instead holds their existing `.oats-start.lock`
|
|
4601
|
+
mutex until its final invocation receipt is persisted. A start blocked by an
|
|
4602
|
+
upgrade mutex names the same-key retry. A partial receipt refuses starts through the remaining
|
|
4603
|
+
finalization. The following stop/retire notes describe the original table.
|
|
4604
|
+
|
|
4219
4605
|
- **A holder is answered before a stale plan, by both verbs.** A guarded
|
|
4220
4606
|
retire and a stop apply compare the revision they were sent only once
|
|
4221
4607
|
they hold the claim, so beside a holder the answer is the cell above
|
|
@@ -4291,7 +4677,7 @@ since, action}`, with `holder` on `E_LIFECYCLE_BUSY`:
|
|
|
4291
4677
|
stop this may be a child of the instance asked for.**
|
|
4292
4678
|
- `lock`: the file that names the holder. `pid` and `since`: the holder's
|
|
4293
4679
|
pid and when it took the claim.
|
|
4294
|
-
- **`action`: the holder's verb**, `"retire"` or `"
|
|
4680
|
+
- **`action`: the holder's verb**, `"retire"`, `"stop"` or `"upgrade"`. A claim written
|
|
4295
4681
|
by a kernel before this feature has no verb and reads as `"retire"`. A
|
|
4296
4682
|
reader treats a value it does not know as busy.
|
|
4297
4683
|
- <a id="claim-file-text"></a>**Text of a claim file is never part of an
|
|
@@ -5130,7 +5516,7 @@ line and says that nothing was done:
|
|
|
5130
5516
|
second for a retire, which does not wait).
|
|
5131
5517
|
`details` is `{instance, home, lock, holder: "unknown"}`; the message is
|
|
5132
5518
|
`<lock> is not a readable claim; nothing was done — inspect it and remove
|
|
5133
|
-
it if no oats retire or oats instance
|
|
5519
|
+
it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry`.
|
|
5134
5520
|
- A claim whose holder is gone and that this kernel cannot take over is
|
|
5135
5521
|
never removed either: its `nonce` is not the 32 hexadecimal digits a claim
|
|
5136
5522
|
carries (a file written or damaged by hand); or it is the claim of a
|
|
@@ -5142,7 +5528,7 @@ line and says that nothing was done:
|
|
|
5142
5528
|
The message is `the
|
|
5143
5529
|
process that held <lock> (pid <pid>) is gone, and this file is not a claim
|
|
5144
5530
|
this kernel can take over (<why>); nothing was done — inspect <lock> and
|
|
5145
|
-
remove it if no oats retire or oats instance
|
|
5531
|
+
remove it if no oats retire, oats instance stop or oats instance upgrade holds it, then retry` (0.52.0, #874; before,
|
|
5146
5532
|
the first was answered as a live holder, to wait for, and the second as
|
|
5147
5533
|
`E_LIFECYCLE_FAILED` with the system's `ENAMETOOLONG` about a file that
|
|
5148
5534
|
does not exist). Removing that one file lets the next retire take the
|
|
@@ -5379,6 +5765,60 @@ removal begins, and only with the home kept (`reached.home: "kept"`). A
|
|
|
5379
5765
|
typed refusal keeps its code, its details and its own words; the inspections'
|
|
5380
5766
|
and the recovery's refusals end with the sentence of their phase, once.
|
|
5381
5767
|
|
|
5768
|
+
## An instance's colour (`oats instance color`)
|
|
5769
|
+
|
|
5770
|
+
Feature `instance-color` (awebai/oats#1421).
|
|
5771
|
+
|
|
5772
|
+
```text
|
|
5773
|
+
oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]
|
|
5774
|
+
```
|
|
5775
|
+
|
|
5776
|
+
The colour is presentation, not identity. Anyone may change it at any time,
|
|
5777
|
+
the agent on its own instance included, and it is never an address.
|
|
5778
|
+
|
|
5779
|
+
- **The palette** is closed: `sand`, `sage`, `slate`, `mauve`, `clay`,
|
|
5780
|
+
`olive`, the clients' own (`packages/client/soul-colors.mjs`).
|
|
5781
|
+
- **The record** is `<home>/.oats-color.json`, `{"colorApi": 1, "color":
|
|
5782
|
+
"sage", "at": "<ISO time>"}`, mode 0600, written atomically. `--clear`
|
|
5783
|
+
removes it. It is a kernel-owned home file: a capability cannot declare it
|
|
5784
|
+
as its own, and it is no change to the home at retire.
|
|
5785
|
+
- **A reader** takes a regular file only, without following a link, of at
|
|
5786
|
+
most 4 KiB. Anything that is not such a valid record reads as no colour
|
|
5787
|
+
(`null`), never as an error.
|
|
5788
|
+
- **The instance** is addressed as `oats instance stop` addresses it, and
|
|
5789
|
+
refused with the same answers: not found, ambiguous, a `--home` that is not
|
|
5790
|
+
its home, a record that cannot be read.
|
|
5791
|
+
|
|
5792
|
+
The answer:
|
|
5793
|
+
|
|
5794
|
+
```json
|
|
5795
|
+
{"instanceColorApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","color":"sage","changed":true}
|
|
5796
|
+
```
|
|
5797
|
+
|
|
5798
|
+
`color` is `null` after `--clear`. Setting the colour the instance already
|
|
5799
|
+
has answers `changed: false` and writes nothing; so does clearing an instance
|
|
5800
|
+
with no colour.
|
|
5801
|
+
|
|
5802
|
+
| Code | When |
|
|
5803
|
+
|---|---|
|
|
5804
|
+
| `E_BAD_ARGS` | The colour is not in the palette: `"<value>" is not an instance colour: use one of sand, sage, slate, mauve, clay, olive, or --clear`. Also: both a colour and `--clear`, neither, or two colours |
|
|
5805
|
+
| *(as `oats instance stop`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
|
|
5806
|
+
| `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, as `oats worktree add` reads it), or the home is quarantined. Nothing was written |
|
|
5807
|
+
| `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` |
|
|
5808
|
+
|
|
5809
|
+
Routed with `--server <id>`, the command runs on the host
|
|
5810
|
+
([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
|
|
5811
|
+
not advertise `instance-color` is refused with `E_REMOTE_INCOMPATIBLE`, and
|
|
5812
|
+
nothing is sent.
|
|
5813
|
+
|
|
5814
|
+
Where it is read: `color` on [status rows](#the-roster-oats-status---json),
|
|
5815
|
+
on [remote roster rows](#the-remote-roster-oats-server-roster---json) (only a
|
|
5816
|
+
palette name is relayed, anything else is `null`), and on `oats inspect
|
|
5817
|
+
--home` as `instance.color`. A client draws a row's colour by one rule,
|
|
5818
|
+
`instanceColor(row)` in `packages/client/instance-presentation.mjs`: the
|
|
5819
|
+
row's palette name, else none. Colour never says a state alone: a client's
|
|
5820
|
+
mark keeps the state by its shape.
|
|
5821
|
+
|
|
5382
5822
|
## Sessions and launch configurations
|
|
5383
5823
|
|
|
5384
5824
|
### Input
|
|
@@ -5427,6 +5867,16 @@ oats session restart --home <abs> [the same options] [--stop-grace <1-300 s>] --
|
|
|
5427
5867
|
Features `session-start`, `session-restart`, and `launch-config` for the
|
|
5428
5868
|
selection flags. See [the start workflow](desktop-instance-start.md).
|
|
5429
5869
|
|
|
5870
|
+
Start and restart keep the home's recorded module copies. Their successful
|
|
5871
|
+
results with package drift include `drift:[{capability, recorded:{version,commit},
|
|
5872
|
+
locked:{version,commit}}]` for package modules behind the deployment lock,
|
|
5873
|
+
and omit the field when none are behind. Text prints one line after the start:
|
|
5874
|
+
`<n> package module(s) behind the lock (<cap> <version> @ <shortcommit> → <version> @ <shortcommit>); to move them: oats instance stop <instance>; oats instance upgrade <instance> --plan`.
|
|
5875
|
+
Restart has no upgrade flag. A partial upgrade receipt refuses a start with
|
|
5876
|
+
`E_UPGRADE_PARTIAL`, naming the retry with the original idempotency key.
|
|
5877
|
+
A committed receipt with `steps.cleaned: false` permits start and adds one
|
|
5878
|
+
warning naming the same-key cleanup retry.
|
|
5879
|
+
|
|
5430
5880
|
- The result is `{instance, agent, home, harness, backend, model,
|
|
5431
5881
|
launchConfig, yolo, target, startedAt, restartCount, reused, warnings}`,
|
|
5432
5882
|
plus `nativeRecordId` and `stop` (a restart's stop receipt) when they apply,
|