pi-legion 5.0.1 → 5.2.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/CHANGELOG.md +858 -0
- package/CONTRIBUTING.md +33 -2
- package/README.md +10 -5
- package/agents/centurion.md +32 -7
- package/agents/scout.md +11 -0
- package/docs/contracts/abort-soft-interrupt-v1.md +162 -0
- package/docs/contracts/centurion-declared-phases-v1.md +104 -0
- package/docs/contracts/declarative-phase-machine-v5.md +43 -0
- package/docs/contracts/extension-inheritance-wiring-v1.md +88 -0
- package/docs/contracts/finished-cache-eviction-v1.md +169 -0
- package/docs/contracts/galaxy-scratch-v1.md +78 -0
- package/docs/contracts/legion-chart-frame-buckets-v1.md +201 -0
- package/docs/contracts/legion-main-screen-mount-v1.md +161 -0
- package/docs/contracts/legion-page-floor-v1.md +129 -0
- package/docs/contracts/legion-session-continuity-v1.md +118 -0
- package/docs/contracts/mailbox-delivery-v1.md +162 -0
- package/docs/contracts/notice-claim-v1.md +206 -0
- package/docs/contracts/partial-failure-exit-v1.md +235 -0
- package/docs/contracts/proc-sweep-v1.md +107 -0
- package/docs/contracts/provider-empty-generation-retry-v1.md +161 -0
- package/docs/contracts/stall-visibility-v1.md +218 -0
- package/docs/contracts/subagent-renewal-v1.md +5 -3
- package/docs/contracts/vexillatio-nonblocking-launch-v1.md +1 -0
- package/docs/contracts/viz-frame-alloc-v1.md +123 -0
- package/docs/contracts/wait-mail-preempt-v1.md +117 -0
- package/docs/contracts/wait-not-stop.md +1 -1
- package/docs/design.md +4 -1
- package/docs/inprocess-supervisor.md +9 -3
- package/docs/legion-v2-contract.md +122 -20
- package/docs/vexillatio-contract.md +5 -1
- package/index.ts +1903 -130
- package/package.json +5 -5
- package/skills/pi-legion/SKILL.md +2 -1
- package/src/agents/agents.ts +26 -1
- package/src/agents/settings.ts +67 -2
- package/src/api.ts +17 -0
- package/src/extension/child-guard.ts +2 -1
- package/src/extension/join.ts +54 -0
- package/src/extension/legion-commands.ts +15 -4
- package/src/extension/legion-doctor.ts +48 -6
- package/src/extension/legion-status.ts +44 -2
- package/src/extension/legion-tools.ts +1044 -109
- package/src/extension/notify.ts +31 -2
- package/src/extension/playbook.ts +6 -3
- package/src/extension/runtime.ts +882 -81
- package/src/extension/spawn-hints.ts +52 -12
- package/src/extension/summary.ts +7 -15
- package/src/extension/timing.ts +4 -15
- package/src/legion/db.ts +23 -1
- package/src/legion/events.ts +7 -0
- package/src/legion/interrupt.ts +98 -0
- package/src/legion/mail-release.ts +266 -0
- package/src/legion/mail.ts +456 -29
- package/src/legion/nodes.ts +31 -0
- package/src/legion/phase-conditions.ts +7 -1
- package/src/legion/phase-machine.ts +160 -8
- package/src/legion/state-machine.ts +34 -2
- package/src/runs/acceptance.ts +105 -6
- package/src/runs/args.ts +16 -0
- package/src/runs/child-scope.ts +323 -0
- package/src/runs/extension-inheritance.ts +145 -19
- package/src/runs/orchestrator.ts +613 -55
- package/src/runs/store.ts +149 -5
- package/src/shared/proc-sweep.ts +317 -0
- package/src/shared/progress.ts +11 -2
- package/src/shared/session-map.ts +29 -0
- package/src/shared/session.ts +308 -6
- package/src/shared/types.ts +34 -0
- package/src/supervisor/inprocess-supervisor.ts +158 -12
- package/src/supervisor/race-timeout.ts +55 -0
- package/src/supervisor/routing-supervisor.ts +55 -4
- package/src/supervisor/rpc-supervisor.ts +215 -29
- package/src/supervisor/types.ts +439 -2
- package/src/tui/status.ts +2 -1
- package/src/tui/viz/canvas.ts +358 -36
- package/src/tui/viz/palette.ts +18 -2
- package/src/tui/viz/panels.ts +507 -104
- package/src/tui/viz/rate.ts +120 -15
- package/src/tui/viz/view.ts +72 -4
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One name, one scope (#312).
|
|
3
|
+
*
|
|
4
|
+
* Child names are resolved in four different places — `status`, `collect`,
|
|
5
|
+
* `stop`, `continue` — and before this module each one had its own idea of what
|
|
6
|
+
* a name means:
|
|
7
|
+
*
|
|
8
|
+
* - `status` went through {@link pickChildByName}, which walks EVERY run in
|
|
9
|
+
* the store and prefers a live record and then the newest `createdAt`, so a
|
|
10
|
+
* name could resolve to a node in another session's run;
|
|
11
|
+
* - `collect` acted on the orchestrator's own children map, i.e. only the
|
|
12
|
+
* direct children of one run.
|
|
13
|
+
*
|
|
14
|
+
* Same name, adjacent calls, two different nodes — and neither path ever
|
|
15
|
+
* reported the disagreement. The reported incident collected a *successful*
|
|
16
|
+
* demo child while the parent was trying to collect a *failed* one, and `stop`
|
|
17
|
+
* masked the whole thing as `No non-retired children to stop.`
|
|
18
|
+
*
|
|
19
|
+
* The fix is one resolution order, shared by all four callers:
|
|
20
|
+
*
|
|
21
|
+
* 1. the direct children of the current run win, always, and silently — the
|
|
22
|
+
* common case must not grow a new line of noise;
|
|
23
|
+
* 2. otherwise the same name may exist in other runs: exactly one candidate is
|
|
24
|
+
* a *reportable* answer (the caller decides whether that is enough to act
|
|
25
|
+
* on, or only to show);
|
|
26
|
+
* 3. two or more candidates are an ambiguity, never a guess.
|
|
27
|
+
*
|
|
28
|
+
* `direct` and `scan` are injected so this module stays free of store/runtime
|
|
29
|
+
* imports: it is the pure rule, and the two data sources are the caller's.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
import type { ChildRecord, RunRecord } from "../shared/types.ts";
|
|
33
|
+
|
|
34
|
+
/** One same-named node found outside the current run. */
|
|
35
|
+
export interface ChildScopeCandidate {
|
|
36
|
+
runId: string;
|
|
37
|
+
nodeId?: string;
|
|
38
|
+
state: string;
|
|
39
|
+
sessionFile?: string;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* What a name resolved to.
|
|
44
|
+
*
|
|
45
|
+
* - `direct`: this run's own child. Nothing is said about it beyond that.
|
|
46
|
+
* - `elsewhere`: not a direct child; `candidates` is what the name matched
|
|
47
|
+
* elsewhere. `length === 1` is unambiguous — show or act on it, but say so.
|
|
48
|
+
* `length >= 2` is an ambiguity the caller must report instead of picking.
|
|
49
|
+
* - `absent`: the name exists nowhere the caller can see.
|
|
50
|
+
*/
|
|
51
|
+
export type ChildScopeHit =
|
|
52
|
+
| { kind: "direct"; name: string; child: ChildRecord }
|
|
53
|
+
| { kind: "elsewhere"; name: string; candidates: ChildScopeCandidate[] }
|
|
54
|
+
| { kind: "absent"; name: string; candidates: [] };
|
|
55
|
+
|
|
56
|
+
/** One node the caller may scan, with the run it lives in. */
|
|
57
|
+
export interface ChildScopeScanEntry extends ChildScopeCandidate {
|
|
58
|
+
name: string;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* The node a resolution answered with, plus the run that holds it.
|
|
63
|
+
*
|
|
64
|
+
* Same shape `findChild` / `findChildAcrossStores` answer with, so a caller does
|
|
65
|
+
* not care which of them resolved it.
|
|
66
|
+
*/
|
|
67
|
+
export interface ScopedRunChild {
|
|
68
|
+
runId: string;
|
|
69
|
+
run: RunRecord;
|
|
70
|
+
child: ChildRecord;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function resolveChildScope(input: {
|
|
74
|
+
name: string;
|
|
75
|
+
/**
|
|
76
|
+
* Explicit scope from the tool call. When present only that run is scanned,
|
|
77
|
+
* so a caller can address a node by `runId` even when the name repeats.
|
|
78
|
+
*/
|
|
79
|
+
runId?: string;
|
|
80
|
+
/** This run's own child, or `undefined`. Injected: see the module header. */
|
|
81
|
+
direct: (name: string) => ChildRecord | undefined;
|
|
82
|
+
/** Every node the caller may consider, across runs. */
|
|
83
|
+
scan: () => ChildScopeScanEntry[];
|
|
84
|
+
}): ChildScopeHit {
|
|
85
|
+
const { name, runId } = input;
|
|
86
|
+
|
|
87
|
+
// 1. Direct children first, and unscoped by `runId`: `direct` is already the
|
|
88
|
+
// current run by construction, and an explicit `runId` that names a
|
|
89
|
+
// different run narrows only the SEARCH below — the run this session
|
|
90
|
+
// actually owns still answers first, because that is the one it can act on.
|
|
91
|
+
const direct = input.direct(name);
|
|
92
|
+
if (direct) return { kind: "direct", name, child: direct };
|
|
93
|
+
|
|
94
|
+
// 2. Same name, other runs.
|
|
95
|
+
const seen = new Set<string>();
|
|
96
|
+
const candidates: ChildScopeCandidate[] = [];
|
|
97
|
+
for (const entry of input.scan()) {
|
|
98
|
+
if (entry.name !== name) continue;
|
|
99
|
+
if (runId !== undefined && entry.runId !== runId) continue;
|
|
100
|
+
// A run holds one record per name, so the identity is (runId, nodeId) —
|
|
101
|
+
// `nodeId` is absent on pre-M2 records, where the run alone is the key.
|
|
102
|
+
const key = `${entry.runId}\u0000${entry.nodeId ?? ""}`;
|
|
103
|
+
if (seen.has(key)) continue;
|
|
104
|
+
seen.add(key);
|
|
105
|
+
candidates.push({
|
|
106
|
+
runId: entry.runId,
|
|
107
|
+
...(entry.nodeId ? { nodeId: entry.nodeId } : {}),
|
|
108
|
+
state: entry.state,
|
|
109
|
+
...(entry.sessionFile ? { sessionFile: entry.sessionFile } : {}),
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
if (candidates.length === 0) return { kind: "absent", name, candidates: [] };
|
|
114
|
+
// Sorted so two resolutions of the same store produce the same message.
|
|
115
|
+
candidates.sort((a, b) => a.runId.localeCompare(b.runId));
|
|
116
|
+
return { kind: "elsewhere", name, candidates };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* One line per candidate, `runId` / `nodeId` / `state` in that order.
|
|
121
|
+
*
|
|
122
|
+
* The caller owns the surrounding sentence — what a given action may do with the
|
|
123
|
+
* list differs — but the facts must look the same everywhere, so they are
|
|
124
|
+
* rendered in one place.
|
|
125
|
+
*/
|
|
126
|
+
export function describeChildScopeCandidates(
|
|
127
|
+
candidates: readonly ChildScopeCandidate[],
|
|
128
|
+
): string {
|
|
129
|
+
return candidates
|
|
130
|
+
.map((candidate) => {
|
|
131
|
+
const parts = [`run ${candidate.runId}`];
|
|
132
|
+
if (candidate.nodeId) parts.push(`node ${candidate.nodeId}`);
|
|
133
|
+
parts.push(`state ${candidate.state}`);
|
|
134
|
+
return ` - ${parts.join(" · ")}`;
|
|
135
|
+
})
|
|
136
|
+
.join("\n");
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// ── wiring the rule to a store's run records ───────────────────────────────
|
|
140
|
+
//
|
|
141
|
+
// These three live here, next to the rule they implement, because there must be
|
|
142
|
+
// exactly ONE definition of "what a name means": the lazy resolver below and the
|
|
143
|
+
// callers that already hold every run both go through them.
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* The record `scopeRunId` actually owns for `name`, or `null`.
|
|
147
|
+
*
|
|
148
|
+
* This is the whole definition of "a direct child": an exact `(runId, name)`
|
|
149
|
+
* pair — never "the newest record with that name".
|
|
150
|
+
*/
|
|
151
|
+
export function foundInScope(
|
|
152
|
+
runs: readonly RunRecord[],
|
|
153
|
+
scopeRunId: string | undefined,
|
|
154
|
+
name: string,
|
|
155
|
+
): ScopedRunChild | null {
|
|
156
|
+
if (!scopeRunId) return null;
|
|
157
|
+
const run = runs.find((candidate) => candidate.runId === scopeRunId);
|
|
158
|
+
const child = run?.children.find((candidate) => candidate.name === name);
|
|
159
|
+
if (!run || !child) return null;
|
|
160
|
+
return { runId: run.runId, run, child };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** {@link resolveChildScope}, wired to one store's run records. */
|
|
164
|
+
export function scopeHitFor(input: {
|
|
165
|
+
name: string;
|
|
166
|
+
/**
|
|
167
|
+
* The run whose children count as direct: the explicit `runId` when the caller
|
|
168
|
+
* named one, else the run this session owns. Separate from `explicitRunId` on
|
|
169
|
+
* purpose — see it below.
|
|
170
|
+
*/
|
|
171
|
+
directRunId: string | undefined;
|
|
172
|
+
/**
|
|
173
|
+
* The `runId` the CALLER passed, which is the only thing allowed to narrow the
|
|
174
|
+
* cross-run search. The inferred session run must not: with it in the filter a
|
|
175
|
+
* name that lives in another run would come back `absent` instead of
|
|
176
|
+
* `elsewhere`, and the refusal that tells the caller where it actually is
|
|
177
|
+
* would never be reachable.
|
|
178
|
+
*/
|
|
179
|
+
explicitRunId?: string | undefined;
|
|
180
|
+
runs: readonly RunRecord[];
|
|
181
|
+
}): ChildScopeHit {
|
|
182
|
+
return resolveChildScope({
|
|
183
|
+
name: input.name,
|
|
184
|
+
runId: input.explicitRunId,
|
|
185
|
+
direct: (name) => foundInScope(input.runs, input.directRunId, name)?.child,
|
|
186
|
+
scan: () =>
|
|
187
|
+
input.runs.flatMap((run) =>
|
|
188
|
+
run.children.map((child) => ({
|
|
189
|
+
runId: run.runId,
|
|
190
|
+
nodeId: child.nodeId,
|
|
191
|
+
name: child.name,
|
|
192
|
+
state: child.state,
|
|
193
|
+
sessionFile: child.sessionFile,
|
|
194
|
+
})),
|
|
195
|
+
),
|
|
196
|
+
});
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* The one node an `elsewhere` hit points at, when it is unambiguous.
|
|
201
|
+
*
|
|
202
|
+
* `null` for `absent` and for an ambiguity: a caller that cannot name the node
|
|
203
|
+
* must not pick one, and the ambiguity is reported before this is consulted.
|
|
204
|
+
*/
|
|
205
|
+
export function foundElsewhere(
|
|
206
|
+
runs: readonly RunRecord[],
|
|
207
|
+
name: string,
|
|
208
|
+
hit: ChildScopeHit,
|
|
209
|
+
): ScopedRunChild | null {
|
|
210
|
+
if (hit.kind !== "elsewhere" || hit.candidates.length !== 1) return null;
|
|
211
|
+
const only = hit.candidates[0];
|
|
212
|
+
if (!only) return null;
|
|
213
|
+
return foundInScope(runs, only.runId, name);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** What {@link resolveScopedChild} answers. */
|
|
217
|
+
export interface ScopedChildResolution {
|
|
218
|
+
/** What the name resolved to — the same three-way answer as {@link resolveChildScope}. */
|
|
219
|
+
readonly hit: ChildScopeHit;
|
|
220
|
+
/** The node the hit points at; `null` for `absent` and for an `elsewhere` ambiguity. */
|
|
221
|
+
readonly found: ScopedRunChild | null;
|
|
222
|
+
/**
|
|
223
|
+
* Every readable run, oldest first. Scans on FIRST use and at most once, so a
|
|
224
|
+
* caller that also needs the full registry (an overview, an owner verdict)
|
|
225
|
+
* pays for it a single time — and a caller that does not never pays at all.
|
|
226
|
+
*
|
|
227
|
+
* Treat the array as read-only.
|
|
228
|
+
*/
|
|
229
|
+
runs(): RunRecord[];
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** A `readRun` that reports a malformed `runId` as "not found" instead of throwing. */
|
|
233
|
+
function readRunOrNull(
|
|
234
|
+
readRun: (runId: string) => RunRecord | null,
|
|
235
|
+
runId: string,
|
|
236
|
+
): RunRecord | null {
|
|
237
|
+
try {
|
|
238
|
+
return readRun(runId);
|
|
239
|
+
} catch {
|
|
240
|
+
// `RunStore.readRun` rejects run ids that cannot be a directory name
|
|
241
|
+
// (`../../etc`, `a/b`). Such an id names no run, which is exactly what a
|
|
242
|
+
// caller-supplied `runId` deserves: `absent`, resolved like any other miss.
|
|
243
|
+
return null;
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Resolve one name, paying for the run registry only when the answer needs it (#344).
|
|
249
|
+
*
|
|
250
|
+
* Every control call (`collect` / `status` / `steer` / `abort` / `retire` /
|
|
251
|
+
* `continue`) used to start with `store.listRuns()` — a `readdir` plus a
|
|
252
|
+
* `JSON.parse` per run — even when it already knew the run it was scoped to.
|
|
253
|
+
* The scan is O(runs) and the scope is usually free, so the order is inverted
|
|
254
|
+
* here: read the ONE run the scope names, and fall back to the registry only
|
|
255
|
+
* when the answer genuinely depends on other runs.
|
|
256
|
+
*
|
|
257
|
+
* The three steps, in order:
|
|
258
|
+
*
|
|
259
|
+
* 1. **direct hit** — `directRunId` is known (`params.runId` / the session's
|
|
260
|
+
* legion run / the run the runtime tracks the name under) and that run
|
|
261
|
+
* holds the name. The resolver's answer is `direct` by construction, and
|
|
262
|
+
* its scan is never consulted (see `resolveChildScope`: `direct` short-
|
|
263
|
+
* circuits before the scan), so one `readRun` answers it.
|
|
264
|
+
* 2. **explicit `runId`, name not in it** — the cross-run search is narrowed
|
|
265
|
+
* to that same run, so a scan could not produce a candidate: `absent`.
|
|
266
|
+
* 3. **everything else** — the name may live in another run. That is the case
|
|
267
|
+
* #312 exists for (report / refuse instead of adopting), and it needs the
|
|
268
|
+
* registry. `listRuns` is called once, through the store's cached scan.
|
|
269
|
+
*
|
|
270
|
+
* #312's strict-scope semantics are untouched: this function only decides WHICH
|
|
271
|
+
* reads happen, never what a hit means. Steps 1 and 2 are provably identical to
|
|
272
|
+
* what the scan would have answered, which is what makes the shortcut safe.
|
|
273
|
+
*/
|
|
274
|
+
export function resolveScopedChild(input: {
|
|
275
|
+
name: string;
|
|
276
|
+
/** The `runId` the caller passed, if any (narrows the cross-run search). */
|
|
277
|
+
explicitRunId?: string | undefined;
|
|
278
|
+
/** The run this call is scoped to (see `scopeRunIdFor` in the caller). */
|
|
279
|
+
directRunId?: string | undefined;
|
|
280
|
+
/** O(1) single-run read. */
|
|
281
|
+
readRun: (runId: string) => RunRecord | null;
|
|
282
|
+
/** The full registry. Called at most once, and only when a scan is required. */
|
|
283
|
+
listRuns: () => RunRecord[];
|
|
284
|
+
}): ScopedChildResolution {
|
|
285
|
+
const { name, explicitRunId, directRunId } = input;
|
|
286
|
+
let scanned: RunRecord[] | undefined;
|
|
287
|
+
const runs = (): RunRecord[] => (scanned ??= input.listRuns());
|
|
288
|
+
|
|
289
|
+
if (directRunId !== undefined) {
|
|
290
|
+
const scopeRun = readRunOrNull(input.readRun, directRunId);
|
|
291
|
+
// The record's own `runId` has to agree with the directory the caller
|
|
292
|
+
// asked for: `foundInScope` matches on the FIELD, so a tampered run.json
|
|
293
|
+
// whose field disagrees with its directory is not a direct hit either.
|
|
294
|
+
const child =
|
|
295
|
+
scopeRun && scopeRun.runId === directRunId
|
|
296
|
+
? scopeRun.children.find((candidate) => candidate.name === name)
|
|
297
|
+
: undefined;
|
|
298
|
+
if (scopeRun && child) {
|
|
299
|
+
return {
|
|
300
|
+
hit: { kind: "direct", name, child },
|
|
301
|
+
found: { runId: scopeRun.runId, run: scopeRun, child },
|
|
302
|
+
runs,
|
|
303
|
+
};
|
|
304
|
+
}
|
|
305
|
+
// Step 2: an explicit `runId` filters the scan to the very run just read
|
|
306
|
+
// (`scopeRunIdFor` puts the explicit id first, so the two agree), and "not
|
|
307
|
+
// in that run" is then `absent` without asking the registry. The equality
|
|
308
|
+
// test keeps this a shortcut instead of an assumption: given a scope that
|
|
309
|
+
// somehow differs from the explicit id, the scan below decides.
|
|
310
|
+
if (explicitRunId !== undefined && explicitRunId === directRunId) {
|
|
311
|
+
return { hit: { kind: "absent", name, candidates: [] }, found: null, runs };
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
// Step 3: the registry. One scan, memoized for whoever else needs it.
|
|
316
|
+
const all = runs();
|
|
317
|
+
const hit = scopeHitFor({ name, directRunId, explicitRunId, runs: all });
|
|
318
|
+
const found =
|
|
319
|
+
hit.kind === "direct"
|
|
320
|
+
? foundInScope(all, directRunId, name)
|
|
321
|
+
: foundElsewhere(all, name, hit);
|
|
322
|
+
return { hit, found, runs };
|
|
323
|
+
}
|
|
@@ -286,14 +286,64 @@ export function parsePiList(output: string): string[] {
|
|
|
286
286
|
return dirs;
|
|
287
287
|
}
|
|
288
288
|
|
|
289
|
+
/**
|
|
290
|
+
* How much of `pi list`'s stderr the one-shot warning may echo.
|
|
291
|
+
*
|
|
292
|
+
* The warning has to be actionable (#317: "could not ask" used to look exactly
|
|
293
|
+
* like "nothing installed"), but it is also a single log line that must not turn
|
|
294
|
+
* a stack trace into the operator's terminal.
|
|
295
|
+
*/
|
|
296
|
+
export const DISCOVERY_STDERR_LIMIT = 200;
|
|
297
|
+
|
|
298
|
+
/** Best-effort text of an unknown error field: never throws. */
|
|
299
|
+
function asText(value: unknown): string {
|
|
300
|
+
if (typeof value === "string") return value;
|
|
301
|
+
if (value === undefined || value === null) return "";
|
|
302
|
+
try {
|
|
303
|
+
return String(value);
|
|
304
|
+
} catch {
|
|
305
|
+
return "";
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/**
|
|
310
|
+
* One bounded line explaining why a probe failed.
|
|
311
|
+
*
|
|
312
|
+
* `pi list` can fail with no stderr at all (a killed child, a bare `exit 4`), so
|
|
313
|
+
* the summary degrades through stderr → exit code → `error.message`. The code
|
|
314
|
+
* sits BEFORE the message on purpose: Node's `execFile` always fills `message`
|
|
315
|
+
* with `Command failed: pi list`, so a message-first order would make the exit
|
|
316
|
+
* code branch unreachable — and `pi list exited 4` says more than the generic
|
|
317
|
+
* wrapper text. A non-numeric code (`ENOENT`) still falls through to the message
|
|
318
|
+
* (`spawn pi ENOENT`), which is the actionable one there. It must never throw: a
|
|
319
|
+
* warning is not allowed to fail a launch (#317).
|
|
320
|
+
*/
|
|
321
|
+
function describeProbeFailure(error: unknown): string {
|
|
322
|
+
const err = error as { stderr?: unknown; message?: unknown; code?: unknown } | undefined;
|
|
323
|
+
const stderr = asText(err?.stderr).replace(/\s+/g, " ").trim();
|
|
324
|
+
if (stderr) {
|
|
325
|
+
return stderr.length > DISCOVERY_STDERR_LIMIT ? `${stderr.slice(0, DISCOVERY_STDERR_LIMIT)}…` : stderr;
|
|
326
|
+
}
|
|
327
|
+
if (typeof err?.code === "number") return `pi list exited ${err.code} with no stderr`;
|
|
328
|
+
const message = asText(err?.message).replace(/\s+/g, " ").trim();
|
|
329
|
+
if (message) {
|
|
330
|
+
return message.length > DISCOVERY_STDERR_LIMIT ? `${message.slice(0, DISCOVERY_STDERR_LIMIT)}…` : message;
|
|
331
|
+
}
|
|
332
|
+
return "pi list failed with no output";
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/** One probe's outcome: resolved entries, or the reason the probe could not answer. */
|
|
336
|
+
type DiscoveryProbe = { ok: true; entries: string[] } | { ok: false; reason: string };
|
|
337
|
+
|
|
289
338
|
/**
|
|
290
339
|
* Run one `pi list` and resolve it to extension entry paths.
|
|
291
340
|
*
|
|
292
|
-
* Returns
|
|
293
|
-
* exit, timeout
|
|
294
|
-
* not ask"
|
|
341
|
+
* Returns a failure (with a short reason) when discovery itself failed — no `pi`
|
|
342
|
+
* on PATH, non-zero exit, timeout — so the caller can both distinguish "nothing
|
|
343
|
+
* installed" from "could not ask" and say which one happened (#317). Only the
|
|
344
|
+
* latter stays retryable.
|
|
295
345
|
*/
|
|
296
|
-
async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<
|
|
346
|
+
async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<DiscoveryProbe> {
|
|
297
347
|
let dirs: string[];
|
|
298
348
|
try {
|
|
299
349
|
const { stdout } = await execFileAsync("pi", ["list"], {
|
|
@@ -302,17 +352,20 @@ async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] |
|
|
|
302
352
|
maxBuffer: 4 * 1024 * 1024,
|
|
303
353
|
});
|
|
304
354
|
dirs = parsePiList(stdout);
|
|
305
|
-
} catch {
|
|
306
|
-
return
|
|
355
|
+
} catch (error) {
|
|
356
|
+
return { ok: false, reason: describeProbeFailure(error) };
|
|
307
357
|
}
|
|
308
358
|
const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
|
|
309
359
|
const seen = new Set<string>();
|
|
310
|
-
return
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
360
|
+
return {
|
|
361
|
+
ok: true,
|
|
362
|
+
entries: entries.filter((entry) => {
|
|
363
|
+
const key = path.resolve(entry);
|
|
364
|
+
if (seen.has(key)) return false;
|
|
365
|
+
seen.add(key);
|
|
366
|
+
return true;
|
|
367
|
+
}),
|
|
368
|
+
};
|
|
316
369
|
}
|
|
317
370
|
|
|
318
371
|
/**
|
|
@@ -332,6 +385,40 @@ async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] |
|
|
|
332
385
|
*/
|
|
333
386
|
export const FAILURE_TTL_MS = 5_000;
|
|
334
387
|
|
|
388
|
+
/**
|
|
389
|
+
* Record a failed probe (the `failedAt` backoff stamp) and warn ONCE.
|
|
390
|
+
*
|
|
391
|
+
* The stamp doubles as the "already told the operator" bit (#317): while it is
|
|
392
|
+
* set, a later failing probe updates the time but stays quiet, so a host that
|
|
393
|
+
* will never have `pi list` working cannot flood the log once per spawn.
|
|
394
|
+
*
|
|
395
|
+
* Scope of "once": one warning per PROCESS. A successful probe caches through
|
|
396
|
+
* `discovered`, and `ensureHostExtensions` short-circuits on that forever — so
|
|
397
|
+
* once discovery has worked there is no further probe to fail, and the stamp
|
|
398
|
+
* being deleted on success cannot produce a second warning in production. The
|
|
399
|
+
* only way back is `resetExtensionDiscoveryCache`, which is a test seam and also
|
|
400
|
+
* clears the stamp, i.e. a genuinely fresh start. No extra state is needed for
|
|
401
|
+
* this bound (the frozen backoff already models exactly this window).
|
|
402
|
+
*
|
|
403
|
+
* Never throws: the warning itself must not be able to fail a launch, and an
|
|
404
|
+
* empty `pi list` stderr must not turn into a TypeError here.
|
|
405
|
+
*/
|
|
406
|
+
function noteDiscoveryFailure(reason: string): void {
|
|
407
|
+
const alreadyReported = store.failedAt !== undefined;
|
|
408
|
+
store.failedAt = Date.now();
|
|
409
|
+
if (alreadyReported) return;
|
|
410
|
+
const retryS = Math.round(FAILURE_TTL_MS / 1000);
|
|
411
|
+
try {
|
|
412
|
+
console.error(
|
|
413
|
+
`[pi-legion] host extension discovery failed (pi list): ${reason}. ` +
|
|
414
|
+
`Children get 0 inherited extensions until a probe succeeds (next attempt after ${retryS}s); ` +
|
|
415
|
+
"run `/legion doctor` (Extensions) or set PI_LEGION_CHILD_EXTENSIONS=<paths> to load them explicitly.",
|
|
416
|
+
);
|
|
417
|
+
} catch {
|
|
418
|
+
// A log line that cannot be written must not break the spawn either.
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
|
|
335
422
|
/**
|
|
336
423
|
* Discover the host's extensions once per process and return them.
|
|
337
424
|
*
|
|
@@ -350,6 +437,10 @@ export const FAILURE_TTL_MS = 5_000;
|
|
|
350
437
|
* that keeps the three warm-up points idempotent (R2-b). Once the stamp ages out,
|
|
351
438
|
* the next call probes again, so a failure is never a permanent off switch (F23).
|
|
352
439
|
*
|
|
440
|
+
* #317 adds visibility only: the failure is now also reported once (see
|
|
441
|
+
* `noteDiscoveryFailure`) and is readable through `hostExtensionDiscoveryState`.
|
|
442
|
+
* Neither the never-reject contract nor the backoff semantics changed.
|
|
443
|
+
*
|
|
353
444
|
* `env` is handed to `execFile` (a caller can point discovery at a specific
|
|
354
445
|
* PATH); the cache itself is process-wide and does not vary by env.
|
|
355
446
|
*/
|
|
@@ -359,21 +450,21 @@ export async function ensureHostExtensions(env: NodeJS.ProcessEnv = process.env)
|
|
|
359
450
|
if (!store.inFlight) {
|
|
360
451
|
store.inFlight = (async () => {
|
|
361
452
|
try {
|
|
362
|
-
const
|
|
363
|
-
if (!
|
|
364
|
-
|
|
453
|
+
const probe = await resolveHostExtensions(env);
|
|
454
|
+
if (!probe.ok) {
|
|
455
|
+
noteDiscoveryFailure(probe.reason);
|
|
365
456
|
return [];
|
|
366
457
|
}
|
|
367
|
-
store.discovered =
|
|
458
|
+
store.discovered = probe.entries;
|
|
368
459
|
// A success supersedes any earlier failure, so the backoff stamp must not
|
|
369
460
|
// outlive it — otherwise a later re-probe (after a reset) would inherit an
|
|
370
461
|
// unrelated window.
|
|
371
462
|
delete store.failedAt;
|
|
372
|
-
return
|
|
373
|
-
} catch {
|
|
463
|
+
return probe.entries;
|
|
464
|
+
} catch (error) {
|
|
374
465
|
// Belt and braces: the contract is "never rejects", and a launch must
|
|
375
466
|
// never fail because the host could not be asked about packages.
|
|
376
|
-
|
|
467
|
+
noteDiscoveryFailure(describeProbeFailure(error));
|
|
377
468
|
return [];
|
|
378
469
|
} finally {
|
|
379
470
|
// Success caches through `discovered`; failure leaves the `failedAt`
|
|
@@ -400,6 +491,41 @@ export function discoveredHostExtensions(): string[] | undefined {
|
|
|
400
491
|
return store.discovered;
|
|
401
492
|
}
|
|
402
493
|
|
|
494
|
+
/**
|
|
495
|
+
* What this process knows about host extension discovery, read-only (#317).
|
|
496
|
+
*
|
|
497
|
+
* Exists because `discoveredHostExtensions() ?? []` collapses two different
|
|
498
|
+
* situations into one empty array: "the host really ships no package extensions"
|
|
499
|
+
* and "we could not ask" (and a third: "we never asked"). A caller that wants to
|
|
500
|
+
* tell them apart — `/legion doctor` does — reads this instead of guessing.
|
|
501
|
+
*
|
|
502
|
+
* Pure in-memory read: no probe, no subprocess. That is deliberate, so doctor
|
|
503
|
+
* can report `never` without silently kicking off a 0.3–0.9 s `pi list`.
|
|
504
|
+
*/
|
|
505
|
+
export interface HostExtensionDiscoveryState {
|
|
506
|
+
/** `ok` = a probe succeeded (count is the resolved set, possibly 0). */
|
|
507
|
+
status: "ok" | "failed" | "unknown";
|
|
508
|
+
/** Entries the last successful probe resolved; 0 unless `status` is `ok`. */
|
|
509
|
+
count: number;
|
|
510
|
+
/** `Date.now()` of the last FAILED probe (only set when `status` is `failed`). */
|
|
511
|
+
at?: number;
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
export type HostExtensionDiscoveryStatus = HostExtensionDiscoveryState["status"];
|
|
515
|
+
|
|
516
|
+
/**
|
|
517
|
+
* Read the discovery state without changing it.
|
|
518
|
+
*
|
|
519
|
+
* A success wins over a stale stamp on purpose: `ensureHostExtensions` deletes
|
|
520
|
+
* `failedAt` on success, so both being set only means a reset raced a re-probe —
|
|
521
|
+
* the cache is the newer truth either way.
|
|
522
|
+
*/
|
|
523
|
+
export function hostExtensionDiscoveryState(): HostExtensionDiscoveryState {
|
|
524
|
+
if (store.discovered !== undefined) return { status: "ok", count: store.discovered.length };
|
|
525
|
+
if (store.failedAt !== undefined) return { status: "failed", count: 0, at: store.failedAt };
|
|
526
|
+
return { status: "unknown", count: 0 };
|
|
527
|
+
}
|
|
528
|
+
|
|
403
529
|
/**
|
|
404
530
|
* Does this extension match an `excludeExtensions` entry?
|
|
405
531
|
*
|