@awebai/oats 0.67.1 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -65,6 +65,19 @@ export function workspaceOf(state, id, at) {
65
65
  if (id === null) return null;
66
66
  return viewModel(heldOf(state, at), TERMS).views.find((v) => v.id === id || v.deployments.includes(id))?.id ?? null;
67
67
  }
68
+ /** What a workspace's memory for the run is kept under (docs/tui.md, "Tabs"): the workspace that
69
+ * holds deployment `id` (workspaceOf), so another of its deployments finds the same memory; a
70
+ * deployment that reports no workspace, by its own id. Null for no deployment. */
71
+ export const memoryKey = (state, id, at) => (id === null ? null : workspaceOf(state, id, at) ?? id);
72
+ /** The palette's recency of the open workspace (`recent`, per memoryKey): its instances opened or
73
+ * shown in this run, the latest first. */
74
+ export const recentOf = (state, at) => state.recent.get(memoryKey(state, state.open, at)) ?? [];
75
+ /** The memoryKeys the views hold now (each view's id, and its deployments'), and the one each
76
+ * deployment whose read failed with nothing kept was in when it was last read (`unreadKeys`): it is
77
+ * in no view but its own until it is read again, so that view may only seem gone. */
78
+ export function memoryKeys(state, at) {
79
+ return new Set([...viewModel(heldOf(state, at), TERMS).views.flatMap((v) => [v.id, ...v.deployments]), ...state.unreadKeys.values()]);
80
+ }
68
81
 
69
82
  const text = (value) => typeof value === "string" && value !== "";
70
83
  const pad = (n) => String(n).padStart(2, "0");
