@awebai/oats 0.55.1 → 0.56.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 (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -10,8 +10,9 @@
10
10
  // Selection is an identity (the shared `instanceId`), never an index, so it survives every read;
11
11
  // the rows it moves among are the model's, in drawn order.
12
12
  import { ACTIONS, bindings } from "./actions.mjs";
13
- import { collapseKey, displayLine, instanceId, pendingEntry } from "./client.mjs";
14
- import { disclosure, roster, switcher } from "./model.mjs";
13
+ import { collapseKey, displayLine, instanceActs, instanceId, pendingEntry } from "./client.mjs";
14
+ import { DETACH_KEY } from "./config.mjs";
15
+ import { disclosure, openDecision, preflightLine, returnedLine, roster, switcher } from "./model.mjs";
15
16
  import { windowOf } from "./views/scroll.mjs";
16
17
 
17
18
  /** The longest filter, in UTF-16 units. */
@@ -33,8 +34,15 @@ const NO_FILTER = Object.freeze({ editing: false, query: "" });
33
34
  * on purpose (see `scrolledList`); the switcher has its own.
34
35
  * `selected`, `top`, `detailTop` are the open view's; `places` keeps them for
35
36
  * the views left behind, and `collapsed` holds every view's keys (each carries its `open`).
36
- * `back`: the view under the help. `offered`: the deployments of `~/Agents` not served. */
37
- export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false }) {
37
+ * `back`: the view under the help. `offered`: the deployments of `~/Agents` not served.
38
+ * `opening`: the agent whose terminal is being opened, or null: `{ id, phase, name, machine,
39
+ * routed }`, `phase` "preflight" while another machine is asked whether its session is there and
40
+ * "lent" while the kernel's viewer has the terminal; `name`, `machine` and `routed` are the row's
41
+ * as it was when Enter was pressed, for the line after. `outcome`: that line (the model's
42
+ * `{ said, under }`), shown above the panes until the next key bound to an action, or null.
43
+ * `detachKey`: tui.json's `open.detachKey`, the key that leaves an agent's terminal.
44
+ * The roster is made from none of the three (lib/model.mjs MADE_FROM). */
45
+ export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, detachKey = DETACH_KEY }) {
38
46
  return Object.freeze({
39
47
  view: deployment === null ? "switcher" : "instances", back: deployment === null ? "switcher" : "instances",
40
48
  ctxs: Object.freeze(deployment === null ? [] : [deployment]), open: deployment,
@@ -44,7 +52,7 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
44
52
  selected: null, collapsed: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(),
45
53
  switcher: Object.freeze({ editing: false, query: "", selected: null, top: 0, loose: false, line: null, refused: null }),
46
54
  offered: Object.freeze({ offered: Object.freeze([]), limited: false }),
47
- helpTop: 0, actions, ascii,
55
+ helpTop: 0, actions, ascii, detachKey, opening: null, outcome: null,
48
56
  });
49
57
  }
50
58
 
@@ -262,7 +270,7 @@ function switched(state, action, page) {
262
270
  const top = windowOf({ top: key === s.keys[0] ? 0 : key === s.keys.at(-1) ? count : drawn, count, height, keep: at }).top;
263
271
  return { state: put({ selected: key, top, loose: false }), effect: null };
264
272
  }
