@awebai/oats 0.68.0 → 0.69.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 (72) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +147 -13
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.68.1.md +102 -0
  15. package/docs/release-notes/v0.69.0.md +658 -0
  16. package/docs/release-notes/v0.69.1.md +25 -0
  17. package/docs/servers.md +44 -5
  18. package/docs/souls-and-instances.md +11 -7
  19. package/docs/tui.md +114 -31
  20. package/docs/upgrading.md +14 -5
  21. package/docs/workspaces.md +1 -1
  22. package/lib/core.mjs +345 -89
  23. package/lib/file-pieces.mjs +49 -0
  24. package/lib/instance-events.mjs +25 -4
  25. package/lib/launch-prompt-fixtures/README.md +62 -0
  26. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  27. package/lib/launch-prompt-fixtures.mjs +49 -0
  28. package/lib/launch-prompt-resume.mjs +55 -0
  29. package/lib/login-environment.mjs +27 -9
  30. package/lib/schedule.mjs +3 -3
  31. package/lib/servers.mjs +117 -23
  32. package/lib/session-end.mjs +82 -0
  33. package/lib/session-input.mjs +43 -9
  34. package/lib/session-resume-contract.mjs +32 -0
  35. package/lib/session-resume.mjs +310 -0
  36. package/lib/session-seen.mjs +163 -0
  37. package/lib/session-viewer.mjs +147 -44
  38. package/lib/soul-composition.mjs +2 -1
  39. package/lib/start-env.mjs +110 -0
  40. package/lib/tmux-server-scope.mjs +139 -14
  41. package/lib/workspace.mjs +38 -4
  42. package/package-catalog.json +10 -4
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +9 -0
  45. package/packages/client/cli-locator.mjs +3 -2
  46. package/packages/client/deployment-data.mjs +7 -0
  47. package/packages/client/deployment-panel.mjs +3 -0
  48. package/packages/client/file-output-exec.mjs +98 -0
  49. package/packages/client/instance-display-name.mjs +18 -0
  50. package/packages/client/launch-prompt-outcome.mjs +25 -13
  51. package/packages/client/own-codes.mjs +2 -0
  52. package/packages/client/session-attach.mjs +35 -5
  53. package/packages/client/session-resume-cli.mjs +64 -0
  54. package/packages/client/session-resume-trigger.mjs +167 -0
  55. package/packages/client/session-resume.mjs +332 -0
  56. package/packages/client/tmux-status.mjs +30 -7
  57. package/packages/client/waiting-on-you.mjs +11 -4
  58. package/packages/client/workspace-step.mjs +17 -5
  59. package/packages/record/lib/last-conversation.mjs +123 -0
  60. package/packages/record/lib/session-roots.mjs +10 -1
  61. package/packages/tui/README.md +1 -1
  62. package/packages/tui/lib/client.mjs +2 -1
  63. package/packages/tui/lib/main.mjs +5 -3
  64. package/packages/tui/lib/model.mjs +57 -15
  65. package/packages/tui/lib/store.mjs +8 -7
  66. package/packages/tui/lib/term/text.mjs +12 -9
  67. package/packages/tui/lib/views/capabilities.mjs +6 -6
  68. package/packages/tui/lib/views/frame.mjs +72 -7
  69. package/packages/tui/lib/views/help.mjs +9 -4
  70. package/packages/tui/lib/views/instances.mjs +46 -29
  71. package/packages/tui/lib/views/souls.mjs +9 -8
  72. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -112,10 +112,15 @@ function commandRows(command, at, cols) {
112
112
  * takes, what it does not do, and where the keys that can be the back key are listed (the help
113
113
  * does not restate the grammar). */
114
114
  export const OPEN_RULES = Object.freeze([
115
- "While the terminal has the focus every other key goes to the agent, Ctrl+C and Ctrl+Z too.",
116
- "Up to 4 terminals are open at a time, each a tab. They have no scrollback but the viewer's own, and no mouse.",
115
+ "While the terminal has the focus every key but its scroll keys goes to the agent, Ctrl+C and Ctrl+Z too.",
116
+ "Up to 4 terminals, as tabs, no mouse. Shift+PageUp or Ctrl+B [ (tmux 3.3+) scrolls back; PageUp, PageDown move, q leaves.",
117
117
  "docs/tui.md has the keys that can be the leader.",
118
118
  ]);
119
+ /** OPEN_RULES for a leader of Ctrl+B, which the TUI takes before the viewer reads it: Ctrl+B [
120
+ * cannot be typed into a terminal there, so the help does not name it. */
121
+ const OPEN_RULES_CTRL_B = Object.freeze(OPEN_RULES.map((sentence, i) => (i === 1 ? "Up to 4 terminals, as tabs, no mouse. Shift+PageUp scrolls back; PageUp, PageDown move, q leaves." : sentence)));
122
+ /** The rules for the leader `detachKey`. */
123
+ const openRulesFor = (detachKey) => (backKeyLabel(detachKey) === "Ctrl+B" ? OPEN_RULES_CTRL_B : OPEN_RULES);
119
124
  /** The rows under the line of `open`, in `room` cells: the leader then Esc, which takes the focus
120
125
  * from the open terminal, and the leader twice, which types it into the terminal (tui.json's
121
126
  * open.detachKey, text from outside), then OPEN_RULES, each sentence on as many rows as it needs. */
@@ -128,7 +133,7 @@ function openRows(detachKey, room, chorded = false) {
128
133
  return [
129
134
  ...pair(`${label} ${esc}`, "takes the focus from the terminal back to the list; the agent keeps running."),
130
135
  ...pair(`${label} ${label}`, "types the leader into the terminal."),
131
- ...[...OPEN_RULES, ...(chorded ? [CHORD_OPEN_RULE] : [])].flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
136
+ ...[...openRulesFor(detachKey), ...(chorded ? [CHORD_OPEN_RULE] : [])].flatMap((sentence) => flow(words(sentence), room).map((text) => [{ col: 0, text: lit(text) }])),
132
137
  ];
133
138
  }
134
139
  /** Under OPEN_RULES, while the chords are listed: they too are the TUI's in a terminal. */
@@ -351,7 +356,7 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null, chords =
351
356
  [marks.unknown, "state unknown"],
352
357
  [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
353
358
  ["+N", "N instances folded away below it"],
354
- [marks.waiting, `needs input, in reverse video: ${NEEDS_INPUT} where the whole name fits`],
359
+ [marks.waiting, `${NEEDS_INPUT}: in place of the state mark, in yellow and reverse video`],
355
360
  ["N", `N instances folded away below it need input: ${belowText("N")} where the whole name fits`],
356
361
  [marks.selected, "the selected row, and the pane the movement keys act on"],
357
362
  [OPEN_MARK, "among the workspaces: the one that is open"],
@@ -3,19 +3,20 @@
3
3
  // marks and the few words around them are the TUI's own. Nothing is told by colour alone: each
4
4
  // state has a mark of its own shape, the selected row carries `>` as well as reverse video (the `>`
5
5
  // only while the list has the focus, not the list of workspaces: the model's `cursor`), and a
6
- // waiting row carries a tag in words, `Needs input`, in reverse video. A row is quiet: its mark
6
+ // waiting row's state mark is the needs-input mark, `!` in reverse video. A row is quiet: its mark
7
7
  // and its name, and a word only where the mark can't say it. Children stand under their parent by
8
8
  // indentation alone; a folded row says how many it folds away, `+n`, and how many of those wait,
9
9
  // `N below`. In a view of two or more deployments the list also holds a heading per deployment
10
10
  // and the sentences the model sets under one: a heading says in words what it is of.
11
11
  import { keyLabel } from "../actions.mjs";
12
12
  import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
13
- import { style } from "../term/style.mjs";
13
+ import { COLORS, style } from "../term/style.mjs";
14
14
  import { textWidth } from "../term/width.mjs";
15
15
 
16
16
  /** The marks, in UTF-8 and in ASCII (docs/tui.md lists them; the help view draws them from here).
17
17
  * The state marks are keyed by the word the shared home gives a row's state, with `shell` and
18
- * `held` beside them (lib/model.mjs says when). A fold has no mark: a folded row shows `+n`. */
18
+ * `held` beside them (lib/model.mjs says when). `waiting` takes the state mark's cell on a row
19
+ * that needs input, whatever its state. A fold has no mark: a folded row shows `+n`. */
19
20
  export const MARKS = Object.freeze({
20
21
  utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", selected: ">", waiting: "!" }),
21
22
  ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", selected: ">", waiting: "!" }),
@@ -25,8 +26,8 @@ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
25
26
  /** Two cells of indent per level, and no deeper than this many levels: a deeper row sits at the last. */
26
27
  const INDENT = 2, LEVELS = 6;
27
28
  /** The cells every row keeps at its right edge, so the word column stands in one place whether a
28
- * row waits or not: they hold a needs-input tag in its short form, ` ! ` to ` 99+ `, whose
29
- * padding is its gap. A tag in words takes more, and one cell of gap before it. */
29
+ * row folds waiting rows away or not: they hold the roll-up's tag in its short form, ` 1 ` to
30
+ * ` 99+ `, whose padding is its gap. A tag in words takes more, and one cell of gap before it. */
30
31
  const EDGE = 5;
31
32
  /** A row's cells before its name: the selection mark, a gap, the state mark, a gap. */
32
33
  const LEAD = 4;
@@ -52,27 +53,42 @@ const PLAIN = style();
52
53
  const BOLD = style({ bold: true });
53
54
  const DIM = style({ dim: true });
54
55
  const SELECTED = style({ reverse: true });
55
- /** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does. */
56
- export const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
56
+ /** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does.
57
+ * No state is yellow: yellow says needs input, and only that. */
58
+ export const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: DIM, held: style({ fg: "magenta" }) });
57
59
  /** The marks an instance's colour (feature instance-color) draws: running in it, stopped and at its shell in
58
60
  * it and dim. The shape still says the state; `unknown` and `held` keep their own look whatever the colour. */
59
61
  const COLOURED = Object.freeze({ running: false, stopped: true, shell: true });
60
- /** A state mark's look for a row of colour `colour` (a terminal colour name, or null for none). */
62
+ /** The colour that is the terminal's own foreground, no `fg` at all: `sand`'s (views/souls.mjs
63
+ * SOUL_COLOURS), which can't be yellow and stays seen on a light theme as on a dark one. */
64
+ export const DEFAULT_FG = "default";
65
+ /** The look an instance's or a soul's colour draws, with `attributes` (`{ dim }`): `colour` a terminal
66
+ * colour name or DEFAULT_FG; null for any other value, which draws no colour. */
67
+ export function colourLook(colour, attributes = {}) {
68
+ if (colour === DEFAULT_FG) return style(attributes);
69
+ return typeof colour === "string" && COLORS.includes(colour) ? style({ fg: colour, ...attributes }) : null;
70
+ }
71
+ /** A state mark's look for a row of colour `colour` (a terminal colour name, DEFAULT_FG, or null for none). */
61
72
  export function markLook(mark, colour) {
62
- if (colour && Object.hasOwn(COLOURED, mark)) return style({ fg: colour, dim: COLOURED[mark] });
63
- return LOOK[mark] ?? LOOK.unknown;
73
+ const coloured = Object.hasOwn(COLOURED, mark) ? colourLook(colour, { dim: COLOURED[mark] }) : null;
74
+ return coloured ?? LOOK[mark] ?? LOOK.unknown;
64
75
  }
65
- /** The needs-input tag: reverse video in the waiting colour, so the reverse video alone carries it
66
- * under NO_COLOR. On the selected row, which is in reverse already, it is the other way round:
67
- * not reversed, a gap in the selection's bar. */
68
- const WAITS = style({ fg: "yellow", bold: true, reverse: true });
76
+ /** The needs-input look, of a waiting row's mark and of the roll-up's tag: bold, in reverse video in
77
+ * the waiting colour (the mark is then a yellow cell with the `!` cut out, the Desktop's disc in
78
+ * one cell), so the reverse video and the `!` carry it under NO_COLOR. On the selected row, which
79
+ * is in reverse already, it is the other way round: not reversed, a gap in the selection's bar.
80
+ * An instance's colour never draws it. */
81
+ export const WAITS = style({ fg: "yellow", bold: true, reverse: true });
69
82
  const WAITS_SELECTED = style({ fg: "yellow", bold: true });
70
83
 
71
- /** The needs-input tag's words, the Desktop's (packages/desktop/renderer/shell.mjs, needsInputMark;
72
- * a test pins them equal): `Needs input` on a waiting row, `N below` on a row that folds away N
73
- * waiting rows, `99+ below` past 99. A row that is both says `Needs input`, as the Desktop's does:
74
- * its own claim wins, and the detail's `below` line names the rest. */
84
+ /** The words for an instance that needs input: the shared home's for a claim that names no reason
85
+ * of its own (packages/client/waiting-on-you.mjs, waitingLabel, which the detail says; a test pins
86
+ * them equal), the help's for the mark, and the waiting row's (views/frame.mjs). A list row says
87
+ * them by its mark, not in words. */
75
88
  export const NEEDS_INPUT = "Needs input";
89
+ /** The roll-up tag's words, the Desktop's (packages/desktop/renderer/shell.mjs, needsInputMark; a
90
+ * test pins them equal): `N below` on a row that folds away N waiting rows, `99+ below` past 99,
91
+ * whether the row waits itself or not: its mark says its own claim, the tag the rest. */
76
92
  /** A count of waiting rows as the tag says it, or the help's letter for one (`N`) as it is. */
77
93
  const count = (n) => (typeof n === "number" && n > 99 ? "99+" : String(n));
78
94
  export const belowText = (n) => `${count(n)} below`;
@@ -93,16 +109,15 @@ export function measured(value) {
93
109
  return { text, width: textWidth(textOf(text)) };
94
110
  }
95
111
 
96
- /** A row's needs-input tag, in words and in its short form (`!`, or the count alone), or null when
97
- * the row neither waits nor folds a waiting row away. Drawn with a cell of padding either side. */
98
- function tagOf(row, marks) {
99
- if (row.waiting) return { full: NEEDS_INPUT, short: marks.waiting };
112
+ /** A row's roll-up tag, in words and in its short form (the count alone), or null when the row
113
+ * folds no waiting row away. Drawn with a cell of padding either side. */
114
+ function tagOf(row) {
100
115
  return row.below > 0 ? { full: belowText(row.below), short: count(row.below) } : null;
101
116
  }
102
117
 
103
- /** One instance's row in a pane `cols` wide: the state mark, the name cut to what is left, on a
104
- * folded row `+n` after the name, the row's word (when it has one) in the word column, and the
105
- * needs-input tag at the edge. A row with no word gives its name the word column's cells too. The
118
+ /** One instance's row in a pane `cols` wide: the state mark (the needs-input mark on a waiting
119
+ * row), the name cut to what is left, on a folded row `+n` after the name, the row's word (when it
120
+ * has one) in the word column, and the roll-up tag at the edge. A row with no word gives its name the word column's cells too. The
106
121
  * name wins over the word: it keeps NAME_LEAST cells (all of it when it is shorter), and when the
107
122
  * word column would leave it fewer, the word is cut to what the name leaves, after it, or given
108
123
  * up under WORD_LEAST cells; the mark and the detail still say it. The name is cut before `+n`
@@ -121,7 +136,7 @@ function instanceRow(row, cols, wordWidth, marks) {
121
136
  // The tag, and where the name and the word end: before the tag in words and a gap, or the EDGE.
122
137
  const hasWord = wordWidth > 0 && row.word !== null && row.word !== undefined;
123
138
  const whole = name.width + (fold ? fold.length + 1 : 0) + (hasWord ? 2 + wordWidth : 0);
124
- const tag = tagOf(row, marks), wide = tag !== null && cols - tag.full.length - 3 - nameCol >= whole;
139
+ const tag = tagOf(row), wide = tag !== null && cols - tag.full.length - 3 - nameCol >= whole;
125
140
  const waits = tag && (wide ? tag.full : tag.short), end = wide ? cols - tag.full.length - 3 : cols - EDGE, room = end - nameCol;
126
141
  // The word's cells: its column's, or what the name's claim leaves of the row, or none.
127
142
  const left = room - claim - 2;
@@ -131,7 +146,9 @@ function instanceRow(row, cols, wordWidth, marks) {
131
146
  const spans = [];
132
147
  if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED });
133
148
  if (row.selected && row.cursor !== false) spans.push({ col: 0, text: lit(marks.selected), style: SELECTED, width: 1 });
134
- spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(markLook(row.mark, row.color)), width: 1 });
149
+ const waitLook = row.selected ? WAITS_SELECTED : WAITS;
150
+ if (row.waiting) spans.push({ col: MARK + at, text: lit(marks.waiting), style: waitLook, width: 1 });
151
+ else spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(markLook(row.mark, row.color)), width: 1 });
135
152
  if (nameEnd > nameCol) {
136
153
  // The count and the gap before it, when there is room for them and for a cell of the name.
137
154
  const after = fold && nameEnd - nameCol > fold.length + 1 ? fold.length + 1 : 0;
@@ -141,9 +158,9 @@ function instanceRow(row, cols, wordWidth, marks) {
141
158
  }
142
159
  if (wordCells) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordCells });
143
160
  // The tag: its padding a blank span in its style, the words over it.
144
- const tagCol = waits ? cols - waits.length - 2 : 0, tagLook = row.selected ? WAITS_SELECTED : WAITS;
161
+ const tagCol = waits ? cols - waits.length - 2 : 0;
145
162
  if (waits && tagCol > MARK + at) {
146
- spans.push({ col: tagCol, width: waits.length + 2, style: tagLook }, { col: tagCol + 1, text: lit(waits), style: tagLook, width: waits.length });
163
+ spans.push({ col: tagCol, width: waits.length + 2, style: waitLook }, { col: tagCol + 1, text: lit(waits), style: waitLook, width: waits.length });
147
164
  }
148
165
  return spans;
149
166
  }
@@ -8,8 +8,8 @@
8
8
  // the refusal in the detail says "Can't spawn here" in words before its warning style.
9
9
  import { keyLabel } from "../actions.mjs";
10
10
  import { lit, shown, shownLines } from "../term/text.mjs";
11
- import { COLORS, style } from "../term/style.mjs";
12
- import { cutNote, headingRow, markLook, marksOf, measured } from "./instances.mjs";
11
+ import { style } from "../term/style.mjs";
12
+ import { DEFAULT_FG, colourLook, cutNote, headingRow, markLook, marksOf, measured } from "./instances.mjs";
13
13
  import { windowOf } from "./scroll.mjs";
14
14
 
15
15
  /** The TUI's own lines in the Souls view. `retry` and `toInstances` stand after the key that does
@@ -25,8 +25,9 @@ export const SOULS_TEXT = Object.freeze({
25
25
  });
26
26
 
27
27
  /** A soul's colour (soul-colors.mjs's palette name) as one of the terminal's sixteen: the model
28
- * maps a row's colour with it, and a name not here leaves the soul uncoloured. */
29
- export const SOUL_COLOURS = Object.freeze({ sand: "yellow", sage: "green", slate: "blue", mauve: "magenta", clay: "red", olive: "cyan" });
28
+ * maps a row's colour with it, and a name not here leaves the soul uncoloured. `sand` is the
29
+ * terminal's own foreground (DEFAULT_FG), not yellow: yellow says needs input, and only that. */
30
+ export const SOUL_COLOURS = Object.freeze({ sand: DEFAULT_FG, sage: "green", slate: "blue", mauve: "magenta", clay: "red", olive: "cyan" });
30
31
 
31
32
  /** A soul's mark, in UTF-8 and in ASCII, and the sign before a count of its instances. */
32
33
  export const SOUL_MARK = Object.freeze({ utf8: "■", ascii: "#" });
@@ -56,8 +57,9 @@ const PLAIN = style();
56
57
  const BOLD = style({ bold: true });
57
58
  const DIM = style({ dim: true });
58
59
  const SELECTED = style({ reverse: true });
59
- /** The refusal's warning style: it says "Can't spawn here" too, so the colour is not alone. */
60
- const WARN = style({ bold: true, fg: "yellow" });
60
+ /** The refusal's warning style: it says "Can't spawn here" too, so the colour is not alone. Red, not
61
+ * yellow: yellow says needs input, and only that. */
62
+ const WARN = style({ bold: true, fg: "red" });
61
63
 
62
64
  const markOf = (ascii) => (ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8);
63
65
  const countText = (count, ascii) => `${ascii ? COUNT_SIGN.ascii : COUNT_SIGN.utf8}${count}`;
@@ -121,10 +123,9 @@ export function flowed(units, width, gap = 1) {
121
123
  function soulRow(row, cols, ascii) {
122
124
  const look = (own) => (row.selected ? SELECTED : own);
123
125
  const quiet = row.refused ? DIM : PLAIN;
124
- const colour = typeof row.color === "string" && COLORS.includes(row.color) ? row.color : null;
125
126
  const spans = [];
126
127
  if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marksOf(ascii).selected), style: SELECTED, width: 1 });
127
- spans.push({ col: MARK, text: lit(markOf(ascii)), style: look(colour ? style({ fg: colour, dim: row.refused === true }) : quiet), width: 1 });
128
+ spans.push({ col: MARK, text: lit(markOf(ascii)), style: look(colourLook(row.color, { dim: row.refused === true }) ?? quiet), width: 1 });
128
129
  const end = cols - 1;
129
130
  if (end <= NAME) return spans;
130
131
  const after = [...(row.refused ? [{ text: "!", style: quiet }] : []), ...(row.count > 0 ? [{ text: countText(row.count, ascii), style: DIM }] : [])];
@@ -24,6 +24,17 @@ repositories belong to an organisation and which packages it trusts. A
24
24
  work, in its own home and terminal. Each workspace has a setup expert soul,
25
25
  `<workspace>-oats-setup-expert`, which holds the `oats.setup` capability.
26
26
 
27
+ **A machine found-list.** Your prompt may hand you a found-list, a JSON file
28
+ whose `machine.platform` is set (oats-omarchy's installer writes one). Then
29
+ the workspace you make is this machine's own workspace. Its setup soul is
30
+ the machine's steward, `oats.machine/steward`, in place of a setup expert
31
+ soul of its own, and the steward gets a global aweb address. Steps 1, 5, 6
32
+ and 7 say what changes. When the found-list lists a deployment whose
33
+ `steward` is `true`, this machine already has its workspace and steward:
34
+ tell the person so, and stop. Wherever a later step says to ask the
35
+ person, on a machine found-list you tell them what happened, as it is, and
36
+ stop instead: the person answers nothing after step 1.
37
+
27
38
  **How to work.**
28
39
  - **Ask first, then run.** Ask everything in one round (step 1), then run the
29
40
  steps yourself and read back what each did.
@@ -68,6 +79,8 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
68
79
 
69
80
  ## 1. Ask, in one round
70
81
 
82
+ On a machine found-list, ask the machine's round below instead of this list.
83
+
71
84
  - **The use case:** what they want agents to do.
72
85
  - **Their repositories and project:** which repositories agents should work
73
86
  in, where they are cloned on this machine, and which are private.
@@ -103,6 +116,32 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
103
116
  - **OATS Desktop:** installed and started unless they decline. **The TUI**
104
117
  (`oats tui`, a terminal client, preview): opened for them or not.
105
118
 
119
+ **The machine's round.** Read the found-list, then ask only these choices,
120
+ together, each with its default and one line on what it is. Enter, or
121
+ "yes", accepts every default. Nothing is asked after this round, and never
122
+ a key. The use case, repositories and knowledge tools are not asked: the
123
+ steward takes them up with the person later.
124
+ - **The workspace:** a new one, the machine's own. Its name defaults to the
125
+ hostname, lowercased, with every character outside `[a-z0-9-]` turned
126
+ into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
127
+ `<github.login>/<workspace>-oats`, private. Or an existing workspace's
128
+ reference.
129
+ - **The namespace `N`:** the part of every agent's address before the `/`,
130
+ which other people's agents use to reach this machine's agents. Default:
131
+ the hostname, normalised as above, so the namespace is the machine's own. Messaging is
132
+ on, and the root's name `A` is `<workspace>-root`.
133
+ - **The steward's name:** lowercase letters and digits, words joined by
134
+ single `-`. Default: `steward`. It gives `R`, the steward's instance name
135
+ here and the name in its address, `N.aweb.ai/R`. `R` is the chosen name,
136
+ or `<hostname>-<chosen name>` (the hostname normalised as above) when the
137
+ person says `N` is a namespace another machine already uses, so that this
138
+ machine never adopts the other machine's resident.
139
+ - **The deployment directory `D`:** default `<home>/Agents/<workspace>`,
140
+ with the home folder spelled out.
141
+ - **OATS Desktop:** installed and started by default; the TUI not opened.
142
+ - **The harness:** the found-list's `harness`. Ask only when it names none,
143
+ with the one you are as the default.
144
+
106
145
  ## 2. Check, and install what is missing
107
146
 
108
147
  ```bash
@@ -311,8 +350,9 @@ name: acme
311
350
  members:
312
351
  - git:github.com/acme/acme-oats # the host is a member too
313
352
  packages:
314
- oats.framework: v1.14.1 # the installed CLI's catalog versions (below)
315
- oats.aweb: v1.31.0 # messaging, and tasks: agent identities, mail, chat and tasks
353
+ oats.framework: v1.15.1 # the installed CLI's catalog versions (below)
354
+ oats.aweb: v1.32.0 # messaging, and tasks: agent identities, mail, chat and tasks
355
+ oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
316
356
  defaults:
317
357
  capabilities:
318
358
  oats.core: { from: package }
@@ -325,11 +365,15 @@ defaultTeam: acme # every soul starts in this team
325
365
 
326
366
  - **The versions** are the installed CLI's catalog's:
327
367
  `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
328
- (for example `oats-framework/v1.14.1`: write the part after the `/`) and
368
+ (for example `oats-framework/v1.15.1`: write the part after the `/`) and
329
369
  `packages."oats.aweb".ref`, but never below `v1.31.0`: that release
330
370
  carries `oats.aweb-tasks`, and a bare version resolves through the
331
371
  catalog's tag convention even when the installed catalog names an older
332
372
  one.
373
+ - **On a machine found-list only,** keep the `oats.machine` line, at the
374
+ catalog's `packages."oats.machine".ref`, and write none of the
375
+ `souls/<workspace>-oats-setup-expert` files below: the steward is the
376
+ workspace's setup soul. Elsewhere, leave the line out.
333
377
  - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
334
378
  its label (here `acme`) is the workspace name.
335
379
  - **Tasks** use aweb, the same identities as messaging: agents assign,
@@ -454,6 +498,9 @@ oats onboard D --workspace W
454
498
  - **Before 0.61.0,** read `oats souls --dir D --json`: the soul named
455
499
  `<workspace>-oats-setup-expert`, else one whose definition declares
456
500
  `oats.setup`.
501
+ - **On a machine found-list,** `S` is `oats.machine/steward`. An existing
502
+ workspace that doesn't offer it: stop, and say that its owner adds
503
+ `oats.machine` to its `packages:`.
457
504
  - **An existing workspace with no such soul:** stop. Show the person the soul
458
505
  files from step 5 and say that the workspace's owner adds them by pull
459
506
  request to its host repository. Once that is merged, run
@@ -464,6 +511,15 @@ at `D/<repo name>`. A new workspace already has it (step 5). For an existing
464
511
  one, clone the repository that holds `S` with the `git clone` line
465
512
  `oats onboard` printed for it, if that line says it is missing.
466
513
 
514
+ **On a machine found-list, record the steward's harness** on this machine
515
+ first. Its soul names none, and without this every later check (readiness,
516
+ harness trust) and the spawn would use the default, pi:
517
+
518
+ ```bash
519
+ oats soul launch set S --harness <harness> --dir D --plan
520
+ oats soul launch set S --harness <harness> --dir D
521
+ ```
522
+
467
523
  ## 7. Hand over to the setup expert
468
524
 
469
525
  **Messaging on this machine first, when the setup expert takes it.** Read
@@ -497,6 +553,8 @@ can't spawn on this machine until it has messaging too. Set it up now:
497
553
  `D/<repo>` change the team id in `oats-workspace.yaml` to
498
554
  `default:N.aweb.ai`, commit and push it, run `oats sync --dir D`, and run
499
555
  both lines again. Then skip items 3 and 4 and go to the check (item 5).
556
+ On a machine found-list, ask nothing: tell the person that the run
557
+ failed, most likely because `N` is taken, and stop.
500
558
  3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
501
559
  `oats aweb invite --soul <their soul> --label L --json` in their own
502
560
  deployment and passes the token to the person privately, never by
@@ -521,6 +579,48 @@ can't spawn on this machine until it has messaging too. Set it up now:
521
579
  The setup expert does the rest of this machine's messaging
522
580
  (`/oats-host-delivery`).
523
581
 
582
+ **The steward's global address (machine found-list only).** The steward
583
+ gets a global, contacts-only aweb address, `<namespace>/R`, made by the
584
+ team root you just signed up, with no API key and nothing for the person to
585
+ type. `R` is the steward's name from step 1, for the resident and the
586
+ instance alike.
587
+
588
+ Without messaging there is no address to make: skip this. Otherwise it
589
+ needs every one of these, and when one fails, take the fallback below:
590
+ - a new workspace: a root that joined by invite (items 3 and 4) does not own
591
+ the namespace, so aweb would refuse the create;
592
+ - `oats.aweb` 1.33.0 or later: the `oats.aweb` row of the
593
+ `oats inspect` you read above, `result.capabilities[].version`;
594
+ - aw 1.36.48 or later: `aw.version` in the check (item 5).
595
+
596
+ Plan, then create, both from `D` and with no `AWEB_API_KEY`:
597
+
598
+ ```bash
599
+ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --plan --json
600
+ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
601
+ ```
602
+
603
+ - **The plan** changes nothing. Run the create only when the plan's `ok` is
604
+ true and either `result.init.route` is `root` (a new resident) or
605
+ `result.init` is `null` (`R` already holds it; the create adopts it and
606
+ never makes a second one). Anything else, a refusal included (no team
607
+ root, say), is the fallback.
608
+ - **`--team-label L`** puts the resident in the team that is already the
609
+ default, so the run maps nothing new and prints the spawn line as its one
610
+ step (`result.steps`). If it prints another step first, stop and tell the
611
+ person what it says: that step is theirs.
612
+ - **Success** prints `PASS resident <address> …`, and `result.address` is
613
+ the steward's address. Spawn with the grant-seat options below.
614
+ - **A failure** is reported to the person as it is, and you spawn nothing.
615
+ If the create was interrupted (killed, or timed out with no answer), run
616
+ the same line again, unchanged, and nothing else. Never empty
617
+ `D/.aweb-residents/R`: the identity may already exist.
618
+ - **The fallback:** spawn the steward without the grant-seat options. It gets
619
+ a local team identity, as every instance does. Tell the person in one line,
620
+ without asking anything: the steward has a local team identity and no
621
+ global address because of <the reason>, and the GLOBAL residents and grant
622
+ seats section of `/oats-aweb` moves it to one later. Never ask for a key.
623
+
524
624
  **Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
525
625
 
526
626
  ```markdown
@@ -528,6 +628,8 @@ The setup expert does the rest of this machine's messaging
528
628
 
529
629
  - Workspace: <workspace> (W), new | existing; deployment directory: D
530
630
  - Setup expert: S, harness <harness>
631
+ - Machine found-list only: steward R, address N.aweb.ai/R | local team
632
+ identity (<the fallback's reason>)
531
633
 
532
634
  ## The person's answers
533
635
  <step 1's answers, in their words: use case, repositories and where they
@@ -567,6 +669,16 @@ oats spawn S --dir D --task-file D/.oats-handover.md --preview
567
669
  oats spawn S --dir D --task-file D/.oats-handover.md
568
670
  ```
569
671
 
672
+ **On a machine found-list,** name the steward `R` (its harness was recorded
673
+ in step 6). With its global address:
674
+
675
+ ```bash
676
+ oats spawn S --dir D --task-file D/.oats-handover.md --name R --provider oats.aweb identity.mode=global --provider oats.aweb identity.resident=R --preview
677
+ oats spawn S --dir D --task-file D/.oats-handover.md --name R --provider oats.aweb identity.mode=global --provider oats.aweb identity.resident=R
678
+ ```
679
+
680
+ In the fallback, or without messaging, leave out both `--provider` options.
681
+
570
682
  - **The preview** shows what the spawn would create. If it reports a
571
683
  problem, stop and tell the person what it says.
572
684
  - **The spawn** prints the instance's home `H`. Then delete the hand-over
@@ -600,7 +712,8 @@ oats spawn S --dir D --task-file D/.oats-handover.md
600
712
  their own terminal, as "How to work" says, with the command
601
713
  `oats tui --dir "D"`.
602
714
 
603
- **Tell the person where the setup expert is**, and that it continues from
715
+ **Tell the person where the setup expert is** (on a machine found-list, the
716
+ steward, and its address), and that it continues from
604
717
  here: in the Desktop or the TUI you started. Without either, they reach it
605
718
  with `oats session attach --home H` in a terminal.
606
719