@awebai/oats 0.56.0 → 0.57.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 +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- 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/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- 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 +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- 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/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/** The facts a spawn preview shows, as data (#855, 6b-2): what the Desktop's spawn dialog draws in its preview
|
|
2
|
+
* column (renderer/spawn-dialog.mjs `renderPreview`, `composePreviewModules`), for any client to draw in its own
|
|
3
|
+
* way. Words about the preview only: no DOM, and nothing that names a client's controls.
|
|
4
|
+
*
|
|
5
|
+
* `previewFacts(data, { name, runsOn, cli })` for a preview projection (spawn-preview-contract.mjs `previewData`):
|
|
6
|
+
* identity [{ label, text, title?, muted? }]: the Name (`name`, the client's own name field; without one the
|
|
7
|
+
* kernel numbers the instance, `muted`) and the Home (relative to the deployment, the full path as
|
|
8
|
+
* `title`)
|
|
9
|
+
* facts [{ label, parts: [{ text, mono?, muted?, sub? }], harness? }]: Works in, Harness (with `harness`,
|
|
10
|
+
* the id a client may badge), Team, Relationship, Setup, Runs on (`runsOn`, the client's own words
|
|
11
|
+
* for the chosen deployment), in that order, each only when the preview says it. A part is plain
|
|
12
|
+
* text, `mono` (a branch), `muted`, or `sub` (a value's second line, muted: where it came from,
|
|
13
|
+
* what else)
|
|
14
|
+
* prompts [{ label, text, mono? }] | null: the launch-prompt note, in the kernel contract's words
|
|
15
|
+
* warnings [[line, …], …]: each capability warning's lines, every one (a client bounds what it shows,
|
|
16
|
+
* capability-warnings-contract.mjs `warningsShown`); [] when none
|
|
17
|
+
* modules { core: [{ layer, label, module }], caps: [module] } | null: the core slots in their order (a
|
|
18
|
+
* `module` or null, an empty slot) and the other capabilities by name; each module is
|
|
19
|
+
* { name, source, why } (why '' when the preview does not say). null when the preview carries no
|
|
20
|
+
* `modules` (an older kernel: no placeholder).
|
|
21
|
+
* `cli` is the CLI the preview was read with: it decides which launch facts the preview's `launch` may show. */
|
|
22
|
+
import { displayLine } from './display-text.mjs';
|
|
23
|
+
import { shownLaunch, launchHarnessName, launchFromText } from './launch-view.mjs';
|
|
24
|
+
|
|
25
|
+
/** The preview's work mode in words (board 6, "Works in"); an unknown mode verbatim. */
|
|
26
|
+
const WORK_PHRASES = Object.freeze({ __proto__: null, worktree: 'own worktree', checkout: 'shared checkout', attached: "a parent's worktree", directory: 'own folder · free to work across repos', workspace: 'all member repos' });
|
|
27
|
+
export const worksInText = work => WORK_PHRASES[work] ?? work;
|
|
28
|
+
/** The preview's home, short enough to read: relative to the deployment (the preview's subject.dir)
|
|
29
|
+
* when it lies inside it, else its last three segments behind "…/". The full path is the title. */
|
|
30
|
+
export function homeText(home, dir) {
|
|
31
|
+
if (typeof home !== 'string' || !home) return null;
|
|
32
|
+
const base = typeof dir === 'string' && dir ? dir.replace(/\/+$/, '') : '';
|
|
33
|
+
if (base && home.startsWith(`${base}/`) && home.length > base.length + 1) return { text: home.slice(base.length + 1), title: home };
|
|
34
|
+
const parts = home.split('/').filter(Boolean);
|
|
35
|
+
return { text: parts.length > 3 ? `…/${parts.slice(-3).join('/')}` : home, title: home };
|
|
36
|
+
}
|
|
37
|
+
/** A worktree spawn's "Works in": the new branch (mono in the view) and the ref it starts from, when the preview says. */
|
|
38
|
+
export function worktreeText(data) {
|
|
39
|
+
return { lead: 'worktree · branch ', branch: data.branch, tail: data.base?.ref ? ` from ${data.base.ref}` : '' };
|
|
40
|
+
}
|
|
41
|
+
/** The relation the preview binds, in words with its anchor ("child of api-2"); null when independent. */
|
|
42
|
+
const RELATION_WORDS = Object.freeze({ __proto__: null, child: 'child of', sibling: 'sibling of', parent: 'parent of' });
|
|
43
|
+
export function relationText(data) {
|
|
44
|
+
const kind = data?.relation;
|
|
45
|
+
if (typeof kind !== 'string' || !kind) return null;
|
|
46
|
+
const anchor = data.decision?.effective?.relation?.anchor?.instance;
|
|
47
|
+
if (!RELATION_WORDS[kind]) return kind;
|
|
48
|
+
return typeof anchor === 'string' && anchor ? `${RELATION_WORDS[kind]} ${anchor}` : RELATION_WORDS[kind];
|
|
49
|
+
}
|
|
50
|
+
/** A preview module's source, as the Capabilities tag says it: the package and version, the member
|
|
51
|
+
* repository, or the kind verbatim. Never a reason: that is moduleWhyText's, beside it. */
|
|
52
|
+
export function moduleSourceText(from) {
|
|
53
|
+
if (from?.kind === 'package') return `package ${from.package ?? ''}${from.version ? ` ${from.version}` : ''}`.trimEnd();
|
|
54
|
+
if (from?.kind === 'member') return `${String(from.repoKey ?? '').split('/').pop().replace(/\.git$/, '') || 'member'} · latest`;
|
|
55
|
+
return typeof from?.kind === 'string' ? from.kind : '';
|
|
56
|
+
}
|
|
57
|
+
/** Why a preview module is there, as the reason tag beside its source says it: the projection's
|
|
58
|
+
* `composedFrom` (feature preview-composed-from) — "Soul" or "Workspace default" (a core row already
|
|
59
|
+
* names its slot). '' (no tag) when the preview does not say: an older CLI, or a value the projection
|
|
60
|
+
* dropped. Never guessed from the soul. */
|
|
61
|
+
export function moduleWhyText(m) {
|
|
62
|
+
if (m?.composedFrom === 'soul') return 'Soul';
|
|
63
|
+
if (m?.composedFrom === 'workspace') return 'Workspace default';
|
|
64
|
+
return '';
|
|
65
|
+
}
|
|
66
|
+
const CORE_SLOTS = Object.freeze([['knowledge', 'Knowledge'], ['messaging', 'Messaging'], ['tasks', 'Tasks']]);
|
|
67
|
+
const CORE_LAYERS = CORE_SLOTS.map(([layer]) => layer);
|
|
68
|
+
/** The preview's `modules` rows [{name, layer, from, composedFrom?}] as the core slots and the other
|
|
69
|
+
* capabilities; null when the preview carries none. A module filling a core slot is the slot's only: never
|
|
70
|
+
* among the others. */
|
|
71
|
+
function previewModules(modules) {
|
|
72
|
+
if (!Array.isArray(modules)) return null;
|
|
73
|
+
const rows = modules.filter(m => m && typeof m === 'object' && typeof m.name === 'string' && m.name);
|
|
74
|
+
const described = m => ({ name: m.name, source: moduleSourceText(m.from), why: moduleWhyText(m) });
|
|
75
|
+
const core = CORE_SLOTS.map(([layer, label]) => { const m = rows.find(x => x.layer === layer); return { layer, label, module: m ? described(m) : null }; });
|
|
76
|
+
const caps = rows.filter(m => !CORE_LAYERS.includes(m.layer)).sort((a, b) => a.name.localeCompare(b.name)).map(described);
|
|
77
|
+
return { core, caps };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
export function previewFacts(data, { name = null, runsOn = null, cli = null } = {}) {
|
|
81
|
+
const preview = data && typeof data === 'object' ? data : {};
|
|
82
|
+
const identity = [name ? { label: 'Name', text: name } : { label: 'Name', text: 'numbered by the kernel', muted: true }];
|
|
83
|
+
const home = homeText(preview.home, preview.subject?.dir);
|
|
84
|
+
if (home) identity.push({ label: 'Home', text: home.text, title: home.title });
|
|
85
|
+
const facts = [], fact = (label, parts, extra = {}) => { facts.push({ label, ...extra, parts }); };
|
|
86
|
+
const worktree = preview.work === 'worktree' && preview.branch ? worktreeText(preview) : null;
|
|
87
|
+
if (worktree) fact('Works in', [{ text: worktree.lead }, { text: worktree.branch, mono: true }, ...(worktree.tail ? [{ text: worktree.tail }] : [])]);
|
|
88
|
+
else if (preview.work) fact('Works in', [{ text: worksInText(preview.work) }]);
|
|
89
|
+
if (preview.harness) {
|
|
90
|
+
// Where the harness came from: the Launch's `from` in words (0.30), else the kernel's modelSource verbatim.
|
|
91
|
+
const launch = shownLaunch(preview.launch, cli);
|
|
92
|
+
const from = launch ? launchFromText(launch.from) : preview.modelSource;
|
|
93
|
+
fact('Harness', [{ text: `${launchHarnessName(preview.harness)} · ${preview.model ?? 'default model'}` }, ...(from ? [{ text: from, sub: true }] : [])], { harness: preview.harness });
|
|
94
|
+
}
|
|
95
|
+
// Team model v2: the default the kernel resolved (or none), then the other teams it may join. A 0.29 kernel reports only `team`, the primary label.
|
|
96
|
+
const others = (preview.teams || []).map(t => t.label).filter(label => label !== preview.defaultTeam?.label);
|
|
97
|
+
const also = others.length ? [{ text: `may also join ${others.join(', ')}`, sub: true }] : [];
|
|
98
|
+
if (preview.defaultTeam) fact('Team', [{ text: preview.defaultTeam.label }, { text: ' · default', muted: true }, ...also]);
|
|
99
|
+
else if (preview.defaultTeam === null && !(preview.teams?.length)) fact('Team', [{ text: 'none', muted: true }]);
|
|
100
|
+
else if (preview.defaultTeam === undefined && typeof preview.team === 'string' && preview.team) fact('Team', [{ text: preview.team }]);
|
|
101
|
+
const relation = relationText(preview);
|
|
102
|
+
if (relation) fact('Relationship', [{ text: relation }]);
|
|
103
|
+
// The capabilities whose `worktree` hook sets up ./work, in the order they run ([] or absent: none).
|
|
104
|
+
const hooks = (preview.worktreeHooks ?? []).map(h => `${displayLine(h.capability) ?? ''}${h.required ? ' (required)' : ''}`);
|
|
105
|
+
if (hooks.length) fact('Setup', [{ text: hooks.join(', ') }, { text: 'Runs after the worktree is made. Can take several minutes.', sub: true }]);
|
|
106
|
+
if (runsOn) fact('Runs on', [{ text: runsOn }]);
|
|
107
|
+
let prompts = null;
|
|
108
|
+
if (preview.launchPromptAnswers) {
|
|
109
|
+
// The launch-prompt policy is a note, not a fact: its words stay the kernel contract's, verbatim.
|
|
110
|
+
const policy = preview.launchPromptAnswers;
|
|
111
|
+
prompts = [{ label: 'Launch prompts', text: policy.awebDevelopmentChannel
|
|
112
|
+
? 'The launcher will answer the aweb development-channel confirmation for this home. This policy does not confirm readiness. A harness update can block the launch until its prompt fixtures are refreshed; no fallback key is sent.'
|
|
113
|
+
: 'None. The launcher will not answer prompts for this home. This policy does not confirm readiness.' }];
|
|
114
|
+
if (policy.consentSource) prompts.push({ label: 'Prompt consent source', text: policy.consentSource, mono: true });
|
|
115
|
+
}
|
|
116
|
+
// Capability warnings (0.49.0): the kernel's strings, each as its lines; they block nothing.
|
|
117
|
+
const warnings = (Array.isArray(preview.warnings) ? preview.warnings : []).map(w => String(w).split('\n'));
|
|
118
|
+
return { identity, facts, prompts, warnings, modules: previewModules(preview.modules) };
|
|
119
|
+
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/** Exact local soul/anchor admission against the deployment's spawn catalog,
|
|
2
|
+
* the two-slot read-only preview budget, and the dialog's settled-answer cache.
|
|
3
|
+
*
|
|
4
|
+
* A client makes its own preview (createSpawnPreview) and owns it: nothing here is
|
|
5
|
+
* held at module level, so two clients' budgets, caches and flights never meet.
|
|
6
|
+
* The cache (60 s, keyed by the admission identity) serves the dialog's preview
|
|
7
|
+
* read and prepare's: an answer is still admitted against the current context
|
|
8
|
+
* before it is returned, and a workspace's entries go when the client observes a
|
|
9
|
+
* change that can alter a preview (the Desktop's: server/oats-web.mjs). Prepare taking
|
|
10
|
+
* a held decision is safe because apply binds it with the kernel's --expect-decision:
|
|
11
|
+
* a decision the kernel no longer makes is refused there (E_DECISION_STALE), never applied. */
|
|
12
|
+
import { dirname } from 'node:path';
|
|
13
|
+
import { performance } from 'node:perf_hooks';
|
|
14
|
+
import { cliSpawnPreview } from './spawn-preview-cli.mjs';
|
|
15
|
+
import { admitInstance } from './instance-admission.mjs';
|
|
16
|
+
import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom } from './spawn-preview-contract.mjs';
|
|
17
|
+
/** One preview's flights: its two-slot budget (`slots`), the flights in the air per invoker (`byInvoker`, where
|
|
18
|
+
* exact duplicates coalesce), and the monotonic clock that stamps each flight's start (`started`). The cache is
|
|
19
|
+
* given the same clock: it orders flight starts against invalidations, so a flight that started before its
|
|
20
|
+
* workspace was invalidated never fills the cache, even when a later request coalesced onto it. */
|
|
21
|
+
export function createSpawnPreviewFlights() {
|
|
22
|
+
let stamp = 0;
|
|
23
|
+
return { slots: new Set(), byInvoker: new WeakMap(), started: new WeakMap(), clock: () => ++stamp };
|
|
24
|
+
}
|
|
25
|
+
const missing = (factory, what) => new TypeError(`${factory}: ${what} is required`);
|
|
26
|
+
export const PREVIEW_CACHE_TTL_MS = 60000;
|
|
27
|
+
// A name refusal answers the same name the same way until something changes.
|
|
28
|
+
const CACHED_REFUSALS = ['E_INSTANCE_NAME_TAKEN', 'E_INSTANCE_NAME_INVALID'];
|
|
29
|
+
const cacheable = result => result?.status === 'available' || result?.status === 'unavailable' && CACHED_REFUSALS.includes(result.reason?.code);
|
|
30
|
+
/** `clock` is the flights' clock (createSpawnPreviewFlights): required, never a clock of its own. */
|
|
31
|
+
export function createSpawnPreviewCache({ ttlMs = PREVIEW_CACHE_TTL_MS, limit = 64, now = () => performance.now(), clock } = {}) {
|
|
32
|
+
if (typeof clock !== 'function') throw missing('createSpawnPreviewCache', 'clock (the flights\' clock)');
|
|
33
|
+
const entries = new Map(), invalidatedAt = new Map();
|
|
34
|
+
let clearedAt = 0;
|
|
35
|
+
return {
|
|
36
|
+
get(identity) {
|
|
37
|
+
const entry = entries.get(identity);
|
|
38
|
+
if (!entry) return null;
|
|
39
|
+
if (now() >= entry.expires) { entries.delete(identity); return null; }
|
|
40
|
+
return structuredClone(entry.result);
|
|
41
|
+
},
|
|
42
|
+
set(identity, workspace, result, startedAt) {
|
|
43
|
+
if (!cacheable(result) || typeof startedAt !== 'number' || startedAt <= clearedAt || startedAt <= (invalidatedAt.get(workspace) ?? 0)) return;
|
|
44
|
+
entries.delete(identity); entries.set(identity, { workspace, result: structuredClone(result), expires: now() + ttlMs });
|
|
45
|
+
for (const [key, entry] of entries) if (now() >= entry.expires) entries.delete(key);
|
|
46
|
+
while (entries.size > limit) entries.delete(entries.keys().next().value);
|
|
47
|
+
},
|
|
48
|
+
/** A workspace's answers go (no argument: every workspace's), and no flight in the air may refill them. */
|
|
49
|
+
invalidate(workspace) {
|
|
50
|
+
if (workspace === undefined) { clearedAt = clock(); entries.clear(); return; }
|
|
51
|
+
invalidatedAt.set(workspace, clock());
|
|
52
|
+
for (const [key, entry] of entries) if (entry.workspace === workspace) entries.delete(key);
|
|
53
|
+
},
|
|
54
|
+
size: () => entries.size,
|
|
55
|
+
clock,
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
export function admitSpawnSelection(selector, choices, { workspace: w, cli, agents = [], instances = [] } = {}) {
|
|
59
|
+
const fail = error => ({ error });
|
|
60
|
+
if (!w || typeof w.id !== 'string' || !w.id || !absolute(w.scope)) return fail('E_WORKSPACE_UNKNOWN');
|
|
61
|
+
if (w.remote || w.server) return fail('unsupported-remote-operation');
|
|
62
|
+
if (!previewSupported(cli)) return fail('E_PREVIEW_UNAVAILABLE');
|
|
63
|
+
const rows = agents.filter(a => a.name === selector.soul && a.agentsRoot === selector.agentsRoot);
|
|
64
|
+
if (rows.length !== 1) return fail('E_SOUL_UNKNOWN');
|
|
65
|
+
const soul = rows[0];
|
|
66
|
+
if (soul.remote || soul.server) return fail('unsupported-remote-operation');
|
|
67
|
+
if (soul.work === 'attached') return fail('E_UNSUPPORTED_MODE'); // no renderer workDir authority
|
|
68
|
+
// An exact (unprefixed) name only where the CLI advertises it.
|
|
69
|
+
if (choices.name !== undefined && !cli.features.includes('spawn-name')) return fail('E_UNSUPPORTED_OPTION');
|
|
70
|
+
if (choices.identity !== undefined && !cli.features.includes('spawn-provider-payload')) return fail('E_UNSUPPORTED_OPTION');
|
|
71
|
+
// The one work override offered: a checkout soul asked for a worktree.
|
|
72
|
+
if (choices.work !== undefined && soul.work !== 'checkout') return fail('E_UNSUPPORTED_OPTION');
|
|
73
|
+
const work = choices.work ?? soul.work;
|
|
74
|
+
if ((choices.base !== undefined || choices.branch !== undefined) && work !== 'worktree') return fail('E_UNSUPPORTED_OPTION');
|
|
75
|
+
const supports = (values, value) => Array.isArray(values) && values.includes(value);
|
|
76
|
+
if (choices.harness && !supports(cli.harnesses, choices.harness) || choices.backend && !supports(cli.sessionBackends, choices.backend)
|
|
77
|
+
|| choices.yolo !== undefined && !supports(cli.launchOptions, 'yolo') || choices.launchConfig && !cli.features.includes('launch-config')) return fail('E_UNSUPPORTED_OPTION');
|
|
78
|
+
let anchorIdentity = null;
|
|
79
|
+
if (choices.relation.kind !== 'unrelated') {
|
|
80
|
+
const a = choices.relation.anchor, admitted = admitInstance(a, { workspace: w, cli, instances });
|
|
81
|
+
if (admitted.code) return fail(admitted.code);
|
|
82
|
+
// The CLI takes name+root, not agent+name+root. Do not pretend that a more
|
|
83
|
+
// precise renderer selector can disambiguate what its public argv cannot.
|
|
84
|
+
const expressible = instances.filter(i => i.instance === a.instance && i.agentsRoot === a.agentsRoot && (i.server ?? null) === null);
|
|
85
|
+
if (expressible.length !== 1) return fail('E_RELATIVE_AMBIGUOUS');
|
|
86
|
+
anchorIdentity = [admitted.target, expressible[0].createdAt ?? null];
|
|
87
|
+
}
|
|
88
|
+
const target = { workspace: w.id, context: dirname(soul.agentsRoot), selector };
|
|
89
|
+
const identity = JSON.stringify([w.id, w.scope, target, soul.work, soul.repo, soul.capability, anchorIdentity, choices,
|
|
90
|
+
cli.bin, cli.version, cli.spawnPreviewApi, cli.spawnApplyApi, cli.features, cli.harnesses, cli.sessionBackends, cli.launchOptions]);
|
|
91
|
+
return { target, identity, cli: structuredClone(cli) };
|
|
92
|
+
}
|
|
93
|
+
/** One read of a preview. `flights` (createSpawnPreviewFlights) is required: the reads of one preview share it,
|
|
94
|
+
* and a cache given here must run on its clock. maxAge: the dialog's reads may reuse member heads the kernel
|
|
95
|
+
* observed within that many seconds (feature spawn-preview-max-age, passed only when the admitted CLI
|
|
96
|
+
* advertises it). Prepare's reads never do. exec: as createSpawnPreview's. */
|
|
97
|
+
export function createSpawnPreviewBoundary({ invoke = cliSpawnPreview, cache = null, maxAge = null, flights, exec } = {}) {
|
|
98
|
+
if (!flights?.slots || !flights.byInvoker || !flights.started || typeof flights.clock !== 'function') throw missing('createSpawnPreviewBoundary', 'flights (createSpawnPreviewFlights)');
|
|
99
|
+
if (cache && cache.clock !== flights.clock) throw new TypeError('createSpawnPreviewBoundary: the cache must run on the flights\' clock');
|
|
100
|
+
const { slots, byInvoker, started } = flights, io = exec ? [{ exec }] : [];
|
|
101
|
+
return async function read(request, getContext) {
|
|
102
|
+
try {
|
|
103
|
+
if (!record(request) || request.action !== 'preview' || Object.keys(request).some(k => !['action', 'selector', 'choices'].includes(k))) return previewFailure('E_BAD_ARGS');
|
|
104
|
+
const selector = previewSelector(request.selector), choices = previewChoices(request.choices);
|
|
105
|
+
if (!selector || !choices) return previewFailure('E_BAD_ARGS');
|
|
106
|
+
const selected = admitSpawnSelection(selector, choices, getContext());
|
|
107
|
+
if (selected.error) return previewFailure(selected.error);
|
|
108
|
+
const { target, identity, cli } = selected;
|
|
109
|
+
const held = cache?.get(identity);
|
|
110
|
+
if (held) return held; // admitted above against the current context, like a fresh answer
|
|
111
|
+
let pending = byInvoker.get(invoke); if (!pending) { pending = new Map(); byInvoker.set(invoke, pending); }
|
|
112
|
+
const reuse = maxAge !== null && cli.features.includes('spawn-preview-max-age') ? { maxAge } : {};
|
|
113
|
+
// A reusing read and a live one never coalesce: prepare must not ride on a dialog read's older heads.
|
|
114
|
+
const key = reuse.maxAge ? `${identity}\u0000max-age` : identity;
|
|
115
|
+
if (!pending.has(key)) {
|
|
116
|
+
if (slots.size >= 2) return previewFailure('E_BUSY', target);
|
|
117
|
+
const slot = {}; slots.add(slot);
|
|
118
|
+
const flight = Promise.resolve().then(() => invoke(cli, { target, choices, ...reuse }, ...io)).then(envelope => {
|
|
119
|
+
if (envelope?.schemaVersion !== 1 || envelope.ok !== true) return previewFailure(envelope?.error?.code, target, envelope?.error?.message, envelope?.error?.details?.fix);
|
|
120
|
+
const data = previewData(envelope.result, target, { composedFrom: previewComposedFrom(cli) });
|
|
121
|
+
return data ? { spawnPreviewViewApi: 1, status: 'available', target, data, reason: null } : previewFailure('E_CLI_PROTOCOL', target);
|
|
122
|
+
}).catch(() => previewFailure('E_CLI_FAILED', target)).finally(() => { slots.delete(slot); pending.delete(key); });
|
|
123
|
+
started.set(flight, flights.clock()); pending.set(key, flight);
|
|
124
|
+
}
|
|
125
|
+
const flight = pending.get(key), result = await flight, current = admitSpawnSelection(selector, choices, getContext());
|
|
126
|
+
if (current.identity !== identity) return previewFailure('E_TARGET_CHANGED', target);
|
|
127
|
+
cache?.set(identity, target.workspace, result, started.get(flight));
|
|
128
|
+
return result;
|
|
129
|
+
} catch { return previewFailure('E_CLI_FAILED'); }
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
export const PREVIEW_MAX_AGE_S = 60;
|
|
133
|
+
/** One client's spawn preview: `{ read, prepareRead, cache }`.
|
|
134
|
+
* read the dialog's read, through the cache; its kernel reads may reuse recent member heads (maxAge,
|
|
135
|
+
* where the CLI declares spawn-preview-max-age)
|
|
136
|
+
* prepareRead prepare's read (spawn-apply.mjs createSpawnApplyBoundary's `read`), through the same cache,
|
|
137
|
+
* never with maxAge; a reusing read and a live one never coalesce
|
|
138
|
+
* cache `invalidate(workspace?)` (no argument: every workspace's answers) and `size()`
|
|
139
|
+
* The two reads share one two-slot budget, one set of coalesced flights and one clock, the cache's too.
|
|
140
|
+
* exec optional: the client's own execFile, passed to `invoke` as `invoke(cli, options, { exec })` for both
|
|
141
|
+
* reads (cli-adapter.mjs `runJson` has the rule); without it `invoke` is given no third argument and
|
|
142
|
+
* cliSpawnPreview's own default runs. A read is a read: its options carry no `detached` and a 30 s
|
|
143
|
+
* deadline, and it ends with its caller. */
|
|
144
|
+
export function createSpawnPreview({ invoke = cliSpawnPreview, exec, now = () => performance.now(), ttlMs = PREVIEW_CACHE_TTL_MS, limit = 64, maxAge = PREVIEW_MAX_AGE_S } = {}) {
|
|
145
|
+
const flights = createSpawnPreviewFlights();
|
|
146
|
+
const cache = createSpawnPreviewCache({ ttlMs, limit, now, clock: flights.clock });
|
|
147
|
+
return {
|
|
148
|
+
read: createSpawnPreviewBoundary({ invoke, cache, maxAge, flights, exec }),
|
|
149
|
+
prepareRead: createSpawnPreviewBoundary({ invoke, cache, flights, exec }),
|
|
150
|
+
cache: { invalidate: workspace => cache.invalidate(workspace), size: () => cache.size() },
|
|
151
|
+
};
|
|
152
|
+
}
|
|
@@ -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
|
+
}
|
package/packages/tui/README.md
CHANGED
|
@@ -6,7 +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,
|
|
9
|
+
them, opens an agent's terminal in a panel beside the list, and stops, starts, restarts and retires an
|
|
10
|
+
agent after a confirmation. While it is a preview its screens and its
|
|
10
11
|
configuration file may change without notice.
|
|
11
12
|
|
|
12
13
|
[`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
|
|
@@ -23,17 +24,19 @@ never does.
|
|
|
23
24
|
| `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
|
|
24
25
|
| `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
|
|
25
26
|
| `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
|
|
26
|
-
| `lib/
|
|
27
|
-
| `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
|
|
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
|
+
| `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) |
|
|
28
29
|
| `lib/store.mjs` | the state and `reduce(state, event)`: pure |
|
|
29
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 |
|
|
30
31
|
| `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
|
|
31
32
|
| `lib/term/width.mjs` | the cells a grapheme takes |
|
|
32
33
|
| `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
|
|
33
|
-
| `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 |
|
|
34
37
|
| `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
|
|
35
|
-
| `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize,
|
|
36
|
-
| `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help |
|
|
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`) |
|
|
37
40
|
|
|
38
41
|
Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
39
42
|
|
|
@@ -41,8 +44,11 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
41
44
|
one path in `lib/client.mjs`. No dynamic `import()`.
|
|
42
45
|
- Nothing in `lib/` or `bin/` of the kernel imports this package, except the
|
|
43
46
|
one dynamic import where `bin/oats.mjs` dispatches the word.
|
|
44
|
-
- Only `term/screen.mjs` and `term/tty.mjs`
|
|
45
|
-
|
|
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.
|
|
46
52
|
- No function of this package decodes a kernel answer, groups or orders
|
|
47
53
|
instances, or decides what a failed read means: `lib/model.mjs` and
|
|
48
54
|
`lib/read.mjs` call the shared readers and pass their answers on. A string
|
|
@@ -50,9 +56,29 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
50
56
|
- The store holds no size and no cell: a key event carries the height of the
|
|
51
57
|
panes as the last frame drew them.
|
|
52
58
|
- Every read runs in a session of its own and is ended on every way out.
|
|
53
|
-
The
|
|
54
|
-
the user's terminal
|
|
55
|
-
on every way out
|
|
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
|
|
74
|
+
change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
|
|
75
|
+
start, a restart) is never signalled: on the way out it is let go, and its
|
|
76
|
+
output goes to files, so it never meets a closed pipe.
|
|
77
|
+
- The acts decide nothing the shared home decides: which act a row offers is
|
|
78
|
+
`instanceActs`, a stop or a retire is the shared confirmation over the
|
|
79
|
+
run's one lifecycle boundary, a start or a restart is `startInstance`, and
|
|
80
|
+
no lifecycle sentence is written in this package where the shared home
|
|
81
|
+
has one.
|
|
56
82
|
- The screen takes safe text only. Text the TUI did not write goes through
|
|
57
83
|
`shown()`; `lit()` is for the TUI's own words and refuses anything the
|
|
58
84
|
display filter would change, a run of spaces included, so a row is spans
|
|
@@ -60,8 +86,12 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
|
|
|
60
86
|
|
|
61
87
|
Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
|
|
62
88
|
`test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
|
|
63
|
-
socket (`test/tui-terminal.test.mjs
|
|
64
|
-
|
|
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
|
|
65
95
|
(`npm ci` at the repository root). The package has no dependency of its own,
|
|
66
96
|
but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
|
|
67
97
|
install's own bin/oats.mjs, and its `version --json` is a record the probe
|
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
// (term/keys.mjs keyId); they are the part a user's tui.json replaces (config.mjs), so everything
|
|
4
4
|
// that acts on a key or names one reads the EFFECTIVE table it is handed, never this constant.
|
|
5
5
|
// An action that does one thing in the list of instances and another in the switcher (`open`)
|
|
6
|
-
// says so in `views`: what it does in each, in the order the help lists them.
|
|
6
|
+
// says so in `views`: what it does in each, in the order the help lists them. An action of one
|
|
7
|
+
// view only (the four acts) names that view, so the help says where it acts.
|
|
7
8
|
export const ACTIONS = Object.freeze([
|
|
8
9
|
{ id: "up", keys: ["up", "k"], label: "up" },
|
|
9
10
|
{ id: "down", keys: ["down", "j"], label: "down" },
|
|
@@ -16,9 +17,24 @@ export const ACTIONS = Object.freeze([
|
|
|
16
17
|
{ id: "detail", keys: ["tab"], label: "detail" },
|
|
17
18
|
{ id: "filter", keys: ["/"], label: "filter" },
|
|
18
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.
|
|
19
22
|
{ id: "instances", keys: ["1"], label: "instances" },
|
|
23
|
+
{ id: "souls", keys: ["2"], label: "souls" },
|
|
24
|
+
{ id: "capabilities", keys: ["3"], label: "capabilities" },
|
|
20
25
|
{ id: "workspaces", keys: ["w"], label: "workspaces" },
|
|
21
|
-
{ 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"]] },
|
|
32
|
+
// The four acts on an instance: each opens a confirmation, and nothing is done before a move and
|
|
33
|
+
// a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
|
|
34
|
+
{ id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
|
|
35
|
+
{ id: "retire", keys: ["D"], label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
|
|
36
|
+
{ id: "start", keys: ["S"], label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
|
|
37
|
+
{ id: "restart", keys: ["R"], label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
|
|
22
38
|
{ id: "help", keys: ["?"], label: "help" },
|
|
23
39
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
24
40
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|
|
@@ -26,6 +26,10 @@ export { instanceActs, openAct } from "../../client/instance-acts.mjs";
|
|
|
26
26
|
export { sessionAttachArgv, prepareRemoteTerm, detachKeySupported, hostDetachKeySupported, preflightFailure, DETACH_KEY_FEATURE } from "../../client/session-attach.mjs";
|
|
27
27
|
export { attachExit } from "../../client/attach-exit.mjs";
|
|
28
28
|
export { kernelLines } from "../../client/kernel-lines.mjs";
|
|
29
|
+
export { createLifecycleBoundary } from "../../client/instance-lifecycle.mjs";
|
|
30
|
+
export { createLifecycleConfirmation } from "../../client/lifecycle-confirmation.mjs";
|
|
31
|
+
export { startGate, startInstance } from "../../client/session-start.mjs";
|
|
32
|
+
export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
|
|
29
33
|
export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
|
|
30
34
|
export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
|
|
31
35
|
|
|
@@ -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
|
}
|