@awebai/oats 0.67.1 → 0.68.1
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 +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +316 -63
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- 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-notes/v0.68.0.md +504 -0
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +663 -243
- package/docs/upgrading.md +66 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- 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 +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +4 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +143 -21
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +57 -35
- package/packages/tui/lib/views/instances.mjs +48 -30
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
package/docs/upgrading.md
CHANGED
|
@@ -6,11 +6,11 @@ host that comes from it.
|
|
|
6
6
|
|
|
7
7
|
## Upgrading to the latest version
|
|
8
8
|
|
|
9
|
-
The latest version is **OATS 0.
|
|
10
|
-
The 0.
|
|
9
|
+
The latest version is **OATS 0.68.1** ([release notes](release-notes/v0.68.1.md)).
|
|
10
|
+
The 0.68.1 Desktop accepts OATS CLIs `>=0.26.0 <0.69.0`.
|
|
11
11
|
|
|
12
12
|
**First, read the `## Upgrade` section of every release after yours, up to
|
|
13
|
-
0.
|
|
13
|
+
0.68.1,** in the [release notes](release-notes/): it says what to do before
|
|
14
14
|
the CLI changes, and what else must change with it (the Desktop, another
|
|
15
15
|
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
16
16
|
names the releases that ask for more than the steps below. `oats version`
|
|
@@ -19,8 +19,8 @@ prints the version you have.
|
|
|
19
19
|
Then, on each host:
|
|
20
20
|
|
|
21
21
|
```sh
|
|
22
|
-
# 0. where the Desktop is installed: Desktop 0.
|
|
23
|
-
npm install -g @awebai/oats@0.
|
|
22
|
+
# 0. where the Desktop is installed: Desktop 0.68.1 first
|
|
23
|
+
npm install -g @awebai/oats@0.68.1 # 1. the CLI
|
|
24
24
|
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
25
25
|
oats doctor # 3. in the same deployment
|
|
26
26
|
```
|
|
@@ -66,7 +66,8 @@ before either.
|
|
|
66
66
|
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
67
67
|
the bridge, never a package. A deployment's capabilities come from the
|
|
68
68
|
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
69
|
-
([Packages](packages.md)).
|
|
69
|
+
([Packages](packages.md)). To move an existing stopped home to those locked
|
|
70
|
+
versions, follow [the package-module deploy step](#moving-existing-homes-to-locked-package-versions).
|
|
70
71
|
|
|
71
72
|
Run steps 2 and 3 in every deployment on the host, or name one from anywhere
|
|
72
73
|
with `oats update --dir <deployment>`.
|
|
@@ -100,6 +101,61 @@ Versions are compared as semver, so a prerelease is below its release:
|
|
|
100
101
|
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
101
102
|
installed over it.
|
|
102
103
|
|
|
104
|
+
## Moving existing homes to locked package versions
|
|
105
|
+
|
|
106
|
+
After changing a package pin and running `oats sync`, move each existing home
|
|
107
|
+
explicitly. Run these from its deployment or a parent's home:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
oats instance stop <instance>
|
|
111
|
+
oats instance upgrade <instance> --plan --json
|
|
112
|
+
oats instance upgrade <instance> --plan-revision <revision> --idempotency-key <key> --json
|
|
113
|
+
oats session start --home <absolute-home>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Read the plan before applying it. It lists every moving package module,
|
|
117
|
+
skill/inject/hook changes and provider adoption decisions, modules kept
|
|
118
|
+
because their package is no longer locked, and member drift for information.
|
|
119
|
+
One provider refusal refuses the whole move. A running or unreadable session
|
|
120
|
+
refuses with `E_SESSION_RUNNING`; stop it first. A stale plan returns
|
|
121
|
+
`E_PLAN_STALE` and a fresh plan to review.
|
|
122
|
+
|
|
123
|
+
Modules move whole, with skills, instructions and hooks recomposed from the
|
|
124
|
+
same sources as spawn. The soul body stays at its recorded commit, and member
|
|
125
|
+
modules stay unchanged. `oats status` drift clears after the move. Start and
|
|
126
|
+
restart keep the recorded copies; when they lag the lock they report drift
|
|
127
|
+
and print the stop/upgrade command.
|
|
128
|
+
|
|
129
|
+
Before commit, a failure restores composed home bytes only when no provider
|
|
130
|
+
apply hook succeeded and no outcome is uncertain. A non-zero result must be
|
|
131
|
+
observed and recorded in the same invocation; a killed or interrupted hook
|
|
132
|
+
can already have adopted host state even when no success was recorded. A hook
|
|
133
|
+
reporting failure is responsible for leaving no provider effects of its own.
|
|
134
|
+
After success or an uncertain outcome, failure records `partial` and moves
|
|
135
|
+
forward only: retry with the same `--idempotency-key` to finish pending work,
|
|
136
|
+
including an uncertain idempotent hook. A refusal on retry stays partial.
|
|
137
|
+
Start refuses with `E_UPGRADE_PARTIAL` until it finishes. If it cannot finish,
|
|
138
|
+
respawn the instance. Do not restore old modules by hand under adopted or
|
|
139
|
+
possibly adopted host registrations.
|
|
140
|
+
|
|
141
|
+
After swap and baseline, the receipt commits before publishing the success
|
|
142
|
+
event and cleaning staging.
|
|
143
|
+
If cleanup fails, the upgrade is complete and the same-key retry cleans up
|
|
144
|
+
only, without hooks or copies. Start is allowed with one warning naming that
|
|
145
|
+
retry. A new upgrade or undo plan refuses until cleanup finishes. Retirement
|
|
146
|
+
keeps its normal behavior; it does not finish upgrade cleanup.
|
|
147
|
+
|
|
148
|
+
The latest previous state is kept in `.oats/previous/<receipt>/`. To request
|
|
149
|
+
the reverse move, use `oats instance upgrade <instance> --undo --plan --json`,
|
|
150
|
+
then apply with `--undo --plan-revision <revision> --idempotency-key <key>`.
|
|
151
|
+
Undo verifies that copy and asks the version being restored to adopt the
|
|
152
|
+
current state through its own `upgrade` hook. A version lacking that hook
|
|
153
|
+
cannot be restored through undo; respawn instead. Each successful move replaces
|
|
154
|
+
the one previous state, and retirement carries it into recovery.
|
|
155
|
+
|
|
156
|
+
This act handles one local home at a time. A deployment loops over its homes;
|
|
157
|
+
it does not upgrade automatically or through `--server`.
|
|
158
|
+
|
|
103
159
|
## Coming from an older version
|
|
104
160
|
|
|
105
161
|
Read the `## Upgrade` section of every release after yours, up to the
|
|
@@ -110,6 +166,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
|
|
|
110
166
|
must follow is in its release's Upgrade section whether or not it is listed
|
|
111
167
|
here.
|
|
112
168
|
|
|
169
|
+
- **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the CLI: a 0.67 Desktop refuses a 0.68
|
|
170
|
+
CLI. The catalog pins new package versions; after `oats sync`, a stopped
|
|
171
|
+
home can move to them with `oats instance upgrade` instead of a respawn
|
|
172
|
+
([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
|
|
113
173
|
- **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
|
|
114
174
|
0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
|
|
115
175
|
platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
|
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.
|
|
58
|
-
oats.okf: v5.
|
|
57
|
+
oats.framework: v1.14.1 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.3.0
|
|
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
|
|
@@ -11,10 +11,11 @@
|
|
|
11
11
|
* inside the capability), and a provider payload's value against the manifest's
|
|
12
12
|
* `settings.<key>.values`. Dependency-free. */
|
|
13
13
|
|
|
14
|
-
export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree"]);
|
|
14
|
+
export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree", "upgrade"]);
|
|
15
15
|
/** The events whose hook may be declared `required: true`: each has a moment
|
|
16
16
|
* that can fail closed (a spawn's transaction; `oats worktree add`, which
|
|
17
|
-
* removes the tree it made).
|
|
17
|
+
* removes the tree it made). Upgrade instead enforces its own adoption
|
|
18
|
+
* protocol independently of the `required` flag. */
|
|
18
19
|
export const REQUIRABLE_HOOKS = new Set(["spawn", "worktree"]);
|
|
19
20
|
export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
|
|
20
21
|
export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
|
|
@@ -105,9 +106,9 @@ export function manifestContract(m) {
|
|
|
105
106
|
if (isObject(value) && value.required !== undefined && typeof value.required !== "boolean") bad(`${at}/required`, `hook "${event}": "required" must be a boolean`);
|
|
106
107
|
// An unknown event its author declared essential cannot be skipped.
|
|
107
108
|
else if (!known && isObject(value) && value.required === true) bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`);
|
|
108
|
-
//
|
|
109
|
-
//
|
|
110
|
-
else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
|
|
109
|
+
// Upgrade has its own adoption protocol; the other events outside spawn
|
|
110
|
+
// and worktree have no transaction where `required` can fail closed.
|
|
111
|
+
else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (upgrade uses its adoption protocol; retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
|
|
111
112
|
if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
|
|
112
113
|
if (!known && problems.length === sound) warnings.push({ code: "hook-event-unsupported", pointer: at, message: `capability ${id} declares hook "${event}", which this kernel does not run; it is ignored (this kernel runs ${[...APPROVED_HOOKS].join(", ")})` });
|
|
113
114
|
}
|