@awebai/oats 0.57.0 → 0.57.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 (50) hide show
  1. package/docs/configuration.md +17 -27
  2. package/docs/desktop.md +14 -0
  3. package/docs/execution-targets.md +6 -1
  4. package/docs/implementation.md +7 -1
  5. package/docs/integrations.md +3 -1
  6. package/docs/official-catalog.md +1 -1
  7. package/docs/packages.md +5 -5
  8. package/docs/release-notes/v0.57.1.md +275 -0
  9. package/docs/servers.md +18 -0
  10. package/docs/tui.md +214 -87
  11. package/docs/workspaces.md +1 -1
  12. package/lib/session-viewer.mjs +29 -4
  13. package/package-catalog.json +1 -1
  14. package/package.json +1 -1
  15. package/packages/client/cli-adapter.mjs +9 -7
  16. package/packages/client/composed-gate.mjs +34 -0
  17. package/packages/client/inspect-boundary.mjs +157 -0
  18. package/packages/client/inspect-cache.mjs +86 -0
  19. package/packages/client/keyed-catalog.mjs +132 -0
  20. package/packages/client/launch-view.mjs +46 -0
  21. package/packages/client/session-attach.mjs +7 -5
  22. package/packages/client/soul-catalog.mjs +77 -0
  23. package/packages/client/soul-colors.mjs +31 -0
  24. package/packages/client/soul-facts.mjs +85 -0
  25. package/packages/client/soul-rows.mjs +48 -0
  26. package/packages/client/spawn-apply-cli.mjs +11 -6
  27. package/packages/client/spawn-apply.mjs +212 -0
  28. package/packages/client/spawn-messages.mjs +131 -85
  29. package/packages/client/spawn-preview-contract.mjs +3 -0
  30. package/packages/client/spawn-preview-facts.mjs +119 -0
  31. package/packages/client/spawn-preview.mjs +152 -0
  32. package/packages/client/spawn-transaction.mjs +136 -0
  33. package/packages/tui/README.md +32 -11
  34. package/packages/tui/lib/actions.mjs +10 -1
  35. package/packages/tui/lib/config.mjs +9 -14
  36. package/packages/tui/lib/main.mjs +165 -57
  37. package/packages/tui/lib/model.mjs +28 -24
  38. package/packages/tui/lib/panel.mjs +955 -0
  39. package/packages/tui/lib/read.mjs +5 -14
  40. package/packages/tui/lib/store.mjs +77 -30
  41. package/packages/tui/lib/term/capture.mjs +260 -0
  42. package/packages/tui/lib/term/screen.mjs +44 -8
  43. package/packages/tui/lib/term/style.mjs +78 -6
  44. package/packages/tui/lib/term/text.mjs +24 -4
  45. package/packages/tui/lib/term/through.mjs +213 -0
  46. package/packages/tui/lib/term/tty.mjs +7 -60
  47. package/packages/tui/lib/views/frame.mjs +126 -40
  48. package/packages/tui/lib/views/help.mjs +12 -10
  49. package/skills/oats-getting-started/SKILL.md +3 -2
  50. package/packages/tui/lib/open.mjs +0 -45
