@awebai/oats 0.57.0 → 0.58.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +24 -11
- package/docs/configuration.md +19 -28
- package/docs/desktop-cli-api.md +38 -15
- package/docs/desktop.md +14 -0
- package/docs/execution-targets.md +10 -1
- package/docs/implementation.md +7 -1
- package/docs/integrations.md +3 -1
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/release-notes/v0.58.0.md +107 -0
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +9 -0
- package/docs/tui.md +224 -87
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +11 -4
- package/lib/session-viewer.mjs +29 -4
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +19 -8
- package/packages/client/spawn-apply.mjs +216 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-cli.mjs +2 -1
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +164 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/record/lib/directory-identity.mjs +14 -0
- package/packages/record/lib/native-history.mjs +6 -5
- package/packages/tui/README.md +32 -11
- package/packages/tui/lib/actions.mjs +10 -1
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +165 -57
- package/packages/tui/lib/model.mjs +28 -24
- package/packages/tui/lib/panel.mjs +1019 -0
- package/packages/tui/lib/read.mjs +5 -14
- package/packages/tui/lib/store.mjs +77 -30
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/frame.mjs +126 -40
- package/packages/tui/lib/views/help.mjs +12 -10
- package/skills/oats-getting-started/SKILL.md +3 -2
- package/packages/tui/lib/open.mjs +0 -45
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/** The spawn transaction, the client's half (#855, 6b-2): prepare, apply only the decision the operator confirmed,
|
|
2
|
+
* follow a `pending` apply, check an unknown outcome and recover a reference after a reload, on the /api/spawn
|
|
3
|
+
* contract (spawn-apply-contract.mjs). Each answer is classified into an outcome; what a client shows for it,
|
|
4
|
+
* and where it keeps the job, stay the client's own. No notifications, rows, storage, DOM or timers beyond `sleep`,
|
|
5
|
+
* and no module-level state: each client makes its own transaction.
|
|
6
|
+
*
|
|
7
|
+
* `createSpawnTransaction({ request, now, sleep, pollMs })`:
|
|
8
|
+
* request(body, job) the client's boundary: answers the raw reply to `body` for the job's `address` (the
|
|
9
|
+
* Desktop posts it to /api/spawn?ws=<address>); throws on transport failure
|
|
10
|
+
* now() the clock the deadline is read on (Date.now)
|
|
11
|
+
* sleep(ms) the wait between two `result` reads while the apply is pending
|
|
12
|
+
* pollMs that wait (RECOVER_POLL_MS)
|
|
13
|
+
* answers `{ submit, check, recover }`. Each takes `{ alive, progress }` for its own call and resolves an outcome
|
|
14
|
+
* `{ kind, view, reason, job }`, or null once `alive()` answers false (the client's owner went away: nothing is
|
|
15
|
+
* reported). `progress(event, job)` hears 'submitted' after a prepare whose decision is the confirmed one, before
|
|
16
|
+
* the apply is requested (`spawnRef` and `deadline` set), and 'pending' on each pending answer it goes on following.
|
|
17
|
+
*
|
|
18
|
+
* submit({ address, selector, input, decision }) prepares `input` (the prepare body), applies the prepared
|
|
19
|
+
* reference when its decision is `decision` (spawn-decision.mjs `sameSpawnDecision`), and follows it
|
|
20
|
+
* check(job) reads `result`; an `unknown` result re-applies the same reference, never a new one
|
|
21
|
+
* recover(job) reads `result` for a reference kept across a reload ({ address, selector, spawnRef, deadline? }):
|
|
22
|
+
* one that was submitted, which it records
|
|
23
|
+
*
|
|
24
|
+
* `job` is the transaction's record of the intent, { address, selector, spawnRef, deadline, submitted, prepared },
|
|
25
|
+
* the object `submit` made (or the one a client passes to check and recover); a client stores it as it likes.
|
|
26
|
+
* The deadline is the broker's CLI deadline (`applyWithinMs`, else SPAWN_APPLY_MS) plus FOLLOW_MARGIN_MS from the
|
|
27
|
+
* press, an absolute time; a recovered job without one follows RECOVER_WITHIN_MS from now.
|
|
28
|
+
*
|
|
29
|
+
* `kind`, in the order an answer is classified:
|
|
30
|
+
* created complete, partial or incomplete (`view.status` says which); `reason` the view's
|
|
31
|
+
* pending-expired still pending past the deadline; `reason` null
|
|
32
|
+
* cleanup-owed unknown with a rolled-back code (ROLLED_BACK_CODES); `reason` the view's
|
|
33
|
+
* unknown an unknown answer, a failure after the apply was requested, or E_INTENT_EXPIRED once
|
|
34
|
+
* submitted (the record is gone: proof of nothing); `reason` E_OUTCOME_UNKNOWN's, or the
|
|
35
|
+
* E_INTENT_EXPIRED reason itself; `view` null after a failure
|
|
36
|
+
* rolled-back refused with a rolled-back code; `reason` the view's
|
|
37
|
+
* never-submitted the reference was prepared and never applied; `reason` the view's
|
|
38
|
+
* drifted the prepared decision is not the confirmed one (`view` the prepared one, `reason` null), or
|
|
39
|
+
* E_DECISION_STALE (`reason` it)
|
|
40
|
+
* refused everything else: a prepare that did not prepare, a refusal, or a failure before the apply
|
|
41
|
+
* was requested (`reason` spawnApplyReason(code), `view` null). Nothing was submitted or the
|
|
42
|
+
* kernel says so. */
|
|
43
|
+
import { spawnApplyView, spawnApplyReason, SPAWN_APPLY_MS, ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
|
|
44
|
+
import { sameSpawnDecision } from './spawn-decision.mjs';
|
|
45
|
+
|
|
46
|
+
/** A pending apply reads `result` this often, until the job's deadline. */
|
|
47
|
+
export const RECOVER_POLL_MS = 2000;
|
|
48
|
+
/** A job's deadline is the broker's CLI deadline (applyWithinMs) plus this margin, from the press. */
|
|
49
|
+
export const FOLLOW_MARGIN_MS = 30000;
|
|
50
|
+
/** The CLI deadline of a spawn without `worktree` hooks, plus the margin: what a recovered job without a deadline follows. */
|
|
51
|
+
export const RECOVER_WITHIN_MS = SPAWN_APPLY_MS + FOLLOW_MARGIN_MS;
|
|
52
|
+
|
|
53
|
+
export function createSpawnTransaction({ request, now = () => Date.now(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), pollMs = RECOVER_POLL_MS } = {}) {
|
|
54
|
+
if (typeof request !== 'function') throw new TypeError('createSpawnTransaction: request must be a function');
|
|
55
|
+
const outcome = (kind, view, reason, job) => ({ kind, view, reason, job });
|
|
56
|
+
const calls = ({ alive = () => true, progress = () => {} } = {}) => ({ alive, progress });
|
|
57
|
+
|
|
58
|
+
/** One reply, projected; null once the owner went away. A reply without a view, or whose decision is not
|
|
59
|
+
* the prepared one, is a protocol failure. */
|
|
60
|
+
async function ask(job, body, { alive }) {
|
|
61
|
+
const raw = await request(body, job);
|
|
62
|
+
if (!alive()) return null;
|
|
63
|
+
const view = spawnApplyView(raw, { workspace: job.address, ref: body.spawnRef, selector: job.selector });
|
|
64
|
+
if (!view || view.preview && job.prepared && body.action !== 'prepare' && !sameSpawnDecision(view.preview.decision, job.prepared.preview.decision)) throw Object.assign(Error(), { code: 'E_CLI_PROTOCOL' });
|
|
65
|
+
return view;
|
|
66
|
+
}
|
|
67
|
+
/** An answer after the apply was requested, read as data (a pending one is followed). */
|
|
68
|
+
function classify(job, view, call) {
|
|
69
|
+
if (['complete', 'partial', 'incomplete'].includes(view.status)) return outcome('created', view, view.reason ?? null, job);
|
|
70
|
+
if (view.status === 'pending') return follow(job, view, call);
|
|
71
|
+
if (view.status === 'unknown' && ROLLED_BACK_CODES.includes(view.reason?.code)) return outcome('cleanup-owed', view, view.reason, job);
|
|
72
|
+
if (view.status === 'unknown') return outcome('unknown', view, spawnApplyReason('E_OUTCOME_UNKNOWN'), job);
|
|
73
|
+
if (view.status === 'refused' && ROLLED_BACK_CODES.includes(view.reason?.code)) return outcome('rolled-back', view, view.reason, job);
|
|
74
|
+
if (view.status === 'prepared') return outcome('never-submitted', view, view.reason ?? null, job);
|
|
75
|
+
if (view.reason?.code === 'E_INTENT_EXPIRED' && job.submitted) return outcome('unknown', view, view.reason, job);
|
|
76
|
+
if (view.reason?.code === 'E_DECISION_STALE') return outcome('drifted', view, view.reason, job);
|
|
77
|
+
return outcome('refused', view, view.reason ?? null, job);
|
|
78
|
+
}
|
|
79
|
+
/** Still running in the broker: read `result` every pollMs until it settles or the deadline passes. */
|
|
80
|
+
async function follow(job, view, call) {
|
|
81
|
+
for (;;) {
|
|
82
|
+
if (now() >= job.deadline) return outcome('pending-expired', view, null, job);
|
|
83
|
+
call.progress('pending', job);
|
|
84
|
+
await sleep(pollMs);
|
|
85
|
+
if (!call.alive()) return null;
|
|
86
|
+
view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
|
|
87
|
+
if (!view) return null;
|
|
88
|
+
if (view.status !== 'pending') return classify(job, view, call);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
/** After the apply was requested a failure proves nothing: the outcome is unknown. */
|
|
92
|
+
const failed = (job, call) => call.alive() ? outcome('unknown', null, spawnApplyReason('E_OUTCOME_UNKNOWN'), job) : null;
|
|
93
|
+
const referenced = (job, name) => { if (!job || typeof job.spawnRef !== 'string' || !job.spawnRef) throw new TypeError(`${name}: job.spawnRef is required`); };
|
|
94
|
+
|
|
95
|
+
return {
|
|
96
|
+
async submit(intent, options) {
|
|
97
|
+
const call = calls(options);
|
|
98
|
+
const job = { address: intent.address, selector: intent.selector, spawnRef: null, deadline: null, submitted: false, prepared: null };
|
|
99
|
+
try {
|
|
100
|
+
const prepared = await ask(job, intent.input, call);
|
|
101
|
+
if (!prepared) return null;
|
|
102
|
+
if (prepared.status !== 'prepared') return outcome('refused', prepared, prepared.reason ?? null, job);
|
|
103
|
+
// Apply only the decision the operator saw; the kernel's --expect-decision guards it again at apply.
|
|
104
|
+
if (!sameSpawnDecision(prepared.preview.decision, intent.decision)) return outcome('drifted', prepared, null, job);
|
|
105
|
+
job.prepared = prepared; job.spawnRef = prepared.spawnRef; job.submitted = true;
|
|
106
|
+
job.deadline = now() + (prepared.applyWithinMs ?? SPAWN_APPLY_MS) + FOLLOW_MARGIN_MS;
|
|
107
|
+
call.progress('submitted', job);
|
|
108
|
+
const view = await ask(job, { action: 'apply', spawnRef: job.spawnRef }, call);
|
|
109
|
+
return view ? await classify(job, view, call) : null;
|
|
110
|
+
} catch (error) {
|
|
111
|
+
if (!call.alive()) return null;
|
|
112
|
+
return job.submitted ? failed(job, call) : outcome('refused', null, spawnApplyReason(error?.code), job);
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
async check(job, options) {
|
|
116
|
+
referenced(job, 'check');
|
|
117
|
+
const call = calls(options);
|
|
118
|
+
try {
|
|
119
|
+
let view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
|
|
120
|
+
if (!view) return null;
|
|
121
|
+
if (view.status === 'unknown') { view = await ask(job, { action: 'apply', spawnRef: job.spawnRef }, call); if (!view) return null; }
|
|
122
|
+
return await classify(job, view, call);
|
|
123
|
+
} catch { return failed(job, call); }
|
|
124
|
+
},
|
|
125
|
+
async recover(job, options) {
|
|
126
|
+
referenced(job, 'recover');
|
|
127
|
+
const call = calls(options);
|
|
128
|
+
job.submitted = true;
|
|
129
|
+
if (!Number.isFinite(job.deadline)) job.deadline = now() + RECOVER_WITHIN_MS;
|
|
130
|
+
try {
|
|
131
|
+
const view = await ask(job, { action: 'result', spawnRef: job.spawnRef }, call);
|
|
132
|
+
return view ? await classify(job, view, call) : null;
|
|
133
|
+
} catch { return failed(job, call); }
|
|
134
|
+
},
|
|
135
|
+
};
|
|
136
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** Whether `actual` ({dev, ino, birthtimeNs?}, read now) is the directory `recorded` names.
|
|
2
|
+
* The inode is the identity: on one volume a different directory has a different inode.
|
|
3
|
+
* macOS gives an APFS volume a new `dev` each time it is mounted, so after a reboot `dev`
|
|
4
|
+
* no longer matches; there an equal inode is enough, unless the record holds a birth time
|
|
5
|
+
* (a decimal string of ns), which must then match too. Birth time is not an identity (it can
|
|
6
|
+
* be set, and copies keep it): it closes only the gap a dropped `dev` opens, another volume
|
|
7
|
+
* showing the same inode. A record without one, or with "0" (no birth times on that volume),
|
|
8
|
+
* is judged by the inode alone. Elsewhere `dev` and `ino` must both match. */
|
|
9
|
+
export function sameDirectory(recorded, actual, platform = process.platform) {
|
|
10
|
+
if (!recorded || !actual || recorded.ino !== actual.ino) return false;
|
|
11
|
+
if (recorded.dev === actual.dev) return true;
|
|
12
|
+
if (platform !== "darwin") return false;
|
|
13
|
+
return recorded.birthtimeNs === undefined || recorded.birthtimeNs === "0" || recorded.birthtimeNs === actual.birthtimeNs;
|
|
14
|
+
}
|
|
@@ -6,6 +6,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
|
|
|
6
6
|
import { isDeepStrictEqual } from "node:util";
|
|
7
7
|
import { isUtf8 } from "node:buffer";
|
|
8
8
|
import { nativeLaunchLocations } from "./session-roots.mjs";
|
|
9
|
+
import { sameDirectory } from "./directory-identity.mjs";
|
|
9
10
|
|
|
10
11
|
function canonical(home) {
|
|
11
12
|
try { return realpathSync(home); }
|
|
@@ -215,7 +216,7 @@ function validateReceipt(row, home, id) {
|
|
|
215
216
|
function validateWitness(row, rows) {
|
|
216
217
|
const witness = row.rootWitness, establishing = witness && rows.get(witness.establishedBy.nativeRecordId);
|
|
217
218
|
if (!establishing || establishing.version !== 2 || !["root-established", "started"].includes(establishing.state) || establishing.home !== row.home || establishing.incarnationId !== row.incarnationId || establishing.rootWitness?.establishedBy.nativeRecordId !== establishing.id || !isDeepStrictEqual(establishing.intent, witness.establishedBy.intent) || !isDeepStrictEqual(establishing.rootWitness, witness)) custodyError("original establishing receipt is missing or contradictory");
|
|
218
|
-
if (!
|
|
219
|
+
if (!sameDirectory(witness.identity, directoryIdentity(row.proposedRoot))) custodyError("original Pi session directory was replaced");
|
|
219
220
|
}
|
|
220
221
|
function selection(home, authority, withIntent = false, creating = false) {
|
|
221
222
|
closed(authority, ["incarnationId", "sessionDir", ...(withIntent ? ["intent"] : []), ...(creating ? ["assertAuthority"] : [])]);
|
|
@@ -266,7 +267,7 @@ export function prepareCapturedPiStart(home, authority) {
|
|
|
266
267
|
authority.assertAuthority();
|
|
267
268
|
for (const [path, identity] of directories) if (!isDeepStrictEqual(directoryIdentity(path), identity)) custodyError("original native custody parent changed");
|
|
268
269
|
for (const [id, row] of rows) if (!isDeepStrictEqual(privateJson(join(history, id + ".json")), row)) custodyError("original native receipt changed during preparation");
|
|
269
|
-
if (witness && !
|
|
270
|
+
if (witness && !sameDirectory(witness.identity, directoryIdentity(authority.sessionDir))) custodyError("original root changed during preparation");
|
|
270
271
|
};
|
|
271
272
|
const id = randomUUID(), pending = { version: 2, id, home, runtime: "pi", incarnationId: authority.incarnationId, intent: structuredClone(authority.intent), state: "pending", proposedRoot: authority.sessionDir, rootWitness: structuredClone(witness) };
|
|
272
273
|
const claimed = validateManifest({ version: 2, home, completeHistory: header.completeHistory, capturedPi: { incarnationId: authority.incarnationId, nativeRecordIds: [...(header.capturedPi?.nativeRecordIds ?? []), id] } }, home);
|
|
@@ -282,7 +283,7 @@ export function prepareCapturedPiStart(home, authority) {
|
|
|
282
283
|
const identity = directoryIdentity(authority.sessionDir); syncDirectory(dirname(authority.sessionDir)); claimCheck();
|
|
283
284
|
established = { schemaVersion: 1, profile: "pi-zero-print-1", path: authority.sessionDir, identity, establishedBy: { nativeRecordId: id, intent: structuredClone(authority.intent) } };
|
|
284
285
|
}
|
|
285
|
-
const guard = () => { claimCheck(); if (!
|
|
286
|
+
const guard = () => { claimCheck(); if (!sameDirectory(established.identity, directoryIdentity(authority.sessionDir))) custodyError("captured root changed during establishment"); };
|
|
286
287
|
publishCaptured(home, { ...pending, state: "root-established", rootWitness: established }, pending, guard);
|
|
287
288
|
inventory(home); // no unlisted/unfinished writes may be ignored before return
|
|
288
289
|
return id;
|
|
@@ -310,7 +311,7 @@ function recordCapturedPiStart(home, id, runtime, args, env) {
|
|
|
310
311
|
if (!isDeepStrictEqual(protectedManifest(home), header)) custodyError("expected-ID claim changed before execution");
|
|
311
312
|
const current = privateJson(join(nativeHistoryPath(home), establish.id + ".json"));
|
|
312
313
|
if (establish.id !== id && !isDeepStrictEqual(current, establish)) custodyError("establishing receipt changed");
|
|
313
|
-
if (!
|
|
314
|
+
if (!sameDirectory(row.rootWitness.identity, directoryIdentity(row.proposedRoot))) custodyError("native root changed before execution");
|
|
314
315
|
};
|
|
315
316
|
publishCaptured(home, { ...row, state: "started", startedAt: new Date().toISOString(), locations: [row.proposedRoot] }, row, check);
|
|
316
317
|
}
|
|
@@ -344,7 +345,7 @@ export function assertCapturedPiProof(proof, path) {
|
|
|
344
345
|
for (let current = path; ; current = dirname(current)) {
|
|
345
346
|
const stat = physical(current, current !== path);
|
|
346
347
|
if (current === row.proposedRoot) {
|
|
347
|
-
if (!stat.isDirectory() || !
|
|
348
|
+
if (!stat.isDirectory() || !sameDirectory(row.rootWitness.identity, { dev: stat.dev, ino: stat.ino })) custodyError("native root changed during contained-path validation");
|
|
348
349
|
break;
|
|
349
350
|
}
|
|
350
351
|
}
|
package/packages/tui/README.md
CHANGED
|
@@ -6,7 +6,7 @@ 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 an agent's terminal, and stops, starts, restarts and retires an
|
|
9
|
+
them, opens an agent's terminal in a panel beside the list, and stops, starts, restarts and retires an
|
|
10
10
|
agent after a confirmation. While it is a preview its screens and its
|
|
11
11
|
configuration file may change without notice.
|
|
12
12
|
|
|
@@ -24,16 +24,18 @@ 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/
|
|
27
|
+
| `lib/panel.mjs` | the open terminal: the run's private tmux server (one control client, one window per viewer), the kernel's `oats session attach` in a pane of it, captures when tmux says the pane changed, keys typed into it, and the sweep of what a dead run left; the only module that runs tmux |
|
|
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
29
|
| `lib/store.mjs` | the state and `reduce(state, event)`: pure |
|
|
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 |
|
|
33
33
|
| `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
|
|
34
|
-
| `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
|
|
34
|
+
| `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
|
|
35
|
+
| `lib/term/capture.mjs` | a pane's capture (`capture-pane -e -N`) to rows of cells: characters and an allowlist of SGR, every other sequence and control dropped |
|
|
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 |
|
|
35
37
|
| `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
|
|
36
|
-
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize,
|
|
38
|
+
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
|
|
37
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`) |
|
|
38
40
|
|
|
39
41
|
Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
@@ -42,8 +44,11 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
42
44
|
one path in `lib/client.mjs`. No dynamic `import()`.
|
|
43
45
|
- Nothing in `lib/` or `bin/` of the kernel imports this package, except the
|
|
44
46
|
one dynamic import where `bin/oats.mjs` dispatches the word.
|
|
45
|
-
- Only `term/screen.mjs` and `term/tty.mjs`
|
|
46
|
-
|
|
47
|
+
- Only `term/screen.mjs` and `term/tty.mjs` write an ESC byte in a string,
|
|
48
|
+
and only they write to the terminal. `term/through.mjs` (the back key's
|
|
49
|
+
bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
|
|
50
|
+
pane) hold theirs as numbers. Views are pure: no IO, no clock, no escape
|
|
51
|
+
bytes.
|
|
47
52
|
- No function of this package decodes a kernel answer, groups or orders
|
|
48
53
|
instances, or decides what a failed read means: `lib/model.mjs` and
|
|
49
54
|
`lib/read.mjs` call the shared readers and pass their answers on. A string
|
|
@@ -51,8 +56,21 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
51
56
|
- The store holds no size and no cell: a key event carries the height of the
|
|
52
57
|
panes as the last frame drew them.
|
|
53
58
|
- Every read runs in a session of its own and is ended on every way out.
|
|
54
|
-
The viewer
|
|
55
|
-
|
|
59
|
+
The viewer runs in a pane of the run's private tmux server
|
|
60
|
+
(`lib/panel.mjs`), never on the user's terminal: the guard never lends the
|
|
61
|
+
terminal, and `panel.end()` kills that server on every way out. After a
|
|
62
|
+
SIGKILL the server's keeper window kills it: the keeper reads the run's
|
|
63
|
+
FIFO `alive`, whose write end the TUI holds, until no writer is left (see
|
|
64
|
+
THE KEEPER in `lib/panel.mjs`, which says why the control client's stdin
|
|
65
|
+
EOF is not enough). The next run's sweep removes the directory. The panel
|
|
66
|
+
runs a process to make that FIFO, to ask tmux's version, to start the
|
|
67
|
+
server, to make a window and to end the server, and the sweep one to ask
|
|
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 the pane
|
|
70
|
+
changed. A capture goes out of band: tmux saves it to the run's file
|
|
71
|
+
`capture`, so no pane's text is ever in the control client's stream, and
|
|
72
|
+
a block that says what its command never says ends that client (THE
|
|
73
|
+
CAPTURE in `lib/panel.mjs`). A
|
|
56
74
|
change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
|
|
57
75
|
start, a restart) is never signalled: on the way out it is let go, and its
|
|
58
76
|
output goes to files, so it never meets a closed pipe.
|
|
@@ -68,9 +86,12 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
68
86
|
|
|
69
87
|
Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
|
|
70
88
|
`test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
|
|
71
|
-
socket (`test/tui-terminal.test.mjs
|
|
72
|
-
|
|
73
|
-
`test/tui-acts.test.mjs` for the acts, run on CI only).
|
|
89
|
+
socket (`test/tui-terminal.test.mjs`; `test/tui-panel.test.mjs` for the
|
|
90
|
+
terminal panel, with a second private server for the agents, and
|
|
91
|
+
`test/tui-acts.test.mjs` for the acts, both run on CI only).
|
|
92
|
+
`packages/tui/test/panel.test.mjs` drives `lib/panel.mjs` against a fake
|
|
93
|
+
tmux (`test/fixtures/panel/tmux.mjs`) that records each call and plays the
|
|
94
|
+
control-mode answers. All of them need the root's install
|
|
74
95
|
(`npm ci` at the repository root). The package has no dependency of its own,
|
|
75
96
|
but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
|
|
76
97
|
install's own bin/oats.mjs, and its `version --json` is a record the probe
|
|
@@ -17,9 +17,18 @@ export const ACTIONS = Object.freeze([
|
|
|
17
17
|
{ id: "detail", keys: ["tab"], label: "detail" },
|
|
18
18
|
{ id: "filter", keys: ["/"], label: "filter" },
|
|
19
19
|
{ id: "refresh", keys: ["r"], label: "refresh" },
|
|
20
|
+
// The views by their number. The header names the views and never draws a digit against a name
|
|
21
|
+
// (docs/tui.md, "The header"): the digits are named here, so in the help and the footer.
|
|
20
22
|
{ id: "instances", keys: ["1"], label: "instances" },
|
|
23
|
+
{ id: "souls", keys: ["2"], label: "souls" },
|
|
24
|
+
{ id: "capabilities", keys: ["3"], label: "capabilities" },
|
|
21
25
|
{ id: "workspaces", keys: ["w"], label: "workspaces" },
|
|
22
|
-
{ id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
|
|
26
|
+
{ id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal beside the list, or go to it when it is the open one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
|
|
27
|
+
// 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 back key (tui.json's open.detachKey), so neither of
|
|
29
|
+
// these is ever read there.
|
|
30
|
+
{ id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the open terminal with the whole screen; the back key brings the list back"]] },
|
|
31
|
+
{ id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the open terminal; the agent keeps running"]] },
|
|
23
32
|
// The four acts on an instance: each opens a confirmation, and nothing is done before a move and
|
|
24
33
|
// a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
|
|
25
34
|
{ id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// The user's key file, tui.json: which keys do what, whether the screen is drawn in ASCII, and the
|
|
2
|
-
// key that
|
|
2
|
+
// key that takes the focus from an agent's terminal back to the list.
|
|
3
3
|
// Read once at start and never written. A file that is wrong in any way is refused whole, each
|
|
4
4
|
// problem as one line that says what to change: the TUI resolves no conflict and guesses nothing
|
|
5
5
|
// (there is no "last wins"), because a key that silently does something else is worse than a
|
|
@@ -11,6 +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
15
|
|
|
15
16
|
/** The largest tui.json that is read, in bytes. A larger file is refused by its size, unread. */
|
|
16
17
|
export const CONFIG_LIMIT = 64 * 1024;
|
|
@@ -18,11 +19,9 @@ export const CONFIG_LIMIT = 64 * 1024;
|
|
|
18
19
|
const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
|
|
19
20
|
const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
|
|
20
21
|
const SETTINGS = "the settings are keys, ascii and open";
|
|
21
|
-
/** The key
|
|
22
|
+
/** The back key when tui.json names none: the key that takes the focus from an agent's terminal
|
|
23
|
+
* back to the list (the setting keeps its name, `open.detachKey`, from when it left a viewer). */
|
|
22
24
|
export const DETACH_KEY = "C-\\";
|
|
23
|
-
/** A detach key as tui.json may hold it: 1 to 16 printable ASCII characters. Its grammar is the
|
|
24
|
-
* kernel's, never checked here: a key the kernel refuses is said when an agent is opened. */
|
|
25
|
-
const DETACH_KEY_TEXT = /^[\x20-\x7e]{1,16}$/;
|
|
26
25
|
/** An action id this program had and has no more, with what it is called now. */
|
|
27
26
|
const RENAMED = Object.freeze({ "open-workspace": "open" });
|
|
28
27
|
const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
|
|
@@ -112,19 +111,15 @@ export function effectiveConfig(value, defaults = ACTIONS) {
|
|
|
112
111
|
return { ok: true, actions, ascii: value.ascii === true, detachKey: value.open?.detachKey ?? DETACH_KEY };
|
|
113
112
|
}
|
|
114
113
|
|
|
115
|
-
/** What is wrong with the `open` setting, or null. It holds one member, `detachKey`:
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
* its grammar begins with one), and a value the display filter would change, which the footer and
|
|
120
|
-
* the help would draw as another key. */
|
|
114
|
+
/** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: the back key,
|
|
115
|
+
* one key of the TUI's own grammar (term/through.mjs BACK_KEY), which the TUI takes from the bytes
|
|
116
|
+
* typed into an agent's terminal and never hands to the kernel. A key outside the grammar is
|
|
117
|
+
* refused here, where the file is named, and not when an agent is opened. */
|
|
121
118
|
function openProblem(given) {
|
|
122
119
|
if (!isObject(given)) return 'open must be an object, like {"detachKey": "F12"}';
|
|
123
120
|
for (const [member, key] of Object.entries(given)) {
|
|
124
121
|
if (member !== "detachKey") return `${plain(member) ? `unknown member ${member} of open` : "a member of open whose name cannot be shown is unknown"}; open has detachKey`;
|
|
125
|
-
if (
|
|
126
|
-
if (key.startsWith("-")) return "open.detachKey cannot begin with -";
|
|
127
|
-
if (displayLine(key) !== key) return "open.detachKey is a key the help cannot name; give a key whose characters can be shown";
|
|
122
|
+
if (!isBackKey(key)) return `open.detachKey must be one key: ${BACK_KEY_RULE}`;
|
|
128
123
|
}
|
|
129
124
|
return null;
|
|
130
125
|
}
|