@awebai/oats 0.57.0 → 0.58.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 (60) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +19 -28
  3. package/docs/desktop-cli-api.md +38 -15
  4. package/docs/desktop.md +14 -0
  5. package/docs/execution-targets.md +10 -1
  6. package/docs/implementation.md +7 -1
  7. package/docs/integrations.md +3 -1
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.57.1.md +275 -0
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/servers.md +18 -0
  13. package/docs/souls-and-instances.md +9 -0
  14. package/docs/tui.md +224 -87
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +11 -4
  17. package/lib/session-viewer.mjs +29 -4
  18. package/package-catalog.json +1 -1
  19. package/package.json +1 -1
  20. package/packages/client/cli-adapter.mjs +9 -7
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/composed-gate.mjs +34 -0
  23. package/packages/client/inspect-boundary.mjs +157 -0
  24. package/packages/client/inspect-cache.mjs +86 -0
  25. package/packages/client/keyed-catalog.mjs +132 -0
  26. package/packages/client/launch-view.mjs +46 -0
  27. package/packages/client/panel-views.mjs +1 -1
  28. package/packages/client/session-attach.mjs +7 -5
  29. package/packages/client/soul-catalog.mjs +77 -0
  30. package/packages/client/soul-colors.mjs +31 -0
  31. package/packages/client/soul-facts.mjs +85 -0
  32. package/packages/client/soul-rows.mjs +48 -0
  33. package/packages/client/spawn-apply-cli.mjs +19 -8
  34. package/packages/client/spawn-apply.mjs +216 -0
  35. package/packages/client/spawn-messages.mjs +131 -85
  36. package/packages/client/spawn-preview-cli.mjs +2 -1
  37. package/packages/client/spawn-preview-contract.mjs +3 -0
  38. package/packages/client/spawn-preview-facts.mjs +119 -0
  39. package/packages/client/spawn-preview.mjs +164 -0
  40. package/packages/client/spawn-transaction.mjs +136 -0
  41. package/packages/record/lib/directory-identity.mjs +14 -0
  42. package/packages/record/lib/native-history.mjs +6 -5
  43. package/packages/tui/README.md +32 -11
  44. package/packages/tui/lib/actions.mjs +10 -1
  45. package/packages/tui/lib/config.mjs +9 -14
  46. package/packages/tui/lib/main.mjs +165 -57
  47. package/packages/tui/lib/model.mjs +28 -24
  48. package/packages/tui/lib/panel.mjs +1019 -0
  49. package/packages/tui/lib/read.mjs +5 -14
  50. package/packages/tui/lib/store.mjs +77 -30
  51. package/packages/tui/lib/term/capture.mjs +260 -0
  52. package/packages/tui/lib/term/screen.mjs +44 -8
  53. package/packages/tui/lib/term/style.mjs +78 -6
  54. package/packages/tui/lib/term/text.mjs +24 -4
  55. package/packages/tui/lib/term/through.mjs +213 -0
  56. package/packages/tui/lib/term/tty.mjs +7 -60
  57. package/packages/tui/lib/views/frame.mjs +126 -40
  58. package/packages/tui/lib/views/help.mjs +12 -10
  59. package/skills/oats-getting-started/SKILL.md +3 -2
  60. package/packages/tui/lib/open.mjs +0 -45
@@ -1,7 +1,8 @@
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";
@@ -16,10 +17,16 @@ import { switcher } from "./switcher.mjs";
16
17
  export const MIN_SIZE = Object.freeze({ cols: 60, rows: 15 });
17
18
  /** From this width up the detail stands beside the list; under it, it is a page of its own. */
18
19
  export const WIDE = 80;
19
- /** The views, named so the frame has its shape. Two are dim: they cannot be opened yet, and the
20
- * help says what to run instead. */
21
- 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;
22
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;
23
30
  /** One cell of margin on each side of the header and the footer. */
24
31
  const MARGIN = 1;
