@awebai/oats 0.58.0 → 0.60.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +1 -1
- package/docs/desktop-cli-api.md +80 -8
- package/docs/desktop.md +30 -3
- package/docs/execution-targets.md +18 -2
- package/docs/implementation.md +3 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +4 -4
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.59.0.md +288 -0
- package/docs/release-notes/v0.60.0.md +104 -0
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +21 -0
- package/docs/tui.md +753 -119
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +258 -57
- package/lib/read-ahead-worker.mjs +119 -0
- package/lib/read-ahead.mjs +115 -0
- package/lib/retire-state.mjs +33 -0
- package/lib/servers.mjs +9 -1
- package/lib/session-input.mjs +53 -26
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/capability-catalog.mjs +93 -0
- package/packages/client/capability-facts.mjs +59 -0
- package/packages/client/capability-rows.mjs +121 -0
- package/packages/client/catalog-messages.mjs +12 -0
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/instance-acts.mjs +23 -8
- package/packages/client/instance-presentation.mjs +3 -2
- package/packages/client/instance-tree.mjs +84 -39
- package/packages/client/lifecycle-confirmation.mjs +9 -3
- package/packages/client/remote-roster.mjs +4 -1
- package/packages/client/retire-in-flight.mjs +65 -0
- package/packages/client/retire-state.mjs +30 -0
- package/packages/client/soul-catalog.mjs +8 -0
- package/packages/client/soul-facts.mjs +7 -0
- package/packages/client/spawn-apply.mjs +13 -4
- package/packages/client/spawn-messages.mjs +8 -0
- package/packages/client/subsequence-score.mjs +15 -0
- package/packages/tui/README.md +23 -10
- package/packages/tui/lib/actions.mjs +63 -5
- package/packages/tui/lib/client.mjs +17 -1
- package/packages/tui/lib/config.mjs +7 -2
- package/packages/tui/lib/main.mjs +364 -82
- package/packages/tui/lib/model.mjs +614 -57
- package/packages/tui/lib/panel.mjs +436 -125
- package/packages/tui/lib/read.mjs +52 -26
- package/packages/tui/lib/store.mjs +1025 -65
- package/packages/tui/lib/term/keys.mjs +9 -2
- package/packages/tui/lib/term/text.mjs +4 -0
- package/packages/tui/lib/term/through.mjs +12 -1
- package/packages/tui/lib/views/capabilities.mjs +239 -0
- package/packages/tui/lib/views/frame.mjs +433 -99
- package/packages/tui/lib/views/help.mjs +61 -15
- package/packages/tui/lib/views/instances.mjs +43 -25
- package/packages/tui/lib/views/palette.mjs +66 -0
- package/packages/tui/lib/views/souls.mjs +270 -0
- package/packages/tui/lib/views/spawn.mjs +301 -0
- package/packages/tui/lib/views/split.mjs +29 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/** A capability row as both clients read it: the pure rules over `oats capabilities` rows, workspace
|
|
2
|
+
* status and the roster's module rows that the Desktop's Capabilities view and capability page draw
|
|
3
|
+
* from. Which source a row comes from and the group it sits in, the view's sections and search, who
|
|
4
|
+
* uses it ("Used by"), and a core capability's name. Nothing here makes DOM; nothing is resolved,
|
|
5
|
+
* joined across the non-collapse boundary, or inferred. */
|
|
6
|
+
|
|
7
|
+
const list = value => Array.isArray(value) ? value : [];
|
|
8
|
+
const text = value => typeof value === 'string' && value ? value : null;
|
|
9
|
+
/** A member's display name from workspace status; the key's tail otherwise. */
|
|
10
|
+
export function memberNames(status) {
|
|
11
|
+
const names = new Map();
|
|
12
|
+
for (const member of list(status?.members)) if (text(member.key)) names.set(member.key, text(member.name) || member.key.split('/').pop());
|
|
13
|
+
return names;
|
|
14
|
+
}
|
|
15
|
+
/** The source a capability row came from, in the kernel's own kind. */
|
|
16
|
+
export function capabilitySource(row, names = new Map()) {
|
|
17
|
+
if (row.kind === 'package') return { kind: 'package', key: `package:${row.package}`, label: text(row.package) || row.name };
|
|
18
|
+
if (row.kind === 'member') return { kind: 'member', key: `member:${row.repoKey}`, label: names.get(row.repoKey) || String(row.repoKey || '').split('/').pop() || 'member' };
|
|
19
|
+
return { kind: 'external', key: `external:${row.repoKey || row.origin}`, label: String(row.repoKey || row.origin || 'external').split('/').pop() };
|
|
20
|
+
}
|
|
21
|
+
/** Souls whose instances carry this capability as a recorded module, from
|
|
22
|
+
* the roster's own module rows; moved = the kernel reported drift. "Used by" before the kernel
|
|
23
|
+
* reported each soul's composition (souls-capabilities); soulsUsing is the rule with it. */
|
|
24
|
+
export function capabilityUse(instances, name) {
|
|
25
|
+
const souls = new Map(); let moved = 0;
|
|
26
|
+
for (const instance of list(instances)) {
|
|
27
|
+
const rows = Array.isArray(instance.modules) ? instance.modules : Object.entries(instance.modules || {}).map(([key, row]) => ({ name: key, ...row }));
|
|
28
|
+
const row = rows.find(module => module?.name === name);
|
|
29
|
+
if (!row) continue;
|
|
30
|
+
if (row.status === 'moved') moved++;
|
|
31
|
+
const soul = text(instance.agent);
|
|
32
|
+
if (soul && !souls.has(soul)) souls.set(soul, { name: soul, agentsRoot: instance.agentsRoot });
|
|
33
|
+
}
|
|
34
|
+
return { souls: [...souls.values()], moved };
|
|
35
|
+
}
|
|
36
|
+
/** The CLI feature under which every `oats souls` row reports its composed capabilities
|
|
37
|
+
* (deployment-data.mjs soulCapabilitiesOf): "Used by" is then the souls whose composition includes
|
|
38
|
+
* the capability, not only the souls whose live instances recorded it. */
|
|
39
|
+
export const SOULS_CAPABILITIES_FEATURE = 'souls-capabilities';
|
|
40
|
+
export const soulsComposition = cli => list(cli?.features).includes(SOULS_CAPABILITIES_FEATURE);
|
|
41
|
+
/** A soul's agent name in the roster (an instance's `agent`): a package soul's is the kernel's
|
|
42
|
+
* `<package>--<soul>`, the package id with every character outside [a-z0-9-] as '-'
|
|
43
|
+
* (lib/workspace.mjs packageSoulAgentName); every other soul's is its name. */
|
|
44
|
+
export function rosterAgentName(soul) {
|
|
45
|
+
if (soul?.soulKind === 'package' && text(soul.package)) return `${soul.package.replace(/[^a-z0-9-]/g, '-')}--${soul.name}`;
|
|
46
|
+
return soul?.name;
|
|
47
|
+
}
|
|
48
|
+
/** Whether a soul's composition entry is this catalog row: the same name, kind and origin (the repository
|
|
49
|
+
* for a member capability, the package for a package one). A repo-owned row matches the same way; an
|
|
50
|
+
* external row never does (the kernel reports no external entry). */
|
|
51
|
+
export function composes(entry, row) {
|
|
52
|
+
if (!entry || entry.name !== row?.name || entry.kind !== row.kind) return false;
|
|
53
|
+
return row.kind === 'package' ? !!text(row.package) && entry.package === row.package : !!text(row.repoKey) && entry.repoKey === row.repoKey;
|
|
54
|
+
}
|
|
55
|
+
/** The souls (the `oats souls` rows the Souls tab shows) whose composition includes this row; a soul that
|
|
56
|
+
* did not resolve (`capabilities: null`) is never counted. */
|
|
57
|
+
export function soulsUsing(souls, row) {
|
|
58
|
+
return list(souls).filter(soul => Array.isArray(soul?.capabilities) && soul.capabilities.some(entry => composes(entry, row)));
|
|
59
|
+
}
|
|
60
|
+
/** The repository group a member or external capability sits in, as the Souls tab groups souls:
|
|
61
|
+
* the workspace host's repository first, then the other members by name, then one "external"
|
|
62
|
+
* group for every source outside the member repos (a package, never listed here, keeps its own).
|
|
63
|
+
* `hostKey`: workspace status's workspace.key. */
|
|
64
|
+
export function capabilityGroup(row, names = new Map(), hostKey = null) {
|
|
65
|
+
const source = capabilitySource(row, names);
|
|
66
|
+
// A package group (the Packages section) names its pinned version: "package · v1.2.0".
|
|
67
|
+
if (source.kind === 'package') return { key: source.key, rank: 3, icon: 'package', name: source.label, note: ['package', text(row.version) ? `v${row.version}` : null].filter(Boolean).join(' · '), mono: true };
|
|
68
|
+
if (source.kind !== 'member') return { key: 'external', rank: 2, icon: 'external', name: 'external', note: 'not in a member repo', mono: false };
|
|
69
|
+
const host = !!hostKey && row.repoKey === hostKey;
|
|
70
|
+
return { key: source.key, rank: host ? 0 : 1, icon: 'repo', name: source.label, note: host ? 'member repo · host' : 'member repo', mono: true };
|
|
71
|
+
}
|
|
72
|
+
/** Rows in their repository groups, in the Souls tab's order: [{ key, rank, icon, name, note, mono, rows }]. */
|
|
73
|
+
export function groupCapabilities(rows, names = new Map(), hostKey = null) {
|
|
74
|
+
const groups = new Map();
|
|
75
|
+
for (const row of list(rows)) {
|
|
76
|
+
const group = capabilityGroup(row, names, hostKey);
|
|
77
|
+
if (!groups.has(group.key)) groups.set(group.key, { ...group, rows: [] });
|
|
78
|
+
groups.get(group.key).rows.push(row);
|
|
79
|
+
}
|
|
80
|
+
return [...groups.values()].sort((a, b) => a.rank - b.rank || a.name.localeCompare(b.name));
|
|
81
|
+
}
|
|
82
|
+
/** The workspace host's repository key, from workspace status (null when not reported). */
|
|
83
|
+
export const hostKeyOf = status => text(status?.workspace?.key);
|
|
84
|
+
/** The view search: capability names containing the query, case-insensitive. */
|
|
85
|
+
export function matchCapabilities(rows, query = '') {
|
|
86
|
+
const needle = String(query || '').trim().toLowerCase();
|
|
87
|
+
return needle ? list(rows).filter(row => String(row.name).toLowerCase().includes(needle)) : list(rows);
|
|
88
|
+
}
|
|
89
|
+
/** The Capabilities view's three sections, from the catalog rows' own facts:
|
|
90
|
+
* workspace owned (listed to every soul), packages, and repo owned (the
|
|
91
|
+
* kernel's private: true, usable only by that repository's souls). */
|
|
92
|
+
export function capabilitySections(rows) {
|
|
93
|
+
const all = list(rows);
|
|
94
|
+
return {
|
|
95
|
+
workspace: all.filter(row => row.kind !== 'package' && row.private !== true),
|
|
96
|
+
packages: all.filter(row => row.kind === 'package'),
|
|
97
|
+
repo: all.filter(row => row.kind !== 'package' && row.private === true),
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
const LAYERS = { knowledge: 'Knowledge', messaging: 'Messaging', tasks: 'Tasks' };
|
|
101
|
+
/** A core capability's name in the UI (Knowledge, Messaging, Tasks), else the layer verbatim. */
|
|
102
|
+
export const layerLabel = layer => LAYERS[layer] || layer;
|
|
103
|
+
|
|
104
|
+
/** An instance's recorded module row for a capability (its `modules`, a list or a map by name), or null. */
|
|
105
|
+
function moduleRow(instance, name) {
|
|
106
|
+
const rows = Array.isArray(instance.modules) ? instance.modules : Object.entries(instance.modules || {}).map(([key, row]) => ({ name: key, ...row }));
|
|
107
|
+
return rows.find(m => m?.name === name) || null;
|
|
108
|
+
}
|
|
109
|
+
/** "Used by" (the capability page's table): with `composition` (souls-capabilities) the souls whose composition
|
|
110
|
+
* includes the row (soulsUsing), before it the souls whose instances carry it (capabilityUse). Each with
|
|
111
|
+
* `carrying`, its instances that carry the module (the roster's agent name, a package soul's being
|
|
112
|
+
* `<package>--<soul>`, within the soul's agents root), and `behind`, how many of those report it moved. */
|
|
113
|
+
export function capabilityUsers(row, { souls, instances, composition } = {}) {
|
|
114
|
+
const users = composition ? soulsUsing(souls, row) : capabilityUse(instances, row.name).souls;
|
|
115
|
+
return users.map(soul => {
|
|
116
|
+
const agent = composition ? rosterAgentName(soul) : soul.name;
|
|
117
|
+
const carrying = list(instances).filter(i => i.agent === agent && i.agentsRoot === soul.agentsRoot && moduleRow(i, row.name));
|
|
118
|
+
const behind = carrying.filter(i => moduleRow(i, row.name)?.status === 'moved').length;
|
|
119
|
+
return { soul, carrying, behind };
|
|
120
|
+
});
|
|
121
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** The sentence of a failed catalog read (a held entry's `reason`), the same in every client and for
|
|
2
|
+
* every catalog a client shows: the souls (soul-catalog.mjs) and the capabilities
|
|
3
|
+
* (capability-catalog.mjs). The noun is one of those two, so no client words a third catalog its own
|
|
4
|
+
* way. The kernel's message in it is text from outside: a client draws it through its display
|
|
5
|
+
* filter. */
|
|
6
|
+
const NOUNS = Object.freeze(['souls', 'capabilities']);
|
|
7
|
+
|
|
8
|
+
export function catalogFailure(noun, reason) {
|
|
9
|
+
if (!NOUNS.includes(noun)) throw new TypeError(`catalogFailure: noun must be one of ${NOUNS.join(', ')}`);
|
|
10
|
+
const message = typeof reason?.message === 'string' && reason.message ? reason.message : '';
|
|
11
|
+
return message ? `Couldn't read this workspace's ${noun}: ${message}` : `Couldn't read this workspace's ${noun}.`;
|
|
12
|
+
}
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.61.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 61, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -8,6 +8,7 @@ import { teamRow, teamRowsOf, defaultTeamOf, TEAM_ID } from './team-rows.mjs';
|
|
|
8
8
|
import { launchOf, REPORT_FROM } from './launch-contract.mjs';
|
|
9
9
|
import { readIdentity } from './workspace-views.mjs';
|
|
10
10
|
import { waitingOnYouData } from './waiting-on-you.mjs';
|
|
11
|
+
import { retireData } from './retire-state.mjs';
|
|
11
12
|
const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
|
|
12
13
|
const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
|
|
13
14
|
const own = (value, key) => Object.hasOwn(value, key);
|
|
@@ -209,6 +210,9 @@ export function deploymentStatusData(document, deployment) {
|
|
|
209
210
|
if (own(instance, 'tmux')) row.tmux = instance.tmux === null ? null : fields(instance.tmux, ['session', 'window', 'socket']);
|
|
210
211
|
if (own(instance, 'sessionTarget')) row.sessionTarget = sessionTarget(instance.sessionTarget);
|
|
211
212
|
if (own(instance, 'retirePending')) row.retirePending = true;
|
|
213
|
+
// #1247 (feature status-retire-state): the retire that runs, or failed, or was interrupted. Validated, never
|
|
214
|
+
// check()ed: a value out of the contract is dropped and the row reads as if it had none.
|
|
215
|
+
if (own(instance, 'retire')) { const retire = retireData(instance.retire); if (retire) row.retire = retire; }
|
|
212
216
|
if (own(instance, 'rollbackIncomplete')) row.rollbackIncomplete = true;
|
|
213
217
|
// #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
|
|
214
218
|
// any other value is dropped, never checked: the row stays an ordinary one.
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
import { dirname } from 'node:path';
|
|
14
14
|
import { livenessOrigin } from './liveness.mjs';
|
|
15
15
|
import { knownOrigin, hasRuntimeError, byRuntimeState } from './instance-presentation.mjs';
|
|
16
|
+
import { retireData } from './retire-state.mjs';
|
|
16
17
|
|
|
17
18
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
18
19
|
|
|
@@ -98,6 +99,8 @@ export function panelInstance(i) {
|
|
|
98
99
|
...(i.modelFrom !== undefined ? { modelFrom: i.modelFrom } : {}),
|
|
99
100
|
...(i.identityAddress !== undefined ? { identityAddress: i.identityAddress } : {}),
|
|
100
101
|
...(i.retirePending ? { retirePending: true } : {}),
|
|
102
|
+
// #1247: the retire's state, validated again here (retire-state.mjs): a value out of the contract is absent.
|
|
103
|
+
...(retireData(i.retire) ? { retire: retireData(i.retire) } : {}),
|
|
101
104
|
...(i.rollbackIncomplete ? { rollbackIncomplete: true } : {}),
|
|
102
105
|
// #802: a spawn setting up its worktree (deployment-data.mjs keeps it as true only).
|
|
103
106
|
...(i.spawnInProgress === true ? { spawnInProgress: true } : {}),
|
|
@@ -2,10 +2,11 @@
|
|
|
2
2
|
* keys or its buttons from this answer: verbs and reasons, never a label, an icon or a key.
|
|
3
3
|
*
|
|
4
4
|
* instanceActs(instance) -> { blocked: Reason | null, limited: Reason | null, acts: Act[] }
|
|
5
|
-
* Act = { verb, enabled, reason: Reason | null }
|
|
5
|
+
* Act = { verb, enabled, reason: Reason | null, secondary? }
|
|
6
6
|
* Reason = { code, sentence } and, by code:
|
|
7
7
|
* { code: 'unaddressable', key, sentence, origin? } key: the row reason's own (remote-address.mjs rowReason)
|
|
8
|
-
* { code: 'held', kind, sentence }
|
|
8
|
+
* { code: 'held', kind, sentence, origin? } kind: instance-tree.mjs HELD_HOMES's: 'spawning' |
|
|
9
|
+
* 'spawn-incomplete' | 'retiring' | 'retire-failed' | 'retire-incomplete'
|
|
9
10
|
* { code: 'unsupported-session', sentence, origin? }
|
|
10
11
|
* { code: 'not-running', sentence } an `open` act's only (`openAct`)
|
|
11
12
|
* { code: 'state-unknown', sentence } an `open` act's only
|
|
@@ -19,7 +20,8 @@
|
|
|
19
20
|
* answer's `origin` is passed on as it is, never decided again here): "kernel", "terminal-probe" or
|
|
20
21
|
* "roster-read" when the row names the speaker of its `runtimeError`, "unattributed" when the row's text
|
|
21
22
|
* stands beside no speaker. It is absent on a sentence this home wrote and on the stand-in for an older
|
|
22
|
-
* kernel's Herdr row
|
|
23
|
+
* kernel's Herdr row. A `held` reason has one ("kernel") only for a failed retire whose row carries the
|
|
24
|
+
* kernel's message or code (#1247, instance-tree.mjs heldHome `said`). A client shows a sentence with an `origin`
|
|
23
25
|
* through its display filter, after instance-presentation.mjs `originLead`'s words when the value names
|
|
24
26
|
* a speaker, and a sentence with none as written, as this home's own.
|
|
25
27
|
*
|
|
@@ -29,10 +31,20 @@
|
|
|
29
31
|
* `blocked` and `limited` are never both set. An act's own `reason` says why that one act is listed
|
|
30
32
|
* and not enabled; the others stay as they are.
|
|
31
33
|
*
|
|
34
|
+
* `secondary: true` (#1247; absent otherwise): the act stays listed and enabled, behind its usual
|
|
35
|
+
* confirmation, but it is not the row's default or primary affordance. A client keeps it where the row's
|
|
36
|
+
* acts are listed (the Desktop's row menu, the TUI's key) and draws no inline primary control for it,
|
|
37
|
+
* never makes it the default act (the menu's first focus, a key's default) and does not advertise it
|
|
38
|
+
* (the TUI's footer). Only Retire on a retiring row is secondary: a second retire is safe (the kernel
|
|
39
|
+
* refuses it while one runs: E_INSTANCE_RETIRING, E_LIFECYCLE_BUSY) and, while the holder can't be read,
|
|
40
|
+
* may be the only way on.
|
|
41
|
+
*
|
|
32
42
|
* In order, the first that applies:
|
|
33
43
|
* a remote row the kernel does not report addressable blocked (unaddressable); no acts
|
|
34
44
|
* a home the kernel holds, spawning blocked (held); no acts
|
|
35
|
-
* a home the kernel holds,
|
|
45
|
+
* a home the kernel holds, retiring limited (held); retire (secondary)
|
|
46
|
+
* a home the kernel holds, spawn incomplete, limited (held); retire
|
|
47
|
+
* retire failed or incomplete
|
|
36
48
|
* a session backend OATS no longer has inspect, start (not enabled, unsupported-session), stop, retire
|
|
37
49
|
* running === true inspect, restart, stop, retire
|
|
38
50
|
* running === false inspect, start, stop, retire
|
|
@@ -54,7 +66,7 @@ import { heldHome } from './instance-tree.mjs';
|
|
|
54
66
|
import { unsupportedSession } from './instance-presentation.mjs';
|
|
55
67
|
import { canAddressRemote, rowReason } from './remote-address.mjs';
|
|
56
68
|
|
|
57
|
-
const act = (verb, reason = null) => ({ verb, enabled: !reason, reason });
|
|
69
|
+
const act = (verb, reason = null, secondary = false) => ({ verb, enabled: !reason, reason, ...(secondary ? { secondary: true } : {}) });
|
|
58
70
|
// An `open` act's own two codes, and the one sentence both carry.
|
|
59
71
|
const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown';
|
|
60
72
|
const NO_LIVE_TERMINAL = 'No live terminal is reported.';
|
|
@@ -65,11 +77,14 @@ export function instanceActs(instance) {
|
|
|
65
77
|
return { blocked: { code: 'unaddressable', key, sentence, ...(origin !== undefined ? { origin } : {}) }, limited: null, acts: [] };
|
|
66
78
|
}
|
|
67
79
|
// #802: a home the kernel holds starts, stops and opens nothing. Retire only when a spawn or a retire left it
|
|
68
|
-
// half cleaned (the kernel's retire completes it), nothing while its spawn sets up the worktree
|
|
80
|
+
// half cleaned (the kernel's retire completes it), nothing while its spawn sets up the worktree; while a
|
|
81
|
+
// retire runs (#1247), Retire stays reachable but secondary.
|
|
69
82
|
const held = heldHome(instance);
|
|
70
83
|
if (held) {
|
|
71
|
-
const
|
|
72
|
-
|
|
84
|
+
const { sentence, origin } = held.said;
|
|
85
|
+
const reason = { code: 'held', kind: held.kind, sentence, ...(origin !== undefined ? { origin } : {}) };
|
|
86
|
+
return held.retire ? { blocked: null, limited: reason, acts: [act('retire', null, held.retire === 'secondary')] }
|
|
87
|
+
: { blocked: reason, limited: null, acts: [] };
|
|
73
88
|
}
|
|
74
89
|
// A Herdr-recorded row cannot start or restart: Start stays listed, not enabled, with the kernel's reason.
|
|
75
90
|
// Its sentence and its `origin` are the row reason's own (rowReason answers this reason first for such a row).
|
|
@@ -6,10 +6,11 @@ export function runtimeState(instance) {
|
|
|
6
6
|
}
|
|
7
7
|
|
|
8
8
|
const RUNTIME_ORDER = Object.freeze({ running: 0, unknown: 1, stopped: 2 });
|
|
9
|
-
/** The
|
|
9
|
+
/** The panel's runtime order, a comparator for `sort`: running, then unknown (`running` null or anything not
|
|
10
10
|
* a boolean: it may be running, so it stands above the rows nobody needs to watch), then stopped; by name
|
|
11
11
|
* within each. Each row's place depends on that row alone, so it is a total order whatever `running` holds.
|
|
12
|
-
* Read by `
|
|
12
|
+
* Read by `panelInstances` (deployment-panel.mjs). The sidebar's roster orders by name (instance-tree.mjs
|
|
13
|
+
* `rosterOrder`, #1262). */
|
|
13
14
|
export function byRuntimeState(a, b) {
|
|
14
15
|
return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
|
|
15
16
|
}
|
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
* no element: a client draws from these answers with its own means. */
|
|
5
5
|
import { waitingClaim } from './waiting-on-you.mjs';
|
|
6
6
|
import { byRuntimeState } from './instance-presentation.mjs';
|
|
7
|
+
import { retireData } from './retire-state.mjs';
|
|
8
|
+
import { displayLine } from './display-text.mjs';
|
|
7
9
|
|
|
8
10
|
export function collapseKey(workspace, instance) {
|
|
9
11
|
return `${workspace || ""}\u0000${instance}`;
|
|
@@ -54,6 +56,15 @@ export function resolveLinkId(fromInstance, name, byName) {
|
|
|
54
56
|
return sameRoot.length === 1 ? instanceId(sameRoot[0]) : null;
|
|
55
57
|
}
|
|
56
58
|
|
|
59
|
+
/** The roster's order, a comparator for `sort`: by instance name, ties broken by `instanceId`, so it is total and
|
|
60
|
+
* deterministic. It ranks roots, siblings under one parent, and so clusters (by their first root). A start or a
|
|
61
|
+
* stop moves no row; only adding or removing one does (Pepe's decision on #1262, comment 6196531154, which
|
|
62
|
+
* replaces #1083's running-first order for the roster). The one place the roster's order is decided. */
|
|
63
|
+
function rosterOrder(a, b) {
|
|
64
|
+
const ia = instanceId(a), ib = instanceId(b);
|
|
65
|
+
return String(a.instance).localeCompare(String(b.instance)) || (ia < ib ? -1 : ia > ib ? 1 : 0);
|
|
66
|
+
}
|
|
67
|
+
|
|
57
68
|
/** Group instances into agent CLUSTERS — connected components of the
|
|
58
69
|
* undirected relation graph (parent/child spawn edges + sibling links).
|
|
59
70
|
* Unrelated instances are single-node clusters. Within a cluster the
|
|
@@ -62,7 +73,9 @@ export function resolveLinkId(fromInstance, name, byName) {
|
|
|
62
73
|
* Nodes are keyed by instanceId (composite identity), never bare name —
|
|
63
74
|
* duplicate names across repos render as distinct nodes.
|
|
64
75
|
* Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
|
|
65
|
-
* their first
|
|
76
|
+
* their first ROOT in the roster's order (`rosterOrder`), never by another member (#1262): a bundle sits where
|
|
77
|
+
* its root sits, and gaining or losing a child, or a start or a stop, moves nothing. A cluster without a root
|
|
78
|
+
* (a malformed cycle) ranks by its first member in that order. */
|
|
66
79
|
export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
67
80
|
const byId = new Map(instances.map((i) => [instanceId(i), i]));
|
|
68
81
|
const byName = new Map();
|
|
@@ -86,7 +99,7 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
|
86
99
|
adj.get(oid).add(id);
|
|
87
100
|
}
|
|
88
101
|
}
|
|
89
|
-
const rank =
|
|
102
|
+
const rank = rosterOrder;
|
|
90
103
|
const seen = new Set();
|
|
91
104
|
const clusters = [];
|
|
92
105
|
for (const start of [...instances].sort(rank)) {
|
|
@@ -122,11 +135,12 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
|
122
135
|
// Deterministic cluster label: the lexically-smallest ROOT name —
|
|
123
136
|
// independent of liveness, so the visible cluster name does not flip
|
|
124
137
|
// when a different member starts/stops running (review f921f7d nit).
|
|
125
|
-
// `rank` (
|
|
138
|
+
// `rank` (rosterOrder: by name) governs display ORDER within the cluster.
|
|
126
139
|
const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
|
|
127
|
-
clusters.push({ key: rootNames[0], instances: ordered });
|
|
140
|
+
clusters.push({ key: rootNames[0], instances: ordered, head: roots[0] ?? [...members].sort(rank)[0] });
|
|
128
141
|
}
|
|
129
|
-
|
|
142
|
+
// Stable: clusters whose heads rank equal keep the order they were found in (the roster's order of members).
|
|
143
|
+
return clusters.sort((a, b) => rank(a.head, b.head)).map(({ head: _head, ...c }) => c);
|
|
130
144
|
}
|
|
131
145
|
|
|
132
146
|
/** Find the roster instance a UI reference means. References carry the
|
|
@@ -214,22 +228,52 @@ const HELD_HOMES = Object.freeze({
|
|
|
214
228
|
sentence: name => `${name} is setting up its worktree. It can't be used until the spawn finishes.` },
|
|
215
229
|
"spawn-incomplete": { state: "Spawn didn't finish", hint: "Retire it to clean up", status: "Spawn didn't finish", retire: true,
|
|
216
230
|
sentence: name => `The spawn of ${name} didn't finish. Retire it to clean up.` },
|
|
231
|
+
// #1247: a retire that runs (or whose holder's liveness can't be read): Retire stays offered, secondary.
|
|
232
|
+
retiring: { state: "Retiring…", status: "Retiring…", retire: "secondary",
|
|
233
|
+
sentence: name => `${name} is being retired.` },
|
|
234
|
+
"retire-failed": { state: "Retire failed", hint: "Retire it again to finish", status: "Retire failed", retire: true,
|
|
235
|
+
sentence: name => `The retire of ${name} failed. Retire it again to finish.` },
|
|
217
236
|
"retire-incomplete": { state: "Retire didn't finish", hint: "Retire it again to complete", status: "Retire didn't finish", retire: true,
|
|
218
237
|
sentence: name => `The retire of ${name} didn't finish. Retire it again to complete.` },
|
|
219
238
|
});
|
|
220
|
-
/**
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
239
|
+
/** Which retire kind a row's kernel facts are (#1247), or null: the kernel's `retire` (retire-state.mjs, read
|
|
240
|
+
* again here: a value out of the contract is absent); a row with no `retire` but `retirePending` (a kernel or a
|
|
241
|
+
* host before `status-retire-state`) reads `retiring`. */
|
|
242
|
+
function retireKind(instance) {
|
|
243
|
+
const retire = retireData(instance.retire);
|
|
244
|
+
if (retire) return retire.state === "failed" ? "retire-failed" : retire.state === "interrupted" ? "retire-incomplete" : "retiring";
|
|
245
|
+
return instance.retirePending ? "retiring" : null;
|
|
246
|
+
}
|
|
247
|
+
/** What the kernel's roster row says holds this home, or null (#802, #1247): `spawning` while a spawn
|
|
248
|
+
* that runs its worktree hooks is verifiably alive (`spawnInProgress: true`), `spawn-incomplete` when a
|
|
249
|
+
* spawn left it for retire to clean up (`rollbackIncomplete`); then the retire kinds (`retireKind`):
|
|
250
|
+
* `retiring` while a retire runs, its holder can't be read, the row is an older kernel's `retirePending`
|
|
251
|
+
* or this client's own retire is in flight; `retire-failed` when a self-retire's completion recorded an
|
|
252
|
+
* error; `retire-incomplete` when a scheduled completion is gone without an outcome. A retire this client
|
|
253
|
+
* started and has not read the roster after (retire-in-flight.mjs `retireInFlight`) is `retiring` whatever
|
|
254
|
+
* the row says: it is the newest fact, and the kernel refuses it (letting the row go) where a live spawn
|
|
255
|
+
* holds the home. Of the kernel's facts, rollbackIncomplete wins over spawnInProgress (the spawn is gone,
|
|
256
|
+
* not live), and a live spawn over a retire (the kernel refuses to retire it). Every surface draws such a row from this: a spawning or retiring one starts,
|
|
257
|
+
* stops, restarts and opens nothing new; one with `retire` offers Retire only, and `retire: "secondary"`
|
|
258
|
+
* (retiring: a second retire is refused while one runs, and safe) offers it out of the way (instance-acts.mjs).
|
|
259
|
+
* `state` is the row's text, `hint` its muted line (none while retiring), `status` the hover card's Status.
|
|
260
|
+
* `sentence` is every client's, so it promises no act of one client: a spawning home "can't be used until
|
|
261
|
+
* the spawn finishes", whoever started the spawn and whether or not it ends finished. `said` is what the
|
|
262
|
+
* row's reason says (instance-acts.mjs): the sentence, or for a failed retire with a recorded message or code the
|
|
263
|
+
* kernel's words (`message`, `code`, or `message (code)`) with `origin: "kernel"`, shown only through the display
|
|
264
|
+
* filter. */
|
|
229
265
|
export function heldHome(instance) {
|
|
230
|
-
const kind = !instance ? null : instance.rollbackIncomplete ? "spawn-incomplete"
|
|
231
|
-
: instance.spawnInProgress === true ? "spawning" : instance
|
|
232
|
-
|
|
266
|
+
const kind = !instance ? null : instance.retireInFlight === true ? "retiring" : instance.rollbackIncomplete ? "spawn-incomplete"
|
|
267
|
+
: instance.spawnInProgress === true ? "spawning" : retireKind(instance);
|
|
268
|
+
if (!kind) return null;
|
|
269
|
+
const held = HELD_HOMES[kind], retire = kind === "retire-failed" ? retireData(instance.retire) : null;
|
|
270
|
+
// The kernel's words, message or code, are said as the kernel's, and shown only through the display filter; one the
|
|
271
|
+
// filter reduces to nothing (blank) says nothing; one it withholds is said, and shown withheld. With neither, the row's own words stand.
|
|
272
|
+
const shown = text => (text && displayLine(text) !== null ? text : null);
|
|
273
|
+
const message = shown(retire?.message), code = shown(retire?.code);
|
|
274
|
+
const said = message || code ? { sentence: message && code ? `${message} (${code})` : message || code, origin: "kernel" }
|
|
275
|
+
: { sentence: held.sentence(instance.instance) };
|
|
276
|
+
return { kind, ...held, said };
|
|
233
277
|
}
|
|
234
278
|
|
|
235
279
|
/* ── roster grouping: repo → agent family (soul), with sort modes ── */
|
|
@@ -239,9 +283,8 @@ export const ROSTER_SORTS = Object.freeze([
|
|
|
239
283
|
Object.freeze({ id: "name", label: "Name" }),
|
|
240
284
|
]);
|
|
241
285
|
|
|
242
|
-
/** Comparator for one sibling level. "status" is
|
|
243
|
-
*
|
|
244
|
-
* alphabetical. Unknown ids fall back to "status" so a stale persisted choice
|
|
286
|
+
/** Comparator for one sibling level. "status" is `byRuntimeState` (running, unknown, stopped, then by name:
|
|
287
|
+
* #1083's order, which the roster no longer uses, #1262); "name" is purely alphabetical. No client calls it. Unknown ids fall back to "status" so a stale persisted choice
|
|
245
288
|
* can never break rendering. */
|
|
246
289
|
export function rosterRank(sortBy) {
|
|
247
290
|
const byName = (a, b) => String(a.instance).localeCompare(String(b.instance));
|
|
@@ -355,30 +398,32 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
|
|
|
355
398
|
.filter((c) => c.instances.length);
|
|
356
399
|
}
|
|
357
400
|
|
|
358
|
-
/** The sidebar roster's groups (Redesign v3), shared with the command palette:
|
|
359
|
-
* each multi-member relation cluster under its deterministic name,
|
|
360
|
-
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
363
|
-
*
|
|
364
|
-
*
|
|
365
|
-
*
|
|
366
|
-
*
|
|
367
|
-
*
|
|
368
|
-
* is visible: the label is the name, the key adds the cluster's place among the
|
|
369
|
-
* multi-member clusters of the full roster. */
|
|
401
|
+
/** The sidebar roster's groups (Redesign v3), shared with the command palette and the TUI: the full roster's
|
|
402
|
+
* clusters in their one order (#1262), each multi-member relation cluster a group under its deterministic name,
|
|
403
|
+
* and each RUN of consecutive single-instance clusters one "independent" group, in place. So an instance that
|
|
404
|
+
* gains its first child stays where it was and becomes a group there; losing its last child, it rejoins the run
|
|
405
|
+
* at the same place. A cluster's group is decided on the FULL roster: a filter or a collapse decides which rows
|
|
406
|
+
* are listed and never moves a row to another group; a group with no visible row is left out. Returns
|
|
407
|
+
* [{ key, label, clusters: [{ key, instances }] }], each cluster projected to its visible members, which carry
|
|
408
|
+
* their tree depth. A group's key is unique even when two roots share a name (other agents roots or hosts), and
|
|
409
|
+
* does not depend on what is visible: a cluster's is `cluster:<its place among the full roster's multi-member
|
|
410
|
+
* clusters>:<name>`, a run's `independent:<instanceId of its first member in the full roster>`. */
|
|
370
411
|
export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks } = {}) {
|
|
371
412
|
const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
|
|
372
|
-
const
|
|
373
|
-
let place = 0;
|
|
413
|
+
const groups = [];
|
|
414
|
+
let place = 0, run = null;
|
|
374
415
|
for (const c of clusterInstances(allInstances, { links })) {
|
|
375
|
-
const at = c.instances.length > 1 ? place++ : -1;
|
|
376
416
|
const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
|
|
377
|
-
if (
|
|
378
|
-
|
|
379
|
-
|
|
417
|
+
if (c.instances.length > 1) {
|
|
418
|
+
run = null;
|
|
419
|
+
const at = place++;
|
|
420
|
+
if (shown.instances.length) groups.push({ key: `cluster:${at}:${c.key}`, label: c.key, clusters: [shown] });
|
|
421
|
+
continue;
|
|
422
|
+
}
|
|
423
|
+
if (!run) { run = { key: `independent:${instanceId(c.instances[0])}`, label: "independent", clusters: [] }; groups.push(run); }
|
|
424
|
+
if (shown.instances.length) run.clusters.push(shown);
|
|
380
425
|
}
|
|
381
|
-
return
|
|
426
|
+
return groups.filter((g) => g.clusters.length);
|
|
382
427
|
}
|
|
383
428
|
|
|
384
429
|
/** Whether an item remains visible under VS Code-style collapsed ancestors.
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
* { type: 'rows', rows: [{ text, quote? }] } a stop's results or a retire's children
|
|
29
29
|
* { type: 'lines', lines: [{ text, path? }] } what a retire did
|
|
30
30
|
* applyRunningSentence(running, terms) -> the sentence for an apply of this client that is still running
|
|
31
|
-
* createLifecycleConfirmation({ request, target, operation, terms, onSettled, onChange, label, leftover })
|
|
31
|
+
* createLifecycleConfirmation({ request, target, operation, terms, onSettled, onChange, label, leftover, retires })
|
|
32
32
|
* -> { state(), view(), setChoice(id, value), refresh(), apply(), checkAgain(), close() }
|
|
33
33
|
*/
|
|
34
34
|
import { lifecyclePlan, lifecycleOptions, planReference, lifecycleReason, lifecycleDetailCode, publicLifecycleReceipt, decodedStoppedTargets,
|
|
@@ -325,8 +325,11 @@ const SETTLED_OFFERS = Object.freeze({ complete: ['close'], partial: ['refresh',
|
|
|
325
325
|
* `onSettled(result, target)` is called once for every apply answer that reads and is not a return to review;
|
|
326
326
|
* what it does or throws changes nothing here. `label`: the server's label for a routed row; `leftover`: the row
|
|
327
327
|
* is a home a failed spawn left. Each step carries this confirmation's latest-intent token: an answer to an
|
|
328
|
-
* earlier step, or one after close, changes nothing and is not told. Nothing is kept beyond the instance.
|
|
329
|
-
|
|
328
|
+
* earlier step, or one after close, changes nothing and is not told. Nothing is kept beyond the instance.
|
|
329
|
+
* `retires` (#1247): the client's retires in flight (retire-in-flight.mjs). Every apply of a retire is begun
|
|
330
|
+
* there before it is sent and settled with its answer's kind, whether or not the confirmation is still open
|
|
331
|
+
* or that answer is still the latest: the row reads Retiring… from the send until the roster was read after it. */
|
|
332
|
+
export function createLifecycleConfirmation({ request, target, operation, terms, onSettled = () => {}, onChange = () => {}, label = null, leftover = false, choices: initial = null, retires = null } = {}) {
|
|
330
333
|
requireTerms(terms, 'createLifecycleConfirmation');
|
|
331
334
|
if (typeof request !== 'function' || !target?.instance || !['stop', 'retire'].includes(operation)) throw new TypeError('createLifecycleConfirmation: a request, a target and an operation (stop or retire)');
|
|
332
335
|
let choices = lifecycleOptions(operation, initial) ?? (operation === 'stop' ? { recursive: true } : { discardWorktree: false });
|
|
@@ -372,9 +375,12 @@ export function createLifecycleConfirmation({ request, target, operation, terms,
|
|
|
372
375
|
current = { kind: 'applying', title: `${operation === 'retire' ? 'Retiring' : 'Stopping'} ${target.instance}…`,
|
|
373
376
|
message: operation === 'retire' ? `Retiring ${target.instance}. This can take up to a minute while sessions stop.` : `Stopping ${target.instance}. This can take up to a minute.` };
|
|
374
377
|
tell('applying', { view: current });
|
|
378
|
+
let own = null;
|
|
379
|
+
if (operation === 'retire') { try { own = retires?.begin(target) ?? null; } catch { /* the hold is a drawing aid only */ } }
|
|
375
380
|
let result = null, view;
|
|
376
381
|
try { result = await request({ action: 'apply', planRef: reference }); view = outcomeView(result, { target, operation, choices, plan: snapshot, leftover }, terms); }
|
|
377
382
|
catch { view = outcomeView(null, { target, operation, choices, plan: snapshot, leftover }, terms); }
|
|
383
|
+
try { own?.settle(view.kind); } catch { /* as above */ }
|
|
378
384
|
if (mine !== ticket || closed) return;
|
|
379
385
|
if (view.kind === 'stale') {
|
|
380
386
|
plan = view.plan; planRef = view.planRef; shown = view.plan; notice = view.notice; phase = 'review';
|
|
@@ -2,6 +2,7 @@ import { harnessOf } from "./harness-names.mjs";
|
|
|
2
2
|
import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
|
|
3
3
|
import { madeByKernel } from "./kernel-made.mjs";
|
|
4
4
|
import { waitingOnYouData } from "./waiting-on-you.mjs";
|
|
5
|
+
import { retireData } from "./retire-state.mjs";
|
|
5
6
|
import { readIdentity } from "./workspace-views.mjs";
|
|
6
7
|
/** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
|
|
7
8
|
export function remoteWorkspace(group) {
|
|
@@ -43,7 +44,7 @@ export function remotePanel(group, at) {
|
|
|
43
44
|
// A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
|
|
44
45
|
const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
|
|
45
46
|
// A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
|
|
46
|
-
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, ...i }) => {
|
|
47
|
+
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, ...i }) => {
|
|
47
48
|
const unsupported = unsupportedSession(i);
|
|
48
49
|
const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
|
|
49
50
|
const row = {
|
|
@@ -58,6 +59,8 @@ export function remotePanel(group, at) {
|
|
|
58
59
|
tmux: i.tmux || null, git: i.git || null, task: i.task || "", next: i.next || "",
|
|
59
60
|
// Needs input: only a remote kernel with the feature reports it — validated, never synthesized when absent.
|
|
60
61
|
...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
|
|
62
|
+
// #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
|
|
63
|
+
...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
|
|
61
64
|
...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
|
|
62
65
|
};
|
|
63
66
|
return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/** Retires this client started, read as Retiring… before the roster says so (#1247). One per client: the
|
|
2
|
+
* Desktop's window and the TUI's run each keep one, and their lifecycle confirmations tell it
|
|
3
|
+
* (lifecycle-confirmation.mjs `retires`).
|
|
4
|
+
*
|
|
5
|
+
* createRetiresInFlight({ mark, onChange }) -> { begin, landed, ids, holds }
|
|
6
|
+
* mark() the client's read mark now: a value that grows with every roster read the client
|
|
7
|
+
* begins (a counter, a clock); compared with `>` only
|
|
8
|
+
* onChange() the set changed: the client draws its rows again
|
|
9
|
+
* begin(target) an apply of a retire of `target` (a row's identity: server and home) starts. The row
|
|
10
|
+
* is held from now. Answers `{ settle(kind) }`, for the apply's answer: an outcome kind
|
|
11
|
+
* of lifecycle-confirmation.mjs `outcomeView`
|
|
12
|
+
* landed(at, covers?) an owned roster read the client began at mark `at` was read. A held row whose
|
|
13
|
+
* retire has answered, and whose answer came before that read began, is let go, when
|
|
14
|
+
* `covers(target)` says this read covers its row (default: every row)
|
|
15
|
+
* ids() the held rows' instanceIds
|
|
16
|
+
* holds(row) whether `row` is held
|
|
17
|
+
*
|
|
18
|
+
* retiringRows(rows, ids) -> rows, each held one copied with `retireInFlight: true`
|
|
19
|
+
*
|
|
20
|
+
* A row is held from the moment an apply starts until its answer is in and the roster was read after it, and
|
|
21
|
+
* while any other apply of a retire of it is held (a second Retire, offered while one runs, is one).
|
|
22
|
+
* An answer that ran nothing (a refusal, `refused`; a plan that changed under it, `stale`) lets its apply go at
|
|
23
|
+
* once: with no other apply held, the row reads again as the roster says. Any other answer (complete, partial, unknown, pending, unreadable)
|
|
24
|
+
* holds it until a read: that read says what the retire left. instance-tree.mjs `heldHome` reads
|
|
25
|
+
* `retireInFlight` as `retiring`. Nothing is kept beyond the client's run. */
|
|
26
|
+
import { instanceId } from './instance-tree.mjs';
|
|
27
|
+
|
|
28
|
+
const RAN_NOTHING = new Set(['refused', 'stale']);
|
|
29
|
+
|
|
30
|
+
export function createRetiresInFlight({ mark, onChange = () => {} } = {}) {
|
|
31
|
+
if (typeof mark !== 'function') throw new TypeError('createRetiresInFlight: a mark of the client\'s roster reads');
|
|
32
|
+
// instanceId -> { target, applies }: every apply of a retire of that row, each `{ settled, after }`. The row is
|
|
33
|
+
// held while any one holds it, so an answer to a later apply (a refusal: one is still running) never lets go
|
|
34
|
+
// of an earlier one that has not answered or was not read after.
|
|
35
|
+
const held = new Map();
|
|
36
|
+
const changed = () => { try { onChange(); } catch { /* a client's drawing changes nothing here */ } };
|
|
37
|
+
const drop = (id, entry, apply) => { entry.applies.delete(apply); if (!entry.applies.size && held.get(id) === entry) held.delete(id); };
|
|
38
|
+
return {
|
|
39
|
+
begin(target) {
|
|
40
|
+
const id = instanceId(target), entry = held.get(id) ?? { target, applies: new Set() }, apply = { settled: false, after: undefined };
|
|
41
|
+
entry.applies.add(apply); held.set(id, entry); changed();
|
|
42
|
+
return {
|
|
43
|
+
settle(kind) {
|
|
44
|
+
if (apply.settled || !entry.applies.has(apply)) return;
|
|
45
|
+
apply.settled = true;
|
|
46
|
+
if (RAN_NOTHING.has(kind)) { drop(id, entry, apply); changed(); } else apply.after = mark();
|
|
47
|
+
},
|
|
48
|
+
};
|
|
49
|
+
},
|
|
50
|
+
landed(at, covers = () => true) {
|
|
51
|
+
const before = held.size;
|
|
52
|
+
for (const [id, entry] of held) {
|
|
53
|
+
if (!covers(entry.target)) continue;
|
|
54
|
+
for (const apply of [...entry.applies]) if (apply.settled && at > apply.after) drop(id, entry, apply);
|
|
55
|
+
}
|
|
56
|
+
if (held.size !== before) changed();
|
|
57
|
+
},
|
|
58
|
+
ids: () => new Set(held.keys()),
|
|
59
|
+
holds: row => !!row && held.has(instanceId(row)),
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function retiringRows(rows, ids) {
|
|
64
|
+
return ids?.size ? rows.map(row => ids.has(instanceId(row)) ? { ...row, retireInFlight: true } : row) : rows;
|
|
65
|
+
}
|