@awebai/oats 0.56.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 (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
@@ -1,11 +1,13 @@
1
1
  // The frame: (model, size) -> the rows of the whole screen. Pure: no IO, no clock, no escape
2
2
  // byte. It places the views: the header, the list of instances and the detail beside it (or as a
3
- // page of its own on a narrow terminal), the switcher of workspaces over the whole body, the
4
- // help, and the footer. The TUI's own words are lit(); everything else is shown(). Meaning never
3
+ // page of its own on a narrow terminal), an agent's open terminal in the detail's place (or over
4
+ // the whole body, zoomed), the switcher of workspaces over the whole body, the help, and the
5
+ // footer. The TUI's own words are lit(); everything else is shown(). Meaning never
5
6
  // rests on colour alone: what is dim or bold also says what it is in words or by a mark.
6
7
  import { keyLabel } from "../actions.mjs";
7
8
  import { lit, shown, shownLines } from "../term/text.mjs";
8
9
  import { style } from "../term/style.mjs";
10
+ import { act } from "./act.mjs";
9
11
  import { detail } from "./detail.mjs";
10
12
  import { help, keyText } from "./help.mjs";
11
13
  import { instances, measured } from "./instances.mjs";
@@ -15,10 +17,16 @@ import { switcher } from "./switcher.mjs";
15
17
  export const MIN_SIZE = Object.freeze({ cols: 60, rows: 15 });
16
18
  /** From this width up the detail stands beside the list; under it, it is a page of its own. */
17
19
  export const WIDE = 80;
18
- /** The views, named so the frame has its shape. Two are dim: they cannot be opened yet, and the
19
- * help says what to run instead. */
20
- const VIEWS = Object.freeze([Object.freeze({ name: "1 Instances", open: true }), Object.freeze({ name: "2 Souls", open: false }), Object.freeze({ name: "3 Capabilities", open: false })]);
20
+ /** The views, the header's second row: navigation, so no count and no digit stands against a name
21
+ * (the help and the footer name the digits). The open one is drawn in reverse; the two that
22
+ * cannot be opened yet are dim, and their key says what to run instead. */
23
+ const VIEWS = Object.freeze([Object.freeze({ name: "Instances", open: true }), Object.freeze({ name: "Souls", open: false }), Object.freeze({ name: "Capabilities", open: false })]);
24
+ /** The cells between two views' names: each name has one cell on each side of it (the reverse bar
25
+ * of the open one), and one between. */
26
+ const VIEW_GAP = 1;
21
27
  const GAP = 3;
28
+ /** The least width of a terminal beside the list: under it the terminal has the whole body. */
29
+ export const PANEL_MIN = 40;
22
30
  /** One cell of margin on each side of the header and the footer. */
23
31
  const MARGIN = 1;
24
32
  /** The longest run one lit() holds with room to spare: the display filter bounds a line, and a
@@ -40,6 +48,8 @@ const NAME_MIN = 8;
40
48
 
41
49
  const BOLD = style({ bold: true });
42
50
  const DIM = style({ dim: true });
51
+ const REVERSE = style({ reverse: true });
52
+ const FOCUSED = style({ bold: true, reverse: true });
43
53
 
44
54
  const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
45
55
  const tooSmall = (size) => size.cols < MIN_SIZE.cols || size.rows < MIN_SIZE.rows;
@@ -181,14 +191,21 @@ function countSpans(counts, cols) {
181
191
  * first, and a kept filter and the other hints take what is left. The hints stand in the order
182
192
  * given, and when they do not all fit they are given up in an order of their own (`keep`, the
183
193
  * 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. */
194
+ * list of instances the acts go first (`restart`, `start`, `retire`, then `stop`), then the views
195
+ * (one hint for the three, `1-3 views`), then `workspaces`, `refresh`, the key that clears a
196
+ * kept filter, `detail`, the open terminal's `close-terminal` and `zoom`, `open` and last `filter`
197
+ * (`filter` before `open` while a filter is kept: its own `/` stands in the footer then). A row
198
+ * too narrow for the whole of a hint drops it.
199
+ * `open` stands first while Enter would open the selected agent's terminal, or (`focus terminal`)
200
+ * go to the one open on the selected row; while another machine is asked first, the key that
201
+ * gives the open up stands in its place. With a terminal open, `zoom` and `close-terminal` follow
202
+ * it; then the acts whose key opens a confirmation for the selected row now (the model's
203
+ * `actable`). While the terminal has the focus the TUI reads no key but the back key, and the
204
+ * footer names that alone (tui.json's `open.detachKey`, text from outside). In a confirmation the
205
+ * buttons are on the screen, and the footer says how to work them: the close key with the close
206
+ * button's label, the keys that move, Enter, and `quit`. The switcher has a filter of its own,
207
+ * drawn as the list's. A key's label is the user's (views/help.mjs keyText); everything is placed
208
+ * by cells. */
192
209
  function footer(m, cols) {
193
210
  const action = (id) => m.actions.find((a) => a.id === id && a.keys.length);
194
211
  /** A hint: a key and what it does, the TUI's word or safe text with its width. */
@@ -197,6 +214,8 @@ function footer(m, cols) {
197
214
  return { key, word: said, width: key.width + 1 + said.width };
198
215
  };
199
216
  const hint = (id, label) => { const a = action(id); return a ? made(keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
217
+ /** The hints that are no one action's: made below. */
218
+ const hintOf = {};
200
219
  const edge = cols - MARGIN; // nothing stands at or past it
201
220
  /** A hint's spans at `col`, never past the edge. */
202
221
  const put = (h, col, look) => [
@@ -204,9 +223,18 @@ function footer(m, cols) {
204
223
  ...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 })),
205
224
  ].filter((span) => span.width > 0);
206
225
  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)`.
226
+ // A word is drawn as one span, unless it was made of spans already.
208
227
  const spansOf = (h) => ({ ...h, word: { ...h.word, spans: h.word.spans ?? [{ col: 0, text: h.word.text, width: h.word.width }] } });
209
228
 
229
+ // While what is typed goes to the agent the TUI takes one key, the back key, and the footer
230
+ // names it alone (tui.json's open.detachKey, text from outside), in every such frame: before
231
+ // anything else the footer could show.
232
+ const listing = m.view !== "help" && m.view !== "switcher";
233
+ if (listing && m.terminal?.focus === "terminal") {
234
+ const key = keyText(m.detachKey), word = "back to the list";
235
+ return [{ col: MARGIN, text: key.text, width: Math.max(0, Math.min(key.width, edge - MARGIN)) },
236
+ { col: MARGIN + key.width + 1, text: lit(word), width: Math.max(0, Math.min(word.length, edge - MARGIN - key.width - 1)) }].filter((s) => s.width > 0);
237
+ }
210
238
  if (m.view !== "help" && m.filter.editing) {
211
239
  const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean).map(spansOf);
212
240
  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) }];
@@ -214,28 +242,47 @@ function footer(m, cols) {
214
242
  for (const h of hints) { spans.push(...put(h, col, { style: DIM })); col += h.width + GAP; }
215
243
  return spans;
216
244
  }
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";
245
+ if (m.view === "act" && m.act) {
246
+ // The confirmation: its buttons are the offers, on the screen; the footer says how to work them.
247
+ const close = action("close"), shut = m.act.buttons.find((button) => button.id === "close");
248
+ const hints = [
249
+ ...(close && shut ? [made(keyText(keyLabel(close.keys[0])), shut.label)] : []),
250
+ ...(m.act.buttons.length > 1 ? [made({ text: lit("Left/Right"), width: "Left/Right".length }, "move")] : []),
251
+ made({ text: lit("Enter"), width: "Enter".length }, "press"),
252
+ ].map(spansOf);
253
+ const quit = hint("quit");
254
+ const all = [...hints, ...(quit ? [spansOf(quit)] : [])];
255
+ const spans = [];
256
+ let col = MARGIN;
257
+ for (const h of all) { if (col + h.width > edge) break; spans.push(...put(h, col)); col += h.width + GAP; }
258
+ return spans;
259
+ }
226
260
  // While another machine is asked first, Esc gives the open up, and that is all it does: the
227
261
  // hint stands where `open` stood, is kept as long, and `close` is not listed beside it.
228
262
  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);
263
+ // An action with no key (tui.json may unbind one) has no hint: nothing stands first then. On the
264
+ // row whose terminal is open, Enter goes to it.
265
+ const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.onTerminal ? [["open", hint("open", "focus terminal")]] : listing && m.openable ? [["open", hint("open")]] : []).filter(([, h]) => h);
266
+ // With a terminal open, the keys that zoom it and close it stand after `open`, kept as long.
267
+ const terminal = listing && m.terminal ? [["zoom", hint("zoom")], ["close-terminal", hint("close-terminal")]].filter(([, h]) => h) : [];
268
+ // The acts the selected row offers now stand after those, and are the first given up.
269
+ const acts = listing && !asking ? (m.actable ?? []).map((verb) => [verb, hint(verb)]).filter(([, h]) => h) : [];
270
+ const ACTS = ["stop", "retire", "start", "restart"];
271
+ // The three views are one hint, `views`, named by their keys: `1-3` while they are the digits
272
+ // in order, else each key (tui.json may rebind one), and a view with no key left out. The
273
+ // header shows which views there are; the help names each key.
274
+ const viewKeys = ["instances", "souls", "capabilities"].map((id) => action(id)).filter(Boolean).map((a) => keyLabel(a.keys[0]));
275
+ const views = viewKeys.length === 0 ? null : made(keyText(viewKeys.join("") === "123" ? "1-3" : viewKeys.join("/")), "views");
276
+ hintOf.views = views;
277
+ const VIEW_KEYS = ["views"];
231
278
  const [ids, keep] = m.view === "help" ? [["close"], ["close"]]
232
279
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
233
280
  // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
234
281
  : 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"]]
282
+ : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "close", "refresh", ...ACTS]]
236
283
  // 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)]);
284
+ : [["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces", ...VIEW_KEYS], [...(m.filter.query ? ["open", "zoom", "close-terminal", "filter"] : ["filter", "open", "zoom", "close-terminal"]), "detail", "close", "refresh", "workspaces", ...VIEW_KEYS, ...ACTS]];
285
+ const hints = [...first, ...terminal, ...acts, ...ids.filter((id) => !(asking && id === "close")).map((id) => [id, id in hintOf ? hintOf[id] : hint(id)])].filter(([, h]) => h).map(([id, h]) => [id, spansOf(h)]);
239
286
  const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean).map(spansOf);
240
287
  const spans = [];
241
288
  let col = MARGIN;
@@ -243,7 +290,10 @@ function footer(m, cols) {
243
290
  // The kept filter has a place of its own width, so the hints stand where they always do;
244
291
  // it gives way, down to nothing, before `help` and `quit` do, and before the hint that
245
292
  // 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;
293
+ // The room of that first hint is kept only when it fits beside `help` and `quit`: a hint that
294
+ // cannot stand takes no room from the filter.
295
+ const firstFits = first.length > 0 && col + first[0][1].width + GAP + span(last) <= edge;
296
+ const held = firstFits ? first[0][1].width + GAP : 0;
247
297
  const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0) - held);
248
298
  if (slot >= 2) {
249
299
  spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(m.filter.query), style: BOLD, width: slot - 1 });
@@ -282,10 +332,23 @@ export function frame(m, size) {
282
332
  const nameCol = MARGIN + "oats".length + 2;
283
333
  rows[0] = [{ col: MARGIN, text: lit("oats"), style: BOLD }, ...nameSpans(m, nameCol, counts.start - 2 - nameCol), ...counts.spans];
284
334
  let col = MARGIN;
285
- for (const view of VIEWS) { rows[1].push({ col, text: lit(view.name), ...(view.open && !listing ? {} : { style: DIM }), width: view.name.length }); col += view.name.length + GAP; }
335
+ for (const view of VIEWS) {
336
+ // The Instances view is the open one but while the switcher is shown: then none is.
337
+ const look = !view.open ? DIM : listing ? null : REVERSE;
338
+ if (look === REVERSE) rows[1].push({ col, width: view.name.length + 2, style: REVERSE });
339
+ rows[1].push({ col: col + 1, text: lit(view.name), ...(look ? { style: look } : {}), width: view.name.length });
340
+ col += view.name.length + 2 + VIEW_GAP;
341
+ }
286
342
  if (m.readAt) { const read = `read ${m.readAt}`; rows[1].push({ col: cols - MARGIN - read.length, text: lit(read), style: DIM, width: read.length }); }
287
343
  rows[size.rows - 1] = footer(m, cols);
288
344
 
345
+ if (m.view === "act" && m.act) {
346
+ rows[2] = rule(cols, m.ascii);
347
+ rows[size.rows - 2] = rule(cols, m.ascii);
348
+ const drawn = act(m, { cols, rows: g.body.rows });
349
+ drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
350
+ return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: drawn.room };
351
+ }
289
352
  if (m.view === "help") {
290
353
  rows[2] = rule(cols, m.ascii);
291
354
  rows[size.rows - 2] = rule(cols, m.ascii);
@@ -315,9 +378,12 @@ export function frame(m, size) {
315
378
  for (const line of g.note) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
316
379
  for (const spans of g.outcome) said.push(placed(spans, MARGIN));
317
380
  said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
318
- const paged = !g.wide && m.focus === "detail" && m.detail;
319
- // Two panes only over an observed deployment: with no instance there is nothing to put beside the list.
320
- const split = g.wide && g.panes.rows > 0 && m.observed;
381
+ const area = terminalAt(m, size, g);
382
+ const zoomed = area !== null && area.whole;
383
+ const paged = !zoomed && !g.wide && m.focus === "detail" && m.detail;
384
+ // Two panes only over an observed deployment, or beside an open terminal: with no instance and
385
+ // no terminal there is nothing to put beside the list.
386
+ const split = !zoomed && g.wide && g.panes.rows > 0 && (m.observed || area !== null);
321
387
  const joint = split ? { col: g.listCols } : null;
322
388
  // The rule that opens the panes: the one under the header, or the one under the reason and the note.
323
389
  const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
@@ -327,12 +393,62 @@ export function frame(m, size) {
327
393
 
328
394
  const pane = { cols: g.wide ? g.listCols : cols, rows: g.panes.rows };
329
395
  let extent = 0;
330
- if (!paged) instances(m, pane).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
331
- if (split || paged) {
396
+ if (!paged && !zoomed) instances(m, pane).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
397
+ const bar = split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : [];
398
+ if (area !== null) {
399
+ for (let i = 0; i < g.panes.rows; i++) rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar];
400
+ terminalRows(m, area).forEach((spans, i) => { rows[area.title + i] = [...rows[area.title + i], ...spans]; });
401
+ } else if (split || paged) {
332
402
  const at = paged ? MARGIN : g.listCols + 2;
333
403
  const drawn = detail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
334
404
  extent = drawn.extent;
335
- drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...(split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : []), ...placed(spans, at)]; });
405
+ drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar, ...placed(spans, at)]; });
406
+ }
407
+ // The agent's cursor, where the agent has it, while what is typed goes to the agent.
408
+ const agent = area !== null && m.terminal.focus === "terminal" ? m.screen?.cursor : null;
409
+ const cursor = agent?.visible && agent.y < area.rows && agent.x < area.cols ? { row: area.top + agent.y, col: area.col + agent.x } : null;
410
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows), terminal: area, cursor };
411
+ }
412
+
413
+ /** Where the open terminal stands for a model and a size, or null while it is not shown (no
414
+ * terminal; another view over the body; the detail in its place; the list's focus on a terminal
415
+ * too narrow for it beside the list). `{ title, top, col, cols, rows, whole }`: `title` is the row
416
+ * that names the agent, and the agent's screen is `rows` rows of `cols` cells from (`top`, `col`)
417
+ * (the size the panel gives the viewer). With the terminal's focus it has the whole body when it is
418
+ * zoomed, under WIDE columns, and when the side beside the list would be under PANEL_MIN cells
419
+ * (`whole`); else it stands beside the list, edge to edge, in the detail's place. */
420
+ export function terminalArea(m, size) {
421
+ if (tooSmall(size)) return null;
422
+ return terminalAt(m, size, layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome }));
423
+ }
424
+ function terminalAt(m, size, g) {
425
+ const t = m.terminal;
426
+ if (!t || m.view !== "instances" || m.under === "switcher" || g.panes.rows < 2) return null;
427
+ const side = size.cols - g.listCols - 1;
428
+ const narrow = !g.wide || side < PANEL_MIN;
429
+ const whole = t.focus === "terminal" && (t.zoom || narrow);
430
+ // From the list's focus it stands beside the list, unless the detail stands there or there is no room.
431
+ if (t.focus !== "terminal" && (m.focus === "detail" || narrow)) return null;
432
+ const col = whole ? 0 : g.listCols + 1;
433
+ return { title: g.panes.top, top: g.panes.top + 1, col, cols: whole ? size.cols : side, rows: g.panes.rows - 1, whole };
434
+ }
435
+
436
+ /** The open terminal's rows from its title row: the agent's name (and its machine, when it is
437
+ * another's), in reverse while what is typed goes to it, then the agent's screen as the last
438
+ * capture made it (lib/panel.mjs, term/capture.mjs: spans of the agent's own text and styles), each
439
+ * row placed at the terminal's first column and kept inside its cells. */
440
+ function terminalRows(m, area) {
441
+ const t = m.terminal, focused = t.focus === "terminal";
442
+ const name = measured(t.name), title = [];
443
+ if (focused) title.push({ col: area.col, width: Math.min(area.cols, name.width + 2), style: FOCUSED });
444
+ title.push({ col: area.col + 1, text: name.text, style: focused ? FOCUSED : BOLD, width: Math.max(0, Math.min(name.width, area.cols - 2)) });
445
+ if (t.routed && t.machine !== null) {
446
+ const where = measured(t.machine), at = area.col + name.width + 3;
447
+ if (at + ON.length + 1 < area.col + area.cols) title.push({ col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.max(0, area.col + area.cols - (at + ON.length + 1)) });
336
448
  }
337
- return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows) };
449
+ const lines = m.screen?.lines ?? [];
450
+ const body = Array.from({ length: area.rows }, (_, r) => (lines[r] ?? [])
451
+ .filter((span) => span.col < area.cols)
452
+ .map((span) => ({ ...span, col: area.col + span.col, width: Math.min(span.width ?? area.cols, area.cols - span.col) })));
453
+ return [title, ...body];
338
454
  }
@@ -30,9 +30,7 @@ export function keyText(label) {
30
30
  * removes a line when it adds the act. */
31
31
  export const NOT_YET = Object.freeze([
32
32
  Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
33
- Object.freeze({ what: "stop an agent", command: "oats instance stop <instance>" }),
34
- Object.freeze({ what: "start or restart an agent", command: "oats session start --home <home>" }),
35
- Object.freeze({ what: "retire an agent", command: "oats retire <instance>" }),
33
+ Object.freeze({ what: "start with another harness or model", command: "oats session start --home <home>" }),
36
34
  Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
37
35
  Object.freeze({ what: "check a machine", command: "oats server check <id>" }),
38
36
  Object.freeze({ what: "remove a machine", command: "oats server remove <id>" }),
@@ -83,17 +81,19 @@ function table(pairs, cols, look) {
83
81
  });
84
82
  }
85
83
 
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). */
84
+ /** The TUI's own sentences under the line of `open` in the list of instances: what the terminal
85
+ * takes, what it does not do, and where the keys that can be the back key are listed (the help
86
+ * does not restate the grammar). */
89
87
  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.",
88
+ "While the terminal has the focus every other key goes to the agent, Ctrl+C and Ctrl+Z too.",
89
+ "One terminal is open at a time. It has no scrollback but the viewer's own, and no mouse.",
90
+ "docs/tui.md has the keys that can be the back key.",
92
91
  ]);
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. */
92
+ /** The rows under the line of `open`, in `room` cells: the back key, which takes the focus from the
93
+ * open terminal (tui.json's open.detachKey, text from outside), then OPEN_RULES, each sentence on
94
+ * as many rows as it needs. */
95
95
  function openRows(detachKey, room) {
96
- const key = keyText(detachKey), said = "brings oats tui back; the agent keeps running.";
96
+ const key = keyText(detachKey), said = "takes the focus from the terminal back to the list; the agent keeps running.";
97
97
  const first = flow(words(said), Math.max(1, room - key.width - 1));
98
98
  return [
99
99
  [{ col: 0, text: key.text, width: key.width }, { col: key.width + 1, text: lit(first[0]) }],
@@ -101,6 +101,13 @@ function openRows(detachKey, room) {
101
101
  ...OPEN_RULES.flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
102
102
  ];
103
103
  }
104
+ /** The TUI's own sentences under the line of the last act: how a confirmation is worked, and that
105
+ * what it sent is never ended by the TUI. */
106
+ export const ACT_RULES = Object.freeze([
107
+ "Each act opens a confirmation with Cancel chosen: move to the act with Left/Right or Tab, then press Enter.",
108
+ "Esc closes a confirmation; an act it sent goes on, also after oats tui quits.",
109
+ ]);
110
+ const actRows = (room) => ACT_RULES.flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }]));
104
111
  const heading = (text) => [{ col: INDENT, text: lit(text), style: TITLE }];
105
112
  /** Sentences, each from the left margin on as many rows as it needs, with that margin kept at
106
113
  * the right too: its later rows are set in, so the next sentence is seen to start. */
@@ -112,8 +119,8 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
112
119
  /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
113
120
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
114
121
  * 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. */
122
+ * the line of opening an agent stand the back key (`detachKey`, tui.json's `open.detachKey`) and
123
+ * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. */
117
124
  export function helpRows(actions, ascii, cols = 100, detachKey = null) {
118
125
  const marks = marksOf(ascii);
119
126
  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 "));
@@ -123,7 +130,8 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
123
130
  ...table(actions.flatMap((action) => {
124
131
  const left = action.keys.length ? keyText(keysLabel(action)) : "(no key)";
125
132
  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]);
133
+ return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room)
134
+ : action.id === "restart" ? actRows : undefined]);
127
135
  }), cols, KEYS),
128
136
  [],
129
137
  heading("Marks"),
@@ -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.1 # bare versions resolve through the official catalog
64
- oats.okf: v5.1.0
63
+ oats.framework: v1.12.0 # bare versions resolve through the official catalog
64
+ oats.okf: v5.2.0
65
65
  defaults:
66
66
  capabilities: { oats.core: { from: package } }
67
67
  knowledge: { oats.okf: { from: package } }
@@ -184,7 +184,8 @@ plugin:aweb-channel@awebai-marketplace` (the default `delivery: channel`,
184
184
  `docs/configuration.md#the-development-channel-confirmation`. There is no
185
185
  consent setting. To keep the prompt for a person, set
186
186
  `settings.oats.aweb.delivery: session` or `claudeChannelMode: approved` in
187
- `oats-local.yaml`. An old `launchPromptAnswers` block is ignored with a warning
187
+ `oats-local.yaml`. The approved route and the host wake broker are set up with
188
+ oats.setup's `/oats-host-delivery`. An old `launchPromptAnswers` block is ignored with a warning
188
189
  (remove it); one with `awebDevelopmentChannel: false` is refused. Handle
189
190
  folder trust explicitly with `oats harness trust --dir D --harness claude --plan`,
190
191
  then the same command without `--plan` to apply. Run it on the target host with
@@ -1,45 +0,0 @@
1
- // Opening an agent's terminal: the one child of the TUI that is not a read. It is the kernel's own
2
- // viewer (`oats session attach … --detach-key <key>`), whose arguments the shared home builds
3
- // (client.mjs sessionAttachArgv, prepareRemoteTerm): nothing here names an argument, a tmux
4
- // server or an exit status. The TUI builds no viewer and runs no tmux command.
5
- //
6
- // UNLIKE EVERY READ (lib/read.mjs), THE VIEWER IS NOT STARTED IN A SESSION OF ITS OWN. It needs
7
- // the terminal as its controlling terminal and must be in the foreground process group, so the
8
- // terminal's signals reach it as they reach the TUI. It is the loop's child, never the reader's:
9
- // the reader ends only the reads it started, and nothing of its clean-up can reach a viewer.
10
- import { spawn as nodeSpawn } from "node:child_process";
11
-
12
- /** The most of the viewer's stderr that is kept, in bytes: the last ones. */
13
- export const STDERR_KEPT = 4096;
14
-
15
- /** Start the viewer: `node <bin> <args…>` with stdin and stdout on the terminal (inherited) and
16
- * stderr on a pipe; no shell, the TUI's own environment (the instance variables were removed at
17
- * the start; the kernel's viewer drops TMUX for its own child). Answers `{ closed, end, release }`:
18
- * `closed` resolves once the child has closed, never rejects, with `{ status, stderr }`: `status`
19
- * the exit status as Node reports it (null when a signal ended it, or when it did not start),
20
- * `stderr` the last STDERR_KEPT bytes it printed, as text. `end()` asks it to end (SIGTERM to the
21
- * child alone: the kernel closes its viewer on it); after it has closed, end() does nothing.
22
- * `release()` lets go of a viewer that did not end when asked: its stderr pipe is destroyed and
23
- * its handle no longer holds the process, which can then exit while the viewer lives on. */
24
- export function startViewer(bin, args, { env = process.env, spawn = nodeSpawn } = {}) {
25
- let child, over = false;
26
- const closed = new Promise((resolve) => {
27
- let kept = Buffer.alloc(0);
28
- const done = (status) => { if (!over) { over = true; resolve({ status, stderr: kept.toString("utf8") }); } };
29
- try {
30
- child = spawn(process.execPath, [bin, ...args], { stdio: ["inherit", "inherit", "pipe"], env, shell: false });
31
- } catch { return done(null); }
32
- child.stderr?.on("error", () => {});
33
- child.stderr?.on("data", (chunk) => {
34
- kept = Buffer.concat([kept, chunk]);
35
- if (kept.length > STDERR_KEPT) kept = kept.subarray(kept.length - STDERR_KEPT);
36
- });
37
- child.on("error", () => { if (!child.pid) done(null); });
38
- child.once("close", (code) => done(Number.isInteger(code) ? code : null));
39
- });
40
- return {
41
- closed,
42
- end() { if (!over && child) { try { child.kill("SIGTERM"); } catch { /* gone */ } } },
43
- release() { if (!over && child) { child.stderr?.destroy(); child.unref(); } },
44
- };
45
- }