265
- case "open-workspace": {
273
+ case "open": {
266
274
  const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
267
275
  if (!item) return stay;
268
276
  if (item.path !== undefined) return { state: put({ refused: null }), effect: { admit: item.path } };
@@ -281,11 +289,56 @@ function switched(state, action, page) {
281
289
  * (one outcome of the roster read), `{ collecting }`, `{ offered: { offered, limited } }` (the
282
290
  * deployments of `~/Agents` not served), `{ admitted: <deployment>, at }` and `{ refused: <path> }`
283
291
  * (what a picked folder turned out to be).
292
+ * Opening an agent gives three more: `{ prepared: { id, error? } }` (the preflight of another
293
+ * machine's agent ended: `error` is what the shared prepareRemoteTerm threw), `{ given: true }`
294
+ * (the loop gave the preflight up itself: a suspend) and `{ returned: { id, status, stderr } }`
295
+ * (the viewer closed: its exit status as Node reports it, and the stderr it kept).
284
296
  * An effect is something only the loop can do: "quit", "suspend", "redraw", or an object with
285
- * any of `refresh: { live }` (read now), `offer: true` (list `~/Agents` again) and
286
- * `admit: <path>` (ask whether a picked folder is a deployment); or null. */
297
+ * any of `refresh: { live }` (read now), `offer: true` (list `~/Agents` again),
298
+ * `admit: <path>` (ask whether a picked folder is a deployment), `open: <decision>` (open the
299
+ * agent's terminal: the model's openDecision, with its target), `lend: <id>` (the preflight is
300
+ * over: start the viewer it prepared) and `abandon: true` (give the preflight up); or null.
301
+ * The line after an open stands until the next key that is bound to an action: a key bound to
302
+ * nothing (a stray detach key is no key at all) leaves it. */
287
303
  export function reduce(state, event, keymap = bindings(state.actions)) {
304
+ if (state.outcome !== null && typeof event.key === "string" && keymap.has(event.key)) state = next(state, { outcome: null });
305
+ return reduced(state, event, keymap);
306
+ }
307
+
308
+ /** The preflight of another machine's agent ended. Given up meanwhile (Esc, a suspend, a second
309
+ * open): dropped. Failed: the line that says so, unless it is the person's own giving up. Else
310
+ * the viewer is started, unless the row it is for has gone from the roster since. */
311
+ function prepared(state, { id, error }) {
312
+ const opening = state.opening;
313
+ if (opening === null || opening.id !== id || opening.phase !== "preflight") return { state, effect: null };
314
+ if (error !== undefined) return { state: next(state, { opening: null, outcome: preflightLine(opening, error) }), effect: null };
315
+ if (!roster(state).instances.some((row) => instanceId(row) === id)) return { state: next(state, { opening: null }), effect: null };
316
+ return { state: next(state, { opening: Object.freeze({ ...opening, phase: "lent" }) }), effect: { lend: id } };
317
+ }
318
+
319
+ /** The viewer closed: the line that says what happened, and the instances read again at once
320
+ * (an exit status says nothing of the agent but that it was left by the key). */
321
+ function returned(state, { id, status, stderr }) {
322
+ const opening = state.opening;
323
+ if (opening === null || opening.id !== id) return { state, effect: null };
324
+ return { state: next(state, { opening: null, outcome: returnedLine(opening, status, stderr) }), effect: { refresh: { live: true } } };
325
+ }
326
+
327
+ /** Enter in the list of instances: the selected agent's terminal, or the line that says why not.
328
+ * Nothing while an open is under way. */
329
+ function openAgent(state, r, at) {
330
+ if (state.opening !== null || at < 0) return { state, effect: null };
331
+ const row = r.items[at].row, decision = openDecision(state, row, instanceActs(row));
332
+ if (!decision.open) return { state: next(state, { outcome: decision.said }), effect: null };
333
+ const opening = Object.freeze({ id: decision.id, phase: decision.routed ? "preflight" : "lent", name: decision.name, machine: decision.machine, routed: decision.routed });
334
+ return { state: next(state, { opening, outcome: null }), effect: { open: decision } };
335
+ }
336
+
337
+ function reduced(state, event, keymap) {
288
338
  const stay = { state, effect: null };
339
+ if (event.prepared !== undefined) return prepared(state, event.prepared);
340
+ if (event.given !== undefined) return state.opening?.phase === "preflight" ? { state: next(state, { opening: null }), effect: null } : stay;
341
+ if (event.returned !== undefined) return returned(state, event.returned);
289
342
  if (event.entry !== undefined) return took(state, event);
290
343
  if (event.roster !== undefined) return heard(state, event.roster);
291
344
  if (event.collecting !== undefined) return { state: event.collecting === state.collecting ? state : next(state, { collecting: event.collecting === true }), effect: null };
@@ -323,7 +376,8 @@ export function reduce(state, event, keymap = bindings(state.actions)) {
323
376
  if (state.view === "switcher") return switched(state, action, page);
324
377
 
325
378
  if (action === "close") {
326
- // In this order: a kept filter, the detail.
379
+ // In this order: an open under way (another machine is asked first), a kept filter, the detail.
380
+ if (state.opening?.phase === "preflight") return { state: next(state, { opening: null }), effect: { abandon: true } };
327
381
  if (state.filter.query !== "") return { state: queried(state, ""), effect: null };
328
382
  return state.focus === "detail" ? { state: next(state, { focus: "list" }), effect: null } : stay;
329
383
  }
@@ -331,6 +385,7 @@ export function reduce(state, event, keymap = bindings(state.actions)) {
331
385
  const at = indexOf(r, state.selected);
332
386
  switch (action) {
333
387
  case "filter": return { state: next(state, { focus: "list", filter: Object.freeze({ ...state.filter, editing: true }) }), effect: null };
388
+ case "open": return openAgent(state, r, at);
334
389
  case "detail": return at < 0 ? stay : { state: next(state, { focus: state.focus === "detail" ? "list" : "detail" }), effect: null };
335
390
  case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
336
391
  if (state.focus === "detail") return { state: next(state, { detailTop: scrolled(state.detailTop) }), effect: null };
@@ -4,7 +4,7 @@
4
4
  // no mouse or focus reporting, no keyboard protocol, no keypad or cursor-key mode, no title, no
5
5
  // clipboard, no bell, no query that expects a reply.
6
6
  //
7
- // Handing the terminal to someone else (the shell at a suspend; a viewer in later versions) is
7
+ // Handing the terminal to someone else (the shell at a suspend; the kernel's viewer at a lend) is
8
8
  // leave() and enter(), and only that pair.
9
9
 
10
10
  const mode = (number, on) => `\x1b[?${number}${on ? "h" : "l"}`;
@@ -22,6 +22,9 @@ export const SIGNAL_STATUS = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP:
22
22
  export const TERMINAL_GONE_STATUS = SIGNAL_STATUS.SIGHUP;
23
23
  /** How long a suspend waits for the stop before it concludes there was none. */
24
24
  const STOP_GRACE_MS = 100;
25
+ /** How long a run that is ending while the terminal is lent waits for the borrower to close after
26
+ * it was asked to end, before it ends anyway. */
27
+ export const LEND_END_GRACE_MS = 3000;
25
28
 
26
29
  /** A terminal on both ends that can be addressed: no escape byte is ever written to anything else. */
27
30
  export function isTerminal({ stdin, stdout, env }) {
@@ -41,6 +44,9 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
41
44
  let entered = false, raw = false, modes = false;
42
45
  let suspended = false, stopTimer = null;
43
46
  let over = false, blocked = false, stale = false;
47
+ /** While the terminal is lent: `{ end, ending }`, the borrower's end() and, once the run is
48
+ * ending, the `[status, error]` it ends with when the borrower has closed. Else null. */
49
+ let lent = null, endTimer = null;
44
50
  let settle;
45
51
  const done = new Promise((resolve) => { settle = resolve; });
46
52
  const listeners = [];
@@ -72,6 +78,7 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
72
78
  if (over) return;
73
79
  over = true;
74
80
  leave();
81
+ if (endTimer !== null) { clearTimer(endTimer); endTimer = null; }
75
82
  // What it throws must not keep the run from ending, nor replace the status it ends with.
76
83
  if (onEnd) quietly(onEnd);
77
84
  if (stopTimer !== null) { clearTimer(stopTimer); stopTimer = null; }
@@ -82,15 +89,15 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
82
89
  }
83
90
 
84
91
  /** Run one of the loop's own steps. What it throws ends the run as an uncaught error would,
85
- * without waiting for the process to say so. */
92
+ * without waiting for the process to say so (while the terminal is lent, the borrower first). */
86
93
  function attempt(step) {
87
- try { step(); } catch (error) { finish(1, error); }
94
+ try { step(); } catch (error) { out(1, error); }
88
95
  }
89
96
 
90
97
  /** One write per frame. While the last write has not drained nothing is queued: the newest frame
91
98
  * is made when it has. */
92
99
  function draw() {
93
- if (!entered || over) return;
100
+ if (!entered || over || lent) return;
94
101
  if (blocked) { stale = true; return; }
95
102
  const bytes = frame();
96
103
  if (bytes && stdout.write(bytes) === false) blocked = true;
@@ -143,27 +150,79 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
143
150
  /** SIGCONT. After our own suspend: come back. Otherwise the process was stopped and continued
144
151
  * from outside while it held the terminal. */
145
152
  function continued() {
146
- if (over) return;
153
+ if (over || lent) return; // a lent terminal is the borrower's: it takes care of its own
147
154
  if (suspended) return resume();
148
155
  if (onResume && entered) { attempt(() => onResume(false)); if (over) return; }
149
156
  reassert();
150
157
  }
151
158
 
159
+ /** Lend the terminal to a program of its own (the kernel's viewer) and take it back when it
160
+ * ends. The suspend path, without the stop: leave() (the modes, then raw mode off), input
161
+ * paused, so two readers do not split the keys; then `run()`, which starts the borrower with
162
+ * the terminal as its own and resolves when it has closed; then enter(), input resumed and a
163
+ * full redraw. Answers a promise of `{ value }` (what run resolved with) or `{ error }` (what it
164
+ * threw or rejected with: the terminal is taken back all the same).
165
+ * WHILE LENT nothing is drawn, whatever asks; a SIGQUIT does not end the run (a second
166
+ * Ctrl+\ after the viewer gave the terminal back is the terminal's QUIT, and the viewer handles
167
+ * its own); a SIGTSTP is not heard, so its default action stops the whole group and SIGCONT
168
+ * continues it, and nothing of the suspend path runs. SIGINT, SIGTERM, SIGHUP, a terminal that
169
+ * goes away and an uncaught error end the run as always, but the borrower first: `end()` is
170
+ * called and the run ends when the borrower has closed, or LEND_END_GRACE_MS later. The
171
+ * terminal is already restored, so nothing more is written to it.
172
+ * Lending a terminal that is not the TUI's now (not entered, lent, over) runs nothing. */
173
+ function lend(run, { end = null, release = null } = {}) {
174
+ if (!entered || over || lent) return Promise.resolve({ error: new Error("the terminal is not the TUI's to lend now") });
175
+ leave();
176
+ quietly(() => stdin.pause());
177
+ proc.removeListener("SIGTSTP", suspend);
178
+ const mine = lent = { end, release, ending: null };
179
+ let running;
180
+ try { running = Promise.resolve(run()); } catch (error) { running = Promise.reject(error); }
181
+ return running.then((value) => ({ value }), (error) => ({ error })).then((outcome) => {
182
+ lent = null;
183
+ if (mine.ending) { finish(...mine.ending); return outcome; }
184
+ if (over) return outcome;
185
+ proc.on("SIGTSTP", suspend);
186
+ try { enter(); } catch { finish(TERMINAL_GONE_STATUS); return outcome; }
187
+ if (!over) stdin.resume();
188
+ attempt(onRedraw);
189
+ return outcome;
190
+ });
191
+ }
192
+ /** A way out that arrives while the terminal is lent: end the borrower and wait for it. A second
193
+ * one does not wait. */
194
+ function endLent(status, error) {
195
+ // The run does not wait for a borrower past this: what holds it (its handle, its pipe) is let
196
+ // go, so the process can end with the status of the signal although the borrower lives on.
197
+ const mine = lent, givenUp = () => { if (mine.release) attempt(mine.release); finish(status, error); };
198
+ if (mine.ending) return givenUp();
199
+ mine.ending = [status, error];
200
+ if (mine.end) attempt(mine.end);
201
+ if (over) return;
202
+ endTimer = setTimer(() => { endTimer = null; givenUp(); }, LEND_END_GRACE_MS);
203
+ }
204
+ /** Every way out the run can be told of: a signal, an error nobody caught, a terminal gone. */
205
+ function out(status, error) {
206
+ if (over) return;
207
+ if (lent) return endLent(status, error);
208
+ finish(status, error);
209
+ }
210
+
152
211
  /** Every way out is registered before the terminal is touched; then enter. A signal cannot land
153
212
  * inside enter(), which is synchronous, and one that lands after it finds its listener. */
154
213
  function start() {
155
- for (const [signal, status] of Object.entries(SIGNAL_STATUS)) on(proc, signal, () => finish(status));
214
+ for (const [signal, status] of Object.entries(SIGNAL_STATUS)) on(proc, signal, () => { if (!(lent && signal === "SIGQUIT")) out(status); });
156
215
  on(proc, "SIGCONT", continued);
157
216
  proc.on("SIGTSTP", suspend);
158
- on(proc, "uncaughtException", (error) => finish(1, error));
159
- on(proc, "unhandledRejection", (reason) => finish(1, reason));
217
+ on(proc, "uncaughtException", (error) => out(1, error));
218
+ on(proc, "unhandledRejection", (reason) => out(1, reason));
160
219
  on(proc, "exit", () => { leave(); if (onEnd) quietly(onEnd); }); // the last resort: a process.exit() nobody expected
161
220
  // A dead terminal answers a write or a read with an error event. These two listeners are never
162
221
  // removed: the write that restores the terminal can fail after the run is over, and an error
163
222
  // event nobody hears is an uncaught exception, which would turn the status into 1.
164
- for (const stream of [stdin, stdout]) stream.on("error", () => finish(TERMINAL_GONE_STATUS));
165
- on(stdin, "end", () => finish(TERMINAL_GONE_STATUS));
166
- on(stdin, "close", () => finish(TERMINAL_GONE_STATUS));
223
+ for (const stream of [stdin, stdout]) stream.on("error", () => out(TERMINAL_GONE_STATUS));
224
+ on(stdin, "end", () => out(TERMINAL_GONE_STATUS));
225
+ on(stdin, "close", () => out(TERMINAL_GONE_STATUS));
167
226
  on(stdin, "data", (bytes) => { if (entered) attempt(() => onInput(bytes)); });
168
227
  on(stdout, "resize", () => { if (entered) attempt(onResize); });
169
228
  on(stdout, "drain", drained);
@@ -174,5 +233,5 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
174
233
  /** The terminal's size now; 80x24 when the terminal does not say. */
175
234
  const size = () => ({ cols: Number.isInteger(stdout.columns) && stdout.columns > 0 ? stdout.columns : 80, rows: Number.isInteger(stdout.rows) && stdout.rows > 0 ? stdout.rows : 24 });
176
235
 
177
- return { start, enter, leave, finish, suspend, reassert, attempt, draw, size, done, get entered() { return entered; } };
236
+ return { start, enter, leave, finish, suspend, reassert, attempt, draw, lend, size, done, get entered() { return entered; }, get lent() { return lent !== null; } };
178
237
  }
@@ -60,24 +60,72 @@ function rule(cols, ascii, joint = null) {
60
60
  return spans;
61
61
  }
62
62
 
63
+ /** A sentence made of parts (lib/model.mjs OPEN_WORDS): the TUI's own words (`{ own }`) and text
64
+ * from outside (`{ shown }`, a name), each made safe on its own, so no word of the TUI's is ever
65
+ * filtered with a name and no name is ever taken for the TUI's. Set on at most `max` rows of at
66
+ * most `width` cells, broken at the spaces of the TUI's words; a name and what is written against
67
+ * it (a full stop) are never broken apart, and a name wider than a row is cut there. Answers rows
68
+ * of spans from column 0; when more was left, the last row ends in the cut mark. */
69
+ export function partRows(parts, width, max, { ascii = false } = {}) {
70
+ if (width < 1 || max < 1) return [];
71
+ // Units: what is written together, a space between two.
72
+ const units = [];
73
+ let glue = false;
74
+ const put = (piece) => { if (glue && units.length) units.at(-1).push(piece); else units.push([piece]); glue = true; };
75
+ for (const part of parts) {
76
+ if (part.own !== undefined) part.own.split(" ").forEach((word, i) => { if (i > 0) glue = false; if (word) put({ text: lit(word), width: word.length }); });
77
+ else { const m = measured(part.shown); if (m.width > 0) put(m); }
78
+ }
79
+ const unitWidth = (unit) => unit.reduce((sum, piece) => sum + piece.width, 0);
80
+ const rows = [];
81
+ let row = [], used = 0, i = 0;
82
+ for (; i < units.length; i++) {
83
+ const w = unitWidth(units[i]);
84
+ if (row.length && used + 1 + w > width) {
85
+ rows.push(row);
86
+ if (rows.length === max) break;
87
+ row = []; used = 0;
88
+ }
89
+ let col = row.length ? used + 1 : 0;
90
+ for (const piece of units[i]) { if (col < width) row.push({ col, text: piece.text, width: Math.min(piece.width, width - col) }); col += piece.width; }
91
+ used = Math.min(width, col);
92
+ }
93
+ if (i === units.length && row.length) rows.push(row);
94
+ const mark = ascii ? "..." : "\u2026";
95
+ if (i < units.length && rows.length && mark.length <= width) {
96
+ const last = rows[rows.length - 1];
97
+ while (last.length && last.at(-1).col + last.at(-1).width + 1 + mark.length > width) last.pop();
98
+ const end = last.length ? last.at(-1).col + last.at(-1).width + 1 : 0;
99
+ last.push({ col: end, text: lit(mark), width: mark.length });
100
+ }
101
+ return rows;
102
+ }
103
+
63
104
  /** Where everything stands for a size: the body under the header, the reason of a deployment
64
- * that is not live and the note of the one deployment of a view without headings (both wrapped
65
- * here, since their rows take room from the panes), and the panes. `notice` and `note` are the
66
- * model's (lib/model.mjs): the main loop asks for the layout first, because the model's window
67
- * is as tall, and the sentences in its list as wide, as the list pane this gives. The answer's
68
- * `note` is the note's rows. */
69
- export function layout(notice, size, { observed = true, note = null, ascii = false } = {}) {
105
+ * that is not live, the note of the one deployment of a view without headings and the line after
106
+ * an agent was opened (each wrapped here, since their rows take room from the panes), and the
107
+ * panes. `notice`, `note` and `outcome` are the model's (lib/model.mjs): the main loop asks for
108
+ * the layout first, because the model's window is as tall, and the sentences in its list as wide,
109
+ * as the list pane this gives. The answer's `note` is the note's rows and `outcome` the line's:
110
+ * its sentence and each text under it (what the viewer printed, what the kernel said) set as a
111
+ * reason is, on as many rows as a reason may take. */
112
+ export function layout(notice, size, { observed = true, note = null, ascii = false, outcome = null } = {}) {
70
113
  const body = { top: 3, rows: Math.max(0, size.rows - 5) };
71
114
  const wide = size.cols >= WIDE;
72
115
  const listCols = wide ? clamp(Math.floor(size.cols * 0.48), 36, 60) : size.cols;
73
116
  const across = Math.max(1, size.cols - 2 * MARGIN);
74
- const reason = notice ? shownLines(notice.reason, across, clamp(Math.floor(body.rows / 4), 1, REASON_ROWS), { ascii }) : [];
117
+ const reasonRows = clamp(Math.floor(body.rows / 4), 1, REASON_ROWS);
118
+ const reason = notice ? shownLines(notice.reason, across, reasonRows, { ascii }) : [];
75
119
  const noted = note ? shownLines(note, across, NOTE_ROWS, { ascii }) : [];
76
- // The state and its reason, then the note, stand above the panes, over the whole width; a rule
77
- // closes them when instances follow.
78
- const said = (notice ? 1 + reason.length : 0) + noted.length;
120
+ const after = outcome ? [
121
+ ...partRows(outcome.said, across, reasonRows, { ascii }),
122
+ ...outcome.under.flatMap((text) => shownLines(text, across, reasonRows, { ascii }).map((line) => [{ col: 0, text: line, width: across }])),
123
+ ] : [];
124
+ // The state and its reason, then the note, then the line after an open, stand above the panes,
125
+ // over the whole width; a rule closes them when instances follow.
126
+ const said = (notice ? 1 + reason.length : 0) + noted.length + after.length;
79
127
  const above = said ? Math.min(body.rows, said + (observed ? 1 : 0)) : 0;
80
- return { body, wide, listCols, reason, note: noted, above, panes: { top: body.top + above, rows: Math.max(0, body.rows - above) }, page: Math.max(0, body.rows - above) };
128
+ return { body, wide, listCols, reason, note: noted, outcome: after, above, panes: { top: body.top + above, rows: Math.max(0, body.rows - above) }, page: Math.max(0, body.rows - above) };
81
129
  }
82
130
 
83
131
  /** The header's middle, from `col` on in `room` cells: the workspace's name and, when the view
@@ -130,54 +178,87 @@ function countSpans(counts, cols) {
130
178
 
131
179
  /** The footer: the filter field while it is open; else the actions that apply now, read from the
132
180
  * effective table, as many as fit, `help` and `quit` last and always: their room is set aside
133
- * first, and a kept filter and the other hints take what is left. A hint that does not fit ends
134
- * the row's hints, so the order they are tried in is the order they are given up from the end:
135
- * `workspaces` stands after `refresh`, and a row too narrow for both keeps `refresh`. The
136
- * switcher has a filter of its own, drawn as the list's. A key's label is the user's
137
- * (views/help.mjs keyText); everything is placed by cells. */
181
+ * first, and a kept filter and the other hints take what is left. The hints stand in the order
182
+ * given, and when they do not all fit they are given up in an order of their own (`keep`, the
183
+ * first kept longest), so a hint can stand first and still be given up before another: in the
184
+ * list of instances `workspaces` goes first, then `refresh`, the key that clears a kept filter,
185
+ * `detail`, `open` and last `filter` (`filter` before `open` while a filter is kept: its own `/`
186
+ * stands in the footer then). A row too narrow for the whole of a hint drops it.
187
+ * `open` stands first while Enter would open the selected agent's terminal, and names the key
188
+ * that brings the TUI back (tui.json's `open.detachKey`, text from outside); while another
189
+ * machine is asked first, the key that gives the open up stands in its place. The switcher has
190
+ * a filter of its own, drawn as the list's. A key's label is the user's (views/help.mjs keyText);
191
+ * everything is placed by cells. */
138
192
  function footer(m, cols) {
139
193
  const action = (id) => m.actions.find((a) => a.id === id && a.keys.length);
140
- /** A hint: a key and what it does. */
141
- const made = (key, word) => ({ key, word, width: key.width + 1 + word.length });
194
+ /** A hint: a key and what it does, the TUI's word or safe text with its width. */
195
+ const made = (key, word) => {
196
+ const said = typeof word === "string" ? { text: lit(word), width: word.length } : word;
197
+ return { key, word: said, width: key.width + 1 + said.width };
198
+ };
142
199
  const hint = (id, label) => { const a = action(id); return a ? made(keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
143
200
  const edge = cols - MARGIN; // nothing stands at or past it
144
201
  /** A hint's spans at `col`, never past the edge. */
145
202
  const put = (h, col, look) => [
146
203
  { col, text: h.key.text, width: Math.max(0, Math.min(h.key.width, edge - col)), ...look },
147
- { col: col + h.key.width + 1, text: lit(h.word), width: Math.max(0, Math.min(h.word.length, edge - col - h.key.width - 1)), ...look },
204
+ ...h.word.spans.map((span) => ({ ...span, col: col + h.key.width + 1 + span.col })).map((span) => ({ ...span, width: Math.max(0, Math.min(span.width, edge - span.col)), ...look })),
148
205
  ].filter((span) => span.width > 0);
149
206
  const span = (hints) => hints.reduce((sum, h) => sum + h.width, 0) + Math.max(0, hints.length - 1) * GAP;
207
+ // A word is drawn as one span, or as the open hint's three: `open (`, the key, `returns)`.
208
+ const spansOf = (h) => ({ ...h, word: { ...h.word, spans: h.word.spans ?? [{ col: 0, text: h.word.text, width: h.word.width }] } });
150
209
 
151
210
  if (m.view !== "help" && m.filter.editing) {
152
- const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean);
211
+ const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean).map(spansOf);
153
212
  const spans = [{ col: MARGIN, text: lit("/"), style: BOLD, width: 1 }, { col: MARGIN + 1, text: shown(m.filter.query), width: Math.max(0, edge - span(hints) - GAP - MARGIN - 1) }];
154
213
  let col = Math.max(MARGIN + 2, edge - span(hints));
155
214
  for (const h of hints) { spans.push(...put(h, col, { style: DIM })); col += h.width + GAP; }
156
215
  return spans;
157
216
  }
158
- const ids = m.view === "help" ? ["close"]
217
+ /** The open hint: `Enter open (C-\ returns)`, the detach key drawn as text from outside. */
218
+ const opener = () => {
219
+ const a = action("open");
220
+ if (!a) return null;
221
+ const key = keyText(m.detachKey), lead = "open (", tail = "returns)";
222
+ const spans = [{ col: 0, text: lit(lead), width: lead.length }, { col: lead.length, text: key.text, width: key.width }, { col: lead.length + key.width + 1, text: lit(tail), width: tail.length }];
223
+ return made(keyText(keyLabel(a.keys[0])), { spans, width: lead.length + key.width + 1 + tail.length });
224
+ };
225
+ const listing = m.view !== "help" && m.view !== "switcher";
226
+ // While another machine is asked first, Esc gives the open up, and that is all it does: the
227
+ // hint stands where `open` stood, is kept as long, and `close` is not listed beside it.
228
+ const asking = listing && m.opening?.phase === "preflight";
229
+ // An action with no key (tui.json may unbind one) has no hint: nothing stands first then.
230
+ const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.openable ? [["open", opener()]] : []).filter(([, h]) => h);
231
+ const [ids, keep] = m.view === "help" ? [["close"], ["close"]]
159
232
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
160
233
  // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
161
- : m.view === "switcher" ? ["open-workspace", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])]
162
- : m.focus === "detail" ? ["detail", "close", "refresh"]
163
- : ["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces"];
164
- const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean);
234
+ : m.view === "switcher" ? [["open", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])], null]
235
+ : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "detail", "close", "refresh"]]
236
+ // A kept filter shows its own `/` beside the hints: then `open` outlives the `/ filter` hint.
237
+ : [["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces"], [...(m.filter.query ? ["open", "filter"] : ["filter", "open"]), "detail", "close", "refresh", "workspaces"]];
238
+ const hints = [...first, ...ids.filter((id) => !(asking && id === "close")).map((id) => [id, hint(id)])].filter(([, h]) => h).map(([id, h]) => [id, spansOf(h)]);
239
+ const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean).map(spansOf);
165
240
  const spans = [];
166
241
  let col = MARGIN;
167
242
  if (m.view !== "help" && m.filter.query) {
168
243
  // The kept filter has a place of its own width, so the hints stand where they always do;
169
- // it gives way, down to nothing, before `help` and `quit` do.
170
- const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0));
244
+ // it gives way, down to nothing, before `help` and `quit` do, and before the hint that
245
+ // stands first while Enter would open an agent (or Esc gives an open up).
246
+ const held = first.length ? first[0][1].width + GAP : 0;
247
+ const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0) - held);
171
248
  if (slot >= 2) {
172
249
  spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(m.filter.query), style: BOLD, width: slot - 1 });