@@ -0,0 +1,136 @@
1
+ /** The spawn transaction, the client's half (#855, 6b-2): prepare, apply only the decision the operator confirmed,
2
+ * follow a `pending` apply, check an unknown outcome and recover a reference after a reload, on the /api/spawn
3
+ * contract (spawn-apply-contract.mjs). Each answer is classified into an outcome; what a client shows for it,
4
+ * and where it keeps the job, stay the client's own. No notifications, rows, storage, DOM or timers beyond `sleep`,
5
+ * and no module-level state: each client makes its own transaction.
6
+ *
7
+ * `createSpawnTransaction({ request, now, sleep, pollMs })`:
8
+ * request(body, job) the client's boundary: answers the raw reply to `body` for the job's `address` (the
9
+ * Desktop posts it to /api/spawn?ws=<address>); throws on transport failure
10
+ * now() the clock the deadline is read on (Date.now)
11
+ * sleep(ms) the wait between two `result` reads while the apply is pending
12
+ * pollMs that wait (RECOVER_POLL_MS)
13
+ * answers `{ submit, check, recover }`. Each takes `{ alive, progress }` for its own call and resolves an outcome
14
+ * `{ kind, view, reason, job }`, or null once `alive()` answers false (the client's owner went away: nothing is
15
+ * reported). `progress(event, job)` hears 'submitted' after a prepare whose decision is the confirmed one, before
16
+ * the apply is requested (`spawnRef` and `deadline` set), and 'pending' on each pending answer it goes on following.
17
+ *
18
+ * submit({ address, selector, input, decision }) prepares `input` (the prepare body), applies the prepared
19
+ * reference when its decision is `decision` (spawn-decision.mjs `sameSpawnDecision`), and follows it
20
+ * check(job) reads `result`; an `unknown` result re-applies the same reference, never a new one
21
+ * recover(job) reads `result` for a reference kept across a reload ({ address, selector, spawnRef, deadline? }):
22
+ * one that was submitted, which it records
23
+ *
24
+ * `job` is the transaction's record of the intent, { address, selector, spawnRef, deadline, submitted, prepared },
25
+ * the object `submit` made (or the one a client passes to check and recover); a client stores it as it likes.
26
+ * The deadline is the broker's CLI deadline (`applyWithinMs`, else SPAWN_APPLY_MS) plus FOLLOW_MARGIN_MS from the
27
+ * press, an absolute time; a recovered job without one follows RECOVER_WITHIN_MS from now.
28
+ *
29
+ * `kind`, in the order an answer is classified:
30
+ * created complete, partial or incomplete (`view.status` says which); `reason` the view's
31
+ * pending-expired still pending past the deadline; `reason` null
32
+ * cleanup-owed unknown with a rolled-back code (ROLLED_BACK_CODES); `reason` the view's
33
+ * unknown an unknown answer, a failure after the apply was requested, or E_INTENT_EXPIRED once
34
+ * submitted (the record is gone: proof of nothing); `reason` E_OUTCOME_UNKNOWN's, or the
35
+ * E_INTENT_EXPIRED reason itself; `view` null after a failure
36
+ * rolled-back refused with a rolled-back code; `reason` the view's
37
+ * never-submitted the reference was prepared and never applied; `reason` the view's
38
+ * drifted the prepared decision is not the confirmed one (`view` the prepared one, `reason` null), or
39
+ * E_DECISION_STALE (`reason` it)
40
+ * refused everything else: a prepare that did not prepare, a refusal, or a failure before the apply
41
+ * was requested (`reason` spawnApplyReason(code), `view` null). Nothing was submitted or the
42
+ * kernel says so. */
43
+ import { spawnApplyView, spawnApplyReason, SPAWN_APPLY_MS, ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
44
+ import { sameSpawnDecision } from './spawn-decision.mjs';
45
+
46
+ /** A pending apply reads `result` this often, until the job's deadline. */
47
+ export const RECOVER_POLL_MS = 2000;
48
+ /** A job's deadline is the broker's CLI deadline (applyWithinMs) plus this margin, from the press. */
49
+ export const FOLLOW_MARGIN_MS = 30000;
50
+ /** The CLI deadline of a spawn without `worktree` hooks, plus the margin: what a recovered job without a deadline follows. */
51
+ export const RECOVER_WITHIN_MS = SPAWN_APPLY_MS + FOLLOW_MARGIN_MS;
52
+
53
+ export function createSpawnTransaction({ request, now = () => Date.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), pollMs = RECOVER_POLL_MS } = {}) {
54
+ if (typeof request !== 'function') throw new TypeError('createSpawnTransaction: request must be a function');
55
+ const outcome = (kind, view, reason, job) => ({ kind, view, reason, job });
56
+ const calls = ({ alive = () => true, progress = () => {} } = {}) => ({ alive, progress });
57
+
58
+ /** One reply, projected; null once the owner went away. A reply without a view, or whose decision is not
59
+ * the prepared one, is a protocol failure. */
60
+ async function ask(job, body, { alive }) {
61
+ const raw = await request(body, job);
62
+ if (!alive()) return null;
63
+ const view = spawnApplyView(raw, { workspace: job.address, ref: body.spawnRef, selector: job.selector });
64
+ if (!view || view.preview && job.prepared && body.action !== 'prepare' && !sameSpawnDecision(view.preview.decision, job.prepared.preview.decision)) throw Object.assign(Error(), { code: 'E_CLI_PROTOCOL' });
65
+ return view;
66
+ }
67
+ /** An answer after the apply was requested, read as data (a pending one is followed). */
68
+ function classify(job, view, call) {
69
+ if (['complete', 'partial', 'incomplete'].includes(view.status)) return outcome('created', view, view.reason ?? null, job);
70
+ if (view.status === 'pending') return follow(job, view, call);
71
+ if (view.status === 'unknown' && ROLLED_BACK_CODES.includes(view.reason?.code)) return outcome('cleanup-owed', view, view.reason, job);
72
+ if (view.status === 'unknown') return outcome('unknown', view, spawnApplyReason('E_OUTCOME_UNKNOWN'), job);
73
+ if (view.status === 'refused' && ROLLED_BACK_CODES.includes(view.reason?.code)) return outcome('rolled-back', view, view.reason, job);
74
+ if (view.status === 'prepared') return outcome('never-submitted', view, view.reason ?? null, job);
75
+ if (view.reason?.code === 'E_INTENT_EXPIRED' && job.submitted) return outcome('unknown', view, view.reason, job);
76
+ if (view.reason?.code === 'E_DECISION_STALE') return outcome('drifted', view, view.reason, job);
77
+ return outcome('refused', view, view.reason ?? null, job);
78
+ }
79
+ /** Still running in the broker: read `result` every pollMs until it settles or the deadline passes. */
80
+ async function follow(job, view, call) {
81
+ for (;;) {
82
+ if (now() >= job.deadline) return outcome('pending-expired', view, null, job);
83
+ call.progress('pending', job);
84
+ await sleep(pollMs);
85
+ if (!call.alive()) return null;
86
+ view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
87
+ if (!view) return null;
88
+ if (view.status !== 'pending') return classify(job, view, call);
89
+ }
90
+ }
91
+ /** After the apply was requested a failure proves nothing: the outcome is unknown. */
92
+ const failed = (job, call) => call.alive() ? outcome('unknown', null, spawnApplyReason('E_OUTCOME_UNKNOWN'), job) : null;
93
+ const referenced = (job, name) => { if (!job || typeof job.spawnRef !== 'string' || !job.spawnRef) throw new TypeError(`${name}: job.spawnRef is required`); };
94
+
95
+ return {
96
+ async submit(intent, options) {
97
+ const call = calls(options);
98
+ const job = { address: intent.address, selector: intent.selector, spawnRef: null, deadline: null, submitted: false, prepared: null };
99
+ try {
100
+ const prepared = await ask(job, intent.input, call);
101
+ if (!prepared) return null;
102
+ if (prepared.status !== 'prepared') return outcome('refused', prepared, prepared.reason ?? null, job);
103
+ // Apply only the decision the operator saw; the kernel's --expect-decision guards it again at apply.
104
+ if (!sameSpawnDecision(prepared.preview.decision, intent.decision)) return outcome('drifted', prepared, null, job);
105
+ job.prepared = prepared; job.spawnRef = prepared.spawnRef; job.submitted = true;
106
+ job.deadline = now() + (prepared.applyWithinMs ?? SPAWN_APPLY_MS) + FOLLOW_MARGIN_MS;
107
+ call.progress('submitted', job);
108
+ const view = await ask(job, { action: 'apply', spawnRef: job.spawnRef }, call);
109
+ return view ? await classify(job, view, call) : null;
110
+ } catch (error) {
111
+ if (!call.alive()) return null;
112
+ return job.submitted ? failed(job, call) : outcome('refused', null, spawnApplyReason(error?.code), job);
113
+ }
114
+ },
115
+ async check(job, options) {
116
+ referenced(job, 'check');
117
+ const call = calls(options);
118
+ try {
119
+ let view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
120
+ if (!view) return null;
121
+ if (view.status === 'unknown') { view = await ask(job, { action: 'apply', spawnRef: job.spawnRef }, call); if (!view) return null; }
122
+ return await classify(job, view, call);
123
+ } catch { return failed(job, call); }
124
+ },
125
+ async recover(job, options) {
126
+ referenced(job, 'recover');
127
+ const call = calls(options);
128
+ job.submitted = true;
129
+ if (!Number.isFinite(job.deadline)) job.deadline = now() + RECOVER_WITHIN_MS;
130
+ try {
131
+ const view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
132
+ return view ? await classify(job, view, call) : null;
133
+ } catch { return failed(job, call); }
134
+ },
135
+ };
136
+ }
@@ -6,7 +6,7 @@ inside `@awebai/oats` and is never published on its own.
6
6
 
