@awebai/oats 0.66.0 → 0.67.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 +66 -13
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +217 -6
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +6 -5
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +3 -2
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +570 -176
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +1 -1
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +3 -1
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +85 -24
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/tui/README.md +3 -3
- package/packages/tui/lib/actions.mjs +57 -14
- package/packages/tui/lib/client.mjs +8 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +40 -13
- package/packages/tui/lib/model.mjs +167 -63
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +148 -54
- package/packages/tui/lib/term/keys.mjs +19 -5
- package/packages/tui/lib/term/kitty.mjs +36 -11
- package/packages/tui/lib/term/through.mjs +61 -28
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +109 -26
- package/packages/tui/lib/views/instances.mjs +59 -20
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/skills/oats-getting-started/SKILL.md +13 -8
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
/** keys.json, the one preference both clients share about their keys: which chord family they bind
|
|
2
|
+
* on Linux and Windows (packages/client/keymap.mjs CHORD_FAMILIES). It is `config/keys.json` in OATS's
|
|
3
|
+
* own directory of this user, beside the TUI's tui.json, and resolved the same way: `$OATS_HOME_DIR`
|
|
4
|
+
* when that is set and not empty, else `<home>/.oats`. Its shape: `{ "chords": "ctrl+alt" | "ctrl+shift" }`.
|
|
5
|
+
*
|
|
6
|
+
* The file is the clients'; the kernel never reads it. Each client does its own IO and hands the text
|
|
7
|
+
* here: the TUI at its start, the Desktop in its main process, which hands the family to its renderer
|
|
8
|
+
* and is the one that writes the file (keysWithFamily). Pure: no fs, no state.
|
|
9
|
+
*
|
|
10
|
+
* keysPath(env, home) -> the file's path
|
|
11
|
+
* chordFamilyFrom(bytes, error) -> { family, why }: the family to bind, and why it is the default
|
|
12
|
+
* chordFamilyNote(read) -> the one line a client shows when the file was not taken, or null
|
|
13
|
+
* keysWithFamily(bytes, family) -> the file's new text: `chords` set, every other key kept, or a
|
|
14
|
+
* KeysUnwritable error when that cannot be done
|
|
15
|
+
*
|
|
16
|
+
* Both clients hand over the file's bytes, not their own reading of them, so the same bytes mean the
|
|
17
|
+
* same family in both: UTF-8 (RFC 8259), a byte-order mark ignored, anything else not text.
|
|
18
|
+
*
|
|
19
|
+
* Every way the file can fail means the default, Ctrl+Alt: none is an error the user must clear. */
|
|
20
|
+
import { join } from "node:path";
|
|
21
|
+
import { CHORD_FAMILIES, DEFAULT_CHORD_FAMILY } from "./keymap.mjs";
|
|
22
|
+
|
|
23
|
+
/** The most a client reads of the file, in bytes: anything longer is not a keys.json. */
|
|
24
|
+
export const KEYS_LIMIT = 16384;
|
|
25
|
+
|
|
26
|
+
/** Why the family is the default, by the `why` chordFamilyFrom answers; null: the file chose it. */
|
|
27
|
+
export const KEYS_WHY = Object.freeze({
|
|
28
|
+
missing: "there is no keys.json",
|
|
29
|
+
unreadable: "keys.json cannot be read",
|
|
30
|
+
"too-large": "keys.json is too large",
|
|
31
|
+
"not-utf8": "keys.json is not UTF-8 text",
|
|
32
|
+
"not-json": "keys.json is not JSON",
|
|
33
|
+
"not-object": "keys.json is not an object",
|
|
34
|
+
"no-chords": "keys.json names no chords",
|
|
35
|
+
"unknown-chords": "keys.json: unknown chords value",
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
39
|
+
const utf8Length = (text) => new TextEncoder().encode(text).length;
|
|
40
|
+
|
|
41
|
+
/** The file's text from what a client read: `{ text }`, or `{ why }` when it is none. `input` is the
|
|
42
|
+
* file's bytes (a Uint8Array, a Buffer), at most KEYS_LIMIT and one of them, decoded as UTF-8 with a
|
|
43
|
+
* leading byte-order mark dropped; or text already decoded (a test's), held to the same rules. */
|
|
44
|
+
function textOf(input) {
|
|
45
|
+
if (input instanceof Uint8Array) {
|
|
46
|
+
if (input.length > KEYS_LIMIT) return { why: "too-large" };
|
|
47
|
+
try { return { text: new TextDecoder("utf-8", { fatal: true }).decode(input) }; } catch { return { why: "not-utf8" }; }
|
|
48
|
+
}
|
|
49
|
+
if (typeof input !== "string") return { why: "unreadable" };
|
|
50
|
+
if (utf8Length(input) > KEYS_LIMIT) return { why: "too-large" };
|
|
51
|
+
return { text: input.startsWith("\uFEFF") ? input.slice(1) : input };
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** What keysWithFamily throws when the file is there and its other keys cannot all be kept: one it
|
|
55
|
+
* cannot read as a JSON object, or one whose new text would be over KEYS_LIMIT. `why` says which
|
|
56
|
+
* (a key of KEYS_WHY, or "unreadable" for a file the client could not read). Nothing is written. */
|
|
57
|
+
export class KeysUnwritable extends Error {
|
|
58
|
+
constructor(why) {
|
|
59
|
+
super(`keys.json cannot be rewritten without losing what it holds (${why})`);
|
|
60
|
+
this.name = "KeysUnwritable";
|
|
61
|
+
this.code = "E_KEYS_UNWRITABLE";
|
|
62
|
+
this.why = why;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The path of keys.json: `config/keys.json` in `$OATS_HOME_DIR` when that is set and not empty, else
|
|
67
|
+
* in `<home>/.oats` (the TUI's configPath for tui.json, packages/tui/lib/config.mjs). */
|
|
68
|
+
export function keysPath(env, home) {
|
|
69
|
+
const own = env?.OATS_HOME_DIR;
|
|
70
|
+
return join(typeof own === "string" && own !== "" ? own : join(home, ".oats"), "config", "keys.json");
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** The family keys.json names. `bytes` is what the client read of the file (textOf: its bytes, at most
|
|
74
|
+
* KEYS_LIMIT and one), or null or undefined when there is none; `error` the error its read threw, if
|
|
75
|
+
* one did (ENOENT and ENOTDIR are no file, any other is a file that cannot be read). Answers a frozen
|
|
76
|
+
* `{ family, why }`: `why` is null when the file chose the family, else a key of KEYS_WHY, and
|
|
77
|
+
* `family` is then the default. */
|
|
78
|
+
export function chordFamilyFrom(bytes, error = null) {
|
|
79
|
+
const fallback = (why) => Object.freeze({ family: DEFAULT_CHORD_FAMILY, why });
|
|
80
|
+
if (error) return fallback(error.code === "ENOENT" || error.code === "ENOTDIR" ? "missing" : "unreadable");
|
|
81
|
+
if (bytes === null || bytes === undefined) return fallback("missing");
|
|
82
|
+
const { text, why } = textOf(bytes);
|
|
83
|
+
if (why) return fallback(why);
|
|
84
|
+
let value;
|
|
85
|
+
try { value = JSON.parse(text); } catch { return fallback("not-json"); }
|
|
86
|
+
if (!isObject(value)) return fallback("not-object");
|
|
87
|
+
if (!Object.hasOwn(value, "chords")) return fallback("no-chords");
|
|
88
|
+
if (!CHORD_FAMILIES.includes(value.chords)) return fallback("unknown-chords");
|
|
89
|
+
return Object.freeze({ family: value.chords, why: null });
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The line a client shows when keys.json was there and not taken ("keys.json: unknown chords value,
|
|
93
|
+
* using Ctrl+Alt"), or null: the file chose the family, or there is none, which is the default
|
|
94
|
+
* with nothing to say. `read` is what chordFamilyFrom answered. */
|
|
95
|
+
export function chordFamilyNote(read) {
|
|
96
|
+
if (!read || read.why === null || read.why === "missing" || !Object.hasOwn(KEYS_WHY, read.why)) return null;
|
|
97
|
+
return `${KEYS_WHY[read.why]}, using Ctrl+Alt`;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** The text of keys.json with `chords` set to `family`, from the file's current `bytes` (as
|
|
101
|
+
* chordFamilyFrom takes them; null when there is no file): every other key of the object is kept,
|
|
102
|
+
* in its place, so that a key a later client adds is not lost to an older one. The text is indented
|
|
103
|
+
* when that fits in KEYS_LIMIT, else on one line, so the clients always read back what was written.
|
|
104
|
+
* Throws KeysUnwritable, so that nothing is written, for a file that is there and is not a JSON
|
|
105
|
+
* object, or whose keys do not fit in KEYS_LIMIT with `chords` set; a TypeError for a `family` that
|
|
106
|
+
* is not one of CHORD_FAMILIES. A client that could not read the file must not call this: it does
|
|
107
|
+
* not know what it would lose. The client writes the answer atomically. */
|
|
108
|
+
export function keysWithFamily(bytes, family) {
|
|
109
|
+
if (!CHORD_FAMILIES.includes(family)) throw new TypeError(`unknown chord family: ${String(family)}`);
|
|
110
|
+
let kept = {};
|
|
111
|
+
if (bytes !== null && bytes !== undefined) {
|
|
112
|
+
const { text, why } = textOf(bytes);
|
|
113
|
+
if (why) throw new KeysUnwritable(why);
|
|
114
|
+
let value;
|
|
115
|
+
try { value = JSON.parse(text); } catch { throw new KeysUnwritable("not-json"); }
|
|
116
|
+
if (!isObject(value)) throw new KeysUnwritable("not-object");
|
|
117
|
+
kept = value;
|
|
118
|
+
}
|
|
119
|
+
const next = { ...kept, chords: family };
|
|
120
|
+
for (const text of [`${JSON.stringify(next, null, 2)}\n`, `${JSON.stringify(next)}\n`]) if (utf8Length(text) <= KEYS_LIMIT) return text;
|
|
121
|
+
throw new KeysUnwritable("too-large");
|
|
122
|
+
}
|
|
@@ -16,13 +16,15 @@ export const CLIENT_OWN_CODES = Object.freeze([
|
|
|
16
16
|
'E_REMOTE_ROSTER', 'E_WORKSPACE_FEATURE', 'E_WORKSPACE_UNKNOWN',
|
|
17
17
|
// This computer's deployments list (#1390): a CLI without it.
|
|
18
18
|
'E_DEPLOYMENTS_FEATURE',
|
|
19
|
-
// A spawn: its preview, its apply and the wake saved with it.
|
|
19
|
+
// A spawn: its preview, its apply and the wake saved with it; a suggest read a newer one ended (E_SUPERSEDED, #1421 §3).
|
|
20
20
|
'E_APPLY_UNAVAILABLE', 'E_BACKEND_UNAVAILABLE', 'E_BUSY', 'E_FORBIDDEN_FRAME', 'E_INPUT_PREPARATION', 'E_INSTANCE_GONE',
|
|
21
|
-
'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_TARGET_CHANGED',
|
|
21
|
+
'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_SUPERSEDED', 'E_TARGET_CHANGED',
|
|
22
22
|
'E_UNSUPPORTED_OPTION', 'E_WAKE_OUTCOME_UNKNOWN', 'E_WAKE_SAVE_FAILED',
|
|
23
23
|
// Stop, start, restart and remove, and the plan a person confirms (a spawn's plan too).
|
|
24
24
|
'E_LIFECYCLE_UNAVAILABLE', 'E_OPTION_UNAVAILABLE', 'E_PLAN_CHANGED', 'E_PLAN_EXPIRED', 'E_PLAN_LIMIT', 'E_PLAN_REQUIRED',
|
|
25
25
|
'E_HOME_UNVERIFIED', 'E_START_UNCONFIRMED',
|
|
26
|
+
// keys.json (packages/client/keys-file.mjs): a write that could not keep every key, so none is made.
|
|
27
|
+
'E_KEYS_UNWRITABLE',
|
|
26
28
|
// An instance's Activity.
|
|
27
29
|
'E_EVENTS_UNAVAILABLE', 'E_NOT_IN_SCOPE',
|
|
28
30
|
// A terminal.
|
|
@@ -18,6 +18,9 @@
|
|
|
18
18
|
* remoteCollecting, // boolean: the remote roster is being read
|
|
19
19
|
* home, // string: the user's home directory, for the short label
|
|
20
20
|
* at, // string: the ISO time of this call
|
|
21
|
+
* learned, // optional: Map<deployment path, identity read> (deployment-identity.mjs
|
|
22
|
+
* // `cliDeploymentIdentity` answers) of this computer's deployments, read before
|
|
23
|
+
* // they were observed: see `deploymentInfo` and `listedViews`
|
|
21
24
|
* }
|
|
22
25
|
*
|
|
23
26
|
* These functions read no clock: the one time they stamp is `held.at`, and the same `held` gives the
|
|
@@ -73,6 +76,13 @@ export function rememberedGroups(held) {
|
|
|
73
76
|
* `roster`. Without it a client makes no roster read (remote-roster.mjs `remoteRosterState`: "gated"). */
|
|
74
77
|
export const cliReadsRemotes = (cli) => !!cli.ok && !!cli.remote?.includes("roster");
|
|
75
78
|
const identityFeature = (held) => !!held.cli.features?.includes("workspace-identity");
|
|
79
|
+
/** What a projected `workspace` object (deployment-data.mjs) says of the identity: readIdentity's
|
|
80
|
+
* classification, `feature` when the CLI reports no identities, `invalid` when the projection marked it. */
|
|
81
|
+
const identityRead = (held, workspace) => (!identityFeature(held) ? { status: "feature" }
|
|
82
|
+
: workspace?.identityInvalid ? { status: "invalid" } : readIdentity(workspace));
|
|
83
|
+
/** The identity read learned of this computer's deployment `id` before it was observed (`held.learned`):
|
|
84
|
+
* the answer when the read answered, else null (not read, or the read failed). */
|
|
85
|
+
const learnedOf = (held, id) => { const read = held.learned?.get?.(id); return read?.ok === true ? read : null; };
|
|
76
86
|
/** One deployment's identity, attachment, machine label and reason. */
|
|
77
87
|
export function deploymentInfo(held, d, terms) {
|
|
78
88
|
requireTerms(terms, 'deploymentInfo');
|
|
@@ -83,14 +93,16 @@ export function deploymentInfo(held, d, terms) {
|
|
|
83
93
|
// it in its view, but it is stale, not live, and says why. Still reachable: this computer's own deployment.
|
|
84
94
|
// Whether one is kept is deployment-facts.mjs `keptFailure`'s to say, never a test of the message.
|
|
85
95
|
const kept = live ? keptFailure(entry) : null;
|
|
86
|
-
|
|
87
|
-
|
|
96
|
+
// Not observed (yet, or its read failed): the identity an identity read learned of it, when one did, places it
|
|
97
|
+
// in its view (`identityFrom: "learned"`); it stays not live, with its reading or unavailable sentence.
|
|
98
|
+
const learned = live ? null : learnedOf(held, d.id);
|
|
99
|
+
const read = live ? identityRead(held, observed.reachable) : learned ? identityRead(held, learned.workspace) : { status: "none" };
|
|
88
100
|
const identity = read.status === "identity" ? read.identity : null;
|
|
89
101
|
const attach = attachment(identity);
|
|
90
102
|
// Not observed (yet): the reading or unavailable sentence, never a silent empty.
|
|
91
103
|
const unavailable = live ? null : deploymentUnavailableText(observed || { status: "pending" }, terms);
|
|
92
104
|
return { id: d.id, local: true, machine: terms.thisMachine, path: d.id, label: shortPath(d.id, { home: held.home }), name: d.name,
|
|
93
|
-
live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
|
|
105
|
+
live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? (live ? "reported" : "learned") : null, identity, attach,
|
|
94
106
|
teamLabel: identity?.defaultTeam?.label ?? null,
|
|
95
107
|
...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable,
|
|
96
108
|
...(kept ? { readError: kept.message, readErrorOrigin: kept.origin } : {}) }, terms)),
|
|
@@ -121,17 +133,58 @@ export function deploymentInfo(held, d, terms) {
|
|
|
121
133
|
export function reasonFields(parts) {
|
|
122
134
|
return parts ? { reason: parts.detail, short: parts.short, fix: parts.fix } : { reason: null, short: null, fix: [] };
|
|
123
135
|
}
|
|
124
|
-
/**
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
const infos = new Map(deployments(held).map((d) => [d.id, deploymentInfo(held, d, terms)]));
|
|
128
|
-
const views = buildViews([...infos.values()]).map((v) => {
|
|
136
|
+
/** buildViews' views over `infos`, each unattached one with its deployment's reason, short reason and ref. */
|
|
137
|
+
function viewsOver(infos) {
|
|
138
|
+
return buildViews([...infos.values()]).map((v) => {
|
|
129
139
|
const unattachedReason = v.unattached ? infos.get(v.primary)?.reason ?? null : null;
|
|
130
140
|
const unattachedShort = v.unattached ? infos.get(v.primary)?.short ?? null : null;
|
|
131
141
|
const ref = v.unattached ? infos.get(v.primary)?.identity?.ref ?? null : null;
|
|
132
142
|
return { ...v, ...(unattachedReason ? { reason: unattachedReason } : {}), ...(unattachedShort ? { short: unattachedShort } : {}), ...(ref ? { ref } : {}) };
|
|
133
143
|
});
|
|
134
|
-
|
|
144
|
+
}
|
|
145
|
+
/** The views and the per-deployment facts they rest on: `{ views, infos: Map<deploymentId, info> }`. */
|
|
146
|
+
export function viewModel(held, terms) {
|
|
147
|
+
requireTerms(terms, 'viewModel');
|
|
148
|
+
const infos = new Map(deployments(held).map((d) => [d.id, deploymentInfo(held, d, terms)]));
|
|
149
|
+
return { views: viewsOver(infos), infos };
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Why an identity read of a listed deployment failed, as reason parts: `Timed out` for the read's time limit
|
|
153
|
+
* (a read that never began before its caller's budget ran out is answered the same), else `Not read`; the
|
|
154
|
+
* sentence is the unavailable one (deployment-facts.mjs), the kernel's words set apart when it gave them. */
|
|
155
|
+
function identityFailure(reason, terms) {
|
|
156
|
+
return { short: reason?.code === "E_CLI_TIMEOUT" ? "Timed out" : "Not read", detail: deploymentUnavailableText({ status: "unavailable", reason: reason || {} }, terms), fix: [] };
|
|
157
|
+
}
|
|
158
|
+
/** One row of this computer's deployments list (deployment-list.mjs: `{ path, name }`) that the client does not
|
|
159
|
+
* serve, as a switcher matches it: an info of `deploymentInfo`'s shape, never live or reachable, `listed: true`,
|
|
160
|
+
* named by the row (its folder's name, a local name to buildViews), with the identity an identity read learned
|
|
161
|
+
* of it (`held.learned`) and `read`: "pending" (no answer yet), "read" or "failed". Its reason says why it is not
|
|
162
|
+
* matched: the read's failure, or the shared reason of an identity that attaches to no workspace; none while it
|
|
163
|
+
* is pending or when it attaches. */
|
|
164
|
+
export function listedInfo(held, row, terms) {
|
|
165
|
+
requireTerms(terms, 'listedInfo');
|
|
166
|
+
const answer = held.learned?.get?.(row.path) ?? null, learned = answer?.ok === true ? answer : null;
|
|
167
|
+
const read = learned ? identityRead(held, learned.workspace) : { status: "none" };
|
|
168
|
+
const identity = read.status === "identity" ? read.identity : null;
|
|
169
|
+
const attach = attachment(identity);
|
|
170
|
+
const parts = answer === null ? null : !learned ? identityFailure(answer.reason, terms)
|
|
171
|
+
: deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref }, terms);
|
|
172
|
+
return { id: row.path, local: true, listed: true, machine: terms.thisMachine, path: row.path, label: shortPath(row.path, { home: held.home }), name: row.name,
|
|
173
|
+
live: false, reachable: false, identityFrom: identity ? "learned" : null, identity, attach, teamLabel: identity?.defaultTeam?.label ?? null,
|
|
174
|
+
read: answer === null ? "pending" : learned ? "read" : "failed", ...reasonFields(parts), note: null };
|
|
175
|
+
}
|
|
176
|
+
/** The switcher's views (#482): `viewModel`'s, with this computer's listed deployments the client does not serve
|
|
177
|
+
* matched in by the same rule (buildViews, over the served deployments first, then these). `listed`: the list's
|
|
178
|
+
* rows (`{ path, name }`), in its order; a row the client serves is passed over. A listed deployment whose
|
|
179
|
+
* identity attaches joins its workspace's view, or makes one; the others are `unmatched`, in order, each
|
|
180
|
+
* `listedInfo`'s answer. `{ views, infos, unmatched }`: `infos` holds the served deployments' and the matched
|
|
181
|
+
* listed ones'. Only a switcher reads this: a listed deployment is in no panel and no route. */
|
|
182
|
+
export function listedViews(held, listed, terms) {
|
|
183
|
+
requireTerms(terms, 'listedViews');
|
|
184
|
+
const model = viewModel(held, terms);
|
|
185
|
+
const offered = (Array.isArray(listed) ? listed : []).filter((row) => !model.infos.has(row?.path)).map((row) => listedInfo(held, row, terms));
|
|
186
|
+
const infos = new Map([...model.infos, ...offered.filter((info) => !info.attach.unattached).map((info) => [info.id, info])]);
|
|
187
|
+
return { views: viewsOver(infos), infos, unmatched: offered.filter((info) => info.attach.unattached) };
|
|
135
188
|
}
|
|
136
189
|
/** The view a selector names: a view id, or a deployment id (answered with the view that holds it, so
|
|
137
190
|
* a selection saved before views opens its view). No selector means the first view. `model` is a
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** The suggested name's rules on the Desktop's side (feature spawn-suggest-name, awebai/oats#1421 §3 "The Desktop's use
|
|
2
|
+
* of it"). The kernel chooses the name (`spawn --preview --suggest-name`); these say when the dialog asks, how it
|
|
3
|
+
* remembers an answer, and how it says a numbered one. */
|
|
4
|
+
import { HARNESS_NAMES } from './harness-names.mjs';
|
|
5
|
+
|
|
6
|
+
/** How long the task text must rest before the dialog asks (about 1.5 s): never on each keystroke. */
|
|
7
|
+
export const SUGGEST_PAUSE_MS = 1500;
|
|
8
|
+
/** The words a task needs before the dialog asks while it is typed. Spawn asks whatever the length. */
|
|
9
|
+
export const SUGGEST_MIN_WORDS = 3;
|
|
10
|
+
|
|
11
|
+
/** The words of `text`: whitespace-separated runs that hold a letter or a digit. */
|
|
12
|
+
export const taskWords = text => (String(text ?? '').match(/\S+/g) || []).filter(w => /[\p{L}\p{N}]/u.test(w)).length;
|
|
13
|
+
|
|
14
|
+
/** What an answer is remembered by: the exact task text and the soul (its root and name). */
|
|
15
|
+
export const namingKey = (selector, text) => JSON.stringify([selector?.agentsRoot ?? null, selector?.soul ?? null, String(text ?? '')]);
|
|
16
|
+
|
|
17
|
+
const harnessName = harness => HARNESS_NAMES[harness] ?? (typeof harness === 'string' && harness ? harness : 'the harness');
|
|
18
|
+
/** Why a spawn was numbered, in the Desktop's words. The kernel's `message` is never shown: it can carry an exit
|
|
19
|
+
* code or a signal. */
|
|
20
|
+
export function numberedWords(reason, harness) {
|
|
21
|
+
switch (reason) {
|
|
22
|
+
case 'no-task': return 'there is no task to name it from';
|
|
23
|
+
case 'unsupported-harness': return `${harnessName(harness)} doesn't suggest names`;
|
|
24
|
+
case 'timeout': return 'naming took longer than 20 seconds';
|
|
25
|
+
case 'harness-failed': return `${harnessName(harness)} couldn't be asked for a name`;
|
|
26
|
+
case 'invalid-reply': return `${harnessName(harness)} gave no usable name`;
|
|
27
|
+
default: return 'it could not be named from its task';
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/** "Named <instance>: <why>." for a spawn that was numbered. */
|
|
31
|
+
export const numberedLine = (instance, reason, harness) => `Named ${instance}: ${numberedWords(reason, harness)}.`;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** Fixed read-only API2 argv. Never dispatch API1 or fall back to spawn. */
|
|
2
2
|
import { execFile } from 'node:child_process';
|
|
3
|
-
import { parseEnvelope } from './cli-adapter.mjs';
|
|
4
|
-
import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv } from './spawn-preview-contract.mjs';
|
|
3
|
+
import { parseEnvelope, writeTaskFile } from './cli-adapter.mjs';
|
|
4
|
+
import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv, suggestSupported, suggestTask } from './spawn-preview-contract.mjs';
|
|
5
5
|
/** A refusal, in the kernel's own shape (`{ code, message, details: { fix } }`). `previewFailure` decides what of the
|
|
6
6
|
* kernel's travels: its message when that is printable and within the bound, and its `fix` only beside that message.
|
|
7
7
|
* No other key of `details` travels. */
|
|
@@ -9,24 +9,39 @@ function failure(code, message, kernelFix) {
|
|
|
9
9
|
const { fix, ...error } = previewFailure(code, null, message, kernelFix).reason;
|
|
10
10
|
return { schemaVersion: 1, ok: false, error: fix === undefined ? error : { ...error, details: { fix } } };
|
|
11
11
|
}
|
|
12
|
-
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`).
|
|
12
|
+
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`).
|
|
13
|
+
* With `task`, the read is a suggest read (feature spawn-suggest-name, awebai/oats#1421 §3): `--suggest-name` with the
|
|
14
|
+
* task in a private temporary `--task-file` (as the apply passes it), removed on every path, and never with a name or a
|
|
15
|
+
* purpose. `signal` ends it: the CLI gets SIGTERM, which ends the kernel's naming call with it, and the read answers
|
|
16
|
+
* `E_SUPERSEDED`. */
|
|
13
17
|
export function cliSpawnPreview(cli, options = {}, io = {}) {
|
|
14
18
|
// Defense at the actual exec owner as well as at HTTP admission.
|
|
15
19
|
if (!previewSupported(cli)) return Promise.resolve(failure('E_PREVIEW_UNAVAILABLE'));
|
|
16
20
|
const target = previewTarget(options.target), choices = previewChoices(options.choices);
|
|
17
|
-
if (!target || !choices || Object.keys(options).some(k => !['target', 'choices', 'maxAge'].includes(k))) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
21
|
+
if (!target || !choices || Object.keys(options).some(k => !['target', 'choices', 'maxAge', 'task', 'signal'].includes(k))) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
22
|
+
const suggest = options.task !== undefined;
|
|
23
|
+
if (suggest && !suggestSupported(cli)) return Promise.resolve(failure('E_PREVIEW_UNAVAILABLE'));
|
|
24
|
+
if (suggest && (!suggestTask(options.task) || choices.name !== undefined || choices.purpose !== undefined)) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
25
|
+
const signal = options.signal;
|
|
26
|
+
if (signal !== undefined && !(signal instanceof AbortSignal)) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
27
|
+
if (signal?.aborted) return Promise.resolve(failure('E_SUPERSEDED'));
|
|
18
28
|
// Feature spawn-preview-max-age: reuse member heads the kernel observed within maxAge seconds. Only
|
|
19
29
|
// where the CLI advertises it (an older kernel refuses the flag); prepare never passes it. The apply's own
|
|
20
30
|
// --max-age is spawn-apply-max-age's (spawn-apply-cli.mjs).
|
|
21
31
|
const maxAge = options.maxAge;
|
|
22
32
|
if (maxAge !== undefined && (!Number.isInteger(maxAge) || maxAge < 1 || maxAge > 3600)) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
23
33
|
const reuse = maxAge !== undefined && Array.isArray(cli.features) && cli.features.includes('spawn-preview-max-age') ? ['--max-age', String(maxAge)] : [];
|
|
24
|
-
|
|
34
|
+
let taskFile = null;
|
|
35
|
+
if (suggest) { try { taskFile = writeTaskFile(options.task, io); } catch { return Promise.resolve(failure('E_CLI_FAILED')); } }
|
|
36
|
+
const naming = taskFile ? ['--suggest-name', '--task-file', taskFile.file] : [];
|
|
37
|
+
const argv = ['spawn', target.selector.soul, '--dir', target.context, '--agents-root', target.selector.agentsRoot, '--preview', ...naming, ...choiceArgv(choices, cli), ...reuse, '--json'];
|
|
25
38
|
const env = { ...(io.env ?? process.env) };
|
|
26
39
|
for (const k of ['PI_AGENTS_ROOT', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION', 'OATS_PREVIEW_PREFLIGHT_BUDGET_MS']) delete env[k];
|
|
27
|
-
return new Promise(
|
|
40
|
+
return new Promise(done => {
|
|
41
|
+
const resolve = v => { taskFile?.cleanup(); done(v); };
|
|
28
42
|
try {
|
|
29
|
-
(io.exec ?? execFile)(cli.bin, argv, { cwd: target.context, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
|
|
43
|
+
(io.exec ?? execFile)(cli.bin, argv, { cwd: target.context, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024, ...(signal ? { signal } : {}) }, (err, stdout) => {
|
|
44
|
+
if (err?.name === 'AbortError' || signal?.aborted) return resolve(failure('E_SUPERSEDED'));
|
|
30
45
|
if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
|
|
31
46
|
if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
|
|
32
47
|
const doc = parseEnvelope(stdout);
|
|
@@ -128,6 +128,24 @@ function modulesOf(v, projected, composedFrom) {
|
|
|
128
128
|
}
|
|
129
129
|
export const previewSupported = cli => cli?.ok === true && absolute(cli.bin) && cli.spawnPreviewApi === 2
|
|
130
130
|
&& Array.isArray(cli.features) && cli.features.includes('spawn-preview-2');
|
|
131
|
+
/** Feature spawn-suggest-name (awebai/oats#1421 §3): `spawn --preview --suggest-name` also chooses the name, from the
|
|
132
|
+
* task, through the soul's harness. The Desktop asks only where it can also pass the name back (`spawn-name`). */
|
|
133
|
+
export const SUGGEST_NAME_FEATURE = 'spawn-suggest-name';
|
|
134
|
+
export const suggestSupported = cli => previewSupported(cli) && cli.features.includes(SUGGEST_NAME_FEATURE) && cli.features.includes('spawn-name');
|
|
135
|
+
/** Why a suggest read was numbered: the kernel's closed set. */
|
|
136
|
+
export const NAMING_REASONS = ['no-task', 'unsupported-harness', 'timeout', 'harness-failed', 'invalid-reply'];
|
|
137
|
+
/** The task a suggest read carries: the apply's bound (spawnPrepareInput), never blank. */
|
|
138
|
+
export const suggestTask = v => typeof v === 'string' && !v.includes('\0') && v.length <= 32768 && new TextEncoder().encode(v).byteLength <= 32768 && !!v.trim();
|
|
139
|
+
/** The preview's `naming`, or null when it is malformed. `suggested` names its harness and model (null: the harness's
|
|
140
|
+
* default); `numbered` names its reason. The kernel's `message` is not projected: it can carry an exit code or a
|
|
141
|
+
* signal, and the Desktop says the reason in its own words. */
|
|
142
|
+
export function namingOf(v) {
|
|
143
|
+
if (!record(v) || !Number.isSafeInteger(v.ms) || v.ms < 0) return null;
|
|
144
|
+
if (v.source === 'suggested') return name(v.harness) && (v.model === null || safe(v.model, 256) && !!v.model)
|
|
145
|
+
? { source: 'suggested', ms: v.ms, harness: v.harness, model: v.model } : null;
|
|
146
|
+
if (v.source === 'numbered') return NAMING_REASONS.includes(v.reason) ? { source: 'numbered', reason: v.reason, ms: v.ms } : null;
|
|
147
|
+
return null;
|
|
148
|
+
}
|
|
131
149
|
export function previewSelector(v) {
|
|
132
150
|
return exact(v, ['soul', 'agentsRoot']) && name(v.soul) && absolute(v.agentsRoot) ? { soul: v.soul, agentsRoot: v.agentsRoot } : null;
|
|
133
151
|
}
|
|
@@ -234,6 +252,7 @@ const errors = {
|
|
|
234
252
|
E_CLI_TIMEOUT: 'The spawn preview timed out.', E_CLI_OUTPUT_LIMIT: 'The spawn preview exceeded its output limit.',
|
|
235
253
|
E_CLI_PROTOCOL: 'The CLI returned an invalid or mismatched API 2 preview.', E_CLI_FAILED: 'The installed CLI could not complete the preview.',
|
|
236
254
|
E_FORBIDDEN_FRAME: 'This frame cannot request a spawn preview.',
|
|
255
|
+
E_SUPERSEDED: 'A newer naming request replaced this one.',
|
|
237
256
|
};
|
|
238
257
|
const KERNEL_CODE = /^E_[A-Z0-9_]{1,63}$/;
|
|
239
258
|
/** A kernel refusal keeps its own code and message (bounded, printable): the
|
|
@@ -304,6 +323,10 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
|
|
|
304
323
|
const launchPromptAnswers = Object.hasOwn(v, 'launchPromptAnswers') ? launchPromptAnswersOf(v.launchPromptAnswers) : undefined;
|
|
305
324
|
if (launchPromptAnswers === null) return null;
|
|
306
325
|
const worktreeHooks = worktreeHooksOf(v.worktreeHooks);
|
|
326
|
+
// Feature spawn-suggest-name: how the name was chosen, on a suggest read only. A malformed one refuses the preview: its
|
|
327
|
+
// name is then not known to be the one a `--name` preview would give.
|
|
328
|
+
const naming = Object.hasOwn(v, 'naming') ? namingOf(v.naming) : undefined;
|
|
329
|
+
if (naming === null) return null;
|
|
307
330
|
// Only reports carry `problem`: a preview that would hit one refuses with the error instead.
|
|
308
331
|
if (Object.hasOwn(v, 'launch') && (launch === undefined || launch.problem !== null || launch.effective.harness !== e.harness || launch.effective.model !== e.model
|
|
309
332
|
|| launch.effective.launchConfig !== e.launchConfig)) return null;
|
|
@@ -315,6 +338,7 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
|
|
|
315
338
|
preflight: { status: v.preflight.status, budgetMs: v.preflight.budgetMs, elapsedMs: v.preflight.elapsedMs }, messaging, teams, modules,
|
|
316
339
|
...(defaultTeam !== undefined ? { defaultTeam } : {}), ...(launch ? { launch } : {}),
|
|
317
340
|
...(launchPromptAnswers ? { launchPromptAnswers } : {}),
|
|
341
|
+
...(naming ? { naming } : {}),
|
|
318
342
|
// Capability warnings (0.49.0): the kernel's message strings, tolerant and idempotent (a malformed list reads as none,
|
|
319
343
|
// never refuses the preview); absent on an older kernel. Shown only: the apply binds nothing on them.
|
|
320
344
|
...(Object.hasOwn(v, 'warnings') ? { warnings: previewWarningsOf(v.warnings) } : {}) };
|
|
@@ -77,13 +77,17 @@ function previewModules(modules) {
|
|
|
77
77
|
return { core, caps };
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
/** `unnamed`: what the Name fact says with no name yet. Given (the dialog's 'named from its task', where it will ask the
|
|
81
|
+
* kernel for one, feature spawn-suggest-name), the preview's numbered name is not the one Spawn creates: the facts
|
|
82
|
+
* derived from it, the home and the new branch, are left out until there is a name. */
|
|
83
|
+
export function previewFacts(data, { name = null, runsOn = null, cli = null, unnamed } = {}) {
|
|
81
84
|
const preview = data && typeof data === 'object' ? data : {};
|
|
82
|
-
const
|
|
83
|
-
const
|
|
85
|
+
const pending = !name && unnamed !== undefined;
|
|
86
|
+
const identity = [name ? { label: 'Name', text: name } : { label: 'Name', text: unnamed ?? 'numbered by the kernel', muted: true }];
|
|
87
|
+
const home = pending ? null : homeText(preview.home, preview.subject?.dir);
|
|
84
88
|
if (home) identity.push({ label: 'Home', text: home.text, title: home.title });
|
|
85
89
|
const facts = [], fact = (label, parts, extra = {}) => { facts.push({ label, ...extra, parts }); };
|
|
86
|
-
const worktree = preview.work === 'worktree' && preview.branch ? worktreeText(preview) : null;
|
|
90
|
+
const worktree = preview.work === 'worktree' && preview.branch && !pending ? worktreeText(preview) : null;
|
|
87
91
|
if (worktree) fact('Works in', [{ text: worktree.lead }, { text: worktree.branch, mono: true }, ...(worktree.tail ? [{ text: worktree.tail }] : [])]);
|
|
88
92
|
else if (preview.work) fact('Works in', [{ text: worksInText(preview.work) }]);
|
|
89
93
|
if (preview.harness) {
|
|
@@ -15,7 +15,7 @@ import { dirname } from 'node:path';
|
|
|
15
15
|
import { performance } from 'node:perf_hooks';
|
|
16
16
|
import { cliSpawnPreview } from './spawn-preview-cli.mjs';
|
|
17
17
|
import { admitInstance } from './instance-admission.mjs';
|
|
18
|
-
import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom } from './spawn-preview-contract.mjs';
|
|
18
|
+
import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom, suggestSupported, suggestTask } from './spawn-preview-contract.mjs';
|
|
19
19
|
/** One preview's flights: its two-slot budget (`slots`), the flights in the air per invoker (`byInvoker`, where
|
|
20
20
|
* exact duplicates coalesce), and the monotonic clock that stamps each flight's start (`started`). The cache is
|
|
21
21
|
* given the same clock: it orders flight starts against invalidations, so a flight that started before its
|
|
@@ -139,10 +139,54 @@ export function createSpawnPreviewBoundary({ invoke = cliSpawnPreview, cache = n
|
|
|
139
139
|
} catch { return previewFailure('E_CLI_FAILED'); }
|
|
140
140
|
};
|
|
141
141
|
}
|
|
142
|
+
/** The suggest read (feature spawn-suggest-name, awebai/oats#1421 §3): a preview that also names the instance from its
|
|
143
|
+
* task, `{ action: 'suggest', selector, choices, task }`, with no name or purpose among the choices. It has its own
|
|
144
|
+
* lane, outside the previews' two slots: ONE read per workspace, and a newer one ends the older (its CLI gets
|
|
145
|
+
* SIGTERM, which ends the kernel's naming call too) and the older answers E_SUPERSEDED. Nothing of it is cached here
|
|
146
|
+
* (the dialog caches by task), except that a suggested answer IS the preview of `--name <instance>` (the kernel's
|
|
147
|
+
* contract), so it is held as that preview's answer, for the dialog's next read and for prepare. */
|
|
148
|
+
export function createSpawnSuggestBoundary({ invoke = cliSpawnPreview, cache = null, maxAge = null, flights, exec } = {}) {
|
|
149
|
+
if (!flights?.clock) throw missing('createSpawnSuggestBoundary', 'flights (createSpawnPreviewFlights)');
|
|
150
|
+
if (cache && cache.clock !== flights.clock) throw new TypeError('createSpawnSuggestBoundary: the cache must run on the flights\' clock');
|
|
151
|
+
const lanes = new Map(), io = exec ? [{ exec }] : [];
|
|
152
|
+
return async function suggest(request, getContext) {
|
|
153
|
+
let lane = null, workspace = null;
|
|
154
|
+
try {
|
|
155
|
+
if (!record(request) || request.action !== 'suggest' || Object.keys(request).some(k => !['action', 'selector', 'choices', 'task'].includes(k))) return previewFailure('E_BAD_ARGS');
|
|
156
|
+
const selector = previewSelector(request.selector), choices = previewChoices(request.choices);
|
|
157
|
+
if (!selector || !choices || !suggestTask(request.task) || choices.name !== undefined || choices.purpose !== undefined) return previewFailure('E_BAD_ARGS');
|
|
158
|
+
const context = getContext(), selected = admitSpawnSelection(selector, choices, context);
|
|
159
|
+
if (selected.error) return previewFailure(selected.error);
|
|
160
|
+
const { target, identity, cli } = selected;
|
|
161
|
+
if (!suggestSupported(cli)) return previewFailure('E_UNSUPPORTED_OPTION', target);
|
|
162
|
+
workspace = target.workspace;
|
|
163
|
+
lanes.get(workspace)?.abort();
|
|
164
|
+
lane = new AbortController(); lanes.set(workspace, lane);
|
|
165
|
+
const startedAt = flights.clock();
|
|
166
|
+
const reuse = maxAge !== null && cli.features.includes('spawn-preview-max-age') ? { maxAge } : {};
|
|
167
|
+
const envelope = await invoke(cli, { target, choices, task: request.task, signal: lane.signal, ...reuse }, ...io);
|
|
168
|
+
if (lane.signal.aborted) return previewFailure('E_SUPERSEDED', target);
|
|
169
|
+
if (envelope?.schemaVersion !== 1 || envelope.ok !== true) return previewFailure(envelope?.error?.code, target, envelope?.error?.message, envelope?.error?.details?.fix);
|
|
170
|
+
const data = previewData(envelope.result, target, { composedFrom: previewComposedFrom(cli) });
|
|
171
|
+
if (!data?.naming) return previewFailure('E_CLI_PROTOCOL', target);
|
|
172
|
+
const current = admitSpawnSelection(selector, choices, getContext());
|
|
173
|
+
if (current.identity !== identity) return previewFailure('E_TARGET_CHANGED', target);
|
|
174
|
+
const result = { spawnPreviewViewApi: 1, status: 'available', target, data, reason: null };
|
|
175
|
+
if (cache && data.naming.source === 'suggested') {
|
|
176
|
+
// The choices as a read of `--name <instance>` admits them (previewChoices's order), so its identity is the same.
|
|
177
|
+
const namedChoices = previewChoices({ ...choices, name: data.instance }), named = namedChoices && admitSpawnSelection(selector, namedChoices, getContext());
|
|
178
|
+
if (named && !named.error) { const { naming, ...plain } = data; cache.set(named.identity, workspace, { ...result, data: plain }, startedAt); }
|
|
179
|
+
}
|
|
180
|
+
return result;
|
|
181
|
+
} catch { return previewFailure('E_CLI_FAILED'); }
|
|
182
|
+
finally { if (lane && lanes.get(workspace) === lane) lanes.delete(workspace); }
|
|
183
|
+
};
|
|
184
|
+
}
|
|
142
185
|
export const PREVIEW_MAX_AGE_S = 60;
|
|
143
|
-
/** One client's spawn preview: `{ read, prepareRead, cache }`.
|
|
186
|
+
/** One client's spawn preview: `{ read, prepareRead, suggest, cache }`.
|
|
144
187
|
* read the dialog's read, through the cache; its kernel reads may reuse recent member heads (maxAge,
|
|
145
188
|
* where the CLI declares spawn-preview-max-age)
|
|
189
|
+
* suggest the suggest read (createSpawnSuggestBoundary): its own lane, one per workspace, the newer ending the older
|
|
146
190
|
* prepareRead prepare's read (spawn-apply.mjs createSpawnApplyBoundary's `read`), through the same cache,
|
|
147
191
|
* taking a held answer up to `prepareReuseMs` old (PREPARE_REUSE_MS), never with maxAge; a reusing
|
|
148
192
|
* read and a live one never coalesce
|
|
@@ -159,6 +203,7 @@ export function createSpawnPreview({ invoke = cliSpawnPreview, exec, now = () =>
|
|
|
159
203
|
return {
|
|
160
204
|
read: createSpawnPreviewBoundary({ invoke, cache, maxAge, heldMs: ttlMs, flights, exec }),
|
|
161
205
|
prepareRead: createSpawnPreviewBoundary({ invoke, cache, heldMs: prepareReuseMs, flights, exec }),
|
|
206
|
+
suggest: createSpawnSuggestBoundary({ invoke, cache, maxAge, flights, exec }),
|
|
162
207
|
cache: { invalidate: workspace => cache.invalidate(workspace), size: () => cache.size() },
|
|
163
208
|
};
|
|
164
209
|
}
|
package/packages/tui/README.md
CHANGED
|
@@ -22,12 +22,12 @@ never does.
|
|
|
22
22
|
| `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
|
|
23
23
|
| `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList` |
|
|
24
24
|
| `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
|
|
25
|
-
| `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey
|
|
25
|
+
| `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
|
|
26
26
|
| `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
|
|
27
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
|
-
| `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), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
|
|
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 identity reads of this computer's listed deployments the run has not opened (`createIdentityReads`: one at a time, under a budget, never on a timer), the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
|
|
29
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
|
-
| `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
|
+
| `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows (a workspace and a line per deployment of it, matched by the shared `listedViews` over the served deployments and the identities the reads learned), 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; under the kitty keyboard protocol it reads a `CSI … u` key as its legacy bytes read, a chord as its own id |
|
|
32
32
|
| `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed |
|
|
33
33
|
| `lib/term/width.mjs` | the cells a grapheme takes |
|