@awebai/oats 0.66.0 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  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 +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  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-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -9,7 +9,7 @@
9
9
  * maxAge seconds the kernel may reuse remote observations on a miss (a local inspect only)
10
10
  * exec how the CLI is run (cli-adapter.mjs `runJson`'s `io.exec`); without it, execFile
11
11
  *
12
- * request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills? }
12
+ * request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills? }
13
13
  * context { workspace, cli, agents, instances, localCwd, catalogKey }
14
14
  *
15
15
  * It resolves the kernel's result with `observedAt` and `refreshing`, and throws an Error with a stable `code`
@@ -28,7 +28,7 @@ import { cliCapability, operationArgs } from './cli-adapter.mjs';
28
28
  import { inspectKey } from './inspect-cache.mjs';
29
29
  import { observationData } from './deployment-data.mjs';
30
30
  import { OBSERVE_MAX_AGE_FEATURE } from './deployment-contract.mjs';
31
- import { hostComposes, hostReportsSkills } from './composed-gate.mjs';
31
+ import { hostComposes, hostReportsSkills, hostComposesSkills } from './composed-gate.mjs';
32
32
  import { canAddressRemote, unaddressableSentence, hostReason, shownLabel, unroutableReason } from './remote-address.mjs';
33
33
 
34
34
  const fail = (message, code = 'E_BAD_ARGS') => { throw Object.assign(new Error(message), { code }); };
@@ -37,7 +37,7 @@ const TEAM_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
37
37
 
38
38
  /** Admit a capability request in its context, or throw. `actions`: the actions the caller serves (an inspect
39
39
  * boundary serves only 'inspect'); any other is the same refusal as an unknown one. Returns what the call needs:
40
- * `{ action, server, label, refresh, instructions, skills, soul, agentsRoot, home, context, key }`, where
40
+ * `{ action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key }`, where
41
41
  * `context` is the --dir the CLI runs in and `key` the inspect cache's key for the subject. */
42
42
  export function capabilityAdmission(request, { workspace, cli, agents = [], instances = [], catalogKey = null }, actions = ['inspect', 'run']) {
43
43
  if (!workspace) fail('Select a known workspace', 'E_WORKSPACE_UNKNOWN');
@@ -74,6 +74,10 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
74
74
  // reports them (composed-gate.mjs hostReportsSkills); otherwise it is dropped and the read is today's.
75
75
  if (request.skills !== undefined && (action !== 'inspect' || typeof request.skills !== 'boolean' || selector.soul === undefined)) fail('Invalid skills flag');
76
76
  const skills = request.skills === true && (!server || hostReportsSkills(cli, workspace.group));
77
+ // composedSkills (feature soul-composed-skills): every skill a spawn gives the instance (`souls[0].composedSkills`),
78
+ // the same way again: inspect of a soul only; routed only when the held row says the host lists them (hostComposesSkills).
79
+ if (request.composedSkills !== undefined && (action !== 'inspect' || typeof request.composedSkills !== 'boolean' || selector.soul === undefined)) fail('Invalid composed skills flag');
80
+ const composedSkills = request.composedSkills === true && (!server || hostComposesSkills(cli, workspace.group));
77
81
  let soul, agentsRoot, home, key;
78
82
  let context = workspace.scope;
79
83
  if (selector.home !== undefined) {
@@ -95,17 +99,17 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
95
99
  const agent = matches[0];
96
100
  soul = agent.name; agentsRoot = agent.agentsRoot;
97
101
  context = dirname(agentsRoot);
98
- key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills });
102
+ key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills, composedSkills });
99
103
  } else fail('Select a soul or an instance home (inspection has no scope subject)');
100
- return { action, server, label, refresh, instructions, skills, soul, agentsRoot, home, context, key };
104
+ return { action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key };
101
105
  }
102
106
 
103
107
  /** The CLI call's options for an admitted request (cli-adapter.mjs `cliCapability`). */
