@awebai/oats 0.67.1 → 0.68.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.
- package/bin/oats.mjs +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +316 -63
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +663 -243
- package/docs/upgrading.md +66 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +4 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +143 -21
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +57 -35
- package/packages/tui/lib/views/instances.mjs +48 -30
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
|
@@ -1,20 +1,22 @@
|
|
|
1
1
|
// The list of instances: (model, pane) -> rows of spans. Pure: no IO, no clock, no escape byte.
|
|
2
2
|
// Every name, word and reason in it is text the TUI did not write and goes through shown(); the
|
|
3
3
|
// marks and the few words around them are the TUI's own. Nothing is told by colour alone: each
|
|
4
|
-
// state has a mark of its own shape, the selected row carries `>` as well as reverse video
|
|
5
|
-
//
|
|
4
|
+
// state has a mark of its own shape, the selected row carries `>` as well as reverse video (the `>`
|
|
5
|
+
// only while the list has the focus, not the list of workspaces: the model's `cursor`), and a
|
|
6
|
+
// waiting row's state mark is the needs-input mark, `!` in reverse video. A row is quiet: its mark
|
|
6
7
|
// and its name, and a word only where the mark can't say it. Children stand under their parent by
|
|
7
8
|
// indentation alone; a folded row says how many it folds away, `+n`, and how many of those wait,
|
|
8
9
|
// `N below`. In a view of two or more deployments the list also holds a heading per deployment
|
|
9
10
|
// and the sentences the model sets under one: a heading says in words what it is of.
|
|
10
11
|
import { keyLabel } from "../actions.mjs";
|
|
11
12
|
import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
|
|
12
|
-
import { style } from "../term/style.mjs";
|
|
13
|
+
import { COLORS, style } from "../term/style.mjs";
|
|
13
14
|
import { textWidth } from "../term/width.mjs";
|
|
14
15
|
|
|
15
16
|
/** The marks, in UTF-8 and in ASCII (docs/tui.md lists them; the help view draws them from here).
|
|
16
17
|
* The state marks are keyed by the word the shared home gives a row's state, with `shell` and
|
|
17
|
-
* `held` beside them (lib/model.mjs says when).
|
|
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`. */
|
|
18
20
|
export const MARKS = Object.freeze({
|
|
19
21
|
utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", selected: ">", waiting: "!" }),
|
|
20
22
|
ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", selected: ">", waiting: "!" }),
|
|
@@ -24,8 +26,8 @@ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
|
|
|
24
26
|
/** Two cells of indent per level, and no deeper than this many levels: a deeper row sits at the last. */
|
|
25
27
|
const INDENT = 2, LEVELS = 6;
|
|
26
28
|
/** The cells every row keeps at its right edge, so the word column stands in one place whether a
|
|
27
|
-
* row
|
|
28
|
-
* 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. */
|
|
29
31
|
const EDGE = 5;
|
|
30
32
|
/** A row's cells before its name: the selection mark, a gap, the state mark, a gap. */
|
|
31
33
|
const LEAD = 4;
|
|
@@ -51,27 +53,41 @@ const PLAIN = style();
|
|
|
51
53
|
const BOLD = style({ bold: true });
|
|
52
54
|
const DIM = style({ dim: true });
|
|
53
55
|
const SELECTED = style({ reverse: true });
|
|
54
|
-
/** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does.
|
|
55
|
-
|
|
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" }) });
|
|
56
59
|
/** The marks an instance's colour (feature instance-color) draws: running in it, stopped and at its shell in
|
|
57
60
|
* it and dim. The shape still says the state; `unknown` and `held` keep their own look whatever the colour. */
|
|
58
61
|
const COLOURED = Object.freeze({ running: false, stopped: true, shell: true });
|
|
59
|
-
/**
|
|
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). */
|
|
60
72
|
export function markLook(mark, colour) {
|
|
61
|
-
|
|
62
|
-
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;
|
|
63
75
|
}
|
|
64
|
-
/** The needs-input
|
|
65
|
-
*
|
|
66
|
-
*
|
|
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. */
|
|
67
81
|
const WAITS = style({ fg: "yellow", bold: true, reverse: true });
|
|
68
82
|
const WAITS_SELECTED = style({ fg: "yellow", bold: true });
|
|
69
83
|
|
|
70
|
-
/** The needs
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
* 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), and the help's for the mark. A row says them by its mark, not in words. */
|
|
74
87
|
export const NEEDS_INPUT = "Needs input";
|
|
88
|
+
/** The roll-up tag's words, the Desktop's (packages/desktop/renderer/shell.mjs, needsInputMark; a
|
|
89
|
+
* test pins them equal): `N below` on a row that folds away N waiting rows, `99+ below` past 99,
|
|
90
|
+
* whether the row waits itself or not: its mark says its own claim, the tag the rest. */
|
|
75
91
|
/** A count of waiting rows as the tag says it, or the help's letter for one (`N`) as it is. */
|
|
76
92
|
const count = (n) => (typeof n === "number" && n > 99 ? "99+" : String(n));
|
|
77
93
|
export const belowText = (n) => `${count(n)} below`;
|
|
@@ -92,16 +108,15 @@ export function measured(value) {
|
|
|
92
108
|
return { text, width: textWidth(textOf(text)) };
|
|
93
109
|
}
|
|
94
110
|
|
|
95
|
-
/** A row's
|
|
96
|
-
*
|
|
97
|
-
function tagOf(row
|
|
98
|
-
if (row.waiting) return { full: NEEDS_INPUT, short: marks.waiting };
|
|
111
|
+
/** A row's roll-up tag, in words and in its short form (the count alone), or null when the row
|
|
112
|
+
* folds no waiting row away. Drawn with a cell of padding either side. */
|
|
113
|
+
function tagOf(row) {
|
|
99
114
|
return row.below > 0 ? { full: belowText(row.below), short: count(row.below) } : null;
|
|
100
115
|
}
|
|
101
116
|
|
|
102
|
-
/** One instance's row in a pane `cols` wide: the state mark
|
|
103
|
-
* folded row `+n` after the name, the row's word (when it
|
|
104
|
-
*
|
|
117
|
+
/** One instance's row in a pane `cols` wide: the state mark (the needs-input mark on a waiting
|
|
118
|
+
* row), the name cut to what is left, on a folded row `+n` after the name, the row's word (when it
|
|
119
|
+
* 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
|
|
105
120
|
* name wins over the word: it keeps NAME_LEAST cells (all of it when it is shorter), and when the
|
|
106
121
|
* word column would leave it fewer, the word is cut to what the name leaves, after it, or given
|
|
107
122
|
* up under WORD_LEAST cells; the mark and the detail still say it. The name is cut before `+n`
|
|
@@ -120,7 +135,7 @@ function instanceRow(row, cols, wordWidth, marks) {
|
|
|
120
135
|
// The tag, and where the name and the word end: before the tag in words and a gap, or the EDGE.
|
|
121
136
|
const hasWord = wordWidth > 0 && row.word !== null && row.word !== undefined;
|
|
122
137
|
const whole = name.width + (fold ? fold.length + 1 : 0) + (hasWord ? 2 + wordWidth : 0);
|
|
123
|
-
const tag = tagOf(row
|
|
138
|
+
const tag = tagOf(row), wide = tag !== null && cols - tag.full.length - 3 - nameCol >= whole;
|
|
124
139
|
const waits = tag && (wide ? tag.full : tag.short), end = wide ? cols - tag.full.length - 3 : cols - EDGE, room = end - nameCol;
|
|
125
140
|
// The word's cells: its column's, or what the name's claim leaves of the row, or none.
|
|
126
141
|
const left = room - claim - 2;
|
|
@@ -128,8 +143,11 @@ function instanceRow(row, cols, wordWidth, marks) {
|
|
|
128
143
|
const wordCol = left >= wordWidth ? end - wordWidth : nameCol + claim + 2;
|
|
129
144
|
const nameEnd = wordCells ? wordCol - 2 : end;
|
|
130
145
|
const spans = [];
|
|
131
|
-
if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }
|
|
132
|
-
spans.push({ col:
|
|
146
|
+
if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED });
|
|
147
|
+
if (row.selected && row.cursor !== false) spans.push({ col: 0, text: lit(marks.selected), style: SELECTED, width: 1 });
|
|
148
|
+
const waitLook = row.selected ? WAITS_SELECTED : WAITS;
|
|
149
|
+
if (row.waiting) spans.push({ col: MARK + at, text: lit(marks.waiting), style: waitLook, width: 1 });
|
|
150
|
+
else spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(markLook(row.mark, row.color)), width: 1 });
|
|
133
151
|
if (nameEnd > nameCol) {
|
|
134
152
|
// The count and the gap before it, when there is room for them and for a cell of the name.
|
|
135
153
|
const after = fold && nameEnd - nameCol > fold.length + 1 ? fold.length + 1 : 0;
|
|
@@ -139,9 +157,9 @@ function instanceRow(row, cols, wordWidth, marks) {
|
|
|
139
157
|
}
|
|
140
158
|
if (wordCells) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordCells });
|
|
141
159
|
// The tag: its padding a blank span in its style, the words over it.
|
|
142
|
-
const tagCol = waits ? cols - waits.length - 2 : 0
|
|
160
|
+
const tagCol = waits ? cols - waits.length - 2 : 0;
|
|
143
161
|
if (waits && tagCol > MARK + at) {
|
|
144
|
-
spans.push({ col: tagCol, width: waits.length + 2, style:
|
|
162
|
+
spans.push({ col: tagCol, width: waits.length + 2, style: waitLook }, { col: tagCol + 1, text: lit(waits), style: waitLook, width: waits.length });
|
|
145
163
|
}
|
|
146
164
|
return spans;
|
|
147
165
|
}
|
|
@@ -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 {
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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 }] : [])];
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
// The list of workspaces at the top of the sidebar (docs/tui.md, "The list of workspaces"): (the
|
|
2
|
+
// model's `workspaces`, a width) -> rows of spans. Pure: no IO, no clock, no escape byte.
|
|
3
|
+
// A row is one line, a workspace's name, which is the shared home's and goes through shown(); `>`,
|
|
4
|
+
// the dot and `+N` are the TUI's. The open workspace's row is in reverse video; while the list has
|
|
5
|
+
// the focus the cursor's row is, with `>`, and the open workspace's name is underlined. A workspace
|
|
6
|
+
// where an instance needs input has a dot after its name, `●` in yellow, `!` without colour or in
|
|
7
|
+
// ASCII, and `+N` has it when one of the workspaces it counts does.
|
|
8
|
+
import { lit, shown } from "../term/text.mjs";
|
|
9
|
+
import { style } from "../term/style.mjs";
|
|
10
|
+
import { measured } from "./instances.mjs";
|
|
11
|
+
|
|
12
|
+
/** The dot of a workspace where an instance needs input: in yellow, or, with no colour to say it
|
|
13
|
+
* (NO_COLOR) or in ASCII, the needs-input mark of the rows. */
|
|
14
|
+
export const WAITING_DOT = Object.freeze({ utf8: "●", ascii: "!" });
|
|
15
|
+
const CURSOR = 0, NAME = 2, MARGIN = 1;
|
|
16
|
+
const PLAIN = style(), BOLD = style({ bold: true }), BAR = style({ bold: true, reverse: true });
|
|
17
|
+
const OPEN = style({ bold: true, underline: true });
|
|
18
|
+
const YELLOW = style({ fg: "yellow", bold: true });
|
|
19
|
+
|
|
20
|
+
/** One row of the list, `cols` wide: `>` under the cursor, the name, cut with an ellipsis where it
|
|
21
|
+
* does not fit, and one cell after the name as drawn the dot (the screen draws it `after` the
|
|
22
|
+
* name: a name cut, or drawn in `?` without UTF-8, leaves no gap before it). The open workspace's
|
|
23
|
+
* row is in reverse video across the row while the list does not have the focus, the cursor's
|
|
24
|
+
* while it has, and then the open workspace's name is underlined, so it stays told apart until
|
|
25
|
+
* Enter opens the cursor's row. The dot's cell is a gap in the reverse video, on the normal
|
|
26
|
+
* background (a yellow cell with a dark dot in it would read as something else). */
|
|
27
|
+
function row(line, cols, { focused, cursor, ascii, colour }) {
|
|
28
|
+
const under = focused && line.key === cursor, barred = under || (!focused && line.current);
|
|
29
|
+
const spans = barred ? [{ col: 0, width: cols, style: BAR }] : [];
|
|
30
|
+
if (under) spans.push({ col: CURSOR, text: lit(">"), style: BAR, width: 1 });
|
|
31
|
+
// The name keeps the row less the margin, and less the dot and the cell before it when there is one.
|
|
32
|
+
const room = Math.max(0, cols - MARGIN - NAME - (line.waiting ? 2 : 0));
|
|
33
|
+
const width = Math.min(room, measured(line.label).width);
|
|
34
|
+
const look = barred ? BAR : focused && line.current ? OPEN : PLAIN;
|
|
35
|
+
if (width > 0) spans.push({ col: NAME, text: shown(line.label), style: look, width });
|
|
36
|
+
if (line.waiting) spans.push(dot(NAME + width + 1, width > 0, { ascii, colour }));
|
|
37
|
+
return spans;
|
|
38
|
+
}
|
|
39
|
+
/** The dot at `col`, drawn `after` what stands before it when `after`. */
|
|
40
|
+
function dot(col, after, { ascii, colour }) {
|
|
41
|
+
const yellow = colour && !ascii;
|
|
42
|
+
return { col, text: lit(yellow ? WAITING_DOT.utf8 : WAITING_DOT.ascii), style: yellow ? YELLOW : BOLD, width: 1, after };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The list's rows: `w` the model's `workspaces` (`lines` windowed, `more`, `moreWaiting`, `focused`,
|
|
46
|
+
* `cursor`), in `cols`; `+N` last when N workspaces are not shown, the dot one cell after it when
|
|
47
|
+
* an instance of one of them needs input. */
|
|
48
|
+
export function workspaceRows(w, cols, { ascii = false, colour = true } = {}) {
|
|
49
|
+
const rows = w.lines.map((line) => row(line, cols, { focused: w.focused, cursor: w.cursor, ascii, colour }));
|
|
50
|
+
if (w.more > 0) {
|
|
51
|
+
const width = String(w.more).length + 1;
|
|
52
|
+
rows.push([{ col: NAME, text: lit(`+${w.more}`), style: style({ dim: true }), width }, ...(w.moreWaiting ? [dot(NAME + width + 1, false, { ascii, colour })] : [])]);
|
|
53
|
+
}
|
|
54
|
+
return rows;
|
|
55
|
+
}
|
|
@@ -29,9 +29,9 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
|
|
|
29
29
|
steps yourself and read back what each did.
|
|
30
30
|
- **Secrets.** The person types only what you must never hold: passwords,
|
|
31
31
|
tokens and logins. Before the spawn there are two ways for that: a browser
|
|
32
|
-
device flow you start (the GitHub login, step 3), and the exact command
|
|
33
|
-
|
|
34
|
-
|
|
32
|
+
device flow you start (the GitHub login, step 3), and the exact command in
|
|
33
|
+
their own terminal (a `sudo` or Homebrew password, an aweb invite token),
|
|
34
|
+
which you open for them (below).
|
|
35
35
|
- Never ask for a secret in the conversation, and never write one to a file.
|
|
36
36
|
- Never suggest Claude Code's `! <command>` for one: its command and output
|
|
37
37
|
enter your context.
|
|
@@ -42,6 +42,26 @@ work, in its own home and terminal. Each workspace has a setup expert soul,
|
|
|
42
42
|
path), write that value in literally.
|
|
43
43
|
- **Sandboxes.** If your harness sandboxes commands, these steps need network
|
|
44
44
|
access and writes in the home folder: ask the person to approve them.
|
|
45
|
+
Starting the Desktop and opening a terminal also run outside the sandbox.
|
|
46
|
+
- **Their own terminal, opened by you.** When a command must run in the
|
|
47
|
+
person's terminal, write it to a file (`mktemp`; it holds no secret) after
|
|
48
|
+
a first line `export PATH="<node dir>:<oats dir>:<harness dir>:$HOME/.local/bin:$PATH"`,
|
|
49
|
+
with the folders `command -v node`, `command -v oats` and `command -v
|
|
50
|
+
<harness>` print written in (a window may load no shell startup file, so a
|
|
51
|
+
version manager's node would be missing), and a last line
|
|
52
|
+
`printf '\nDone: close this window.\n'; read -r _`. Then open a window
|
|
53
|
+
that runs it, with `F` the file's path written in:
|
|
54
|
+
- **macOS:** `osascript -e 'tell application "Terminal" to do script "sh F"'`.
|
|
55
|
+
The first time, macOS may ask the person to let you control Terminal.
|
|
56
|
+
- **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
|
|
57
|
+
or `x-terminal-emulator -e sh "F"` in place of `xdg-terminal-exec` where
|
|
58
|
+
only that exists. Through `systemd-run` the window gets their desktop
|
|
59
|
+
session's environment, not yours.
|
|
60
|
+
|
|
61
|
+
Tell them what to type there, and ask whether the window opened: a
|
|
62
|
+
command that started is no proof of a window. Check the result with a
|
|
63
|
+
read-only command, never by reading the window, then delete the file.
|
|
64
|
+
Only when no window opens do you give them the command to run themselves.
|
|
45
65
|
- **Touch nothing you were not asked to.** Don't edit an existing
|
|
46
66
|
deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
|
|
47
67
|
don't push to a repository the person did not create in step 5.
|
|
@@ -94,9 +114,11 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
94
114
|
- **The harness** they chose must be installed and logged in (`claude
|
|
95
115
|
--version`, `codex --version` or `pi --version`).
|
|
96
116
|
- **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
|
|
97
|
-
- **Without Homebrew,**
|
|
98
|
-
for
|
|
99
|
-
|
|
117
|
+
- **Without Homebrew,** it installs in their own Terminal, which you open
|
|
118
|
+
for them ("How to work") with the command under “Install Homebrew” on
|
|
119
|
+
<https://brew.sh>, since it asks for their password. Then add its
|
|
120
|
+
`brew shellenv` line to their `~/.zprofile` yourself, as its “Next
|
|
121
|
+
steps” say.
|
|
100
122
|
- Your running process does not see their new PATH. Start each later
|
|
101
123
|
command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
|
|
102
124
|
(`/usr/local/bin/brew` on Intel), or ask them to restart you.
|
|
@@ -115,8 +137,14 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
115
137
|
`sudo` in their own terminal, or set a per-user prefix:
|
|
116
138
|
`npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
|
|
117
139
|
each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
|
|
118
|
-
(your shell does not reread their profile)
|
|
119
|
-
|
|
140
|
+
(your shell does not reread their profile). Add that line to their shell's
|
|
141
|
+
startup file yourself, so their own terminal finds `oats` too, and tell
|
|
142
|
+
them you did: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc`
|
|
143
|
+
(for fish, `fish -c 'fish_add_path ~/.local/bin'` instead).
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
|
|
147
|
+
```
|
|
120
148
|
- **Windows** is not supported.
|
|
121
149
|
|
|
122
150
|
## 3. Log in to GitHub
|
|
@@ -149,9 +177,10 @@ In a separate command, a few seconds later, read the code and the URL:
|
|
|
149
177
|
cat "$HOME/.oats-gh-login.txt"
|
|
150
178
|
```
|
|
151
179
|
|
|
152
|
-
- **Give the person the code and the URL**
|
|
153
|
-
|
|
154
|
-
|
|
180
|
+
- **Give the person the code, and open the URL** in their browser
|
|
181
|
+
(`open https://github.com/login/device` on macOS, `xdg-open …` on Linux;
|
|
182
|
+
give them the URL if that fails). The code is not a secret: only their own
|
|
183
|
+
signed-in browser can use it. They enter the code and approve. A code expires after about 15
|
|
155
184
|
minutes; then start again.
|
|
156
185
|
- **Once they say they approved,** check the login and let Git use it:
|
|
157
186
|
|
|
@@ -197,8 +226,10 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
|
197
226
|
- **Download with `gh`, never through a browser.** `gh` sets no quarantine
|
|
198
227
|
on what it downloads, and that copy starts from Finder. A browser download
|
|
199
228
|
would be quarantined.
|
|
200
|
-
- **Install it.** If the Desktop is running,
|
|
201
|
-
|
|
229
|
+
- **Install it.** If the Desktop is running, tell the person and quit it;
|
|
230
|
+
its agents keep running:
|
|
231
|
+
`osascript -e 'quit app "OATS Desktop"'; for i in $(seq 20); do pgrep -xq "OATS Desktop" || break; sleep 1; done`.
|
|
232
|
+
Then, with the folder `pwd` printed:
|
|
202
233
|
|
|
203
234
|
```bash
|
|
204
235
|
cd "<that folder>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
@@ -210,7 +241,11 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
|
210
241
|
Desktop.app"`): never silently.
|
|
211
242
|
|
|
212
243
|
**Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
|
|
213
|
-
per user, without sudo, and shows in the app launcher
|
|
244
|
+
per user, without sudo, and shows in the app launcher. If the Desktop is
|
|
245
|
+
running, tell the person and quit it first; its agents keep running:
|
|
246
|
+
`pkill -o -u "$(id -u)" -x oats-desktop; for i in $(seq 20); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null || break; sleep 1; done; pgrep -u "$(id -u)" -x oats-desktop >/dev/null && echo STILL_RUNNING`
|
|
247
|
+
(the oldest process is the Desktop's main one). On `STILL_RUNNING`, ask the
|
|
248
|
+
person to quit it.
|
|
214
249
|
|
|
215
250
|
```bash
|
|
216
251
|
cd "$(mktemp -d)" &&
|
|
@@ -233,11 +268,10 @@ Terminal=false
|
|
|
233
268
|
Categories=Development;
|
|
234
269
|
```
|
|
235
270
|
|
|
236
|
-
- **Without FUSE** (
|
|
237
|
-
and later ship without `libfuse2`),
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
and wherever you start it.
|
|
271
|
+
- **Without FUSE** (step 8's start fails with a FUSE message; Ubuntu 22.04
|
|
272
|
+
and later ship without `libfuse2`), add ` --appimage-extract-and-run` after
|
|
273
|
+
the AppImage's path in `Exec=` and in step 8's start. That needs no
|
|
274
|
+
`sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
|
|
241
275
|
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
|
|
242
276
|
download, say so and go on.
|
|
243
277
|
|
|
@@ -277,12 +311,13 @@ name: acme
|
|
|
277
311
|
members:
|
|
278
312
|
- git:github.com/acme/acme-oats # the host is a member too
|
|
279
313
|
packages:
|
|
280
|
-
oats.framework: v1.
|
|
281
|
-
oats.aweb: v1.
|
|
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
|
|
282
316
|
defaults:
|
|
283
317
|
capabilities:
|
|
284
318
|
oats.core: { from: package }
|
|
285
319
|
messaging: { oats.aweb: { from: package } }
|
|
320
|
+
tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
|
|
286
321
|
teams:
|
|
287
322
|
acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
|
|
288
323
|
defaultTeam: acme # every soul starts in this team
|
|
@@ -290,12 +325,19 @@ defaultTeam: acme # every soul starts in this team
|
|
|
290
325
|
|
|
291
326
|
- **The versions** are the installed CLI's catalog's:
|
|
292
327
|
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
|
|
293
|
-
(for example `oats-framework/v1.
|
|
294
|
-
`packages."oats.aweb".ref
|
|
328
|
+
(for example `oats-framework/v1.14.1`: write the part after the `/`) and
|
|
329
|
+
`packages."oats.aweb".ref`, but never below `v1.31.0`: that release
|
|
330
|
+
carries `oats.aweb-tasks`, and a bare version resolves through the
|
|
331
|
+
catalog's tag convention even when the installed catalog names an older
|
|
332
|
+
one.
|
|
295
333
|
- **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
|
|
296
334
|
its label (here `acme`) is the workspace name.
|
|
335
|
+
- **Tasks** use aweb, the same identities as messaging: agents assign,
|
|
336
|
+
claim and hand off work as aweb tasks the person sees on the aweb
|
|
337
|
+
dashboard. A workspace that uses Jira or Linear writes that provider in
|
|
338
|
+
`tasks:` instead (the setup expert sets it up).
|
|
297
339
|
- **Without messaging,** leave out the `oats.aweb` line, the `messaging`
|
|
298
|
-
line, `teams` and `defaultTeam`.
|
|
340
|
+
line, the `tasks` line, `teams` and `defaultTeam`.
|
|
299
341
|
- **Add nothing else:** knowledge and the person's own repositories come
|
|
300
342
|
with the setup expert.
|
|
301
343
|
|
|
@@ -463,9 +505,9 @@ can't spawn on this machine until it has messaging too. Set it up now:
|
|
|
463
505
|
`<workspace>-<their machine>`. This works for a hosted team only: if the
|
|
464
506
|
invite is refused, or the join says the team is not hosted, stop, and
|
|
465
507
|
the workspace's owner decides.
|
|
466
|
-
4. **Existing workspace: the person joins in their own terminal,**
|
|
467
|
-
|
|
468
|
-
in:
|
|
508
|
+
4. **Existing workspace: the person joins in their own terminal,** which you
|
|
509
|
+
open for them ("How to work"), typing the token at the hidden prompt. Its
|
|
510
|
+
command, with `D`, `S`, `L`, `A` and `U` filled in:
|
|
469
511
|
|
|
470
512
|
```text
|
|
471
513
|
cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
|
|
@@ -512,9 +554,9 @@ oats harness trust --dir D --harness claude
|
|
|
512
554
|
```
|
|
513
555
|
|
|
514
556
|
- **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
|
|
515
|
-
the writer refuses), don't edit the file or its attributes.
|
|
516
|
-
|
|
517
|
-
harness's folder-trust question and
|
|
557
|
+
the writer refuses), don't edit the file or its attributes. Open their
|
|
558
|
+
own terminal ("How to work") with `cd "D" && claude` (or `codex`); they
|
|
559
|
+
accept the harness's folder-trust question and exit.
|
|
518
560
|
- **Then check** that the `harness-trust` item of
|
|
519
561
|
`oats readiness --soul S --dir D --json` passes.
|
|
520
562
|
|
|
@@ -537,23 +579,30 @@ oats spawn S --dir D --task-file D/.oats-handover.md
|
|
|
537
579
|
**The Desktop**, if installed, starts on the new deployment:
|
|
538
580
|
- **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
|
|
539
581
|
already running, the new launch hands `--dir` to it and exits.
|
|
540
|
-
- **Linux:**
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
582
|
+
- **Linux:** start it yourself through their session manager, so it gets
|
|
583
|
+
their desktop session's environment, not yours (yours may carry your
|
|
584
|
+
harness's variables and sandbox, and the Desktop passes its environment to
|
|
585
|
+
every agent it starts):
|
|
586
|
+
|
|
587
|
+
```bash
|
|
588
|
+
U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
- **`STARTED`:** it shows `D`.
|
|
592
|
+
- **A FUSE message:** see step 4, then start it again.
|
|
593
|
+
- **Anything else,** or no `systemd-run`: tell the person what it printed.
|
|
594
|
+
They open **OATS Desktop** from their app launcher, and it lists `D` in
|
|
595
|
+
its switcher (from OATS 0.65.0).
|
|
544
596
|
- **Never start it with an emptied environment** (`env -i`): it then loses
|
|
545
597
|
HOME, and Git loses the person's login.
|
|
546
598
|
|
|
547
|
-
**The TUI**, if they wanted it, runs in a terminal of its own:
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
- **Linux:** give them `oats tui --dir D` for their terminal.
|
|
599
|
+
**The TUI**, if they wanted it, runs in a terminal of its own: open it in
|
|
600
|
+
their own terminal, as "How to work" says, with the command
|
|
601
|
+
`oats tui --dir "D"`.
|
|
551
602
|
|
|
552
|
-
**Tell the person
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
- `oats tui --dir D`;
|
|
556
|
-
- `oats session attach --home H` in a terminal.
|
|
603
|
+
**Tell the person where the setup expert is**, and that it continues from
|
|
604
|
+
here: in the Desktop or the TUI you started. Without either, they reach it
|
|
605
|
+
with `oats session attach --home H` in a terminal.
|
|
557
606
|
|
|
558
607
|
It will ask them only what the hand-over leaves open, and it opens a pane in
|
|
559
608
|
its own window when they need to type a secret. You are done.
|