173
250
  col += slot + GAP;
174
251
  }
175
252
  }
176
- for (const h of ids.map((id) => hint(id)).filter(Boolean)) {
177
- if (col + h.width + GAP + span(last) > edge) break;
178
- spans.push(...put(h, col));
179
- col += h.width + GAP;
253
+ // Give up hints until the rest fit: the one kept least first, else (no order of its own) the last.
254
+ let kept = hints;
255
+ const room = () => col + span(kept.map(([, h]) => h)) + (kept.length ? GAP : 0) + span(last) <= edge;
256
+ while (kept.length && !room()) {
257
+ const order = keep ?? kept.map(([id]) => id);
258
+ const least = [...order].reverse().find((id) => kept.some(([k]) => k === id)) ?? kept.at(-1)[0];
259
+ kept = kept.filter(([id]) => id !== least);
180
260
  }
261
+ for (const [, h] of kept) { spans.push(...put(h, col)); col += h.width + GAP; }
181
262
  for (const h of last) { spans.push(...put(h, col)); col += h.width + GAP; }
182
263
  return spans;
183
264
  }
@@ -192,7 +273,7 @@ const placed = (spans, col) => spans.map((span) => ({ ...span, col: span.col + c
192
273
  export function frame(m, size) {
193
274
  if (tooSmall(size)) return { rows: tooSmallRows(size), page: 1, extent: 0, room: 1 };
194
275
  const rows = Array.from({ length: size.rows }, () => []);
195
- const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii });
276
+ const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome });
196
277
  const { cols } = size;
