@awebai/oats 0.51.0 → 0.53.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/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
package/docs/capabilities.md
CHANGED
|
@@ -207,7 +207,10 @@ A self-contained package has an `oats.json`:
|
|
|
207
207
|
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
208
|
where there is no `/proc`, as on macOS: the system `ps`, from
|
|
209
209
|
`/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
|
|
210
|
-
`TZ=UTC` environment. A
|
|
210
|
+
`TZ=UTC` environment. A spawning process that has exited or was killed and
|
|
211
|
+
that its parent has not reaped (a zombie) is gone, although it still has
|
|
212
|
+
its pid and its start: the row shows the quarantine and `oats retire`
|
|
213
|
+
completes it. A start that cannot be read is never taken to mean the process is
|
|
211
214
|
gone, nor shown as alive: `oats status` shows the quarantine
|
|
212
215
|
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
213
216
|
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
@@ -244,7 +247,11 @@ A self-contained package has an `oats.json`:
|
|
|
244
247
|
and nothing is silently dropped. Without `--force` that state fails closed with
|
|
245
248
|
`E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
|
|
246
249
|
directory still holds; `--force` removes it and leaves any external state for
|
|
247
|
-
the operator to clean up by hand.
|
|
250
|
+
the operator to clean up by hand. One home is the exception for now: a home
|
|
251
|
+
whose `instance.json` is there and cannot be read is refused by every
|
|
252
|
+
retire, `--force` included, until the file is restored from a copy
|
|
253
|
+
([souls-and-instances.md](souls-and-instances.md#retire); awebai/oats#896).
|
|
254
|
+
Home entries declared in
|
|
248
255
|
`retirement.disposable.home` (below) go with the home: recovery holds no
|
|
249
256
|
copy of them.
|
|
250
257
|
- `retirement.disposable` declares what retirement treats as the provider's
|
|
@@ -541,6 +548,9 @@ Hooks receive:
|
|
|
541
548
|
compatibility alias), `OATS_AGENT`, `OATS_SOUL`, `OATS_SOUL_ID`,
|
|
542
549
|
`OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_ROOT`;
|
|
543
550
|
- `OATS_CLI_BIN` (the running kernel's `bin/oats.mjs`);
|
|
551
|
+
- `OATS_NODE_BIN` (the node to write into anything that outlives the hook:
|
|
552
|
+
the node running the kernel, by a path that survives a Node upgrade,
|
|
553
|
+
[below](#the-node-a-hook-writes-down));
|
|
544
554
|
- `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_META`;
|
|
545
555
|
- the team and workspace variables of
|
|
546
556
|
[Teams in the provider environment](#teams-in-the-provider-environment),
|
|
@@ -560,6 +570,8 @@ from the deployment directory) receives:
|
|
|
560
570
|
|
|
561
571
|
- `OATS_CAPABILITY`;
|
|
562
572
|
- `OATS_CLI_BIN`;
|
|
573
|
+
- `OATS_NODE_BIN`: the node to write into anything that outlives the command,
|
|
574
|
+
as hooks get it;
|
|
563
575
|
- `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`: the home's recorded payload, or
|
|
564
576
|
the soul's merged payload from the deployment;
|
|
565
577
|
- the team and workspace variables, as hooks get them;
|
|
@@ -728,6 +740,47 @@ Spawn order is by capability name; retirement reverses successful
|
|
|
728
740
|
spawn order. Hooks run from the instance's own copy
|
|
729
741
|
(`<home>/.oats/modules/<cap>/`).
|
|
730
742
|
|
|
743
|
+
### The node a hook writes down
|
|
744
|
+
|
|
745
|
+
A hook or a command that writes a `node` path into something that outlives it
|
|
746
|
+
(a harness's settings file, a unit, a script) writes `OATS_NODE_BIN`, never
|
|
747
|
+
its own `process.execPath`: on Homebrew that is the versioned keg
|
|
748
|
+
(`…/Cellar/node/<version>/bin/node`), which the next `brew upgrade node`
|
|
749
|
+
removes, and what was written then fails where nobody sees it. To run
|
|
750
|
+
something at once, `process.execPath` is still right.
|
|
751
|
+
|
|
752
|
+
`OATS_NODE_BIN` is the node running the kernel, the one that runs
|
|
753
|
+
`OATS_CLI_BIN`. A hook is itself run as the `node` first on its `PATH`, which
|
|
754
|
+
can be another one. The kernel computes the path once per process, by the one
|
|
755
|
+
rule it also uses for [the host timer's unit](schedules.md#the-host-timers-unit):
|
|
756
|
+
|
|
757
|
+
1. the keg's `<prefix>/opt/<formula>/bin/node`, when that is the node running
|
|
758
|
+
the kernel;
|
|
759
|
+
2. else the first `node` on the kernel's own `PATH` that is that same file.
|
|
760
|
+
Entries inside an instance home and inside a versioned keg are not looked
|
|
761
|
+
at;
|
|
762
|
+
3. else the node's own path, as it is.
|
|
763
|
+
|
|
764
|
+
The second case answers only a `node` that is the same file as the one
|
|
765
|
+
running the kernel. A version manager's shim is another program, so it is
|
|
766
|
+
never the answer: which node a shim runs depends on the directory it is run
|
|
767
|
+
from. With mise the answer is the version's own install, which lasts until
|
|
768
|
+
that version is removed (measured: mise's shim puts that directory on the
|
|
769
|
+
`PATH` of what it starts). Other version managers were not measured.
|
|
770
|
+
|
|
771
|
+
In the third case a spawn and a start each carry one warning, for every
|
|
772
|
+
harness, that the node path is not stable; a preview carries none. The hook
|
|
773
|
+
itself cannot report it.
|
|
774
|
+
|
|
775
|
+
A package that also runs under a kernel older than the variable falls back to
|
|
776
|
+
`process.execPath` when `OATS_NODE_BIN` is absent or not an absolute path.
|
|
777
|
+
|
|
778
|
+
`oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
|
|
779
|
+
own process, over any value the caller's environment held, before it runs the
|
|
780
|
+
turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
781
|
+
into the capture hooks and the capture watcher's unit. In the third case
|
|
782
|
+
`oats setup` carries the warning, a dry run included.
|
|
783
|
+
|
|
731
784
|
### The worktree event
|
|
732
785
|
|
|
733
786
|
`OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
|
|
@@ -965,8 +1018,20 @@ clears it.
|
|
|
965
1018
|
symlink or not a directory.
|
|
966
1019
|
- **When it writes.** It writes at spawn, because `oats spawn` runs no
|
|
967
1020
|
launch hook, and at every `oats session start|restart`, so the node and
|
|
968
|
-
CLI paths it bakes in follow the current kernel.
|
|
969
|
-
|
|
1021
|
+
CLI paths it bakes in follow the current kernel. The node is
|
|
1022
|
+
`OATS_NODE_BIN` ([the node a hook writes down](#the-node-a-hook-writes-down)):
|
|
1023
|
+
the kernel's own node, by a path that survives a Node upgrade. Under a
|
|
1024
|
+
kernel that does not set the variable it is the hook's own
|
|
1025
|
+
`process.execPath`, which on Homebrew is the versioned keg, gone at the
|
|
1026
|
+
next `brew upgrade node`. With mise the variable is the version's own
|
|
1027
|
+
path, as the hook's own node was (other version managers were not
|
|
1028
|
+
measured), and a start rewrites the hooks after the version changes. The
|
|
1029
|
+
hook a start runs is the copy of oats.core
|
|
1030
|
+
in the home (`.oats/modules/oats.core`), which a start does not refresh. A
|
|
1031
|
+
home spawned with an oats.core that does not read the variable therefore
|
|
1032
|
+
writes its hook's own node path at every start: a restart repairs its
|
|
1033
|
+
hooks after each Node upgrade, and a respawn gives it the lasting path. A
|
|
1034
|
+
launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
|
|
970
1035
|
and pi homes get nothing.
|
|
971
1036
|
- **It never hurts the session.** Claude Code reads a hook's stdout and exit
|
|
972
1037
|
code as decisions. So every command runs the script through `/bin/sh`
|
|
@@ -1207,6 +1272,8 @@ passed as arguments; no shell is involved.
|
|
|
1207
1272
|
- `OATS_CAPABILITY`, `OATS_SETTINGS` (the payload as JSON) and
|
|
1208
1273
|
`OATS_SETTINGS_ORIGINS` (where each leaf came from, as hooks get it);
|
|
1209
1274
|
- `OATS_CLI_BIN`;
|
|
1275
|
+
- `OATS_NODE_BIN` (the node to write into anything that outlives the check,
|
|
1276
|
+
as hooks get it);
|
|
1210
1277
|
- `OATS_WORKSPACE` (the deployment);
|
|
1211
1278
|
- the team variables `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
|
|
1212
1279
|
`OATS_DEFAULT_TEAM_FROM`, `OATS_TEAMS`, `OATS_TEAMS_SOURCE` (see
|
|
@@ -1381,8 +1448,10 @@ its own; the tick records what it folds.
|
|
|
1381
1448
|
**Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
|
|
1382
1449
|
gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
|
|
1383
1450
|
variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
|
|
1384
|
-
`OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `
|
|
1385
|
-
the
|
|
1451
|
+
`OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_NODE_BIN`
|
|
1452
|
+
(the node to write into anything that outlives the run, as hooks get it),
|
|
1453
|
+
`OATS_WORKSPACE`, the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and
|
|
1454
|
+
`OATS_SOUL`. There is no
|
|
1386
1455
|
`OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
|
|
1387
1456
|
Under the host timer, the inherited environment is the timer's (only `PATH`
|
|
1388
1457
|
and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
|
package/docs/configuration.md
CHANGED
|
@@ -60,17 +60,17 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
60
60
|
| `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; it need not be cloned. |
|
|
61
61
|
| `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
|
|
62
62
|
| `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
|
|
63
|
-
| `launchPromptAnswers
|
|
63
|
+
| `launchPromptAnswers` | Ignored, with a warning to remove it; a home entry `awebDevelopmentChannel: false` is refused. See [the development-channel confirmation](#the-development-channel-confirmation). |
|
|
64
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
65
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
66
66
|
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
|
|
67
|
-
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
|
|
67
|
+
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
|
|
68
68
|
| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
|
|
69
69
|
| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
|
|
70
70
|
| `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
|
|
71
71
|
| `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
|
|
72
72
|
| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
|
|
73
|
-
| `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
|
|
73
|
+
| `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. Written by `oats soul launch set\|remove` (0.53). See [Launch preferences](#launch-preferences). |
|
|
74
74
|
|
|
75
75
|
Which teams a soul may join, and its default, are committed in the workspace's
|
|
76
76
|
`souls:`, never here: `souls.teams` and `souls.default` were removed in 0.38.0
|
|
@@ -138,9 +138,9 @@ Claude config directory the host's Claude launch configuration uses (its
|
|
|
138
138
|
Respawn a home to adopt the route. Setup never restarts running agents
|
|
139
139
|
without the operator's word.
|
|
140
140
|
|
|
141
|
-
**No
|
|
142
|
-
[
|
|
143
|
-
|
|
141
|
+
**No prompt** appears in approved mode, so there is nothing for OATS to
|
|
142
|
+
confirm: [the development-channel confirmation](#the-development-channel-confirmation)
|
|
143
|
+
applies only to a launch with the development-channel flag.
|
|
144
144
|
|
|
145
145
|
**Verify:**
|
|
146
146
|
|
|
@@ -170,89 +170,121 @@ development mode, and qualifies only Claude 2.1.289 on `darwin-arm64`.
|
|
|
170
170
|
account-level feature flag gates channels on every route. The allowlist
|
|
171
171
|
matches the marketplace by name.
|
|
172
172
|
|
|
173
|
-
##
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
it
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
`
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
Enter
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
173
|
+
## The development-channel confirmation
|
|
174
|
+
|
|
175
|
+
**What engages it.** Whenever OATS itself starts Claude Code (a spawn, `oats
|
|
176
|
+
session start` or `session restart`, by hand or by an agent) with
|
|
177
|
+
`--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
|
|
178
|
+
in its argv, the launcher confirms Claude's development-channel prompt once.
|
|
179
|
+
Launching with that flag is the decision: there is no consent setting and no
|
|
180
|
+
list of homes. Every Claude home the messaging provider starts in development
|
|
181
|
+
mode (`settings.oats.aweb.delivery: channel` with `claudeChannelMode:
|
|
182
|
+
development`, today's defaults) is covered, existing homes included at their
|
|
183
|
+
next start. This reverses the earlier rule that no existing home is enabled
|
|
184
|
+
automatically. Any other argv (approved-mode `--channels`, another plugin,
|
|
185
|
+
several plugins, contradictory channel arguments), Codex and pi never engage it,
|
|
186
|
+
and nothing is captured. `--no-launch` never answers.
|
|
187
|
+
|
|
188
|
+
**What it proves before the one key.** The visible screen of the pane this start
|
|
189
|
+
created, normalized by the [enumerated tolerance](../lib/launch-prompt-fixtures/README.md)
|
|
190
|
+
(box-drawing rows dropped, whitespace collapsed, nothing else), must equal one
|
|
191
|
+
entry of the tolerance list: the confirmation's own text, exactly one channel
|
|
192
|
+
(`plugin:aweb-channel@awebai-marketplace`), the affirmative option
|
|
193
|
+
`1. I am using this for local development` with `❯` before it, option `2. Exit`
|
|
194
|
+
without it, and nothing else on the screen. Matching does not depend on the pane
|
|
195
|
+
width, the Claude binary or the platform: one entry covers Claude 2.1.289 and
|
|
196
|
+
2.1.296 on macOS and Linux, from committed captures, and a release review
|
|
197
|
+
reports the same match for 2.1.288 on linux-x64. A pane too narrow for Claude to wrap at word
|
|
198
|
+
boundaries (about 40 columns for this prompt) does not match.
|
|
199
|
+
|
|
200
|
+
**What it never does.** It sends one `Enter`, never another key, never a retry,
|
|
201
|
+
and never into a pane it did not create in this start (a respawned pane must
|
|
202
|
+
show a new process and a fresh screen). It confirms no other prompt: folder trust
|
|
203
|
+
(owned by [`oats harness trust`](harness-trust.md)), API-key and login questions
|
|
204
|
+
are unexpected and block. While the screen keeps changing it waits, within 30 s
|
|
205
|
+
at 100 ms. An unknown screen is no verdict until it has held unchanged for the
|
|
206
|
+
settle window (`SETTLE`, 2 s): Claude paints transient frames while it starts (a
|
|
207
|
+
logo mid-animation, a renderer notice) and can hold one for a second or more
|
|
208
|
+
under load. An unknown screen that holds still for `SETTLE` blocks with no key,
|
|
209
|
+
`blocked: unexpected prompt`, and the receipt says what `differed` from the
|
|
210
|
+
nearest entry. A screen still changing when the 30 s bound is reached, or blank
|
|
211
|
+
for the whole bound, never settled into a prompt: it blocks with no key,
|
|
212
|
+
`blocked: observation timeout`, keeping what `differed` and the last screen as
|
|
213
|
+
evidence, and its error and readiness remedy say no prompt was established (look
|
|
214
|
+
at the pane; restart a running session) rather than to read and answer one. The instance then waits for a person: the spawn is retained
|
|
215
|
+
(`E_SPAWN_INCOMPLETE`), the home records `launchPrompts.status: "blocked"`, and
|
|
216
|
+
readiness shows the `launch-prompt` warning. Every attempt and outcome is a
|
|
217
|
+
`launch-prompt` event carrying the Claude version read from the executable's
|
|
218
|
+
path (`claudeVersion`, `claudeVersionSource`) and the entry it matched; the
|
|
219
|
+
version is `unknown` when Claude is started through a wrapper, whose path carries
|
|
220
|
+
no version, so it informs and never decides. What
|
|
221
|
+
follows the Enter is reported, never answered: the start completes after
|
|
222
|
+
`SETTLE` (2 s) of consecutive clean captures (no question marker, no
|
|
223
|
+
confirmation; the screen may keep changing), and a question first painted more
|
|
224
|
+
than 2 s after the session is working is the session's own, not a launch prompt.
|
|
225
|
+
See [launch completion](launch-prompt-completion.md).
|
|
226
|
+
|
|
227
|
+
**When Claude ignores the flag.** This affects a Claude account (or
|
|
228
|
+
organization) for which Claude Code offers no channels, on the messaging
|
|
229
|
+
provider's default `delivery: channel`. Claude Code disables channels when telemetry is opted out (`DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`), so a launch
|
|
230
|
+
environment that sets any of them is affected the same way; the messaging
|
|
231
|
+
provider's readiness warning names the three variables that do it. Claude then ignores
|
|
232
|
+
`--dangerously-load-development-channels`, shows no confirmation, and starts the
|
|
233
|
+
session with a notice: `--dangerously-load-development-channels ignored
|
|
234
|
+
(plugin:aweb-channel@awebai-marketplace) Channels are not currently available`.
|
|
235
|
+
Before 0.52 such a start reported launched and said nothing, and the instance
|
|
236
|
+
was never woken by mail or chat. Now, when that notice block equals a
|
|
237
|
+
`flag-ignored` tolerance entry (the block's rows with their `▎` dropped,
|
|
238
|
+
normalized the same way; never a contains test; the entry takes no input), and
|
|
239
|
+
the screen shows no question (none of the
|
|
240
|
+
[question markers](launch-prompt-completion.md)), OATS sends no key and the start
|
|
241
|
+
succeeds. A notice beside a question blocks like any unknown screen. It records `launchPrompts: {status:
|
|
242
|
+
"flag-ignored", reason: "channels-unavailable", signatureId, startId, at}` (the
|
|
243
|
+
entry's id, no screen text), and the start's warnings say, in place of the
|
|
244
|
+
statement that OATS confirms the prompt:
|
|
245
|
+
|
|
246
|
+
> Claude reported that channels are not currently available and ignored the development-channel flag, so this instance gets no channel delivery: mail and chat will not wake it. Check first for a telemetry opt-out in the launch environment (DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Claude Code disables channels when one is set), then whether this Claude account offers channels; otherwise change the messaging provider's delivery (its readiness warning says where the setting is). See docs/configuration.md#the-development-channel-confirmation.
|
|
247
|
+
|
|
248
|
+
Every start says so until the cause is removed or delivery changes. The kernel's readiness shows no `launch-prompt` warning for it; the
|
|
249
|
+
messaging provider's readiness reports the missing channel. A notice in a wording
|
|
250
|
+
no entry holds is an unknown screen and blocks.
|
|
251
|
+
|
|
252
|
+
**Known limit: a hidden notice.** Claude shows a limited number of notices. On a
|
|
253
|
+
fresh Claude configuration another notice (for example, auto mode becoming the
|
|
254
|
+
default) can take the slot and keep this one behind `1 more notice hidden`,
|
|
255
|
+
typically on an instance's first spawn. OATS cannot see a hidden notice, so that
|
|
256
|
+
start stays `blocked: unexpected prompt` (no key, the home retained). When the
|
|
257
|
+
blocked screen starts with Claude's running-session banner (`Claude Code
|
|
258
|
+
v<semver>` after the logo, which may be caught mid-animation), the error and the readiness remedy add:
|
|
259
|
+
|
|
260
|
+
> Claude may have reported that channels are not currently available and ignored the development-channel flag, its notice hidden behind another one: look at the pane. If the session is running, restart the instance, and the notice will then show. Check first for a telemetry opt-out in the launch environment (DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC), then whether this Claude account offers channels; otherwise change the messaging provider's delivery (its readiness warning says where the setting is). See docs/configuration.md#the-development-channel-confirmation.
|
|
261
|
+
|
|
262
|
+
A restart where the notice shows records `flag-ignored`.
|
|
263
|
+
|
|
264
|
+
**The two settings that stop it.** OATS confirms the prompt only because the
|
|
265
|
+
deployment launches Claude with the development-channel flag. To keep the prompt
|
|
266
|
+
for a person, stop launching that way: `settings.oats.aweb.delivery: session`
|
|
267
|
+
(the host wake broker instead of the channel), or `settings.oats.aweb.claudeChannelMode:
|
|
268
|
+
approved` ([the approved route](#claude-channel-delivery-the-approved-route), no
|
|
269
|
+
prompt at all). Both are captured at spawn, so respawn a home to change it. Every
|
|
270
|
+
start that engages the confirmation says so in its output (`launch-config preview`,
|
|
271
|
+
the spawn's warnings, `session start|restart`). `spawn --preview` cannot say it
|
|
272
|
+
yet: the argv comes from the provider's spawn hook, which a preview does not run.
|
|
273
|
+
|
|
274
|
+
**A new Claude wording** blocks loudly until a reviewed change adds it as a new
|
|
275
|
+
tolerance entry with its captured provenance. Until then, read the prompt in the
|
|
276
|
+
instance's terminal and press Enter yourself.
|
|
277
|
+
|
|
278
|
+
**An old `launchPromptAnswers` block** in `oats-local.yaml` is judged, never used:
|
|
279
|
+
|
|
280
|
+
- only `awebDevelopmentChannel: true` entries, an empty block, or
|
|
281
|
+
`workspaceTrust`: ignored, with one warning per command naming the key and
|
|
282
|
+
saying to remove it;
|
|
283
|
+
- any home entry `awebDevelopmentChannel: false`: refused (`E_WORKSPACE_SCHEMA`,
|
|
284
|
+
reason `removed-key`, at that entry), because this kernel can no longer honour
|
|
285
|
+
that refusal. The message names the two settings above.
|
|
286
|
+
|
|
287
|
+
`launchPromptAnswers` remains refused in workspace and soul declarations.
|
|
256
288
|
|
|
257
289
|
## Launch configurations
|
|
258
290
|
|
|
@@ -276,7 +308,8 @@ configuration is a host choice: a soul never names one.
|
|
|
276
308
|
it.
|
|
277
309
|
- `oats launch-config list` shows the effective entries;
|
|
278
310
|
`oats launch-config set <name> --file <json>` and
|
|
279
|
-
`oats launch-config remove <name>` rewrite only this block
|
|
311
|
+
`oats launch-config remove <name>` rewrite only this block, under the
|
|
312
|
+
lock every kernel command that rewrites `oats-local.yaml` holds;
|
|
280
313
|
`oats launch-config preview (--home <abs> | --soul <name>) --json` shows
|
|
281
314
|
what a start would run (harness, model, executable, argv, redacted
|
|
282
315
|
environment, command and preflight checks) and starts nothing.
|
|
@@ -307,6 +340,18 @@ account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
|
|
|
307
340
|
- **One per harness.** A second `default: true` for the same harness is
|
|
308
341
|
refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
|
|
309
342
|
old one first.
|
|
343
|
+
- **Several configurations and no default is ambiguous for a spawn.** When a
|
|
344
|
+
spawn's harness has more than one configuration here, none of them
|
|
345
|
+
`default: true`, and the spawn names none, it is refused in preview and
|
|
346
|
+
apply alike (`E_LAUNCH_CONFIG_AMBIGUOUS`, naming the harness and its
|
|
347
|
+
configurations) instead of starting the bare harness. Naming one decides
|
|
348
|
+
it: `--launch-config <name>`, `--launch-config none` (the bare harness) or
|
|
349
|
+
a `souls.launch` name (`none` included). An inline `souls.launch`
|
|
350
|
+
preference, the soul's `launch:` and `--harness` alone name no
|
|
351
|
+
configuration. One configuration for the harness is not ambiguous (without
|
|
352
|
+
`default: true` it is not used). `oats souls` and `oats inspect --soul`
|
|
353
|
+
show the refusal as the launch's `problem`. A start or restart of an
|
|
354
|
+
existing home, with `--harness` or `--reselect-launch` too, is not refused.
|
|
310
355
|
- **Existing homes keep their launch** until `--reselect-launch` or a
|
|
311
356
|
respawn, like any change of preference. Declaring a default is such a
|
|
312
357
|
change: `oats readiness --home` warns `launch-changed` on each existing
|
|
@@ -345,6 +390,38 @@ souls:
|
|
|
345
390
|
oats.engineering/code-reviewer: { harness: codex } # a package soul
|
|
346
391
|
```
|
|
347
392
|
|
|
393
|
+
- **Write `souls.launch` with `oats soul launch`** (0.53.0), not by hand:
|
|
394
|
+
|
|
395
|
+
```
|
|
396
|
+
oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>])
|
|
397
|
+
oats soul launch remove <soul>|'*'|<exact key>
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
each with `--plan` (every check, nothing written), `--dir <deployment>`
|
|
401
|
+
and `--json`.
|
|
402
|
+
- `set` names the soul as a spawn does and writes the key that soul has:
|
|
403
|
+
its bare name, or `<package>/<soul>` for a package's. So it cannot write
|
|
404
|
+
a key that names no soul. `'*'` is every soul without an entry of its
|
|
405
|
+
own. `--launch-config <name>` must be a launch configuration this file
|
|
406
|
+
declares (`none` is the bare harness); `--harness` writes the inline
|
|
407
|
+
preference.
|
|
408
|
+
- `remove` takes a soul, `'*'`, or the exact text of a key in the file.
|
|
409
|
+
The exact text is tried first and needs no read of the workspace, so a
|
|
410
|
+
key that names no soul can always be removed. An entry the file does not
|
|
411
|
+
have is refused (`E_LAUNCH_PREFERENCE_UNKNOWN`), never answered "done".
|
|
412
|
+
- Both answer what the next spawn of that soul selects, and every key of
|
|
413
|
+
`souls.launch` that still names no soul the workspace offers.
|
|
414
|
+
- **The file is rewritten, and every other entry keeps its value and its
|
|
415
|
+
comments.** The write holds the lock `oats teams` holds, so neither
|
|
416
|
+
drops the other's change.
|
|
417
|
+
- **A name two members offer.** A member's soul is keyed by its bare name,
|
|
418
|
+
so one entry pins every member's soul of that name: an entry cannot pin
|
|
419
|
+
one of them and leave the other. `oats soul launch set <member>/<soul>`
|
|
420
|
+
writes the bare name and lists each soul the entry applies to; the bare
|
|
421
|
+
name alone is refused, as for a spawn (`E_SOUL_AMBIGUOUS`). To run one
|
|
422
|
+
of them differently, name its launch on that spawn (`--launch-config` or
|
|
423
|
+
`--harness`), or keep the other off this machine (`souls.disabled` takes
|
|
424
|
+
`<member>/<soul>`).
|
|
348
425
|
- **Precedence for a new launch:** `--launch-config` or `--harness`, then
|
|
349
426
|
`souls.launch.<soul>`, then `souls.launch."*"`, then the soul's `launch:`,
|
|
350
427
|
then `pi` with its defaults. `--model` alone keeps the deciding layer's
|
|
@@ -353,9 +430,41 @@ souls:
|
|
|
353
430
|
**inline or soul preference** runs its harness the way this host starts it
|
|
354
431
|
without a configuration: [the harness default](#the-harness-default) if
|
|
355
432
|
one is declared, else the executable on `PATH` with no args and no env,
|
|
356
|
-
with the preference's `model`. A
|
|
433
|
+
with the preference's `model`. A spawn is refused instead when the harness
|
|
434
|
+
has several configurations and none is its default
|
|
435
|
+
(`E_LAUNCH_CONFIG_AMBIGUOUS`). A preference without `model` uses the
|
|
357
436
|
harness default's model, else the harness's own; it never borrows a lower
|
|
358
437
|
layer's.
|
|
438
|
+
- **A key that names no soul refuses the launches it might have pinned**
|
|
439
|
+
(0.53). While `souls.launch` holds a key, other than `"*"`, that is the key
|
|
440
|
+
of no soul the workspace offers, a new launch that names no launch, of a
|
|
441
|
+
soul with no entry of its own, is refused
|
|
442
|
+
(`E_LAUNCH_PREFERENCE_UNMATCHED`). `souls.launch."*"`, the soul's `launch:`
|
|
443
|
+
or the host default would have decided that launch, and the kernel cannot
|
|
444
|
+
tell which soul the key was meant to pin. Before 0.53 the key was never
|
|
445
|
+
read, and the soul it was written for ran on the fall-through.
|
|
446
|
+
- **Refused:** `oats spawn`, preview and apply, and `oats session
|
|
447
|
+
start|restart --reselect-launch`, before anything is created, stopped or
|
|
448
|
+
started. `--model` alone names no launch.
|
|
449
|
+
- **Goes on:** a soul with its own entry; a launch named with
|
|
450
|
+
`--launch-config` or `--harness`; a plain start or restart of an
|
|
451
|
+
existing home, which selects nothing again.
|
|
452
|
+
- **The remedy, in this order:** pin the soul the key was meant for (`oats
|
|
453
|
+
soul launch set <soul> --launch-config <name>`, or `--harness <h>`),
|
|
454
|
+
then remove the key (`oats soul launch remove <key>`). Removing first
|
|
455
|
+
ends the refusal and leaves that soul on the fall-through. The refusal
|
|
456
|
+
names the keys and, for each, the nearest soul keys.
|
|
457
|
+
- **Where it shows:** `oats souls` and `oats inspect --soul` carry it on
|
|
458
|
+
each soul a spawn would refuse and list each such key; `oats doctor`
|
|
459
|
+
lists each key with the command that removes it, from this machine's
|
|
460
|
+
last read of the souls.
|
|
461
|
+
- **A key the kernel could not check refuses nothing:** a bare key while a
|
|
462
|
+
member is not confirmed or a member's or an external soul failed to
|
|
463
|
+
read, a `<package>/…` key while that package is declared and not locked
|
|
464
|
+
or one of its souls failed to read, and every key in the standalone view
|
|
465
|
+
of a workspace whose host cannot be read. `oats doctor` says so
|
|
466
|
+
(`launch-preference-unchecked`). The key of a soul listed in
|
|
467
|
+
`souls.disabled` matches that soul. `"*"` is never reported.
|
|
359
468
|
- **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
|
|
360
469
|
names the layer that chose it and the fix (install the harness, or override
|
|
361
470
|
it here in `souls.launch`). `oats souls` still lists the soul, with the
|