@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.
Files changed (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. 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.67.1** ([release notes](release-notes/v0.67.1.md)).
10
- The 0.67.1 Desktop accepts OATS CLIs `>=0.26.0 <0.68.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.67.1,** in the [release notes](release-notes/): it says what to do before
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.67.1 first
23
- npm install -g @awebai/oats@0.67.1 # 1. the CLI
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
@@ -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.13.5 # bare version → resolves through the official catalog
58
- oats.okf: v5.2.1
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
- // Only a spawn or worktree hook can fail what it serves; marking others
109
- // required would promise an enforcement that has no defined moment to act.
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
  }