@awebai/oats 0.58.0 → 0.59.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.
- package/bin/oats.mjs +1 -1
- package/docs/desktop-cli-api.md +68 -3
- package/docs/desktop.md +30 -3
- package/docs/execution-targets.md +11 -0
- package/docs/implementation.md +2 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +4 -4
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.59.0.md +288 -0
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +21 -0
- package/docs/tui.md +644 -118
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +216 -42
- package/lib/read-ahead-worker.mjs +119 -0
- package/lib/read-ahead.mjs +115 -0
- package/lib/retire-state.mjs +33 -0
- package/lib/servers.mjs +9 -1
- package/lib/session-input.mjs +14 -4
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/instance-acts.mjs +23 -8
- package/packages/client/instance-presentation.mjs +3 -2
- package/packages/client/instance-tree.mjs +84 -39
- package/packages/client/lifecycle-confirmation.mjs +9 -3
- package/packages/client/remote-roster.mjs +4 -1
- package/packages/client/retire-in-flight.mjs +65 -0
- package/packages/client/retire-state.mjs +30 -0
- package/packages/client/spawn-apply.mjs +13 -4
- package/packages/tui/README.md +23 -10
- package/packages/tui/lib/actions.mjs +63 -5
- package/packages/tui/lib/client.mjs +12 -1
- package/packages/tui/lib/config.mjs +7 -2
- package/packages/tui/lib/main.mjs +315 -82
- package/packages/tui/lib/model.mjs +523 -56
- package/packages/tui/lib/panel.mjs +436 -125
- package/packages/tui/lib/read.mjs +52 -26
- package/packages/tui/lib/store.mjs +908 -65
- package/packages/tui/lib/term/keys.mjs +9 -2
- package/packages/tui/lib/term/text.mjs +4 -0
- package/packages/tui/lib/term/through.mjs +12 -1
- package/packages/tui/lib/views/frame.mjs +394 -95
- package/packages/tui/lib/views/help.mjs +54 -13
- package/packages/tui/lib/views/instances.mjs +43 -25
- package/packages/tui/lib/views/palette.mjs +61 -0
- package/packages/tui/lib/views/souls.mjs +268 -0
- package/packages/tui/lib/views/spawn.mjs +299 -0
- package/packages/tui/lib/views/split.mjs +29 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
* { type: 'rows', rows: [{ text, quote? }] } a stop's results or a retire's children
|
|
29
29
|
* { type: 'lines', lines: [{ text, path? }] } what a retire did
|
|
30
30
|
* applyRunningSentence(running, terms) -> the sentence for an apply of this client that is still running
|
|
31
|
-
* createLifecycleConfirmation({ request, target, operation, terms, onSettled, onChange, label, leftover })
|
|
31
|
+
* createLifecycleConfirmation({ request, target, operation, terms, onSettled, onChange, label, leftover, retires })
|
|
32
32
|
* -> { state(), view(), setChoice(id, value), refresh(), apply(), checkAgain(), close() }
|
|
33
33
|
*/
|
|
34
34
|
import { lifecyclePlan, lifecycleOptions, planReference, lifecycleReason, lifecycleDetailCode, publicLifecycleReceipt, decodedStoppedTargets,
|
|
@@ -325,8 +325,11 @@ const SETTLED_OFFERS = Object.freeze({ complete: ['close'], partial: ['refresh',
|
|
|
325
325
|
* `onSettled(result, target)` is called once for every apply answer that reads and is not a return to review;
|
|
326
326
|
* what it does or throws changes nothing here. `label`: the server's label for a routed row; `leftover`: the row
|
|
327
327
|
* is a home a failed spawn left. Each step carries this confirmation's latest-intent token: an answer to an
|
|
328
|
-
* earlier step, or one after close, changes nothing and is not told. Nothing is kept beyond the instance.
|
|
329
|
-
|
|
328
|
+
* earlier step, or one after close, changes nothing and is not told. Nothing is kept beyond the instance.
|
|
329
|
+
* `retires` (#1247): the client's retires in flight (retire-in-flight.mjs). Every apply of a retire is begun
|
|
330
|
+
* there before it is sent and settled with its answer's kind, whether or not the confirmation is still open
|
|
331
|
+
* or that answer is still the latest: the row reads Retiring… from the send until the roster was read after it. */
|
|
332
|
+
export function createLifecycleConfirmation({ request, target, operation, terms, onSettled = () => {}, onChange = () => {}, label = null, leftover = false, choices: initial = null, retires = null } = {}) {
|
|
330
333
|
requireTerms(terms, 'createLifecycleConfirmation');
|
|
331
334
|
if (typeof request !== 'function' || !target?.instance || !['stop', 'retire'].includes(operation)) throw new TypeError('createLifecycleConfirmation: a request, a target and an operation (stop or retire)');
|
|
332
335
|
let choices = lifecycleOptions(operation, initial) ?? (operation === 'stop' ? { recursive: true } : { discardWorktree: false });
|
|
@@ -372,9 +375,12 @@ export function createLifecycleConfirmation({ request, target, operation, terms,
|
|
|
372
375
|
current = { kind: 'applying', title: `${operation === 'retire' ? 'Retiring' : 'Stopping'} ${target.instance}…`,
|
|
373
376
|
message: operation === 'retire' ? `Retiring ${target.instance}. This can take up to a minute while sessions stop.` : `Stopping ${target.instance}. This can take up to a minute.` };
|
|
374
377
|
tell('applying', { view: current });
|
|
378
|
+
let own = null;
|
|
379
|
+
if (operation === 'retire') { try { own = retires?.begin(target) ?? null; } catch { /* the hold is a drawing aid only */ } }
|
|
375
380
|
let result = null, view;
|
|
376
381
|
try { result = await request({ action: 'apply', planRef: reference }); view = outcomeView(result, { target, operation, choices, plan: snapshot, leftover }, terms); }
|
|
377
382
|
catch { view = outcomeView(null, { target, operation, choices, plan: snapshot, leftover }, terms); }
|
|
383
|
+
try { own?.settle(view.kind); } catch { /* as above */ }
|
|
378
384
|
if (mine !== ticket || closed) return;
|
|
379
385
|
if (view.kind === 'stale') {
|
|
380
386
|
plan = view.plan; planRef = view.planRef; shown = view.plan; notice = view.notice; phase = 'review';
|
|
@@ -2,6 +2,7 @@ import { harnessOf } from "./harness-names.mjs";
|
|
|
2
2
|
import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
|
|
3
3
|
import { madeByKernel } from "./kernel-made.mjs";
|
|
4
4
|
import { waitingOnYouData } from "./waiting-on-you.mjs";
|
|
5
|
+
import { retireData } from "./retire-state.mjs";
|
|
5
6
|
import { readIdentity } from "./workspace-views.mjs";
|
|
6
7
|
/** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
|
|
7
8
|
export function remoteWorkspace(group) {
|
|
@@ -43,7 +44,7 @@ export function remotePanel(group, at) {
|
|
|
43
44
|
// A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
|
|
44
45
|
const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
|
|
45
46
|
// A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
|
|
46
|
-
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, ...i }) => {
|
|
47
|
+
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, ...i }) => {
|
|
47
48
|
const unsupported = unsupportedSession(i);
|
|
48
49
|
const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
|
|
49
50
|
const row = {
|
|
@@ -58,6 +59,8 @@ export function remotePanel(group, at) {
|
|
|
58
59
|
tmux: i.tmux || null, git: i.git || null, task: i.task || "", next: i.next || "",
|
|
59
60
|
// Needs input: only a remote kernel with the feature reports it — validated, never synthesized when absent.
|
|
60
61
|
...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
|
|
62
|
+
// #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
|
|
63
|
+
...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
|
|
61
64
|
...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
|
|
62
65
|
};
|
|
63
66
|
return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/** Retires this client started, read as Retiring… before the roster says so (#1247). One per client: the
|
|
2
|
+
* Desktop's window and the TUI's run each keep one, and their lifecycle confirmations tell it
|
|
3
|
+
* (lifecycle-confirmation.mjs `retires`).
|
|
4
|
+
*
|
|
5
|
+
* createRetiresInFlight({ mark, onChange }) -> { begin, landed, ids, holds }
|
|
6
|
+
* mark() the client's read mark now: a value that grows with every roster read the client
|
|
7
|
+
* begins (a counter, a clock); compared with `>` only
|
|
8
|
+
* onChange() the set changed: the client draws its rows again
|
|
9
|
+
* begin(target) an apply of a retire of `target` (a row's identity: server and home) starts. The row
|
|
10
|
+
* is held from now. Answers `{ settle(kind) }`, for the apply's answer: an outcome kind
|
|
11
|
+
* of lifecycle-confirmation.mjs `outcomeView`
|
|
12
|
+
* landed(at, covers?) an owned roster read the client began at mark `at` was read. A held row whose
|
|
13
|
+
* retire has answered, and whose answer came before that read began, is let go, when
|
|
14
|
+
* `covers(target)` says this read covers its row (default: every row)
|
|
15
|
+
* ids() the held rows' instanceIds
|
|
16
|
+
* holds(row) whether `row` is held
|
|
17
|
+
*
|
|
18
|
+
* retiringRows(rows, ids) -> rows, each held one copied with `retireInFlight: true`
|
|
19
|
+
*
|
|
20
|
+
* A row is held from the moment an apply starts until its answer is in and the roster was read after it, and
|
|
21
|
+
* while any other apply of a retire of it is held (a second Retire, offered while one runs, is one).
|
|
22
|
+
* An answer that ran nothing (a refusal, `refused`; a plan that changed under it, `stale`) lets its apply go at
|
|
23
|
+
* once: with no other apply held, the row reads again as the roster says. Any other answer (complete, partial, unknown, pending, unreadable)
|
|
24
|
+
* holds it until a read: that read says what the retire left. instance-tree.mjs `heldHome` reads
|
|
25
|
+
* `retireInFlight` as `retiring`. Nothing is kept beyond the client's run. */
|
|
26
|
+
import { instanceId } from './instance-tree.mjs';
|
|
27
|
+
|
|
28
|
+
const RAN_NOTHING = new Set(['refused', 'stale']);
|
|
29
|
+
|
|
30
|
+
export function createRetiresInFlight({ mark, onChange = () => {} } = {}) {
|
|
31
|
+
if (typeof mark !== 'function') throw new TypeError('createRetiresInFlight: a mark of the client\'s roster reads');
|
|
32
|
+
// instanceId -> { target, applies }: every apply of a retire of that row, each `{ settled, after }`. The row is
|
|
33
|
+
// held while any one holds it, so an answer to a later apply (a refusal: one is still running) never lets go
|
|
34
|
+
// of an earlier one that has not answered or was not read after.
|
|
35
|
+
const held = new Map();
|
|
36
|
+
const changed = () => { try { onChange(); } catch { /* a client's drawing changes nothing here */ } };
|
|
37
|
+
const drop = (id, entry, apply) => { entry.applies.delete(apply); if (!entry.applies.size && held.get(id) === entry) held.delete(id); };
|
|
38
|
+
return {
|
|
39
|
+
begin(target) {
|
|
40
|
+
const id = instanceId(target), entry = held.get(id) ?? { target, applies: new Set() }, apply = { settled: false, after: undefined };
|
|
41
|
+
entry.applies.add(apply); held.set(id, entry); changed();
|
|
42
|
+
return {
|
|
43
|
+
settle(kind) {
|
|
44
|
+
if (apply.settled || !entry.applies.has(apply)) return;
|
|
45
|
+
apply.settled = true;
|
|
46
|
+
if (RAN_NOTHING.has(kind)) { drop(id, entry, apply); changed(); } else apply.after = mark();
|
|
47
|
+
},
|
|
48
|
+
};
|
|
49
|
+
},
|
|
50
|
+
landed(at, covers = () => true) {
|
|
51
|
+
const before = held.size;
|
|
52
|
+
for (const [id, entry] of held) {
|
|
53
|
+
if (!covers(entry.target)) continue;
|
|
54
|
+
for (const apply of [...entry.applies]) if (apply.settled && at > apply.after) drop(id, entry, apply);
|
|
55
|
+
}
|
|
56
|
+
if (held.size !== before) changed();
|
|
57
|
+
},
|
|
58
|
+
ids: () => new Set(held.keys()),
|
|
59
|
+
holds: row => !!row && held.has(instanceId(row)),
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function retiringRows(rows, ids) {
|
|
64
|
+
return ids?.size ? rows.map(row => ids.has(instanceId(row)) ? { ...row, retireInFlight: true } : row) : rows;
|
|
65
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/** A retire of a home, as the kernel's roster row reports it (#1247, feature `status-retire-state`): the
|
|
2
|
+
* row's `retire`, absent while no retire runs, is scheduled or is owed.
|
|
3
|
+
*
|
|
4
|
+
* retire: { state, since, self, code?, message? }
|
|
5
|
+
* state 'running' a retire holds the home's claim with a live holder, or a self-retire's
|
|
6
|
+
* completion is alive (its 8 s wait counts)
|
|
7
|
+
* 'unknown' that holder's liveness cannot be read
|
|
8
|
+
* 'failed' a self-retire's completion recorded an error (`code`, `message`)
|
|
9
|
+
* 'interrupted' a scheduled completion is gone and left no outcome
|
|
10
|
+
* since a string (the kernel's ISO time)
|
|
11
|
+
* self a boolean: a self-retire
|
|
12
|
+
* code an `E_…` code; message: a string: what a failed completion recorded
|
|
13
|
+
*
|
|
14
|
+
* `retireData` is the one reading of it every place that carries row facts uses (deployment-data.mjs,
|
|
15
|
+
* deployment-panel.mjs, remote-roster.mjs, the Desktop's active-observation.mjs): the value when it is the
|
|
16
|
+
* contract's, else null, and a client then holds the row as if it had none. Never guessed, never repaired: one
|
|
17
|
+
* field out of the contract drops the whole value (an optional field is absent or a string, never null).
|
|
18
|
+
* `retirePending` is a fact of its own and stays as the kernel reports it. Text in `message` and `code` is the kernel's: a client
|
|
19
|
+
* shows it only through display-text.mjs `displayLine`, as instance-acts.mjs says for a reason with an `origin`. */
|
|
20
|
+
export const RETIRE_STATES = Object.freeze(['running', 'unknown', 'failed', 'interrupted']);
|
|
21
|
+
const CODE = /^E_[A-Z0-9_]+$/;
|
|
22
|
+
|
|
23
|
+
export function retireData(value) {
|
|
24
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
|
|
25
|
+
if (!RETIRE_STATES.includes(value.state) || typeof value.since !== 'string' || typeof value.self !== 'boolean') return null;
|
|
26
|
+
const { code, message } = value;
|
|
27
|
+
if (code !== undefined && !(typeof code === 'string' && CODE.test(code))) return null;
|
|
28
|
+
if (message !== undefined && typeof message !== 'string') return null;
|
|
29
|
+
return { state: value.state, since: value.since, self: value.self, ...(code !== undefined ? { code } : {}), ...(message !== undefined ? { message } : {}) };
|
|
30
|
+
}
|
|
@@ -27,22 +27,31 @@ const scopeKey = c => JSON.stringify([c?.workspace?.id, c?.workspace?.scope, c?.
|
|
|
27
27
|
* reads through the dialog's cache: a fresh held answer for exactly these choices is the decision (no second
|
|
28
28
|
* CLI read); apply's --expect-decision is the drift guard. No held answer: a fresh read.
|
|
29
29
|
* exec optional: the client's own execFile, passed to `invoke` as `invoke(cli, options, { exec })` for every
|
|
30
|
-
* apply (cli-adapter.mjs `runJson` has the rule); without it `invoke` is
|
|
31
|
-
* cliSpawnApply's own default runs. An apply is a change: its options carry `detached: true`
|
|
30
|
+
* apply (cli-adapter.mjs `runJson` has the rule); without it (and without `applyTimer`) `invoke` is
|
|
31
|
+
* given no third argument and cliSpawnApply's own default runs. An apply is a change: its options carry `detached: true`
|
|
32
32
|
* whatever exec is given, which runs it in a session of its own (as execFileInSession does). On a
|
|
33
33
|
* worktree-event kernel cliSpawnApply ends the child at the deadline through what exec returns
|
|
34
34
|
* (`child.kill`): a given exec must return the child. One that returns nothing leaves that apply
|
|
35
35
|
* unended at its deadline; there is no fallback here. On a kernel without worktree-event the options'
|
|
36
36
|
* `timeout` is the apply's only deadline: exec must honour it as execFileInSession does, killing the
|
|
37
37
|
* child when it passes and reporting `killed` even if the child then exits cleanly.
|
|
38
|
+
* applyTimer optional: the timer the apply's own deadline and its SIGTERM grace are armed on, passed to
|
|
39
|
+
* `invoke` as `io.timer` beside `exec` (cliSpawnApply's `timer(fn, ms)`, which returns its cancel).
|
|
40
|
+
* Without it `invoke` is given none, and cliSpawnApply arms them on setTimeout, as before. It is for
|
|
41
|
+
* a client that lets go of an apply when it ends (the TUI on quit): it gives its own timer and clears
|
|
42
|
+
* it then, so its process neither signals the apply nor is kept alive by its deadline, and the apply
|
|
43
|
+
* runs to its own end, unsupervised (the kernel's own limits bound it). `timer` is the boundary's own
|
|
44
|
+
* wait for an answer (answerWithinMs), which it does not pass on.
|
|
38
45
|
* maxAge seconds the kernel may reuse its deployment observations for the apply (#1246 K1: the member heads'
|
|
39
46
|
* ls-remote wave at the press). Passed to `invoke` only where the apply's CLI lists spawn-apply-max-age;
|
|
40
47
|
* null never. The fence is unchanged: apply's --expect-decision refuses a drifted decision (E_DECISION_STALE). */
|
|
41
|
-
export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec, maxAge = PREVIEW_MAX_AGE_S,
|
|
48
|
+
export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec, applyTimer, maxAge = PREVIEW_MAX_AGE_S,
|
|
42
49
|
now = () => performance.now(), mint = () => randomBytes(32).toString('hex'), answerWithinMs = ANSWER_WITHIN_MS,
|
|
43
50
|
timer = (fn, ms) => { const t = setTimeout(fn, ms); return () => clearTimeout(t); } } = {}) {
|
|
44
51
|
if (typeof read !== 'function') throw new TypeError('createSpawnApplyBoundary: read (the client\'s prepareRead) is required');
|
|
45
|
-
|
|
52
|
+
if (applyTimer !== undefined && typeof applyTimer !== 'function') throw new TypeError('createSpawnApplyBoundary: applyTimer, when given, is a timer(fn, ms) that returns its cancel');
|
|
53
|
+
const given = { ...(exec ? { exec } : {}), ...(applyTimer ? { timer: applyTimer } : {}) };
|
|
54
|
+
const prepared = new Map(), submitted = new Map(), active = new Set(), io = Object.keys(given).length ? [given] : [];
|
|
46
55
|
let preparing = 0, reservedBytes = 0;
|
|
47
56
|
const denied = (code, entry = null, status = 'unavailable', message) => spawnApplyFailure(code, { target: entry?.target, spawnRef: entry?.ref, status, message });
|
|
48
57
|
const sweep = () => { for (const map of [prepared, submitted]) for (const [ref, entry] of map) if (!entry.pending && entry.expires <= now()) map.delete(ref); };
|
package/packages/tui/README.md
CHANGED
|
@@ -6,8 +6,8 @@ inside `@awebai/oats` and is never published on its own.
|
|
|
6
6
|
|
|
7
7
|
**It is a preview.** This version shows a workspace's instances, on this
|
|
8
8
|
machine and on the other machines registered on it, in one list, follows
|
|
9
|
-
them, opens
|
|
10
|
-
agent after a confirmation. While it is a preview its screens and its
|
|
9
|
+
them, opens agents' terminals as tabs in a panel beside the list, split in two groups when you want, stops, starts, restarts and retires an
|
|
10
|
+
agent after a confirmation, and spawns an agent on this machine. While it is a preview its screens and its
|
|
11
11
|
configuration file may change without notice.
|
|
12
12
|
|
|
13
13
|
[`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
|
|
@@ -24,9 +24,9 @@ never does.
|
|
|
24
24
|
| `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
|
|
25
25
|
| `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
|
|
26
26
|
| `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
|
|
27
|
-
| `lib/panel.mjs` | the open
|
|
27
|
+
| `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
|
|
28
28
|
| `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
|
|
29
|
-
| `lib/store.mjs` | the state and `reduce(state, event)`: pure |
|
|
29
|
+
| `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
|
|
30
30
|
| `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
|
|
31
31
|
| `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
|
|
32
32
|
| `lib/term/width.mjs` | the cells a grapheme takes |
|
|
@@ -36,7 +36,7 @@ never does.
|
|
|
36
36
|
| `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
|
|
37
37
|
| `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
|
|
38
38
|
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
|
|
39
|
-
| `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`) |
|
|
39
|
+
| `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
|
|
40
40
|
|
|
41
41
|
Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
42
42
|
|
|
@@ -66,19 +66,32 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
66
66
|
runs a process to make that FIFO, to ask tmux's version, to start the
|
|
67
67
|
server, to make a window and to end the server, and the sweep one to ask
|
|
68
68
|
whether a socket answers; every frame, key, resize and close goes through
|
|
69
|
-
its one control client, and a capture runs only after tmux said
|
|
70
|
-
|
|
69
|
+
its one control client, and a capture runs only after tmux said a
|
|
70
|
+
displayed tab's pane changed (each group's shown tab, two at most); a
|
|
71
|
+
hidden tab's first output captures nothing, marks it and pauses its pane
|
|
72
|
+
for the control client until it is displayed again, when it is
|
|
73
|
+
continued before its capture (THE OUTPUT OF A TAB NOT DRAWN in
|
|
74
|
+
`lib/panel.mjs`). A capture goes out of band: tmux saves it to the run's file
|
|
71
75
|
`capture`, so no pane's text is ever in the control client's stream, and
|
|
72
76
|
a block that says what its command never says ends that client (THE
|
|
73
77
|
CAPTURE in `lib/panel.mjs`). A
|
|
74
78
|
change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
|
|
75
|
-
start, a restart) is never signalled
|
|
76
|
-
output goes to files, so it never meets a closed pipe.
|
|
79
|
+
start, a restart, a spawn's apply) is never signalled on the way out: it
|
|
80
|
+
is let go, and its output goes to files, so it never meets a closed pipe.
|
|
81
|
+
Only a spawn's apply has a deadline, the shared apply's, at which it is
|
|
82
|
+
sent its signal (`timeout`, `killSignal`), and only while the run lasts:
|
|
83
|
+
every timer the shared spawn arms is the run's (`lib/main.mjs`
|
|
84
|
+
`createRunTimers`), cleared as the run ends.
|
|
77
85
|
- The acts decide nothing the shared home decides: which act a row offers is
|
|
78
86
|
`instanceActs`, a stop or a retire is the shared confirmation over the
|
|
79
87
|
run's one lifecycle boundary, a start or a restart is `startInstance`, and
|
|
80
88
|
no lifecycle sentence is written in this package where the shared home
|
|
81
|
-
has one.
|
|
89
|
+
has one. A retire this run sent is held by the shared retires-in-flight
|
|
90
|
+
tracker, one per run (`lib/main.mjs`): its row reads Retiring… from the
|
|
91
|
+
send until a read begun after its answer covers the row (a cycle's
|
|
92
|
+
entry marked `read` for this machine's rows, numbered against
|
|
93
|
+
`lib/read.mjs` `begun()`; a roster outcome that reached the row's
|
|
94
|
+
machine for another's), and at once again after a refusal.
|
|
82
95
|
- The screen takes safe text only. Text the TUI did not write goes through
|
|
83
96
|
`shown()`; `lit()` is for the TUI's own words and refuses anything the
|
|
84
97
|
display filter would change, a run of spaces included, so a row is spans
|
|
@@ -23,18 +23,39 @@ export const ACTIONS = Object.freeze([
|
|
|
23
23
|
{ id: "souls", keys: ["2"], label: "souls" },
|
|
24
24
|
{ id: "capabilities", keys: ["3"], label: "capabilities" },
|
|
25
25
|
{ id: "workspaces", keys: ["w"], label: "workspaces" },
|
|
26
|
-
|
|
26
|
+
// The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
|
|
27
|
+
{ id: "palette", keys: ["ctrl+k"], label: "palette" },
|
|
28
|
+
{ id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"]] },
|
|
29
|
+
// The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
|
|
30
|
+
// Instances view, filtered by that soul.
|
|
31
|
+
{ id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
|
|
27
32
|
// The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
|
|
28
|
-
// has the focus the TUI takes no key but the
|
|
29
|
-
// these is ever read there.
|
|
30
|
-
{ id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the
|
|
31
|
-
{ id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the
|
|
33
|
+
// has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
|
|
34
|
+
// these is ever read there: the leader's table has its own (LEADER).
|
|
35
|
+
{ id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader twice brings the list back"]] },
|
|
36
|
+
{ id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
|
|
37
|
+
{ id: "tab-previous", keys: ["["], label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
|
|
38
|
+
{ id: "tab-next", keys: ["]"], label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
|
|
39
|
+
// The split (docs/tui.md, "Splits"): two groups of tabs at most, side by side or one above the
|
|
40
|
+
// other. `group-next`, `tab-move` and `group-close` have no key of their own here by default
|
|
41
|
+
// (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
|
|
42
|
+
{ id: "split-right", keys: ["|"], label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
|
|
43
|
+
{ id: "split-down", keys: ["-"], label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
|
|
44
|
+
{ id: "group-next", keys: [], label: "next group", views: [["instances", "go to the other group's terminal, or to the focused group's from the list"]] },
|
|
45
|
+
{ id: "tab-move", keys: [], label: "move tab", views: [["instances", "move the shown tab to the other group, and go there"]] },
|
|
46
|
+
{ id: "group-close", keys: [], label: "close group", views: [["instances", "close the focused group while it is empty"]] },
|
|
32
47
|
// The four acts on an instance: each opens a confirmation, and nothing is done before a move and
|
|
33
48
|
// a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
|
|
34
49
|
{ id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
|
|
35
50
|
{ id: "retire", keys: ["D"], label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
|
|
36
51
|
{ id: "start", keys: ["S"], label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
|
|
37
52
|
{ id: "restart", keys: ["R"], label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
|
|
53
|
+
// A spawn (docs/tui.md, "Spawning an agent"): a prompt over the list, the soul picked, the
|
|
54
|
+
// shared preview, and one Enter. Only on this machine's workspace, one spawn at a time.
|
|
55
|
+
{ id: "spawn", keys: ["n"], label: "spawn", views: [["instances", "spawn an agent: pick its soul, then the preview, and Enter spawns it"], ["souls", "spawn an agent of the selected soul: the preview, and Enter spawns it"]] },
|
|
56
|
+
{ id: "spawn-another", keys: ["N"], label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
|
|
57
|
+
// Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
|
|
58
|
+
{ id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
|
|
38
59
|
{ id: "help", keys: ["?"], label: "help" },
|
|
39
60
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
40
61
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|
|
@@ -42,6 +63,43 @@ export const ACTIONS = Object.freeze([
|
|
|
42
63
|
{ id: "redraw", keys: ["ctrl+l"], label: "redraw" },
|
|
43
64
|
].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]), ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
|
|
44
65
|
|
|
66
|
+
/** THE LEADER'S TABLE (docs/tui.md, "The leader"): the keys read after the leader (tui.json's
|
|
67
|
+
* open.detachKey) and what each does, from every focus. Fixed: tui.json's `keys` rebinds the plain
|
|
68
|
+
* keys of ACTIONS only. `does` is an action id of ACTIONS, or one of the leader's own: `previous`
|
|
69
|
+
* and `next` (the instance before or after the shown terminal's, or the selection's: its tab
|
|
70
|
+
* shown, or opened as a new one, with the focus in it) and `list` (the list's focus). The leader pressed again is `list` too: it is
|
|
71
|
+
* the user's key, so it is not in this table. `terminal`: named in the hint only while a terminal
|
|
72
|
+
* is open, and nothing without one (the hint names the tab keys only with two tabs or more). */
|
|
73
|
+
export const LEADER = Object.freeze([
|
|
74
|
+
{ keys: ["k", "space"], does: "palette", label: "palette" },
|
|
75
|
+
{ keys: ["1"], does: "instances", label: "instances" },
|
|
76
|
+
{ keys: ["2"], does: "souls", label: "souls" },
|
|
77
|
+
{ keys: ["3"], does: "capabilities", label: "capabilities" },
|
|
78
|
+
{ keys: ["up"], does: "previous", label: "previous instance" },
|
|
79
|
+
{ keys: ["down"], does: "next", label: "next instance" },
|
|
80
|
+
{ keys: ["z"], does: "zoom", label: "zoom", terminal: true },
|
|
81
|
+
{ keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
|
|
82
|
+
{ keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
|
|
83
|
+
{ keys: ["right"], does: "tab-next", label: "next tab", terminal: true },
|
|
84
|
+
{ keys: ["|"], does: "split-right", label: "split right", terminal: true },
|
|
85
|
+
{ keys: ["-"], does: "split-down", label: "split down", terminal: true },
|
|
86
|
+
{ keys: ["tab"], does: "group-next", label: "next group", terminal: true },
|
|
87
|
+
{ keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
|
|
88
|
+
{ keys: ["x"], does: "group-close", label: "close group", terminal: true },
|
|
89
|
+
{ keys: ["X"], does: "stop", label: "stop" },
|
|
90
|
+
{ keys: ["R"], does: "restart", label: "restart" },
|
|
91
|
+
{ keys: ["S"], does: "start", label: "start" },
|
|
92
|
+
{ keys: ["D"], does: "retire", label: "retire" },
|
|
93
|
+
{ keys: ["n"], does: "spawn", label: "spawn" },
|
|
94
|
+
{ keys: ["N"], does: "spawn-another", label: "spawn another" },
|
|
95
|
+
{ keys: ["/"], does: "filter", label: "filter" },
|
|
96
|
+
{ keys: ["o"], does: "workspaces", label: "workspaces" },
|
|
97
|
+
{ keys: ["?"], does: "help", label: "help" },
|
|
98
|
+
{ keys: ["escape"], does: "list", label: "the list" },
|
|
99
|
+
].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
|
|
100
|
+
/** key id -> what the leader then does (LEADER's `does`). */
|
|
101
|
+
export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
|
|
102
|
+
|
|
45
103
|
/** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
|
|
46
104
|
export function bindings(actions = ACTIONS) {
|
|
47
105
|
const map = new Map();
|
|
@@ -17,21 +17,32 @@ export { panelData, cliReadsRemotes, workspaceChoices, viewModel, deployments }
|
|
|
17
17
|
export { remoteRosterState } from "../../client/remote-roster.mjs";
|
|
18
18
|
export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
|
|
19
19
|
export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
|
|
20
|
-
export { shortPath } from "../../client/deployment-label.mjs";
|
|
20
|
+
export { shortPath, deploymentLabel } from "../../client/deployment-label.mjs";
|
|
21
21
|
export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome } from "../../client/instance-tree.mjs";
|
|
22
22
|
export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
|
|
23
23
|
export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
|
|
24
24
|
export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
|
|
25
25
|
export { instanceActs, openAct } from "../../client/instance-acts.mjs";
|
|
26
|
+
export { rowReason } from "../../client/remote-address.mjs";
|
|
26
27
|
export { sessionAttachArgv, prepareRemoteTerm, detachKeySupported, hostDetachKeySupported, preflightFailure, DETACH_KEY_FEATURE } from "../../client/session-attach.mjs";
|
|
27
28
|
export { attachExit } from "../../client/attach-exit.mjs";
|
|
28
29
|
export { kernelLines } from "../../client/kernel-lines.mjs";
|
|
29
30
|
export { createLifecycleBoundary } from "../../client/instance-lifecycle.mjs";
|
|
30
31
|
export { createLifecycleConfirmation } from "../../client/lifecycle-confirmation.mjs";
|
|
32
|
+
export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flight.mjs";
|
|
31
33
|
export { startGate, startInstance } from "../../client/session-start.mjs";
|
|
32
34
|
export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
|
|
33
35
|
export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
|
|
34
36
|
export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
|
|
37
|
+
export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
|
|
38
|
+
export { soulRows } from "../../client/soul-rows.mjs";
|
|
39
|
+
export { soulFacts, spawnRefusal } from "../../client/soul-facts.mjs";
|
|
40
|
+
export { createSpawnPreview } from "../../client/spawn-preview.mjs";
|
|
41
|
+
export { defaultSpawnChoices } from "../../client/spawn-preview-contract.mjs";
|
|
42
|
+
export { createSpawnApplyBoundary } from "../../client/spawn-apply.mjs";
|
|
43
|
+
export { createSpawnTransaction } from "../../client/spawn-transaction.mjs";
|
|
44
|
+
export { spawnProblem, outcomeWords, SPAWN_NEXT } from "../../client/spawn-messages.mjs";
|
|
45
|
+
export { previewFacts } from "../../client/spawn-preview-facts.mjs";
|
|
35
46
|
|
|
36
47
|
/** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
|
|
37
48
|
* Made once, here: every shared function that takes `terms` is passed this constant, and refuses
|
|
@@ -11,7 +11,7 @@ import { isAbsolute, join } from "node:path";
|
|
|
11
11
|
import { ACTIONS, bindings, keyLabel } from "./actions.mjs";
|
|
12
12
|
import { displayLine } from "./client.mjs";
|
|
13
13
|
import { isKeyId } from "./term/keys.mjs";
|
|
14
|
-
import { BACK_KEY_RULE, isBackKey } from "./term/through.mjs";
|
|
14
|
+
import { BACK_KEY_RULE, backKeyId, isBackKey } from "./term/through.mjs";
|
|
15
15
|
|
|
16
16
|
/** The largest tui.json that is read, in bytes. A larger file is refused by its size, unread. */
|
|
17
17
|
export const CONFIG_LIMIT = 64 * 1024;
|
|
@@ -104,11 +104,16 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
104
104
|
if (id === "quit" && list.length === 0) problems.push("quit has no key; give it one");
|
|
105
105
|
}
|
|
106
106
|
}
|
|
107
|
+
// The leader is read as a key wherever the TUI reads keys (docs/tui.md, "The leader"), so no
|
|
108
|
+
// action may hold the key it reads as: `C-l` would be redraw's Ctrl+L, `C-j` open's Enter.
|
|
109
|
+
const detachKey = value.open?.detachKey ?? DETACH_KEY, leader = backKeyId(detachKey);
|
|
110
|
+
const taken = defaults.find((action) => (named.get(action.id) ?? action.keys).includes(leader));
|
|
111
|
+
if (taken) problems.push(`open.detachKey ${detachKey} is read as ${keyLabel(leader)}, the key of ${say(taken.id)}; give the leader a key no action has, or give ${say(taken.id)} another`);
|
|
107
112
|
if (problems.length > 0) return { ok: false, problems };
|
|
108
113
|
|
|
109
114
|
const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
|
|
110
115
|
try { bindings(actions); } catch { return { ok: false, problems: ["a key is given to two actions; a key does one thing"] }; }
|
|
111
|
-
return { ok: true, actions, ascii: value.ascii === true, detachKey
|
|
116
|
+
return { ok: true, actions, ascii: value.ascii === true, detachKey };
|
|
112
117
|
}
|
|
113
118
|
|
|
114
119
|
/** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: the back key,
|