7
7
  **It is a preview.** This version shows a workspace's instances, on this
8
8
  machine and on the other machines registered on it, in one list, follows
9
- them, opens an agent's terminal, and stops, starts, restarts and retires an
9
+ them, opens an agent's terminal in a panel beside the list, and stops, starts, restarts and retires an
10
10
  agent after a confirmation. While it is a preview its screens and its
11
11
  configuration file may change without notice.
12
12
 
@@ -24,16 +24,18 @@ never does.
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
25
25
  | `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
- | `lib/open.mjs` | the viewer of an opened agent: `oats session attach` run by the same kernel on the user's terminal, and the end of its standard error kept |
27
+ | `lib/panel.mjs` | the open terminal: the run's private tmux server (one control client, one window per viewer), the kernel's `oats session attach` in a pane of it, captures when tmux says the pane changed, keys typed into it, and the sweep of what a dead run left; the only module that runs tmux |
28
28
  | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
29
29
  | `lib/store.mjs` | the state and `reduce(state, event)`: pure |
30
30
  | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
31
31
  | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
32
32
  | `lib/term/width.mjs` | the cells a grapheme takes |
33
33
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
34
- | `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
34
+ | `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
35
+ | `lib/term/capture.mjs` | a pane's capture (`capture-pane -e -N`) to rows of cells: characters and an allowlist of SGR, every other sequence and control dropped |
36
+ | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
35
37
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
36
- | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, the lend of the terminal to a viewer, one write per frame |
38
+ | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
37
39
  | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`) |