25
32
  /** The longest run one lit() holds with room to spare: the display filter bounds a line, and a
@@ -41,6 +48,8 @@ const NAME_MIN = 8;
41
48
 
42
49
  const BOLD = style({ bold: true });
43
50
  const DIM = style({ dim: true });
51
+ const REVERSE = style({ reverse: true });
52
+ const FOCUSED = style({ bold: true, reverse: true });
44
53
 
45
54
  const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
46
55
  const tooSmall = (size) => size.cols < MIN_SIZE.cols || size.rows < MIN_SIZE.rows;
@@ -182,18 +191,21 @@ function countSpans(counts, cols) {
182
191
  * first, and a kept filter and the other hints take what is left. The hints stand in the order
183
192
  * given, and when they do not all fit they are given up in an order of their own (`keep`, the
184
193
  * first kept longest), so a hint can stand first and still be given up before another: in the
185
- * list of instances the acts go first (`restart`, `start`, `retire`, then `stop`), then
186
- * `workspaces`, `refresh`, the key that clears a kept filter, `detail`, `open` and last `filter`
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`
187
197
  * (`filter` before `open` while a filter is kept: its own `/` stands in the footer then). A row
188
198
  * too narrow for the whole of a hint drops it.
189
- * `open` stands first while Enter would open the selected agent's terminal, and names the key
190
- * that brings the TUI back (tui.json's `open.detachKey`, text from outside); while another
191
- * machine is asked first, the key that gives the open up stands in its place. After it stand
192
- * the acts whose key opens a confirmation for the selected row now (the model's `actable`). In a
193
- * confirmation the buttons are on the screen, and the footer says how to work them: the close
194
- * key with the close button's label, the keys that move, Enter, and `quit`. The switcher has a
195
- * filter of its own, drawn as the list's. A key's label is the user's (views/help.mjs keyText);
196
- * everything is placed by cells. */
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. */
197
209
  function footer(m, cols) {
198
210
  const action = (id) => m.actions.find((a) => a.id === id && a.keys.length);
199
211
  /** A hint: a key and what it does, the TUI's word or safe text with its width. */
@@ -202,6 +214,8 @@ function footer(m, cols) {
202
214
  return { key, word: said, width: key.width + 1 + said.width };
203
215
  };
204
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 = {};
205
219
  const edge = cols - MARGIN; // nothing stands at or past it
206
220
  /** A hint's spans at `col`, never past the edge. */
207
221
  const put = (h, col, look) => [
@@ -209,9 +223,18 @@ function footer(m, cols) {
209
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 })),
210
224
  ].filter((span) => span.width > 0);
211
225
  const span = (hints) => hints.reduce((sum, h) => sum + h.width, 0) + Math.max(0, hints.length - 1) * GAP;
212
- // 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.
213
227
  const spansOf = (h) => ({ ...h, word: { ...h.word, spans: h.word.spans ?? [{ col: 0, text: h.word.text, width: h.word.width }] } });
214
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
+ }
215
238
  if (m.view !== "help" && m.filter.editing) {
216
239
  const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean).map(spansOf);
217
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) }];
@@ -219,14 +242,6 @@ function footer(m, cols) {
219
242
  for (const h of hints) { spans.push(...put(h, col, { style: DIM })); col += h.width + GAP; }
220
243
  return spans;
221
244
  }
222
- /** The open hint: `Enter open (C-\ returns)`, the detach key drawn as text from outside. */
223
- const opener = () => {
224
- const a = action("open");
225
- if (!a) return null;
226
- const key = keyText(m.detachKey), lead = "open (", tail = "returns)";
227
- 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 }];
228
- return made(keyText(keyLabel(a.keys[0])), { spans, width: lead.length + key.width + 1 + tail.length });
229
- };
230
245
  if (m.view === "act" && m.act) {
231
246
  // The confirmation: its buttons are the offers, on the screen; the footer says how to work them.
232
247
  const close = action("close"), shut = m.act.buttons.find((button) => button.id === "close");
@@ -242,23 +257,32 @@ function footer(m, cols) {
242
257
  for (const h of all) { if (col + h.width > edge) break; spans.push(...put(h, col)); col += h.width + GAP; }
243
258
  return spans;
244
259
  }
245
- const listing = m.view !== "help" && m.view !== "switcher";
246
260
  // While another machine is asked first, Esc gives the open up, and that is all it does: the
247
261
  // hint stands where `open` stood, is kept as long, and `close` is not listed beside it.
248
262
  const asking = listing && m.opening?.phase === "preflight";
249
- // An action with no key (tui.json may unbind one) has no hint: nothing stands first then.
250
- const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.openable ? [["open", opener()]] : []).filter(([, h]) => h);
251
- // The acts the selected row offers now stand after `open`, and are the first given up.
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.
252
269
  const acts = listing && !asking ? (m.actable ?? []).map((verb) => [verb, hint(verb)]).filter(([, h]) => h) : [];
253
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"];
254
278
  const [ids, keep] = m.view === "help" ? [["close"], ["close"]]