@@ -240,8 +253,8 @@ function build(state, at) {
240
253
  status,
241
254
  workspace: text(panel?.workspace?.name) ? panel.workspace.name : "",
242
255
  machines, here,
243
- // The one machine of a view that holds no deployment of this machine: nothing else names it,
244
- // since a view of one deployment has no heading.
256
+ // The one machine of a view that holds no deployment of this machine: a view of one deployment
257
+ // has no heading, so the detail names it (detailOf).
245
258
  machine: !here && away.length === 1 ? away[0] : null,
246
259
  // The counts in the order they are drawn. `shared`: the word is the shared home's.
247
260
  counts: [
@@ -320,11 +333,14 @@ export function disclosure(state, r, item) {
320
333
  /** One row of the list: its mark, its name, the word its mark cannot say (or null), whether it
321
334
  * waits, and on a folded row only, how many instances are folded away under it (`folded`) and how
322
335
  * many of those wait (`below`). A row that is not folded says nothing of its children: they
323
- * stand under it, indented. */
336
+ * stand under it, indented. `selected` the selected row, `cursor` whether it carries `>`. */
324
337
  function listRow(state, r, item) {
325
338
  const closed = disclosure(state, r, item) === "closed";
326
339
  return {
327
340
  id: item.id, name: item.row.instance, depth: item.depth, selected: item.id === state.selected,
341
+ // The selected row keeps its reverse video while the list of workspaces has the focus, but not the
342
+ // cursor: only the region with the focus draws `>`.
343
+ cursor: item.id === state.selected && state.focus !== "workspaces",
328
344
  mark: markOf(item.row), color: rowColour(item.row), word: wordOf(item.row, state.ascii),
329
345
  waiting: waitingClaim(item.row, { stale: r.stale(item.row) }) !== null,
330
346
  folded: closed ? r.folded.get(item.id) ?? 0 : 0,
@@ -372,6 +388,11 @@ const LEADER_CLOSE = LEADER.find((entry) => entry.does === "close-terminal").key
372
388
  export const TAB_WORDS = Object.freeze({
373
389
  full: (limit, leader) => [{ own: `${limit} terminals are open; close one with ` }, { own: `${leader} ${keyLabel(LEADER_CLOSE)}`, whole: true }, { own: "." }],
374
390
  });
391
+ /** The line of a leader whose key came in its own read (docs/tui.md, "The leader"): dropped, and
392
+ * why. */
393
+ export const LEADER_WORDS = Object.freeze({
394
+ merged: (leader) => [{ own: leader, whole: true }, { own: " and the next key came in one read, so nothing ran: press them one after the other." }],
395
+ });
375
396
  /** The lines of a split that is not made (docs/tui.md, "Splits"): a second split, and a panel too
376
397
  * small for two groups (`min` views/split.mjs SPLIT_MIN). */
377
398
  export const SPLIT_WORDS = Object.freeze({
@@ -473,10 +494,12 @@ function detailOf(state, r, item, now, acts) {
473
494
  const row = item.row, facts = [];
474
495
  const add = (label, value, form = "line") => { if (text(value)) facts.push({ label, value, form }); };
475
496
  add("soul", row.agent);
497
+ // Which machine the instance is on: in a view of two or more deployments, and in one whose only
498
+ // deployment is another machine's, where no heading and no row of the list of workspaces names it.
499
+ if (r.multi || r.machine !== null) add("machine", row.deployment?.machine);
476
500
  if (r.multi) {
477
- // Which machine the instance is on, and, when that deployment is not live, the whole
478
- // sentence that says why: a heading has room for the short reason only.
479
- add("machine", row.deployment?.machine);
501
+ // When that deployment is not live, the whole sentence that says why: a heading has room for
502
+ // the short reason only.
480
503
  const of = r.deployments.find((d) => d.id === row.deployment?.id);
481
504
  const said = of ? deploymentState(of) : null;
482
505
  if (said && said.key !== "live") add("", said.detail, "wrap");
@@ -531,6 +554,20 @@ export const LIST_WORDS = Object.freeze({
531
554
  leaving: "oats: a change to this computer's list of deployments is still running; `oats deployments` shows the list.",
532
555
  });
533
556
 
557
+ /** The lines of the list of workspaces (docs/tui.md, "The list of workspaces"): the leader's Up or
558
+ * Down at an end of it, and a row picked there that is not a deployment any more. */
559
+ export const WORKSPACE_WORDS = Object.freeze({
560
+ above: () => [{ own: "No workspace above this one." }],
561
+ below: () => [{ own: "No workspace below this one." }],
562
+ refused: (name) => [{ shown: name }, { own: ": not an OATS deployment any more." }],
563
+ });
564
+ /** The switcher's choices with no filter, in its order (workspaceList's rows are their keys). */
565
+ export const listChoices = (state, at = new Date(0).toISOString()) => switcherOf(state, at, "").made.items.filter((item) => item.key !== undefined);
566
+ /** The switcher's choice of key `key`, with no filter, or null. */
567
+ export const listChoice = (state, key, at) => listChoices(state, at).find((item) => item.key === key) ?? null;
568
+
569
+ /** The help's `keys` on macOS (views/help.mjs chordFamilyLines): no family, no file's note. */
570
+ const MAC_KEYS = Object.freeze({ family: null, label: null, note: null, mac: true });
534
571
  /** What the switcher says above its rows, as views/switcher.mjs leadRows reads it. */
535
572
  const leadOf = (state) => ({ said: state.switcher.line, failure: state.listed.failure?.message ?? null, removing: state.switcher.removing !== null });
536
573
  /** How many rows stand above the switcher's choices in an area `cols` wide (the switcher's is the
@@ -572,13 +609,18 @@ function indicatorState(info) {
572
609
  * cuts the path and keeps it).
573
610
  * `keys` are the choices in order; `selected` is the key the selection stands on (the first choice
574
611
  * when the state's own is not listed). */
575
- export function switcher(state, at = new Date(0).toISOString()) {
612
+ export const switcher = (state, at = new Date(0).toISOString()) => switcherOf(state, at, state.switcher.query).made;
613
+ /** The switcher's rows for `query` (`made`), and of each workspace's key whether some instance of it
614
+ * needs input (`waits`), which the list of workspaces says (workspaceList). */
615
+ function switcherOf(state, at, query) {
576
616
  const held = heldOf(state, at);
577
617
  const unserved = state.listed.rows.filter((row) => !state.ctxs.includes(row.path));
578
618
  // Only a row the kernel says is a deployment is matched: a stale one (missing, not one any more) says so instead.
579
619
  const views = listedViews(held, unserved.filter((row) => row.state === "ok"), TERMS);
580
- const rows = workspaceChoiceRows(workspaceChoices(held, TERMS, views));
581
- const query = state.switcher.query;
620
+ const choices = workspaceChoices(held, TERMS, views), rows = workspaceChoiceRows(choices);
621
+ // Whether some instance of a workspace needs input: what this run observes of it alone, the shared
622
+ // choice's `waiting` (its served deployments' reads; unknown or stale is not).
623
+ const waits = new Map(choices.map((choice) => [`view\u0000${choice.id}`, choice.waiting === true]));
582
624
  const viewOf = (id) => views.views.find((v) => v.id === id);
583
625
  const openView = state.open === null ? null : views.views.find((v) => v.id === state.open || v.deployments.includes(state.open))?.id ?? null;
584
626
  const items = [];
@@ -610,10 +652,72 @@ export function switcher(state, at = new Date(0).toISOString()) {
610
652
  );
611
653
  const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
612
654
  const total = rows.length + unserved.filter((row) => !taken.has(row.path)).length;
613
- return {
655
+ const made = {
614
656
  items, keys, selected: keys.includes(state.switcher.selected) ? state.switcher.selected : keys[0] ?? null,
615
657
  empty: keys.length ? null : total ? "nomatch" : "none",
616
658
  };
659
+ return { made, waits };
660
+ }
661
+ /** THE LIST OF WORKSPACES (docs/tui.md, "The list of workspaces"): one row per workspace the switcher
662
+ * offers, by its name, whatever machines it is on, in the switcher's order, at the top of the
663
+ * sidebar. A workspace only this machine's deployments not opened make is not one of them, nor a
664
+ * view with nothing to open, nor a row of this computer's list: the switcher keeps those (`w` `w`).
665
+ * `lines`: a row `{ key, label, current, waiting }`: `current` the open workspace's row; `waiting`
666
+ * whether some instance of it needs input, as far as this run observes it (an unknown never says
667
+ * so). `rows`: the rows as `{ key, openable }`, for workspaceStep (every row opens). `current`: the
668
+ * open row's key, or null. Kept while what it is made from (LIST_MADE_FROM) is the same: every
669
+ * frame and every key asks for it, and the shared home walks every machine to make it, so it is
670
+ * not asked again for a key or a paint that changed none of that (as `roster` is kept). */
671
+ const LIST_MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "cli", "home", "identities", "listed"];
672
+ let listKept = null;
673
+ export function workspaceList(state, at) {
674
+ if (listKept !== null && LIST_MADE_FROM.every((name) => listKept.state[name] === state[name])) return listKept.list;
675
+ const lines = [], { made, waits } = switcherOf(state, at, "");
676
+ for (const item of made.items) {
677
+ if (item.key === undefined || item.path !== undefined) continue;
678
+ const notOpened = item.join?.length > 0 && item.join.length === item.opens.length;
679
+ const opens = item.join?.length > 0 || item.primary !== null;
680
+ if (notOpened || !opens) continue;
681
+ lines.push(Object.freeze({ key: item.key, label: item.label, current: item.open === true, waiting: waits.get(item.key) === true }));
682
+ }
683
+ const list = Object.freeze({ lines: Object.freeze(lines), rows: Object.freeze(lines.map(({ key }) => Object.freeze({ key, openable: true }))), current: lines.find((line) => line.current)?.key ?? null });
684
+ listKept = { state, list };
685
+ return list;
686
+ }
687
+ /** The most lines the list stands on; more are windowed, and the last line says how many are not
688
+ * shown (`+N`), with the dot when an instance of one of them needs input. */
689
+ export const LIST_LINES = 5;
690
+ /** How many rows stand at the top of the sidebar (views/frame.mjs layout's `list`): the list's,
691
+ * LIST_LINES at most, while a workspace is open and the switcher is not shown; else the title's
692
+ * one. */
693
+ export function listRowsOf(state, at) {
694
+ const under = state.view === "help" || state.view === "act" ? state.back : state.view;
695
+ const list = listModel(state, under, at);
696
+ return list === null ? 1 : list.lines.length + (list.more > 0 ? 1 : 0);
697
+ }
698
+ /** The list as the sidebar draws it (views/workspaces.mjs): its lines windowed around the cursor
699
+ * while the list has the focus, else around the open workspace's row; `more` how many are not
700
+ * shown, and `moreWaiting` whether one of those is waiting; `focused`; `cursor` the cursor's row
701
+ * key, null without the focus. Null while nothing is listed (no workspace open, or the switcher
702
+ * shown): the title stands there. */
703
+ function listModel(state, under, at) {
704
+ if (under === "switcher" || state.open === null) return null;
705
+ const list = workspaceList(state, at);
706
+ if (!list.lines.length) return null;
707
+ const focused = state.view === "instances" && state.focus === "workspaces";
708
+ const cursor = focused ? (list.rows.some((row) => row.key === state.workspaceCursor) ? state.workspaceCursor : list.current) : null;
709
+ return { ...listWindow(list.lines, cursor ?? list.current), focused, cursor };
710
+ }
711
+ /** The lines the list draws, windowed around `keep` (the focused row, else the open one): all of
712
+ * them when they fit, else LIST_LINES - 1 of them, and `more`, how many are not shown, and
713
+ * `moreWaiting`, whether one of those is `waiting`. */
714
+ export function listWindow(lines, keep) {
715
+ if (lines.length <= LIST_LINES) return { lines, more: 0, moreWaiting: false };
716
+ const height = LIST_LINES - 1, at = Math.max(0, lines.findIndex((line) => line.key === keep));
717
+ const top = Math.min(Math.max(0, at - Math.floor(height / 2)), lines.length - height);
718
+ const shown = lines.slice(top, top + height);
719
+ const moreWaiting = lines.some((line, i) => (i < top || i >= top + height) && line.waiting);
720
+ return { lines: shown, more: lines.length - shown.length, moreWaiting };
617
721
  }
618
722
  /** The window of the switcher's `items` in a pane `height` rows tall, from `top`, that holds the choice
619
723
  * `key` and, while they fit, the indicator lines under it (scroll.mjs windowOf, asked to keep the last
@@ -669,7 +773,7 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
669
773
  const r = roster(state, at);
670
774
  const openable = r.instances.filter((row) => openDecision(state, row, instanceActs(row)).open);
671
775
  // The record of focus the shared order reads: larger is more recent, `recent` is the latest first.
672
- const lastFocus = new Map(state.recent.map((id, i) => [id, state.recent.length - i]));
776
+ const recent = recentOf(state, at), lastFocus = new Map(recent.map((id, i) => [id, recent.length - i]));
673
777
  const item = (row) => {
674
778
  const machine = elsewhere(row) ? row.deployment?.machine ?? row.server : null;
675
779
  // `sibling`: the shared words for its siblings, or null; never part of what a query matches.
@@ -721,9 +825,9 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
721
825
  const items = runs.flat(), selectable = items.filter((each) => each.kind !== "group"), instances = selectable.filter((each) => each.kind === "instance");
722
826
  // With nothing chosen yet, the first row that can be selected; but in the palette as it opens (no
723
827
  // query), when that is the shown tab's instance (the most recent), the instance shown before it
724
- // (`recent`'s second, wherever its group puts it), else the second instance: the palette and Enter
725
- // go back to the terminal before it, as the Desktop's recent group did.
726
- const before = instances.find((each) => each.id === state.recent[1]) ?? instances[1];
828
+ // (the second of this workspace's recency, wherever its group puts it), else the second instance:
829
+ // the palette and Enter go back to the terminal before it, as the Desktop's recent group did.
830
+ const before = instances.find((each) => each.id === recentOf(state, at)[1]) ?? instances[1];
727
831
  const first = p.query === "" && instances.length > 1 && selectable[0] === instances[0] && instances[0].id === state.terminal?.id ? before : selectable[0];
728
832
  return {
729
833
  items, runs: runs.map((run) => run.filter((each) => each.kind !== "group").map((each) => each.key)),
@@ -776,12 +880,19 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
776
880
  workspace: r.workspace, machines: r.machines, here: r.here, machine: r.machine, counts: r.counts, readAt: r.readAt, notice: r.notice, note: r.note, empty: r.empty, observed: r.observed,
777
881
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
778
882
  detachKey: state.detachKey, opening: state.opening, openable: false,
779
- // The chords read now, `[key id, does]` (actions.mjs chordsRead), and whether the terminal
780
- // confirms the kitty keyboard protocol: then the help and a terminal's cheat sheet lead with them.
883
+ // The chords read now, `[key id, does]` (actions.mjs chordsRead), whether the terminal confirms
884
+ // the kitty keyboard protocol, and whether every chord bound is read now (under the protocol, or
885
+ // the Alt family, whose keys all come without it): then the help and a terminal's cheat sheet
886
+ // lead with them.
781
887
  chords: [...chordsRead(state.chords, state.keyboard !== null)], kitty: state.keyboard !== null,
888
+ chordsLead: state.chords.size > 0 && chordsRead(state.chords, state.keyboard !== null).size === state.chords.size,
889
+ // Whether a chord shows the Nth tab (tab-1 to tab-9): the tabs carry their numbers only then
890
+ // (views/frame.mjs stripRow). On macOS none does: ⌥⌘N never reaches a terminal.
891
+ tabNumbers: [...state.chords.values()].some((does) => /^tab-[1-9]$/.test(does)),
782
892
  // The family the chords are bound in (keys.json, lib/config.mjs loadKeys), its name, and the line that says
783
893
  // why the file was not taken, or null (the shared chordFamilyNote): the help's chords section names both.
784
- keys: state.keysRead ? Object.freeze({ family: state.keysRead.family, label: CHORD_FAMILY_LABELS[state.keysRead.family] ?? CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY], note: chordFamilyNote(state.keysRead) }) : null,
894
+ // macOS has no family (`mac`): its chords are the arrows, whatever keys.json says.
895
+ keys: state.mac === true ? MAC_KEYS : state.keysRead ? Object.freeze({ family: state.keysRead.family, label: CHORD_FAMILY_LABELS[state.keysRead.family] ?? CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY], note: chordFamilyNote(state.keysRead) }) : null,
785
896
  // The palette's own keys, `[key id, does]` (actions.mjs paletteKeys; none on macOS): its cheat
786
897
  // sheet and the help name them.
787
898
  paletteKeys: [...state.paletteKeys],
@@ -792,13 +903,15 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
792
903
  split: state.split, group: state.group, panelOpen: state.tabs.length > 0, groups: groupsOf(state),
793
904
  tabs: groupsOf(state)[state.group].tabs,
794
905
  act: state.view === "act" && state.act ? actView(state) : null,
795
- // The leader waits for its key (the cheat sheet is its hint), and the palette, while it is open.
796
- leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, body, at),
906
+ // The palette, while it is open.
907
+ palette: state.palette === null ? null : paletteView(state, body, at),
797
908
  souls: under === "souls" ? soulsView(state, page, at) : null,
798
909
  capabilities: under === "capabilities" ? capabilitiesView(state, page, at) : null,
799
910
  spawn: state.spawn === null ? null : spawnView(state, body, at),
800
911
  // The line under the sidebar's title: the last outcome, else a spawn under way (outcomeOf).
801
912
  outcome: outcomeOf(state),
913
+ // The list of workspaces at the top of the sidebar, and whether colour may say the dot.
914
+ workspaces: listModel(state, under, at), colour: state.colour !== false,
802
915
  };
803
916
  if (under === "switcher") {
804
917
  const s = switcher(state, at);