38
40
 
39
41
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
@@ -42,8 +44,11 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
42
44
  one path in `lib/client.mjs`. No dynamic `import()`.
43
45
  - Nothing in `lib/` or `bin/` of the kernel imports this package, except the
44
46
  one dynamic import where `bin/oats.mjs` dispatches the word.
45
- - Only `term/screen.mjs` and `term/tty.mjs` produce an ESC byte. Views are
46
- pure: no IO, no clock, no escape bytes.
47
+ - Only `term/screen.mjs` and `term/tty.mjs` write an ESC byte in a string,
48
+ and only they write to the terminal. `term/through.mjs` (the back key's
49
+ bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
50
+ pane) hold theirs as numbers. Views are pure: no IO, no clock, no escape
51
+ bytes.
47
52
  - No function of this package decodes a kernel answer, groups or orders
48
53
  instances, or decides what a failed read means: `lib/model.mjs` and
49
54
  `lib/read.mjs` call the shared readers and pass their answers on. A string
@@ -51,8 +56,21 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
51
56
  - The store holds no size and no cell: a key event carries the height of the
52
57
  panes as the last frame drew them.
53
58
  - Every read runs in a session of its own and is ended on every way out.
54
- The viewer (`lib/open.mjs`) shares the user's terminal, the guard lends it
55
- the terminal, and it is ended first on every way out while it has it. A
59
+ The viewer runs in a pane of the run's private tmux server
60
+ (`lib/panel.mjs`), never on the user's terminal: the guard never lends the
61
+ terminal, and `panel.end()` kills that server on every way out. After a
62
+ SIGKILL the server's keeper window kills it: the keeper reads the run's
63
+ FIFO `alive`, whose write end the TUI holds, until no writer is left (see
64
+ THE KEEPER in `lib/panel.mjs`, which says why the control client's stdin
65
+ EOF is not enough). The next run's sweep removes the directory. The panel
66
+ runs a process to make that FIFO, to ask tmux's version, to start the
67
+ server, to make a window and to end the server, and the sweep one to ask
68
+ whether a socket answers; every frame, key, resize and close goes through
69
+ its one control client, and a capture runs only after tmux said the pane
70
+ changed. A capture goes out of band: tmux saves it to the run's file
71
+ `capture`, so no pane's text is ever in the control client's stream, and
72
+ a block that says what its command never says ends that client (THE
73
+ CAPTURE in `lib/panel.mjs`). A
56
74
  change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