104
- export function capabilityCall(request, { action, server, refresh, instructions, skills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
108
+ export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
105
109
  return {
106
110
  action, context, server, soul, agentsRoot, home,
107
111
  operation: request.operation, ...(request.args !== undefined ? { args: request.args } : {}), ...(instructions ? { instructions } : {}),
108
- ...(skills ? { skills } : {}),
112
+ ...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}),
109
113
  localCwd: server ? localCwd : context || workspace.scope,
110
114
  // --max-age travels only on a LOCAL inspect (reuse is local only: the kernel refuses it with --server)
111
115
  // and only when the probe declared observe-max-age (the adapter's call).
@@ -19,11 +19,11 @@ export const INSPECT_CACHE_TTL_MS = HELD_TTL_MS;
19
19
  /** Every field travels, absent ones as null: two subjects that differ in any
20
20
  coordinate never share an entry (same soul name under two agents roots, the
21
21
  same home before and after a restart, a catalog that changed under a soul). */
22
- export function inspectKey({ deployment, server = null, kind, soul, agentsRoot, catalogKey, home, instance, identity, instructions = false, skills = false }) {
22
+ export function inspectKey({ deployment, server = null, kind, soul, agentsRoot, catalogKey, home, instance, identity, instructions = false, skills = false, composedSkills = false }) {
23
23
  if (kind !== 'soul' && kind !== 'home') throw Object.assign(new Error('Inspect cache keys name a soul or a home'), { code: 'E_BAD_ARGS' });
24
24
  const part = value => value === undefined ? null : value;
25
25
  return JSON.stringify([part(deployment), part(server), kind, part(soul), part(agentsRoot), part(catalogKey), part(home), part(instance),
26
- Array.isArray(identity) ? identity.map(part) : part(identity), instructions === true, skills === true]);
26
+ Array.isArray(identity) ? identity.map(part) : part(identity), instructions === true, skills === true, composedSkills === true]);
27
27
  }
28
28
 
