@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
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
# Upgrading OATS on a host
|
|
2
|
+
|
|
3
|
+
Upgrading OATS means three things, in this order, on each host:
|
|
4
|
+
|
|
5
|
+
1. **The CLI** (`@awebai/oats`, the kernel).
|
|
6
|
+
2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
|
|
7
|
+
deployments launch pi with: `oats update`, in each deployment.
|
|
8
|
+
3. **A check of each deployment**: `oats doctor`.
|
|
9
|
+
|
|
10
|
+
The kernel and the bridge are published together, from one version tag, and
|
|
11
|
+
must be at the same version: a pi session with an older bridge runs old
|
|
12
|
+
extension code against a new kernel. A host that launches no pi instance has
|
|
13
|
+
no bridge, and step 2 has nothing to move.
|
|
14
|
+
|
|
15
|
+
**A release's own steps are in its notes.** Read the `## Upgrade` section of
|
|
16
|
+
every version between yours and the new one in the
|
|
17
|
+
[release notes](release-notes/) first: it says what to do before the CLI
|
|
18
|
+
changes, and what else must change with it (the Desktop, another tool, a
|
|
19
|
+
package pin). This page is the part that is the same for every release.
|
|
20
|
+
|
|
21
|
+
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
22
|
+
the bridge, never a package. A deployment's capabilities come from the
|
|
23
|
+
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
24
|
+
([Packages](packages.md)).
|
|
25
|
+
|
|
26
|
+
## The steps
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm install -g @awebai/oats # 1. the CLI
|
|
30
|
+
oats update # 2. in a deployment: the plan, then it asks before it runs
|
|
31
|
+
oats doctor # 3. in the same deployment
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Run steps 2 and 3 in every deployment on the host, or name one from anywhere
|
|
35
|
+
with `oats update --dir <deployment>`. Then restart the pi sessions that were
|
|
36
|
+
running: a session keeps the bridge it loaded when it started.
|
|
37
|
+
|
|
38
|
+
In a terminal, `oats update` shows its plan and asks before it runs anything.
|
|
39
|
+
Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
40
|
+
`oats update --check` shows the plan and runs nothing.
|
|
41
|
+
|
|
42
|
+
`oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
|
|
43
|
+
plan starts with that install, and the bridges move to that same version in
|
|
44
|
+
the same run.
|
|
45
|
+
|
|
46
|
+
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
47
|
+
older bridge than the one in place:
|
|
48
|
+
|
|
49
|
+
- **The CLI** is installed only when the version npm lists is newer than the
|
|
50
|
+
installed one. When the installed CLI is ahead of it (a checkout, a build
|
|
51
|
+
that is not published yet), the plan says so in one line and holds no step
|
|
52
|
+
for the CLI.
|
|
53
|
+
- **The bridges** are brought to the version the CLI has after the run: the
|
|
54
|
+
one npm lists when the CLI moves to it, the installed one otherwise. A
|
|
55
|
+
bridge ahead of that version is left alone.
|
|
56
|
+
|
|
57
|
+
Versions are compared as semver, so a prerelease is below its release:
|
|
58
|
+
`0.53.0-rc.1` is ahead of `0.52.0` and behind `0.53.0`. Build metadata makes
|
|
59
|
+
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
60
|
+
installed over it.
|
|
61
|
+
|
|
62
|
+
## Which pi folders
|
|
63
|
+
|
|
64
|
+
pi keeps its packages in one folder: `~/.pi/agent`, or the folder
|
|
65
|
+
`PI_CODING_AGENT_DIR` names. A deployment can launch pi with several folders,
|
|
66
|
+
so `oats update` and `oats doctor` look at each of these:
|
|
67
|
+
|
|
68
|
+
- **the default**, `~/.pi/agent`;
|
|
69
|
+
- **this shell's**, when `PI_CODING_AGENT_DIR` is set where the command runs;
|
|
70
|
+
- **each launch configuration's**: the `PI_CODING_AGENT_DIR` in the `env` of
|
|
71
|
+
every `launch-configs` entry of the deployment's `oats-local.yaml` whose
|
|
72
|
+
harness is `pi` ([Configuration](configuration.md#launch-configurations)).
|
|
73
|
+
The value is a path, or a `{fromEnv: NAME}` reference read from the
|
|
74
|
+
environment the command runs in. A leading `~` is your home.
|
|
75
|
+
|
|
76
|
+
Two names for one folder (two configurations, a configuration that names the
|
|
77
|
+
default, a symbolic link) are one folder, listed once with every reason it is
|
|
78
|
+
looked at.
|
|
79
|
+
|
|
80
|
+
The bridge of a folder is read from
|
|
81
|
+
`<folder>/npm/node_modules/@awebai/oats-pi/package.json`, where pi installs
|
|
82
|
+
it.
|
|
83
|
+
|
|
84
|
+
**The deployment** is the one at or above the directory the command runs in,
|
|
85
|
+
or the one `--dir` names. With no deployment there, `oats update` still moves
|
|
86
|
+
the default folder and this shell's, and says, in the plan and again as its
|
|
87
|
+
last line, that no launch configuration was looked at. It says the same about
|
|
88
|
+
a deployment whose `oats-local.yaml` it cannot load; `oats doctor` reports
|
|
89
|
+
what is wrong with that file. An explicit `--dir` with no deployment at or
|
|
90
|
+
above it is refused.
|
|
91
|
+
|
|
92
|
+
**Folders that are not looked at.** Only the deployment's current
|
|
93
|
+
`launch-configs` are read. An instance home records the launch it was created
|
|
94
|
+
with, and keeps it when the configuration is later changed or removed; a
|
|
95
|
+
folder named only by such a record is not in the list. Move its bridge with
|
|
96
|
+
the command under [By hand](#by-hand).
|
|
97
|
+
|
|
98
|
+
## What `oats update` does in each folder
|
|
99
|
+
|
|
100
|
+
The plan lists every folder with the bridge found in it and one of these:
|
|
101
|
+
|
|
102
|
+
| The plan says | When | What happens |
|
|
103
|
+
|---|---|---|
|
|
104
|
+
| `move to <version>` | the bridge is at an older version | `pi install` runs there |
|
|
105
|
+
| `left alone, already at <version>` | the bridge is at that version | nothing |
|
|
106
|
+
| `left alone, ahead of <version>` | the bridge is at a newer version | nothing: a bridge is never moved back |
|
|
107
|
+
| `no bridge` | the folder does not exist, or holds no bridge | nothing |
|
|
108
|
+
| `not touched`, with a reason | see below | nothing; the plan prints the command to run there |
|
|
109
|
+
|
|
110
|
+
`oats update` moves a bridge. It never creates a folder and never installs a
|
|
111
|
+
first bridge: a spawn's own package check says when a capability needs one
|
|
112
|
+
that is missing.
|
|
113
|
+
|
|
114
|
+
A folder is **not touched** when:
|
|
115
|
+
|
|
116
|
+
- **it does not resolve**: a `{fromEnv: NAME}` whose variable is not set where
|
|
117
|
+
the command runs, or a path that is not absolute. Run `oats update` again
|
|
118
|
+
where the variable is set, or the printed command.
|
|
119
|
+
- **its bridge cannot be read** (a `package.json` that does not parse).
|
|
120
|
+
- **only launch configurations with their own `executable` name it.** A
|
|
121
|
+
wrapper is your program: `oats update` never runs one. The plan prints the
|
|
122
|
+
install command with that executable; when the configurations name several
|
|
123
|
+
executables, one command for each, with the configurations it is for. A
|
|
124
|
+
folder that the default, this shell or a configuration without an
|
|
125
|
+
`executable` also names is moved with the plain `pi`.
|
|
126
|
+
|
|
127
|
+
For a folder it moves, `oats update` runs the `pi` found on `PATH`, with
|
|
128
|
+
`PI_CODING_AGENT_DIR` set to that folder:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
PI_CODING_AGENT_DIR=<folder> npm_config_prefer_online=true pi install npm:@awebai/oats-pi@<version>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
For the default folder the variable is left out, unless this shell sets one.
|
|
135
|
+
|
|
136
|
+
## Nothing is removed before its replacement is known to install
|
|
137
|
+
|
|
138
|
+
The move is one `pi install` over the installed bridge. pi replaces the
|
|
139
|
+
settings entry and the files of a package it already holds, and an install
|
|
140
|
+
that fails leaves the old ones in place. There is no `pi uninstall`.
|
|
141
|
+
|
|
142
|
+
Before any step runs, the CLI's own install included, `oats update` asks the
|
|
143
|
+
registry for the bridge's exact version, with npm told to revalidate its
|
|
144
|
+
cache (`npm view @awebai/oats-pi@<version> version --prefer-online`). A new
|
|
145
|
+
version is listed a few minutes after it is published, and the kernel's
|
|
146
|
+
listing says nothing about the bridge's. If the version does not resolve,
|
|
147
|
+
the update stops with nothing changed and every bridge in place: run it again
|
|
148
|
+
in a few minutes. The same setting goes to pi's own npm for the install
|
|
149
|
+
(`npm_config_prefer_online=true`). `--check` does not make this lookup: it
|
|
150
|
+
shows what would run, and the run looks again.
|
|
151
|
+
|
|
152
|
+
When the installed CLI is ahead of the registry, the version asked for is
|
|
153
|
+
the installed one, and it may not be published at all. The plan does not
|
|
154
|
+
know: it makes no lookup. So when it lists a move to that version, it says
|
|
155
|
+
under the folders what the move depends on:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
A bridge moves to 0.53.0 only if @awebai/oats-pi@0.53.0 is published: the installed kernel is ahead of the registry's 0.52.0, and a run checks that before any step.
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
When the run's lookup then does not find the version, the message says that
|
|
162
|
+
the installed kernel is ahead of the registry, instead of telling you to wait
|
|
163
|
+
a few minutes.
|
|
164
|
+
|
|
165
|
+
**What npm answers is checked before it is used.** Both lookups must answer
|
|
166
|
+
one version and nothing else: three numbers and an optional prerelease, on
|
|
167
|
+
one line. Any other answer (nothing, several lines, a list, text around the
|
|
168
|
+
version) stops the update before any step, with nothing changed. The message
|
|
169
|
+
names the lookup and shows the answer cut to 80 characters, with its control
|
|
170
|
+
characters shown as escapes or replaced. Run `oats update` again.
|
|
171
|
+
|
|
172
|
+
npm's own error output of a lookup is not passed to your terminal either.
|
|
173
|
+
When the first lookup fails, the message says how it ended (`exit 1`) and
|
|
174
|
+
then what npm said, cut to 300 characters and made safe the same way.
|
|
175
|
+
|
|
176
|
+
The update stops at the first step that fails. Its message names the folder
|
|
177
|
+
and the exact step to run again, says what that folder holds now (the old
|
|
178
|
+
bridge still, or no bridge), and lists the folders it did not reach. A step
|
|
179
|
+
that ends without an error but leaves another version in the folder is a
|
|
180
|
+
failure too. Run the printed step, then `oats update` again: folders already
|
|
181
|
+
at the version are left alone.
|
|
182
|
+
|
|
183
|
+
## What `oats doctor` reports
|
|
184
|
+
|
|
185
|
+
`oats doctor` prints one warning per folder whose bridge is not the kernel's
|
|
186
|
+
version, naming the folder and why it is looked at:
|
|
187
|
+
|
|
188
|
+
```text
|
|
189
|
+
WARNING: version skew — kernel 0.53.0, pi bridge 0.52.0 in /srv/pi-work (launch configuration work); run `oats update` (they publish in lockstep)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
A bridge ahead of the kernel is a skew too. `oats update` moves no bridge
|
|
193
|
+
back, and `oats doctor` does not ask the registry, so the warning says what
|
|
194
|
+
ends the skew:
|
|
195
|
+
|
|
196
|
+
```text
|
|
197
|
+
WARNING: version skew — kernel 0.52.0, pi bridge 0.53.0 in /srv/pi-work (launch configuration work); the bridge is ahead of the kernel, and `oats update` never moves a bridge back. The skew ends when the kernel is at 0.53.0 (`oats update` moves it once npm lists that version), or when the kernel's bridge is installed there by hand (docs/upgrading.md, "By hand")
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
It also warns about a folder it could not look at (one that does not
|
|
201
|
+
resolve, or a bridge that cannot be read). A folder that does not exist or
|
|
202
|
+
holds no bridge is not a skew, and it says nothing about it. The warnings are
|
|
203
|
+
in the text output only; `oats doctor --json` does not carry them.
|
|
204
|
+
|
|
205
|
+
## After a change of Node version
|
|
206
|
+
|
|
207
|
+
Two paths are written into things that outlive a command: the kernel's, and
|
|
208
|
+
the `node` that runs it. A new Node version can leave either behind.
|
|
209
|
+
|
|
210
|
+
**The kernel's path.** The CLI is an npm global package: it is installed
|
|
211
|
+
under npm's global prefix (`npm prefix -g`).
|
|
212
|
+
|
|
213
|
+
- **The prefix is outside the Node install.** The kernel's path does not
|
|
214
|
+
change with the Node version: the CLI needs no reinstall.
|
|
215
|
+
- **The prefix is the Node version's own directory**, the usual layout of a
|
|
216
|
+
version manager (mise, nvm, asdf, fnm). Every Node version then has its own
|
|
217
|
+
global packages: a new version has no `oats`, and removing the old version
|
|
218
|
+
removes the kernel with it. Four things name that kernel by its path: each
|
|
219
|
+
instance home's own `oats` (`<home>/.oats/bin/oats`), the Claude Code hooks
|
|
220
|
+
of a Claude instance, the host timer's unit, and what `oats setup` installs
|
|
221
|
+
(the turn record's capture hooks and its watcher, which name the capture
|
|
222
|
+
script inside the kernel). OATS cannot make a path inside a Node version
|
|
223
|
+
outlast that version.
|
|
224
|
+
|
|
225
|
+
Both layouts can exist on one host: check the prefix in the shell that
|
|
226
|
+
installs the CLI.
|
|
227
|
+
|
|
228
|
+
**The `node`'s path**, whatever the prefix. The Claude Code hooks of a
|
|
229
|
+
Claude instance, the host timer's unit and what `oats setup` installs also
|
|
230
|
+
record the `node` that runs them, by one rule
|
|
231
|
+
([the node a hook writes down](capabilities.md#the-node-a-hook-writes-down)):
|
|
232
|
+
|
|
233
|
+
- **On Homebrew**, the `opt` link (`<prefix>/opt/node/bin/node`) when it is
|
|
234
|
+
the `node` running the kernel. `brew upgrade node` repoints it, so the
|
|
235
|
+
recorded path outlasts the upgrade: the hooks, the timer and the capture
|
|
236
|
+
watcher need nothing done.
|
|
237
|
+
- **Otherwise**, a `node` on `PATH` that is the same file as the one running
|
|
238
|
+
the kernel. With mise that is the version's own install, which does not
|
|
239
|
+
outlast the version (other version managers were not measured).
|
|
240
|
+
- **When there is neither**, the path of the `node` as it is. A spawn, a
|
|
241
|
+
start, `oats schedule host install` and `oats setup` then warn that it is
|
|
242
|
+
not stable.
|
|
243
|
+
|
|
244
|
+
**What `oats setup` records is in your own files, not in an instance home:**
|
|
245
|
+
the capture hooks (`Stop` and `SessionEnd`) in every `~/.claude*/settings.json`
|
|
246
|
+
of the user who ran it, and the capture watcher's unit
|
|
247
|
+
(`~/Library/LaunchAgents/ai.aweb.turn-record-capture.plist` on macOS,
|
|
248
|
+
`~/.config/systemd/user/turn-record-capture.service` on Linux). No spawn,
|
|
249
|
+
start or restart writes them: only `oats setup` run again does, and it
|
|
250
|
+
replaces its own hooks and unit, it does not add a second one.
|
|
251
|
+
|
|
252
|
+
Once the recorded `node` no longer exists (an old version removed under a
|
|
253
|
+
version manager, for example), the hooks fail without a message, so the
|
|
254
|
+
instance stops reporting that it waits on you, and
|
|
255
|
+
`oats schedule host status` reports `node-missing`. The capture hooks then
|
|
256
|
+
fail at every stop of every Claude Code session of that user, and launchd or
|
|
257
|
+
systemd keeps restarting a watcher that cannot start.
|
|
258
|
+
|
|
259
|
+
**A home spawned with an oats.core that does not read `OATS_NODE_BIN`** does
|
|
260
|
+
not follow the rule. Its hooks record the path of the `node` its hook ran
|
|
261
|
+
under, which on Homebrew is the versioned keg
|
|
262
|
+
(`…/Cellar/node/<version>/bin/node`), and a start writes that again, because
|
|
263
|
+
a start runs the copy of oats.core in the home. `brew upgrade node` removes
|
|
264
|
+
the keg at once, so such a home needs the restart of step 2 after every Node
|
|
265
|
+
upgrade, until it is respawned.
|
|
266
|
+
|
|
267
|
+
So after moving to another Node version, and before removing the old one,
|
|
268
|
+
wherever a recorded path does not outlast it:
|
|
269
|
+
|
|
270
|
+
1. Where the prefix is the version's own directory, install the CLI in the
|
|
271
|
+
new version: `npm install -g @awebai/oats`.
|
|
272
|
+
2. Restart the instances, from a shell on the new version
|
|
273
|
+
(`oats session restart --home <home>`). A start writes the home's `oats`
|
|
274
|
+
and its Claude Code hooks again
|
|
275
|
+
([Configuration](configuration.md#launch-configurations)).
|
|
276
|
+
3. On a host that runs schedules, run `oats schedule host install` again,
|
|
277
|
+
from your own shell, not from an instance home. Without it,
|
|
278
|
+
`oats schedule host status` reports `oats-bin-missing` or `node-missing`
|
|
279
|
+
once the old version is removed
|
|
280
|
+
([Schedules](schedules.md#the-host-timers-unit)).
|
|
281
|
+
4. On a host where `oats setup` was run, run `oats setup` again, as the same
|
|
282
|
+
user and from your own shell. `oats setup --dry-run` prints the `node` it
|
|
283
|
+
would record and changes nothing.
|
|
284
|
+
|
|
285
|
+
Until the old version is removed, the instances and the timer keep running
|
|
286
|
+
what it holds.
|
|
287
|
+
|
|
288
|
+
## By hand
|
|
289
|
+
|
|
290
|
+
In any pi folder, with the `pi` that is launched with it:
|
|
291
|
+
|
|
292
|
+
```sh
|
|
293
|
+
PI_CODING_AGENT_DIR=<folder> pi install npm:@awebai/oats-pi@<the CLI's version>
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
`oats version` prints the CLI's version. For the default folder, leave the
|
|
297
|
+
assignment out only when your shell does not set `PI_CODING_AGENT_DIR`;
|
|
298
|
+
when it does, name the folder: `PI_CODING_AGENT_DIR="$HOME/.pi/agent"`.
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.9.
|
|
58
|
-
oats.okf: v5.0.
|
|
57
|
+
oats.framework: v1.9.4 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.0.3
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|
|
@@ -198,7 +198,7 @@ as `confirmed` or the reason it is not:
|
|
|
198
198
|
| `not-listed` | the workspace does not list the repo |
|
|
199
199
|
| `no-backlink` | no (or invalid) `oats-membership.yaml` at the member's default branch |
|
|
200
200
|
| `backlink-elsewhere` | the member names a different workspace (a case-only difference is flagged: repo paths are case-sensitive identities) |
|
|
201
|
-
| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory), or this machine's remote cache could not be written (cache) |
|
|
201
|
+
| `cannot-read` | the operator cannot read the member (auth / not-found / network / timeout / killed: the system killed git, e.g. out of memory / unknown: git failed for a reason the kernel cannot name), or this machine's remote cache could not be written (cache) |
|
|
202
202
|
|
|
203
203
|
An unconfirmed member contributes nothing but its row: its souls are invisible,
|
|
204
204
|
its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
|
package/lib/automations.mjs
CHANGED
|
@@ -38,6 +38,7 @@ import { dirname, join } from "node:path";
|
|
|
38
38
|
import { recordLocalInput } from "./local-inputs.mjs";
|
|
39
39
|
import YAML from "yaml";
|
|
40
40
|
import { parseConfigData } from "./config-data.mjs";
|
|
41
|
+
import { editLocal } from "./local-edit.mjs";
|
|
41
42
|
|
|
42
43
|
export const AUTOMATIONS_API = 1;
|
|
43
44
|
export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
|
|
@@ -361,29 +362,28 @@ function refreshViaCli(dep, io) {
|
|
|
361
362
|
// ------------------------------------------------------------ opting out here
|
|
362
363
|
|
|
363
364
|
/** Add or remove `<member>/<id>` in oats-local.yaml `<kind>s.disabled` (`triggers.disabled` or
|
|
364
|
-
* `schedules.disabled`),
|
|
365
|
-
*
|
|
366
|
-
|
|
365
|
+
* `schedules.disabled`), through the one path that rewrites that file (lib/local-edit.mjs editLocal:
|
|
366
|
+
* the deployment's local lock, the file as it is under it, the local schema, a rename): the rest of the
|
|
367
|
+
* file stays as written, comments included, and no other writer's change is dropped.
|
|
368
|
+
* `ctx`: { deployment, localPath }. → { changed, disabled } (the list now). */
|
|
369
|
+
export function setDisabledHere(ctx, kind, qid, disabled) {
|
|
367
370
|
const section = `${kind}s`;
|
|
368
|
-
|
|
369
|
-
const
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
if (problems.length) throw automationError("E_WORKSPACE_SCHEMA", `the rewritten ${localPath} would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`);
|
|
385
|
-
writeFileSync(localPath, out);
|
|
386
|
-
return { changed: true, disabled: next };
|
|
371
|
+
let list = [];
|
|
372
|
+
const { changed } = editLocal(ctx, { verb: `oats ${kind} ${disabled ? "disable" : "enable"}` }, ({ doc }) => {
|
|
373
|
+
const current = doc.getIn([section, "disabled"]);
|
|
374
|
+
list = current && typeof current.toJSON === "function" ? current.toJSON() : Array.isArray(current) ? current : [];
|
|
375
|
+
const next = disabled ? [...new Set([...list, qid])].sort() : list.filter((x) => x !== qid);
|
|
376
|
+
if (JSON.stringify(next) === JSON.stringify(list)) return null;
|
|
377
|
+
if (next.length) doc.setIn([section, "disabled"], next);
|
|
378
|
+
else if (doc.hasIn([section, "disabled"])) {
|
|
379
|
+
doc.deleteIn([section, "disabled"]);
|
|
380
|
+
const rest = doc.get(section);
|
|
381
|
+
if (rest && typeof rest.toJSON === "function" && !Object.keys(rest.toJSON() || {}).length) doc.delete(section);
|
|
382
|
+
}
|
|
383
|
+
list = next;
|
|
384
|
+
return {};
|
|
385
|
+
});
|
|
386
|
+
return { changed, disabled: list };
|
|
387
387
|
}
|
|
388
388
|
|
|
389
389
|
// ------------------------------------------------------------ writing a workspace file
|