57
75
  start, a restart) is never signalled: on the way out it is let go, and its
58
76
  output goes to files, so it never meets a closed pipe.
@@ -68,9 +86,12 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
68
86
 
69
87
  Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
70
88
  `test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
71
- socket (`test/tui-terminal.test.mjs`, and `test/tui-open-terminal.test.mjs`
72
- for opening an agent, with a second private server for the agents;
73
- `test/tui-acts.test.mjs` for the acts, run on CI only). All of them need the root's install
89
+ socket (`test/tui-terminal.test.mjs`; `test/tui-panel.test.mjs` for the
90
+ terminal panel, with a second private server for the agents, and
91
+ `test/tui-acts.test.mjs` for the acts, both run on CI only).
92
+ `packages/tui/test/panel.test.mjs` drives `lib/panel.mjs` against a fake
93
+ tmux (`test/fixtures/panel/tmux.mjs`) that records each call and plays the
94
+ control-mode answers. All of them need the root's install
74
95
  (`npm ci` at the repository root). The package has no dependency of its own,
75
96
  but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
76
97
  install's own bin/oats.mjs, and its `version --json` is a record the probe
@@ -17,9 +17,18 @@ export const ACTIONS = Object.freeze([
17
17
  { id: "detail", keys: ["tab"], label: "detail" },
18
18
  { id: "filter", keys: ["/"], label: "filter" },
19
19
  { id: "refresh", keys: ["r"], label: "refresh" },
20
+ // The views by their number. The header names the views and never draws a digit against a name
21
+ // (docs/tui.md, "The header"): the digits are named here, so in the help and the footer.
20
22
  { id: "instances", keys: ["1"], label: "instances" },
23
+ { id: "souls", keys: ["2"], label: "souls" },
24
+ { id: "capabilities", keys: ["3"], label: "capabilities" },
21
25
  { id: "workspaces", keys: ["w"], label: "workspaces" },
22
- { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
26
+ { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal beside the list, or go to it when it is the open one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
27
+ // The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
28
+ // has the focus the TUI takes no key but the back key (tui.json's open.detachKey), so neither of
29
+ // these is ever read there.
30
+ { id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the open terminal with the whole screen; the back key brings the list back"]] },
31
+ { id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the open terminal; the agent keeps running"]] },
23
32
  // The four acts on an instance: each opens a confirmation, and nothing is done before a move and
24
33
  // a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
25
34
  { id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
@@ -1,5 +1,5 @@
1
1
  // The user's key file, tui.json: which keys do what, whether the screen is drawn in ASCII, and the
2
- // key that leaves an agent's terminal.
2
+ // key that takes the focus from an agent's terminal back to the list.
3
3
  // Read once at start and never written. A file that is wrong in any way is refused whole, each
4
4
  // problem as one line that says what to change: the TUI resolves no conflict and guesses nothing
5
5
  // (there is no "last wins"), because a key that silently does something else is worse than a
@@ -11,6 +11,7 @@ import { isAbsolute, join } from "node:path";
11
11
  import { ACTIONS, bindings, keyLabel } from "./actions.mjs";
12
12
  import { displayLine } from "./client.mjs";
13
13
  import { isKeyId } from "./term/keys.mjs";
14
+ import { BACK_KEY_RULE, isBackKey } from "./term/through.mjs";
14
15
 
15
16
  /** The largest tui.json that is read, in bytes. A larger file is refused by its size, unread. */
16
17
  export const CONFIG_LIMIT = 64 * 1024;
@@ -18,11 +19,9 @@ export const CONFIG_LIMIT = 64 * 1024;
18
19
  const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
19
20
  const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
20
21
  const SETTINGS = "the settings are keys, ascii and open";
21
- /** The key that leaves an agent's terminal when tui.json names none: the kernel's suggested key. */
22
+ /** The back key when tui.json names none: the key that takes the focus from an agent's terminal
23
+ * back to the list (the setting keeps its name, `open.detachKey`, from when it left a viewer). */
22
24
  export const DETACH_KEY = "C-\\";
23
- /** A detach key as tui.json may hold it: 1 to 16 printable ASCII characters. Its grammar is the
24
- * kernel's, never checked here: a key the kernel refuses is said when an agent is opened. */
25
- const DETACH_KEY_TEXT = /^[\x20-\x7e]{1,16}$/;
26
25
  /** An action id this program had and has no more, with what it is called now. */
27
26
  const RENAMED = Object.freeze({ "open-workspace": "open" });
28
27
  const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
@@ -112,19 +111,15 @@ export function effectiveConfig(value, defaults = ACTIONS) {
112
111
  return { ok: true, actions, ascii: value.ascii === true, detachKey: value.open?.detachKey ?? DETACH_KEY };
113
112
  }
114
113
 
115
- /** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: a string of 1
116
- * to 16 printable ASCII characters, handed to `oats session attach --detach-key` as it is. Its
117
- * grammar is the kernel's. Two things that are not grammar are refused here: a value that begins
118
- * with `-`, which the kernel would read as another flag and refuse in that flag's words (no key of
119
- * its grammar begins with one), and a value the display filter would change, which the footer and
120
- * the help would draw as another key. */
114
+ /** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: the back key,
115
+ * one key of the TUI's own grammar (term/through.mjs BACK_KEY), which the TUI takes from the bytes
116
+ * typed into an agent's terminal and never hands to the kernel. A key outside the grammar is
117
+ * refused here, where the file is named, and not when an agent is opened. */
121
118
  function openProblem(given) {
122
119
  if (!isObject(given)) return 'open must be an object, like {"detachKey": "F12"}';
123
120
  for (const [member, key] of Object.entries(given)) {
124
121
  if (member !== "detachKey") return `${plain(member) ? `unknown member ${member} of open` : "a member of open whose name cannot be shown is unknown"}; open has detachKey`;
125
- if (typeof key !== "string" || !DETACH_KEY_TEXT.test(key)) return 'open.detachKey must be 1 to 16 printable ASCII characters, like "F12"';
126
- if (key.startsWith("-")) return "open.detachKey cannot begin with -";
127
- if (displayLine(key) !== key) return "open.detachKey is a key the help cannot name; give a key whose characters can be shown";
122
+ if (!isBackKey(key)) return `open.detachKey must be one key: ${BACK_KEY_RULE}`;
128
123
  }
129
124
  return null;
130
125
  }