197
278
  // The switcher is no view of the three: while it is shown, or is under the help, none is current.
198
279
  const listing = m.under === "switcher";
@@ -208,7 +289,7 @@ export function frame(m, size) {
208
289
  if (m.view === "help") {
209
290
  rows[2] = rule(cols, m.ascii);
210
291
  rows[size.rows - 2] = rule(cols, m.ascii);
211
- const drawn = help(m.actions, { cols, rows: g.body.rows }, { top: m.helpTop, ascii: m.ascii });
292
+ const drawn = help(m.actions, { cols, rows: g.body.rows }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey });
212
293
  drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
213
294
  return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: g.body.rows };
214
295
  }
@@ -232,6 +313,7 @@ export function frame(m, size) {
232
313
  for (const line of g.reason) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
233
314
  }
234
315
  for (const line of g.note) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
316
+ for (const spans of g.outcome) said.push(placed(spans, MARGIN));
235
317
  said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
236
318
  const paged = !g.wide && m.focus === "detail" && m.detail;
237
319
  // Two panes only over an observed deployment: with no instance there is nothing to put beside the list.
@@ -29,7 +29,7 @@ export function keyText(label) {
29
29
  * kernel's own usage, so the help cannot name a command that does not exist. A later version
30
30
  * removes a line when it adds the act. */
31
31
  export const NOT_YET = Object.freeze([
32
- Object.freeze({ what: "open an agent's terminal", command: "oats session attach --home <home>" }),
32
+ Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
33
33
  Object.freeze({ what: "stop an agent", command: "oats instance stop <instance>" }),
34
34
  Object.freeze({ what: "start or restart an agent", command: "oats session start --home <home>" }),
35
35
  Object.freeze({ what: "retire an agent", command: "oats retire <instance>" }),
@@ -67,7 +67,10 @@ const flow = (pieces, room) => pieces.reduce((lines, piece) => {
67
67
  * piece wider than that column puts every meaning under its entry instead, so no row is cut at
68
68
  * the smallest width the frame draws at. */
69
69
  function table(pairs, cols, look) {
70
- // An entry is the TUI's own word, or text made elsewhere with its width (a key's label).
70
+ // An entry is the TUI's own word, or text made elsewhere with its width (a key's label). A
71
+ // third member makes rows of its own under the entry's meaning: given the meaning's column and
72
+ // the cells it has, it answers rows of spans placed from column 0.
73
+ const under = new Map(pairs.map(([, pieces, more]) => [pieces, more]));
71
74
  pairs = pairs.map(([left, pieces]) => [typeof left === "string" ? { text: lit(left), width: left.length } : left, pieces]);
72
75
  const entry = (left) => ({ col: INDENT, text: left.text, width: left.width, ...(look ? { style: look } : {}) });
73
76
  const column = INDENT + Math.max(...pairs.map(([left]) => left.width)) + GAP;
@@ -75,9 +78,29 @@ function table(pairs, cols, look) {
75
78
  const at = stacked ? INDENT + 2 : column;
76
79
  return pairs.flatMap(([left, pieces]) => {
77
80
  const lines = flow(pieces, cols - at).map((text) => ({ col: at, text: lit(text) }));
78
- return stacked ? [[entry(left)], ...lines.map((line) => [line])] : lines.map((line, i) => (i === 0 ? [entry(left), line] : [line]));
81
+ const more = (under.get(pieces)?.(cols - at) ?? []).map((spans) => spans.map((span) => ({ ...span, col: span.col + at })));
82
+ return [...(stacked ? [[entry(left)], ...lines.map((line) => [line])] : lines.map((line, i) => (i === 0 ? [entry(left), line] : [line]))), ...more];
79
83
  });
80
84
  }
85
+
86
+ /** The TUI's own sentences under the line of `open` in the list of instances: the kernel's rule
87
+ * about tmux's copy mode, and where the keys that can be chosen are listed (the help does not
88
+ * restate the grammar). */
89
+ export const OPEN_RULES = Object.freeze([
90
+ "A key that tmux's copy mode binds leaves the viewer once the mode is left.",
91
+ "docs/execution-targets.md has the keys that can be chosen.",
92
+ ]);
93
+ /** The rows under the line of `open`, in `room` cells: the key that leaves an agent's terminal
94
+ * (tui.json's, text from outside), then OPEN_RULES, each sentence on as many rows as it needs. */
95
+ function openRows(detachKey, room) {
96
+ const key = keyText(detachKey), said = "brings oats tui back; the agent keeps running.";
97
+ const first = flow(words(said), Math.max(1, room - key.width - 1));
98
+ return [
99
+ [{ col: 0, text: key.text, width: key.width }, { col: key.width + 1, text: lit(first[0]) }],
100
+ ...first.slice(1).map((text) => [{ col: key.width + 1, text: lit(text) }]),
101
+ ...OPEN_RULES.flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
102
+ ];
103
+ }
81
104
  const heading = (text) => [{ col: INDENT, text: lit(text), style: TITLE }];
82
105
  /** Sentences, each from the left margin on as many rows as it needs, with that margin kept at
83
106
  * the right too: its later rows are set in, so the next sentence is seen to start. */
@@ -88,14 +111,20 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
88
111
 
89
112
  /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
90
113
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
91
- * now. */
92
- export function helpRows(actions, ascii, cols = 100) {
114
+ * now. An action that does one thing in each view has a line per view, its key on each; under
115
+ * the line of opening an agent stand the key that leaves its terminal (`detachKey`, tui.json's
116
+ * `open.detachKey`) and the rules of OPEN_RULES. */
117
+ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
93
118
  const marks = marksOf(ascii);
94
119
  const closing = keyText(["close", "help"].map((id) => actions.find((action) => action.id === id)).filter((action) => action?.keys.length).map((action) => keyLabel(action.keys[0])).join(" or "));
95
120
  return [
96
121
  heading("Keys"),
97
122
  [],
98
- ...table(actions.map((action) => [action.keys.length ? keyText(keysLabel(action)) : "(no key)", words(action.label)]), cols, KEYS),
123
+ ...table(actions.flatMap((action) => {
124
+ const left = action.keys.length ? keyText(keysLabel(action)) : "(no key)";
125
+ if (!action.views) return [[left, words(action.label)]];
126
+ return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room) : undefined]);
127
+ }), cols, KEYS),
99
128
  [],
100
129
  heading("Marks"),
101
130
  [],
@@ -129,8 +158,8 @@ export function helpRows(actions, ascii, cols = 100) {
129
158
 
130
159
  /** `{ rows, extent }`: `size.rows` rows for an area `size.cols` wide, scrolled to `top`, and how
131
160
  * many rows the whole help has. The movement keys scroll it. */
132
- export function help(actions, size, { top = 0, ascii = false } = {}) {
133
- const all = helpRows(actions, ascii, size.cols);
161
+ export function help(actions, size, { top = 0, ascii = false, detachKey = null } = {}) {
162
+ const all = helpRows(actions, ascii, size.cols, detachKey);
134
163
  const rows = Array.from({ length: size.rows }, () => []);
135
164
  const win = windowOf({ top, count: all.length, height: size.rows });
136
165
  all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
@@ -60,8 +60,8 @@ members:
60
60
  - git:github.com/acme/agents # the host is a member too
61
61
  - git:github.com/acme/platform
62
62
  packages:
63
- oats.framework: v1.10.0 # bare versions resolve through the official catalog
64
- oats.okf: v5.0.5
63
+ oats.framework: v1.10.1 # bare versions resolve through the official catalog
64
+ oats.okf: v5.1.0
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }
67
67
  knowledge: { oats.okf: { from: package } }
@@ -192,7 +192,10 @@ native configuration writers quiescent. Use `codex` or `all` for those selected
192
192
  harnesses; inspect the exact canonical root and effective native file first.
193
193
  The command changes only deployment-root trust and records an audit under
194
194
  `D/.agents/harness-trust.jsonl`. A failure can retain an applied native change;
195
- inspect its per-file outcome and audit before retrying. Nested Git boundaries
195
+ inspect its per-file outcome and audit before retrying. A refused entry's
196
+ `problem` names the check that refused its file; for a macOS `@` marker, accept
197
+ the harness's own folder-trust dialog instead and check the `harness-trust`
198
+ item of `oats readiness` (see "When the writer refuses"). Nested Git boundaries
196
199
  can prevent Claude inheritance. See [harness trust](../../docs/harness-trust.md). Folder-trust
197
200
  and API-key questions remain unexpected and blocked. The confirmation is
198
201
  answered with one Enter only when the screen equals an entry of the tolerance