255
279
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
256
280
  // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
257
281
  : m.view === "switcher" ? [["open", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])], null]
258
- : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "detail", "close", "refresh", ...ACTS]]
282
+ : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "close", "refresh", ...ACTS]]
259
283
  // A kept filter shows its own `/` beside the hints: then `open` outlives the `/ filter` hint.
260
- : [["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces"], [...(m.filter.query ? ["open", "filter"] : ["filter", "open"]), "detail", "close", "refresh", "workspaces", ...ACTS]];
261
- const hints = [...first, ...acts, ...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)]);
262
286
  const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean).map(spansOf);
263
287
  const spans = [];
264
288
  let col = MARGIN;
@@ -266,7 +290,10 @@ function footer(m, cols) {
266
290
  // The kept filter has a place of its own width, so the hints stand where they always do;
267
291
  // it gives way, down to nothing, before `help` and `quit` do, and before the hint that
268
292
  // stands first while Enter would open an agent (or Esc gives an open up).
269
- 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;
270
297
  const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0) - held);
271
298
  if (slot >= 2) {
272
299
  spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(m.filter.query), style: BOLD, width: slot - 1 });
@@ -305,7 +332,13 @@ export function frame(m, size) {
305
332
  const nameCol = MARGIN + "oats".length + 2;
306
333
  rows[0] = [{ col: MARGIN, text: lit("oats"), style: BOLD }, ...nameSpans(m, nameCol, counts.start - 2 - nameCol), ...counts.spans];
307
334
  let col = MARGIN;
308
- 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
+ }
309
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 }); }
310
343
  rows[size.rows - 1] = footer(m, cols);
311
344
 
@@ -345,9 +378,12 @@ export function frame(m, size) {
345
378
  for (const line of g.note) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
346
379
  for (const spans of g.outcome) said.push(placed(spans, MARGIN));
347
380
  said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
348
- const paged = !g.wide && m.focus === "detail" && m.detail;
349
- // Two panes only over an observed deployment: with no instance there is nothing to put beside the list.
350
- 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);
351
387
  const joint = split ? { col: g.listCols } : null;
352
388
  // The rule that opens the panes: the one under the header, or the one under the reason and the note.
353
389
  const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
@@ -357,12 +393,62 @@ export function frame(m, size) {
357
393
 
358
394
  const pane = { cols: g.wide ? g.listCols : cols, rows: g.panes.rows };
359
395
  let extent = 0;
360
- if (!paged) instances(m, pane).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
361
- 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) {
362
402
  const at = paged ? MARGIN : g.listCols + 2;
363
403
  const drawn = detail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
364
404
  extent = drawn.extent;
365
- 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)) });
366
448
  }
367
- 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];
368
454
  }
@@ -81,17 +81,19 @@ function table(pairs, cols, look) {
81
81
  });
82
82
  }
83
83
 
84
- /** The TUI's own sentences under the line of `open` in the list of instances: the kernel's rule
85
- * about tmux's copy mode, and where the keys that can be chosen are listed (the help does not
86
- * 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). */
87
87
  export const OPEN_RULES = Object.freeze([
88
- "A key that tmux's copy mode binds leaves the viewer once the mode is left.",
89
- "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.",
90
91
  ]);
91
- /** The rows under the line of `open`, in `room` cells: the key that leaves an agent's terminal
92
- * (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. */
93
95
  function openRows(detachKey, room) {
94
- 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.";
95
97
  const first = flow(words(said), Math.max(1, room - key.width - 1));
96
98
  return [
97
99
  [{ col: 0, text: key.text, width: key.width }, { col: key.width + 1, text: lit(first[0]) }],
@@ -117,8 +119,8 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
117
119
  /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
118
120
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
119
121
  * now. An action that does one thing in each view has a line per view, its key on each; under
120
- * the line of opening an agent stand the key that leaves its terminal (`detachKey`, tui.json's
121
- * `open.detachKey`) and the rules of OPEN_RULES; under the line of the last act, ACT_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. */
122
124
  export function helpRows(actions, ascii, cols = 100, detachKey = null) {
123
125
  const marks = marksOf(ascii);
124
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 "));
@@ -60,7 +60,7 @@ 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.2 # bare versions resolve through the official catalog
63
+ oats.framework: v1.12.0 # bare versions resolve through the official catalog
64
64
  oats.okf: v5.2.0
65
65
  defaults:
66
66
  capabilities: { oats.core: { 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
- }