29
29
  export function createInspectCache({ limit = INSPECT_CACHE_LIMIT, ttlMs = INSPECT_CACHE_TTL_MS, now = () => Date.now() } = {}) {
@@ -0,0 +1,28 @@
1
+ /** The instance-name rule a typed name follows before it reaches `oats spawn --name`: the soul's role is its
2
+ * suffix. One copy for the clients (the Desktop's spawn dialog today); the kernel keeps its own for the
3
+ * suggestion it will make, and test/client-instance-name.test.mjs pins the cases both must agree on.
4
+ *
5
+ * A soul's role is the last word of its name: `oats-desktop-expert` → `expert`, `code-reviewer` → `reviewer`,
6
+ * `cloner` → `cloner`. A package qualifier is dropped first (what follows the last `/` or `--`, as the
7
+ * identity marks read a name: renderer/identity-marks.mjs markText), so `acme-pkg--keeper` → `keeper`.
8
+ * A typed name gets the role once: `desktop-improvements` → `desktop-improvements-expert`, while
9
+ * `desktop-improvements-expert` and `expert` stay as typed. Nothing here validates a name: the
10
+ * kernel owns that grammar and refuses a name that breaks it (E_INSTANCE_NAME_INVALID).
11
+ * DOM-free and import-free, with no module state. */
12
+
13
+ /** The role of a soul name: its last `-`-separated word after any package qualifier; '' when there is none. */
14
+ export function soulRole(soulName) {
15
+ if (typeof soulName !== 'string') return '';
16
+ const slash = soulName.lastIndexOf('/'), dashes = soulName.lastIndexOf('--');
17
+ const bare = soulName.slice(Math.max(slash < 0 ? 0 : slash + 1, dashes < 0 ? 0 : dashes + 2));
18
+ return bare.slice(bare.lastIndexOf('-') + 1);
19
+ }
20
+
21
+ /** `name` with the role of `soulName` as its suffix, unless it already ends in `-<role>` or is the role itself;
22
+ * the name as given when the soul has no role, and '' for no name (the kernel numbers it). */
23
+ export function nameWithRole(name, soulName) {
24
+ if (typeof name !== 'string' || !name) return '';
25
+ const role = soulRole(soulName);
26
+ if (!role || name === role || name.endsWith(`-${role}`)) return name;
27
+ return `${name}-${role}`;
28
+ }
@@ -1,5 +1,6 @@
1
1
  import { HERDR_REMOVED } from "./terminal-contract.mjs";
2
2
  import { requireTerms } from './client-terms.mjs';
3
+ import { SOUL_COLORS } from './soul-colors.mjs';
3
4
 
4
5
  export function runtimeState(instance) {
5
6
  return instance.running === true ? "running" : instance.running === false ? "stopped" : "unknown";
@@ -15,6 +16,16 @@ export function byRuntimeState(a, b) {
15
16
  return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
16
17
  }
17
18
 
19
+ /** Which colour an instance's row shows (feature instance-color, awebai/oats#1421 §2): the row's own `color`
20
+ * when it is a palette name exactly (soul-colors.mjs SOUL_COLORS, which the kernel's INSTANCE_COLORS equals),
21
+ * else null, and null draws the row as it looks without one. The one rule every client draws by: the kernel
22
+ * already validated what it relays, and anything else a row carries is no colour. Colour never says a
23
+ * state alone: a client's mark keeps the state by its shape. */
24
+ export function instanceColor(row) {
25
+ const color = row?.color;
26
+ return typeof color === 'string' && SOUL_COLORS.includes(color) ? color : null;
27
+ }
28
+
18
29
  /** The words for an instance's siblings (#1312; the list `instanceSiblings` answers, instance-tree.mjs):
19
30
  * null for none, else `sibling of a`, `sibling of a and b`, `sibling of a, b and c`, the names in the
20
31
  * order given. The same in every client. */
@@ -1,5 +1,5 @@
1
1
  /** The keys both clients share: the leader, the table read after it, the plain keys of the list
2
- * of instances, and the chords. Written down once, here; the Desktop and the TUI read their defaults
2
+ * of instances, the chords, and the palette's own keys. Written down once, here; the Desktop and the TUI read their defaults
3
3
  * from it (packages/tui/lib/actions.mjs LEADER is LEADER_TABLE, and the TUI's test
4
4
  * packages/tui/test/keymap.test.mjs fails on a `does` the TUI does not handle).
5
5
  *
@@ -8,31 +8,44 @@
8
8
  * Key ids are the TUI's spelling (packages/tui/lib/term/keys.mjs keyId): one character as itself,
9
9
  * case kept (`n`, `N`, `|`, `?`, `/`, `-`); named keys `up` `down` `left` `right` `tab` `escape`
10
10
  * `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+` / `shift+`
11
- * prefixes, in that order. A chord adds two: `shift+` with Ctrl and a letter (`ctrl+shift+k`, which
12
- * the TUI reads only under the kitty keyboard protocol), and `cmd+`, first, for macOS's Command
13
- * (`cmd+k`, the Desktop's ⌘K), which a terminal never passes to a program.
11
+ * prefixes, in that order. A chord adds two: `shift+` with Ctrl or Alt and a letter or an arrow
12
+ * (`ctrl+alt+shift+e`, `alt+shift+up`), and `cmd+`, first, for macOS's Command (`cmd+k`, the
13
+ * Desktop's ⌘K), which a terminal never passes to a program.
14
14
  *
15
- * leaderKey(isMac) -> the leader's key id on that platform "ctrl+\\" / "alt+o"
15
+ * leaderKey(isMac) -> the leader's key id on that platform "ctrl+x" on both
16
16
  * leaderDoes(key) -> what the leader then does for a key id, or null
17
17
  * plainKeys(does) -> the plain key ids of an action (empty when it has none)
18
18
  * leaderRows() -> LEADER_TABLE
19
- * chordKey(does, isMac) -> the chord's key id on that platform, or null
19
+ * chordKey(does, isMac, family) -> the chord's key id on that platform and in that family, or null
20
+ * chordKeyOf(entry, isMac, family) -> the same for a CHORDS row (null where the row has none)
21
+ * doesLabel(does) -> an action's label (its LEADER_TABLE row's, else its CHORDS row's), or null
22
+ * paletteKey(does, isMac) -> the palette's own key id on that platform, or null
20
23
  *
21
- * `does` names an action, not a client's code: each client maps it to its own. */
24
+ * `does` names an action, not a client's code: each client maps it to its own. Its label, the words a
25
+ * help names it by, is its LEADER_TABLE row's, else its CHORDS row's (`doesLabel`): a CHORDS row carries
26
+ * a label only for an action the leader has no key for. The TUI's help reads it; the Desktop names its
27
+ * actions in its own words (packages/desktop/renderer/leader-keys.mjs). */
22
28
 
23
- /** The leader per platform: Ctrl+\ on macOS, Alt+O elsewhere. */
24
- export const LEADER = Object.freeze({ mac: "ctrl+\\", other: "alt+o" });
29
+ /** The leader per platform: Ctrl+X on both, as Emacs has it (#1433). Without the kitty keyboard
30
+ * protocol it is one byte, 0x18, in every terminal; pressed twice it sends that byte to the program
31
+ * (the shell's Ctrl+X Ctrl+E, nano's exit). The Desktop leaves it to Cut in an editable field on
32
+ * Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader"). */
33
+ export const LEADER = Object.freeze({ mac: "ctrl+x", other: "ctrl+x" });
25
34
 
26
35
  /** The keys read after the leader, in the TUI's order, and what each does. `terminal`: named in
27
36
  * the hint only while a terminal is open. The leader pressed twice is not here: it is the user's
28
- * key, and each client says what it does. */
37
+ * key, and each client says what it does. ↑ and ↓ move to the previous and the next workspace of
38
+ * the sidebar's list (`workspace-previous`, `workspace-next`); the previous and the next instance
39
+ * are the chords' alone (CHORDS `previous`, `next`), which carry their own labels for it. Tab and
40
+ * Shift+Tab go to the next and the previous group of a split, as the chords `group-next` and
41
+ * `group-previous` do. */
29
42
  export const LEADER_TABLE = Object.freeze([
30
43
  { keys: ["k", "space"], does: "palette", label: "palette" },
31
44
  { keys: ["1"], does: "instances", label: "instances" },
32
45
  { keys: ["2"], does: "souls", label: "souls" },
33
46
  { keys: ["3"], does: "capabilities", label: "capabilities" },
34
- { keys: ["up"], does: "previous", label: "previous instance" },
35
- { keys: ["down"], does: "next", label: "next instance" },
47
+ { keys: ["up"], does: "workspace-previous", label: "previous workspace" },
48
+ { keys: ["down"], does: "workspace-next", label: "next workspace" },
36
49
  { keys: ["z"], does: "zoom", label: "zoom", terminal: true },
37
50
  { keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
38
51
  { keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
@@ -40,6 +53,7 @@ export const LEADER_TABLE = Object.freeze([
40
53
  { keys: ["|"], does: "split-right", label: "split right", terminal: true },
41
54
  { keys: ["-"], does: "split-down", label: "split down", terminal: true },
42
55
  { keys: ["tab"], does: "group-next", label: "next group", terminal: true },
56
+ { keys: ["shift+tab"], does: "group-previous", label: "previous group", terminal: true },
43
57
  { keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
44
58
  { keys: ["x"], does: "group-close", label: "close group", terminal: true },
45
59
  { keys: ["X"], does: "stop", label: "stop" },
@@ -86,23 +100,93 @@ export const PLAIN_KEYS = Object.freeze([
86
100
  { does: "help", keys: ["?"] },
87
101
  ].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
88
102
 
89
- /** The chords: one key that does what the leader then a key does, the Desktop's direct chords whose
90
- * action the TUI has too, per platform (`mac`, `other`). The Desktop's DEFAULT_KEYMAP reads these
91
- * entries from here (docs/desktop-keyboard.md). The TUI takes the `other` ones, and the `mac` ones
92
- * without `cmd+`, while the terminal confirms the kitty keyboard protocol (docs/tui.md, "Chords"),
93
- * as extras: the leader stays the key that always works. The Desktop's Ctrl+1/2/3 (the stages) are
94
- * the Desktop's own and are not here. */
103
+ /** The chords: one key that does what the leader then a key does, from every focus, the same in
104
+ * both clients, per platform (`mac`) and, on Linux and Windows, per chord family (`alt`, `other`,
105
+ * `shift`: CHORD_FAMILIES). Three have no leader key: `previous` and `next` (the previous / next
106
+ * instance, whose `label` is here, since no LEADER_TABLE row names them) and `edit-instance`. The
107
+ * Desktop's DEFAULT_KEYMAP reads these entries from here (CHORDS_READ, docs/desktop-keyboard.md); the
108
+ * TUI binds the family's ones, and the `mac` ones without `cmd+`, from every focus (docs/tui.md,
109
+ * "Chords"). The leader stays the key that always works: help, the views and the acts (stop,
110
+ * restart, start, retire) are reached by it alone.
111
+ *
112
+ * `alt`, the default family (the product owner's call, 2026-10-22; the maintainer's defaults, f592e979): Alt with
113
+ * a letter or a digit for an action, Alt with an arrow to move between tabs (←/→) and workspaces
114
+ * (↑/↓), Alt+Shift with an arrow between groups (←/→) and instances (↑/↓). These take keys a program
115
+ * in a terminal reads (readline's M-b, M-f and M-digit, an agent's Alt+P); the program still gets
116
+ * each from Esc, then the key, or the user picks Ctrl+Alt (docs/desktop-keyboard.md, the collision
117
+ * table). Alt+letter is ESC then the letter in every terminal, and an Alt arrow has a sequence of its
118
+ * own (`CSI 1;3A`, `CSI 1;4A` with Shift), so all of them reach the TUI with or without the kitty
119
+ * keyboard protocol. A row without an `alt` key keeps its `other` one there.
120
+ *
121
+ * `other`, the Ctrl+Alt family, the option for whoever needs Alt in their programs: Ctrl+Alt with a
122
+ * letter or a digit for an action and Alt+Shift with an arrow to move. It leaves Alt alone, the Alt
123
+ * arrows included: the workspace moves have no chord there (`other: null`, and none in `shift`),
124
+ * so Alt+↑/↓ reach the program in a terminal; the leader's ↑/↓ move between workspaces in every
125
+ * family. A Ctrl+Alt chord reaches the TUI only under the kitty keyboard protocol (ESC then Ctrl+K
126
+ * is what Ctrl+Alt+K sends without it). Its keys are those from before the Alt family, and the
127
+ * previous group, whose Alt+Shift+← is the previous tab's here, is Ctrl+Alt+Shift+A, the next
128
+ * group's Ctrl+Alt+A with Shift.
129
+ *
130
+ * `shift` is the row's key in the Ctrl+Shift family, the option a user picks in keys.json
131
+ * (packages/client/keys-file.mjs) for a terminal that passes Ctrl+Shift apart from Ctrl: foot and
132
+ * Alacritty (docs/tui.md, "Which family for my terminal"). Seven rows move (K palette, P spawn,
133
+ * S workspaces, M zoom, W close, E split right, D split down: the maintainer's cut, a43470ce); the
134
+ * others keep their `other` key: the Alt+Shift arrows, since Ctrl+Shift+arrow selects text in
135
+ * inputs and editors; Ctrl+Alt+1–9, since Ctrl+Shift+digit is a shifted symbol on most layouts;
136
+ * the groups and filter, whose Ctrl+Shift A and F a terminal or an agent takes; and edit-instance.
137
+ *
138
+ * On macOS there is no family and `mac` is the only key. The letters and digits are held by ⌘ (⌘⌥
139
+ * for the rows new in phase 3), and the moves between tabs, groups and workspaces by ⌥ with an arrow
140
+ * (the product owner's call, 2026-10-23): ⌥←/→ the tabs, ⌥⇧←/→ the groups, ⌥↑/↓ the workspaces; ⌥⌘↑/↓ stay the
141
+ * instances. ⌥ with a letter or a digit types a character on many layouts (⌥2 is @ on a Spanish
142
+ * one), so no row takes it. ⌥←/→ are the word moves of macOS text fields and of a shell in a
143
+ * terminal: the clients give way in an editable field (docs/desktop-keyboard.md), and the TUI,
144
+ * which binds the `mac` keys without `cmd+`, reads them from every focus. `tab-N` shows the Nth tab
145
+ * of the focused group, `tab-9` its last. The Desktop's Ctrl+Tab, Ctrl+1/2/3 (the stages) and Ctrl+, are the Desktop's own and are
146
+ * not here. */
95
147
  export const CHORDS = Object.freeze([
96
- { does: "palette", mac: "cmd+k", other: "ctrl+shift+k" },
97
- { does: "spawn", mac: "cmd+p", other: "ctrl+shift+p" },
98
- { does: "tab-next", mac: "ctrl+tab", other: "ctrl+tab" },
99
- { does: "tab-previous", mac: "ctrl+shift+tab", other: "ctrl+shift+tab" },
100
- { does: "close-terminal", mac: "cmd+w", other: "ctrl+shift+w" },
101
- { does: "filter", mac: "cmd+f", other: "ctrl+shift+f" },
102
- { does: "split-right", mac: "cmd+\\", other: "ctrl+shift+e" },
103
- { does: "split-down", mac: "cmd+shift+\\", other: "ctrl+shift+o" },
148
+ { does: "palette", mac: "cmd+k", alt: "alt+k", other: "ctrl+alt+k", shift: "ctrl+shift+k" },
149
+ { does: "spawn", mac: "cmd+p", alt: "alt+p", other: "ctrl+alt+p", shift: "ctrl+shift+p" },
150
+ { does: "workspaces", mac: "cmd+alt+o", alt: "alt+o", other: "ctrl+alt+o", shift: "ctrl+shift+s" },
151
+ { does: "previous", mac: "cmd+alt+up", other: "alt+shift+up", label: "previous instance" },
152
+ { does: "next", mac: "cmd+alt+down", other: "alt+shift+down", label: "next instance" },
153
+ // The Alt family's alone on Linux and Windows: the others leave Alt+↑/↓ to the program.
154
+ { does: "workspace-previous", mac: "alt+up", alt: "alt+up", other: null, shift: null },
155
+ { does: "workspace-next", mac: "alt+down", alt: "alt+down", other: null, shift: null },
156
+ { does: "tab-previous", mac: "alt+left", alt: "alt+left", other: "alt+shift+left" },
157
+ { does: "tab-next", mac: "alt+right", alt: "alt+right", other: "alt+shift+right" },
158
+ ...Array.from({ length: 9 }, (_, i) => ({ does: `tab-${i + 1}`, mac: `cmd+alt+${i + 1}`, alt: `alt+${i + 1}`, other: `ctrl+alt+${i + 1}` })),
159
+ { does: "zoom", mac: "cmd+alt+z", alt: "alt+z", other: "ctrl+alt+z", shift: "ctrl+shift+m" },
160
+ { does: "close-terminal", mac: "cmd+w", alt: "alt+w", other: "ctrl+alt+w", shift: "ctrl+shift+w" },
161
+ { does: "split-right", mac: "cmd+\\", alt: "alt+e", other: "ctrl+alt+e", shift: "ctrl+shift+e" },
162
+ { does: "split-down", mac: "cmd+shift+\\", alt: "alt+shift+e", other: "ctrl+alt+shift+e", shift: "ctrl+shift+d" },
163
+ { does: "group-previous", mac: "alt+shift+left", alt: "alt+shift+left", other: "ctrl+alt+shift+a" },
164
+ { does: "group-next", mac: "alt+shift+right", alt: "alt+shift+right", other: "ctrl+alt+a" },
165
+ { does: "filter", mac: "cmd+f", alt: "alt+f", other: "ctrl+alt+f" },
166
+ // The Desktop's alone for now (#1421): its name and colour dialog. No leader key; the TUI has no
167
+ // such action, so it binds no key for it (chordKeys skips a `does` it does not handle). Not one of
168
+ // the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both of those (the maintainer's ruling).
169
+ { does: "edit-instance", mac: "cmd+alt+r", alt: "alt+r", other: "ctrl+alt+r" },
170
+ ].map((entry) => Object.freeze({ ...entry, alt: entry.alt ?? entry.other, shift: entry.shift ?? entry.other })));
171
+
172
+ /** The palette's own keys, read only while the palette is open: there they win over every binding
173
+ * (the Desktop's ⌘N, `app.chooseSoul`; the chords `previous` and `next`), so they are not CHORDS,
174
+ * which are bound from every focus. The selection goes to the first row of the next group, or of
175
+ * the one before, and wraps (docs/tui.md, "The palette"; packages/desktop/docs/desktop-keyboard.md).
176
+ * On macOS the TUI has none: a terminal never passes ⌘. The previous group is ⌥⌘N, not ⇧⌘N: that is
177
+ * the Desktop's File → New Window, a key its menu shows, which the palette does not shadow. */
178
+ export const PALETTE_KEYS = Object.freeze([
179
+ { does: "palette-next-group", mac: "cmd+n", other: "alt+shift+down" },
180
+ { does: "palette-previous-group", mac: "cmd+alt+n", other: "alt+shift+up" },
104
181
  ].map((entry) => Object.freeze({ ...entry })));
105
182
 
183
+ /** The chord families on Linux and Windows: the default, Alt, and the two options (CHORDS `alt`,
184
+ * `other` and `shift`), with the name a client shows for each. A user who never chose binds the
185
+ * default; one who chose Ctrl+Alt keeps it (keys.json `chords`, packages/client/keys-file.mjs). */
186
+ export const CHORD_FAMILIES = Object.freeze(["alt", "ctrl+alt", "ctrl+shift"]);
187
+ export const DEFAULT_CHORD_FAMILY = "alt";
188
+ export const CHORD_FAMILY_LABELS = Object.freeze({ alt: "Alt", "ctrl+alt": "Ctrl+Alt", "ctrl+shift": "Ctrl+Shift" });
189
+
106
190
  const NONE = Object.freeze([]);
107
191
 
108
192
  /** The leader's key id on macOS (`true`) or elsewhere. */
@@ -126,8 +210,29 @@ export function leaderRows() {
126
210
  return LEADER_TABLE;
127
211
  }
128
212
 
129
- /** The key id of the chord that does `does` on macOS (`true`) or elsewhere, or null when none does. */
130
- export function chordKey(does, isMac) {
213
+ /** The key id of the CHORDS row `entry` on macOS (`true`) or elsewhere, in `family` (CHORD_FAMILIES;
214
+ * anything else is the default, Alt), which macOS ignores; null where the row has no key (the
215
+ * workspace moves outside the Alt family). */
216
+ export function chordKeyOf(entry, isMac, family = DEFAULT_CHORD_FAMILY) {
217
+ if (isMac) return entry.mac ?? null;
218
+ return (family === "ctrl+shift" ? entry.shift : family === "ctrl+alt" ? entry.other : entry.alt) ?? null;
219
+ }
220
+
221
+ /** The key id of the chord that does `does` on macOS (`true`) or elsewhere, in `family` (chordKeyOf),
222
+ * or null when none does there. */
223
+ export function chordKey(does, isMac, family = DEFAULT_CHORD_FAMILY) {
131
224
  const entry = CHORDS.find((each) => each.does === does);
225
+ return entry === undefined ? null : chordKeyOf(entry, isMac, family);
226
+ }
227
+
228
+ /** The label of the action `does`: its LEADER_TABLE row's, else its CHORDS row's, else null (an action
229
+ * no table names in words, such as `edit-instance`, or none). */
230
+ export function doesLabel(does) {
231
+ return LEADER_TABLE.find((row) => row.does === does)?.label ?? CHORDS.find((entry) => entry.does === does)?.label ?? null;
232
+ }
233
+
234
+ /** The key id of the palette's own key that does `does` on macOS (`true`) or elsewhere, or null. */
235
+ export function paletteKey(does, isMac) {
236
+ const entry = PALETTE_KEYS.find((each) => each.does === does);
132
237
  return entry === undefined ? null : isMac ? entry.mac : entry.other;
133
238
  }
@@ -0,0 +1,126 @@
1
+ /** keys.json, the one preference both clients share about their keys: which chord family they bind
2
+ * on Linux and Windows (packages/client/keymap.mjs CHORD_FAMILIES). It is `config/keys.json` in OATS's
3
+ * own directory of this user, beside the TUI's tui.json, and resolved the same way: `$OATS_HOME_DIR`
4
+ * when that is set and not empty, else `<home>/.oats`. Its shape: `{ "chords": "alt" | "ctrl+alt" | "ctrl+shift" }`.
5
+ * No file, or no `chords` in it, is no choice: the default, Alt. A `chords` written is a choice, and
6
+ * stays one when the default changes (a user who chose Ctrl+Alt keeps it).
7
+ *
8
+ * The file is the clients'; the kernel never reads it. Each client does its own IO and hands the text
9
+ * here: the TUI at its start, the Desktop in its main process, which hands the family to its renderer
10
+ * and is the one that writes the file (keysWithFamily). Pure: no fs, no state.
11
+ *
12
+ * keysPath(env, home) -> the file's path
13
+ * chordFamilyFrom(bytes, error) -> { family, why }: the family to bind, and why it is the default
14
+ * chordFamilyNote(read) -> the one line a client shows when the file was not taken, or null
15
+ * keysWithFamily(bytes, family) -> the file's new text: `chords` set, every other key kept, or a
16
+ * KeysUnwritable error when that cannot be done
17
+ *
18
+ * Both clients hand over the file's bytes, not their own reading of them, so the same bytes mean the
19
+ * same family in both: UTF-8 (RFC 8259), a byte-order mark ignored, anything else not text.
20
+ *
21
+ * Every way the file can fail means the default, Alt: none is an error the user must clear. An older
22
+ * client, which knows no `alt`, reads `"chords": "alt"` as an unknown value: its own default, with
23
+ * its note. */
24
+ import { join } from "node:path";
25
+ import { CHORD_FAMILIES, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY } from "./keymap.mjs";
26
+
27
+ /** The most a client reads of the file, in bytes: anything longer is not a keys.json. */
28
+ export const KEYS_LIMIT = 16384;
29
+
30
+ /** Why the family is the default, by the `why` chordFamilyFrom answers; null: the file chose it. */
31
+ export const KEYS_WHY = Object.freeze({
32
+ missing: "there is no keys.json",
33
+ unreadable: "keys.json cannot be read",
34
+ "too-large": "keys.json is too large",
35
+ "not-utf8": "keys.json is not UTF-8 text",
36
+ "not-json": "keys.json is not JSON",
37
+ "not-object": "keys.json is not an object",
38
+ "no-chords": "keys.json names no chords",
39
+ "unknown-chords": "keys.json: unknown chords value",
40
+ });
41
+
42
+ const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
43
+ const utf8Length = (text) => new TextEncoder().encode(text).length;
44
+
45
+ /** The file's text from what a client read: `{ text }`, or `{ why }` when it is none. `input` is the
46
+ * file's bytes (a Uint8Array, a Buffer), at most KEYS_LIMIT and one of them, decoded as UTF-8 with a
47
+ * leading byte-order mark dropped; or text already decoded (a test's), held to the same rules. */
48
+ function textOf(input) {
49
+ if (input instanceof Uint8Array) {
50
+ if (input.length > KEYS_LIMIT) return { why: "too-large" };
51
+ try { return { text: new TextDecoder("utf-8", { fatal: true }).decode(input) }; } catch { return { why: "not-utf8" }; }
52
+ }
53
+ if (typeof input !== "string") return { why: "unreadable" };
54
+ if (utf8Length(input) > KEYS_LIMIT) return { why: "too-large" };
55
+ return { text: input.startsWith("\uFEFF") ? input.slice(1) : input };
56
+ }
57
+
58
+ /** What keysWithFamily throws when the file is there and its other keys cannot all be kept: one it
59
+ * cannot read as a JSON object, or one whose new text would be over KEYS_LIMIT. `why` says which
60
+ * (a key of KEYS_WHY, or "unreadable" for a file the client could not read). Nothing is written. */
61
+ export class KeysUnwritable extends Error {
62
+ constructor(why) {
63
+ super(`keys.json cannot be rewritten without losing what it holds (${why})`);
64
+ this.name = "KeysUnwritable";
65
+ this.code = "E_KEYS_UNWRITABLE";
66
+ this.why = why;
67
+ }
68
+ }
69
+
70
+ /** The path of keys.json: `config/keys.json` in `$OATS_HOME_DIR` when that is set and not empty, else
71
+ * in `<home>/.oats` (the TUI's configPath for tui.json, packages/tui/lib/config.mjs). */
72
+ export function keysPath(env, home) {
73
+ const own = env?.OATS_HOME_DIR;
74
+ return join(typeof own === "string" && own !== "" ? own : join(home, ".oats"), "config", "keys.json");
75
+ }
76
+
77
+ /** The family keys.json names. `bytes` is what the client read of the file (textOf: its bytes, at most
78
+ * KEYS_LIMIT and one), or null or undefined when there is none; `error` the error its read threw, if
79
+ * one did (ENOENT and ENOTDIR are no file, any other is a file that cannot be read). Answers a frozen
80
+ * `{ family, why }`: `why` is null when the file chose the family, else a key of KEYS_WHY, and
81
+ * `family` is then the default. */
82
+ export function chordFamilyFrom(bytes, error = null) {
83
+ const fallback = (why) => Object.freeze({ family: DEFAULT_CHORD_FAMILY, why });
84
+ if (error) return fallback(error.code === "ENOENT" || error.code === "ENOTDIR" ? "missing" : "unreadable");
85
+ if (bytes === null || bytes === undefined) return fallback("missing");
86
+ const { text, why } = textOf(bytes);
87
+ if (why) return fallback(why);
88
+ let value;
89
+ try { value = JSON.parse(text); } catch { return fallback("not-json"); }
90
+ if (!isObject(value)) return fallback("not-object");
91
+ if (!Object.hasOwn(value, "chords")) return fallback("no-chords");
92
+ if (!CHORD_FAMILIES.includes(value.chords)) return fallback("unknown-chords");
93
+ return Object.freeze({ family: value.chords, why: null });
94
+ }
95
+
96
+ /** The line a client shows when keys.json was there and not taken ("keys.json: unknown chords value,
97
+ * using Alt", the default's label), or null: the file chose the family, or there is none, which is the default
98
+ * with nothing to say. `read` is what chordFamilyFrom answered. */
99
+ export function chordFamilyNote(read) {
100
+ if (!read || read.why === null || read.why === "missing" || !Object.hasOwn(KEYS_WHY, read.why)) return null;
101
+ return `${KEYS_WHY[read.why]}, using ${CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY]}`;
102
+ }
103
+
104
+ /** The text of keys.json with `chords` set to `family`, from the file's current `bytes` (as
105
+ * chordFamilyFrom takes them; null when there is no file): every other key of the object is kept,
106
+ * in its place, so that a key a later client adds is not lost to an older one. The text is indented
107
+ * when that fits in KEYS_LIMIT, else on one line, so the clients always read back what was written.
108
+ * Throws KeysUnwritable, so that nothing is written, for a file that is there and is not a JSON
109
+ * object, or whose keys do not fit in KEYS_LIMIT with `chords` set; a TypeError for a `family` that
110
+ * is not one of CHORD_FAMILIES. A client that could not read the file must not call this: it does
111
+ * not know what it would lose. The client writes the answer atomically. */
112
+ export function keysWithFamily(bytes, family) {
113
+ if (!CHORD_FAMILIES.includes(family)) throw new TypeError(`unknown chord family: ${String(family)}`);
114
+ let kept = {};
115
+ if (bytes !== null && bytes !== undefined) {
116
+ const { text, why } = textOf(bytes);
117
+ if (why) throw new KeysUnwritable(why);
118
+ let value;
119
+ try { value = JSON.parse(text); } catch { throw new KeysUnwritable("not-json"); }
120
+ if (!isObject(value)) throw new KeysUnwritable("not-object");
121
+ kept = value;
122
+ }
123
+ const next = { ...kept, chords: family };
124
+ for (const text of [`${JSON.stringify(next, null, 2)}\n`, `${JSON.stringify(next)}\n`]) if (utf8Length(text) <= KEYS_LIMIT) return text;
125
+ throw new KeysUnwritable("too-large");
126
+ }
@@ -16,13 +16,15 @@ export const CLIENT_OWN_CODES = Object.freeze([
16
16
  'E_REMOTE_ROSTER', 'E_WORKSPACE_FEATURE', 'E_WORKSPACE_UNKNOWN',
17
17
  // This computer's deployments list (#1390): a CLI without it.
18
18
  'E_DEPLOYMENTS_FEATURE',
19
- // A spawn: its preview, its apply and the wake saved with it.
19
+ // A spawn: its preview, its apply and the wake saved with it; a suggest read a newer one ended (E_SUPERSEDED, #1421 §3).
20
20
  'E_APPLY_UNAVAILABLE', 'E_BACKEND_UNAVAILABLE', 'E_BUSY', 'E_FORBIDDEN_FRAME', 'E_INPUT_PREPARATION', 'E_INSTANCE_GONE',
21
- 'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_TARGET_CHANGED',
21
+ 'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_SUPERSEDED', 'E_TARGET_CHANGED',
22
22
  'E_UNSUPPORTED_OPTION', 'E_WAKE_OUTCOME_UNKNOWN', 'E_WAKE_SAVE_FAILED',
23
23
  // Stop, start, restart and remove, and the plan a person confirms (a spawn's plan too).
24
24
  'E_LIFECYCLE_UNAVAILABLE', 'E_OPTION_UNAVAILABLE', 'E_PLAN_CHANGED', 'E_PLAN_EXPIRED', 'E_PLAN_LIMIT', 'E_PLAN_REQUIRED',
25
25
  'E_HOME_UNVERIFIED', 'E_START_UNCONFIRMED',
26
+ // keys.json (packages/client/keys-file.mjs): a write that could not keep every key, so none is made.
27
+ 'E_KEYS_UNWRITABLE',
26
28
  // An instance's Activity.
27
29
  'E_EVENTS_UNAVAILABLE', 'E_NOT_IN_SCOPE',
28
30
  // A terminal.