pi-legion 4.0.0 → 5.0.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 +168 -1
- package/README.md +101 -44
- package/agents/centurion.md +20 -16
- package/agents/scout.md +3 -1
- package/agents/worker.md +5 -7
- package/docs/contracts/declarative-phase-machine-v5.md +128 -0
- package/docs/contracts/subagent-renewal-v1.md +260 -0
- package/docs/headless-child-contract.md +6 -3
- package/docs/inprocess-supervisor.md +70 -24
- package/docs/legion-v2-contract.md +9 -0
- package/docs/spawn-mode-visibility-v1.md +4 -1
- package/index.ts +598 -44
- package/package.json +2 -2
- package/src/agents/agents.ts +293 -36
- package/src/agents/overrides.ts +3 -1
- package/src/agents/settings.ts +6 -18
- package/src/extension/child-guard.ts +25 -1
- package/src/extension/legion-tools.ts +66 -21
- package/src/extension/notify.ts +136 -4
- package/src/extension/playbook.ts +2 -2
- package/src/extension/runtime.ts +56 -1
- package/src/extension/summary.ts +13 -4
- package/src/extension/timing.ts +8 -4
- package/src/legion/phase-conditions.ts +164 -0
- package/src/legion/phase-machine.ts +403 -0
- package/src/legion/state-machine.ts +219 -115
- package/src/runs/args.ts +32 -18
- package/src/runs/extension-inheritance.ts +220 -0
- package/src/runs/orchestrator.ts +137 -44
- package/src/runs/progress-signal.ts +137 -0
- package/src/runs/store-lookup.ts +270 -0
- package/src/shared/types.ts +88 -3
- package/src/supervisor/child-context.ts +19 -0
- package/src/supervisor/inprocess-supervisor.ts +29 -5
- package/src/supervisor/routing-supervisor.ts +2 -1
- package/src/supervisor/rpc-supervisor.ts +2 -2
- package/src/tui/tree-view.ts +56 -0
- package/src/tui/viz/palette.ts +0 -3
- package/agents/advisor.md +0 -110
- package/agents/designer.md +0 -87
- package/agents/planner.md +0 -53
- package/agents/prototype.md +0 -72
- package/agents/reviewer.md +0 -113
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which extensions a child session loads (#280).
|
|
3
|
+
*
|
|
4
|
+
* Policy has flipped. Children used to load extensions only when a role card
|
|
5
|
+
* opted in (`inheritExtensions: true`) or an operator set
|
|
6
|
+
* `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1`. #43 made that the default because a
|
|
7
|
+
* heavy host extension (an LSP stack) cost ~1 GB per child, and at the time
|
|
8
|
+
* every child was a separate process.
|
|
9
|
+
*
|
|
10
|
+
* Two things changed that reasoning:
|
|
11
|
+
*
|
|
12
|
+
* - children are in-process by default now (#279), so "one more extension per
|
|
13
|
+
* child" no longer means another process's worth of memory
|
|
14
|
+
* - the opt-in list was per-role and hand-maintained, so in practice children
|
|
15
|
+
* silently lost host capabilities (a provider extension, a guard) that the
|
|
16
|
+
* role never knew to name
|
|
17
|
+
*
|
|
18
|
+
* The default is therefore "inherit everything the parent has", with two ways to
|
|
19
|
+
* narrow it: `excludeExtensions` (subtract specific ones) and
|
|
20
|
+
* `inheritExtensions: false` (load only what the card lists explicitly).
|
|
21
|
+
*
|
|
22
|
+
* Where the parent's list comes from: pi exposes no "list loaded extensions"
|
|
23
|
+
* API, and `pi list` reports only package DIRECTORIES. So discovery resolves
|
|
24
|
+
* each directory the same way pi's own loader does — `package.json`'s
|
|
25
|
+
* `pi.extensions`, else `index.ts`/`index.js` — and caches the result for the
|
|
26
|
+
* process. That covers package-shaped extensions, which is what `pi list`
|
|
27
|
+
* reports; single-file `--extension` arguments and builtins are not discoverable
|
|
28
|
+
* this way and must still be named explicitly (documented limitation, #280).
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
import * as fs from "node:fs";
|
|
32
|
+
import * as path from "node:path";
|
|
33
|
+
import { execFile } from "node:child_process";
|
|
34
|
+
import { promisify } from "node:util";
|
|
35
|
+
import type { AgentConfig } from "../shared/types.ts";
|
|
36
|
+
|
|
37
|
+
/** Env kill-switch, shared with the rpc path. Kept here to avoid a cycle. */
|
|
38
|
+
const CHILD_INHERIT_EXTENSIONS_ENV = "PI_LEGION_CHILD_INHERIT_EXTENSIONS";
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Whether a child loads the host's discovered extensions (#280).
|
|
42
|
+
*
|
|
43
|
+
* Default TRUE: a child starts from everything the parent has and narrows from
|
|
44
|
+
* there. `inheritExtensions: false` on the card, or the env var, loads only the
|
|
45
|
+
* card's own list. The env var accepts either polarity so an operator can flip
|
|
46
|
+
* the whole tree without editing every card.
|
|
47
|
+
*
|
|
48
|
+
* Duplicated in `args.ts` (which re-exports it for the rpc argument builder)
|
|
49
|
+
* rather than imported, because `args.ts` already imports this module.
|
|
50
|
+
*/
|
|
51
|
+
export function childInheritsExtensions(
|
|
52
|
+
agent: Pick<AgentConfig, "inheritExtensions">,
|
|
53
|
+
env: NodeJS.ProcessEnv = process.env,
|
|
54
|
+
): boolean {
|
|
55
|
+
if (agent.inheritExtensions === false) return false;
|
|
56
|
+
const raw = env[CHILD_INHERIT_EXTENSIONS_ENV]?.trim().toLowerCase();
|
|
57
|
+
if (raw === "0" || raw === "false" || raw === "off" || raw === "no") return false;
|
|
58
|
+
if (raw === "1" || raw === "true" || raw === "on" || raw === "yes") return true;
|
|
59
|
+
return true;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const execFileAsync = promisify(execFile);
|
|
63
|
+
|
|
64
|
+
/** Host-discovered package extension paths, resolved once per process. */
|
|
65
|
+
let discovered: string[] | undefined;
|
|
66
|
+
/** In-flight discovery, so concurrent launches share one `pi list`. */
|
|
67
|
+
let discovery: Promise<string[]> | undefined;
|
|
68
|
+
|
|
69
|
+
/** Reset the cache. Test seam only. */
|
|
70
|
+
export function resetExtensionDiscoveryCache(): void {
|
|
71
|
+
discovered = undefined;
|
|
72
|
+
discovery = undefined;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Resolve a package directory to its extension entry points, exactly like pi's
|
|
77
|
+
* own loader: `package.json`'s `pi.extensions` first, then `index.ts`/`index.js`.
|
|
78
|
+
*
|
|
79
|
+
* A directory with neither is not an extension package (a theme pack, a skill
|
|
80
|
+
* bundle) and contributes nothing.
|
|
81
|
+
*/
|
|
82
|
+
export function resolveExtensionEntries(dir: string): string[] {
|
|
83
|
+
const manifestPath = path.join(dir, "package.json");
|
|
84
|
+
try {
|
|
85
|
+
if (fs.existsSync(manifestPath)) {
|
|
86
|
+
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as {
|
|
87
|
+
pi?: { extensions?: unknown };
|
|
88
|
+
};
|
|
89
|
+
const declared = manifest.pi?.extensions;
|
|
90
|
+
if (Array.isArray(declared)) {
|
|
91
|
+
const resolved = declared
|
|
92
|
+
.filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
|
|
93
|
+
.map((entry) => path.resolve(dir, entry))
|
|
94
|
+
.filter((entry) => fs.existsSync(entry));
|
|
95
|
+
if (resolved.length > 0) return resolved;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
} catch {
|
|
99
|
+
// Unreadable/invalid manifest: fall through to the index-file convention.
|
|
100
|
+
}
|
|
101
|
+
for (const candidate of ["index.ts", "index.js"]) {
|
|
102
|
+
const entry = path.join(dir, candidate);
|
|
103
|
+
if (fs.existsSync(entry)) return [entry];
|
|
104
|
+
}
|
|
105
|
+
return [];
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** Parse `pi list` output into the package directories it reports. */
|
|
109
|
+
export function parsePiList(output: string): string[] {
|
|
110
|
+
const dirs: string[] = [];
|
|
111
|
+
for (const raw of output.split("\n")) {
|
|
112
|
+
const line = raw.trim();
|
|
113
|
+
// Package dirs are the indented absolute paths; headers are `User packages:`
|
|
114
|
+
// and `npm:name@version` lines carry no leading slash.
|
|
115
|
+
if (!line.startsWith("/")) continue;
|
|
116
|
+
dirs.push(line);
|
|
117
|
+
}
|
|
118
|
+
return dirs;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Ask pi which packages are installed and resolve them to extension files.
|
|
123
|
+
*
|
|
124
|
+
* Never throws: a host without `pi` on PATH, or a `pi list` failure, degrades to
|
|
125
|
+
* "no discovered extensions" (children still get their explicit list plus the
|
|
126
|
+
* child-guard). Failure to discover must not fail a launch.
|
|
127
|
+
*/
|
|
128
|
+
export async function discoverHostExtensions(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
|
|
129
|
+
if (discovered) return discovered;
|
|
130
|
+
discovery ??= (async () => {
|
|
131
|
+
let dirs: string[] = [];
|
|
132
|
+
try {
|
|
133
|
+
const { stdout } = await execFileAsync("pi", ["list"], {
|
|
134
|
+
env,
|
|
135
|
+
timeout: 15_000,
|
|
136
|
+
maxBuffer: 4 * 1024 * 1024,
|
|
137
|
+
});
|
|
138
|
+
dirs = parsePiList(stdout);
|
|
139
|
+
} catch {
|
|
140
|
+
dirs = [];
|
|
141
|
+
}
|
|
142
|
+
const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
|
|
143
|
+
const seen = new Set<string>();
|
|
144
|
+
discovered = entries.filter((entry) => {
|
|
145
|
+
const key = path.resolve(entry);
|
|
146
|
+
if (seen.has(key)) return false;
|
|
147
|
+
seen.add(key);
|
|
148
|
+
return true;
|
|
149
|
+
});
|
|
150
|
+
return discovered;
|
|
151
|
+
})();
|
|
152
|
+
return discovery;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Synchronous read of whatever discovery has already produced. */
|
|
156
|
+
export function discoveredHostExtensions(): string[] | undefined {
|
|
157
|
+
return discovered;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Does this extension match an `excludeExtensions` entry?
|
|
162
|
+
*
|
|
163
|
+
* Both spellings are accepted because they answer different questions and both
|
|
164
|
+
* are natural to write:
|
|
165
|
+
*
|
|
166
|
+
* - a PATH (`/abs/.../index.ts`, `./relative`, `~/...`) compares resolved
|
|
167
|
+
* paths, so an exact file can be excluded
|
|
168
|
+
* - a NAME (`pi-lens`, `pi-any-endpoint`) compares against the containing
|
|
169
|
+
* package directory name, so a package can be excluded without knowing its
|
|
170
|
+
* entry layout
|
|
171
|
+
*
|
|
172
|
+
* A bare name never matches by path, and a path never matches by name, so the
|
|
173
|
+
* two cannot interfere.
|
|
174
|
+
*/
|
|
175
|
+
export function matchesExcludedExtension(extension: string, exclude: string): boolean {
|
|
176
|
+
const target = exclude.trim();
|
|
177
|
+
if (!target) return false;
|
|
178
|
+
const isPathLike = target.startsWith("/") || target.startsWith("./") || target.startsWith("../") || target.startsWith("~");
|
|
179
|
+
if (isPathLike) {
|
|
180
|
+
const expanded = target.startsWith("~") ? path.join(process.env.HOME ?? "", target.slice(1)) : target;
|
|
181
|
+
return path.resolve(extension) === path.resolve(expanded);
|
|
182
|
+
}
|
|
183
|
+
// Name form: match the package directory that contains the entry file, or the
|
|
184
|
+
// entry file's own basename for a loose `foo.ts`.
|
|
185
|
+
const ext = extension.trim();
|
|
186
|
+
if (ext === target) return true;
|
|
187
|
+
const parts = path.resolve(ext).split(path.sep);
|
|
188
|
+
// `.../node_modules/<name>/...` — the package dir is the segment after node_modules.
|
|
189
|
+
const nodeModulesAt = parts.lastIndexOf("node_modules");
|
|
190
|
+
if (nodeModulesAt >= 0 && parts[nodeModulesAt + 1] === target) return true;
|
|
191
|
+
// `.../<name>/extensions/index.ts` or `.../<name>/index.ts`.
|
|
192
|
+
const file = parts.at(-1) ?? "";
|
|
193
|
+
const dir = parts.at(-2) ?? "";
|
|
194
|
+
if (dir === target) return true;
|
|
195
|
+
if (file === `${target}.ts` || file === `${target}.js`) return true;
|
|
196
|
+
return false;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* The extensions a child should load explicitly.
|
|
201
|
+
*
|
|
202
|
+
* `inherit: false` (role card opted out) loads ONLY the card's own list. The
|
|
203
|
+
* default additionally carries every discovered host extension minus
|
|
204
|
+
* `excludeExtensions`. The child-guard is appended by the caller and is never
|
|
205
|
+
* subject to this policy — a child that skips it would lose the prompt/format
|
|
206
|
+
* contract regardless of what the card asked for.
|
|
207
|
+
*/
|
|
208
|
+
export function inheritedExtensions(
|
|
209
|
+
agent: Pick<AgentConfig, "inheritExtensions" | "excludeExtensions">,
|
|
210
|
+
host: readonly string[],
|
|
211
|
+
env: NodeJS.ProcessEnv = process.env,
|
|
212
|
+
): string[] {
|
|
213
|
+
// `inheritExtensions: false` (card) or the env kill-switch both mean "load
|
|
214
|
+
// only what the card names". Checked here rather than at the call sites so
|
|
215
|
+
// rpc and in-process cannot drift apart.
|
|
216
|
+
if (!childInheritsExtensions(agent, env)) return [];
|
|
217
|
+
const excluded = agent.excludeExtensions ?? [];
|
|
218
|
+
if (excluded.length === 0) return [...host];
|
|
219
|
+
return host.filter((ext) => !excluded.some((pattern) => matchesExcludedExtension(ext, pattern)));
|
|
220
|
+
}
|
package/src/runs/orchestrator.ts
CHANGED
|
@@ -20,7 +20,7 @@ import { appendEvent } from "../legion/events.ts";
|
|
|
20
20
|
import { checkLaunchBudget, withLaunchBudget, type LegionBudgetLimits } from "../legion/budget.ts";
|
|
21
21
|
import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode } from "../legion/nodes.ts";
|
|
22
22
|
import { upsertUsage } from "../legion/usage.ts";
|
|
23
|
-
import { evaluatePhaseTransition,
|
|
23
|
+
import { evaluatePhaseTransition, isTerminalPhase } from "../legion/state-machine.ts";
|
|
24
24
|
import { CHILD_ACCEPTANCE_ROLE_ENV, CHILD_ROLE_ENV } from "../extension/child-guard.ts";
|
|
25
25
|
import {
|
|
26
26
|
ALLOW_NESTED_ENV,
|
|
@@ -46,6 +46,7 @@ import {
|
|
|
46
46
|
type ChildRecord,
|
|
47
47
|
DEFAULTS,
|
|
48
48
|
ErrorCodes,
|
|
49
|
+
unknownChildError,
|
|
49
50
|
type Execution,
|
|
50
51
|
type Handle,
|
|
51
52
|
MAX_NESTED_PATH_ENTRIES,
|
|
@@ -74,7 +75,6 @@ import { type ChildLaunchContext, currentChildContext, runInChildContext } from
|
|
|
74
75
|
import { inProcessDepth, runAtAbsoluteDepth } from "../supervisor/inprocess-depth.ts";
|
|
75
76
|
import { subscribeInProcessSlotReleases } from "../supervisor/routing-supervisor.ts";
|
|
76
77
|
import type { LegionSupervisor, SettleResult, SpawnInput } from "../supervisor/types.ts";
|
|
77
|
-
import { isInProcessSpawn, resolveSpawnMode } from "../supervisor/spawn-mode.ts";
|
|
78
78
|
import type { PendingUIRequest, UIProxy } from "../supervisor/ui-proxy.ts";
|
|
79
79
|
import { applyVerification, type VerifyRunner } from "./acceptance.ts";
|
|
80
80
|
import {
|
|
@@ -413,6 +413,7 @@ export class Orchestrator {
|
|
|
413
413
|
private readonly onLaunchQueueNotice?: (line: string) => void;
|
|
414
414
|
private depthWarningEmitted = false;
|
|
415
415
|
private worktreeDeniedWarningEmitted = false;
|
|
416
|
+
private spawnModeDeniedWarningEmitted = false;
|
|
416
417
|
private spawned = 0;
|
|
417
418
|
private readonly children = new Map<string, ChildRecord>();
|
|
418
419
|
private readonly nameCounter = new Map<string, number>();
|
|
@@ -534,7 +535,7 @@ export class Orchestrator {
|
|
|
534
535
|
return { name, nodeId: node.id, sessionFile: node.sessionFile, ownerToken: `legion-${node.id}`, state: "retired", spawnedAt: new Date(node.createdAt).toISOString(), agent: node.role, kind: node.kind as AgentConfig["kind"], ...(node.model ? { model: node.model } : {}), ...(node.worktreePath ? { worktreePath: node.worktreePath } : {}) };
|
|
535
536
|
}
|
|
536
537
|
|
|
537
|
-
private reserveNode(input: { nodeId: string; name: string; agent: AgentConfig; task: string; sessionFile: string; runId?: string; team?: string; worktreePath?: string; model?: string; utility?: boolean }): LegionNode | null {
|
|
538
|
+
private reserveNode(input: { nodeId: string; name: string; agent: AgentConfig; task: string; sessionFile: string; runId?: string; team?: string; worktreePath?: string; model?: string; utility?: boolean; inProcess?: boolean }): LegionNode | null {
|
|
538
539
|
const legion = this.legion;
|
|
539
540
|
if (!legion) return null;
|
|
540
541
|
const parent = getNode(legion.db, legion.nodeId);
|
|
@@ -559,17 +560,22 @@ export class Orchestrator {
|
|
|
559
560
|
const maxChildren = legion.settings?.maxChildrenPerNode ?? 8;
|
|
560
561
|
const activeReservation = previous && (previous.status === "starting" || previous.status === "running") ? 1 : 0;
|
|
561
562
|
// In-process children use subagents.inprocess.* only — do not spend RPC legion.* slots (#197).
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
563
|
+
//
|
|
564
|
+
// #279: keyed on the ARBITRATED backend, not the role card's spelling. A role
|
|
565
|
+
// that pins `spawnMode: rpc` is demoted to in-process before this runs, and
|
|
566
|
+
// reading the raw card again would charge the rpc buckets for a launch that
|
|
567
|
+
// never runs there (the two backends have separate limits by design).
|
|
568
|
+
// #279: in-process launches are budgeted again. #197 granted them unlimited
|
|
569
|
+
// ledger headroom because rpc was the default and only rpc spent these slots.
|
|
570
|
+
// Now that rpc is reserved for centurion, every other role runs
|
|
571
|
+
// in-process — so "unlimited" would mean "avoid rpc, escape the caps", and a
|
|
572
|
+
// worker could nest without bound. They still get the `inprocess.*` pools
|
|
573
|
+
// enforced inside the in-process supervisor; this restores the ledger floor.
|
|
574
|
+
const limits: LegionBudgetLimits = {
|
|
575
|
+
maxDepth: depthCeiling,
|
|
576
|
+
maxChildrenPerNode: maxChildren,
|
|
577
|
+
maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation,
|
|
578
|
+
};
|
|
573
579
|
const gate = withLaunchBudget(legion.db, { parentId: legion.nodeId, depth: parent.depth + 1, nodeId: input.nodeId }, () => {
|
|
574
580
|
if (previous) {
|
|
575
581
|
updateNode(legion.db, input.nodeId, { status: "starting", sessionFile: input.sessionFile, worktreePath: input.worktreePath ?? previous.worktreePath, model: input.model ?? previous.model, team: team && team !== DEFAULT_TEAM ? team : previous.team }, this.now);
|
|
@@ -664,7 +670,11 @@ export class Orchestrator {
|
|
|
664
670
|
private abortLegionPhase(nodeId: string): void {
|
|
665
671
|
if (!this.legion) return;
|
|
666
672
|
const node = getNode(this.legion.db, nodeId);
|
|
667
|
-
|
|
673
|
+
// #298: a declared machine may name phases the built-in union does not know,
|
|
674
|
+
// and an ABORT must never be blocked by that — a team that cannot be stopped
|
|
675
|
+
// is a safety hole. `isTerminalPhase` still covers the built-in names; a
|
|
676
|
+
// custom name resolves through the machine when one is attached.
|
|
677
|
+
if (!node || !node.phase || isTerminalPhase(node.phase)) return;
|
|
668
678
|
const decision = evaluatePhaseTransition({
|
|
669
679
|
from: node.phase,
|
|
670
680
|
to: "aborted",
|
|
@@ -735,6 +745,32 @@ export class Orchestrator {
|
|
|
735
745
|
this.onBudgetRefused?.(event);
|
|
736
746
|
}
|
|
737
747
|
|
|
748
|
+
/**
|
|
749
|
+
* #279: only `name === "centurion"` may run on the rpc backend.
|
|
750
|
+
*
|
|
751
|
+
* `warnWorktreeDenied` above already forces `worktree: false` for everyone
|
|
752
|
+
* else, but that guard keys on the worktree REQUEST — a role card that pins
|
|
753
|
+
* `spawnMode: rpc` explicitly never consults `resolveSpawnMode`, so it slipped
|
|
754
|
+
* through and got a separate process (the exact isolation the worktree rule
|
|
755
|
+
* exists to reserve). This closes that bypass. Like the worktree rule it warns
|
|
756
|
+
* once per run and demotes, never throws: a stale role card must not turn every
|
|
757
|
+
* launch in the tree into a hard failure.
|
|
758
|
+
*/
|
|
759
|
+
private warnSpawnModeDenied(agentName: string): void {
|
|
760
|
+
if (this.spawnModeDeniedWarningEmitted) return;
|
|
761
|
+
this.spawnModeDeniedWarningEmitted = true;
|
|
762
|
+
const event: BudgetRefusedEvent = {
|
|
763
|
+
type: "budget_refused",
|
|
764
|
+
reason: "spawn_mode_denied_non_centurion",
|
|
765
|
+
agent: agentName,
|
|
766
|
+
};
|
|
767
|
+
console.warn(
|
|
768
|
+
`[pi-legion] rpc denied for non-centurion role '${agentName}'; forced spawnMode: inprocess. ` +
|
|
769
|
+
`Fix the role card (remove spawnMode: rpc) or dispatch a centurion when you need an isolated process.`,
|
|
770
|
+
);
|
|
771
|
+
this.onBudgetRefused?.(event);
|
|
772
|
+
}
|
|
773
|
+
|
|
738
774
|
async launch(
|
|
739
775
|
input: LaunchInput,
|
|
740
776
|
/**
|
|
@@ -772,6 +808,24 @@ export class Orchestrator {
|
|
|
772
808
|
const tempDir = this.runDir;
|
|
773
809
|
const parentRole = this.legion ? getNode(this.legion.db, this.legion.nodeId)?.role : undefined;
|
|
774
810
|
const isCenturion = input.agent.name === "centurion";
|
|
811
|
+
// #281: only the ROOT session may dispatch a centurion.
|
|
812
|
+
//
|
|
813
|
+
// Every other guard here keys on the CHILD's role, so without this a worker
|
|
814
|
+
// could dispatch a centurion and silently acquire worktree + rpc isolation
|
|
815
|
+
// (measured: `subagent({agent:"centurion"})` from a worker launched on rpc
|
|
816
|
+
// with a fresh worktree). A centurion exists to own an isolated tree and its
|
|
817
|
+
// own team; nesting one inside another agent's turn produces a second
|
|
818
|
+
// command chain the root cannot collect, so it is refused rather than
|
|
819
|
+
// demoted — a demoted centurion can neither create a worktree nor do its job.
|
|
820
|
+
//
|
|
821
|
+
// Refused BEFORE any worktree/dir is created, so a rejected dispatch leaves
|
|
822
|
+
// no artifacts behind.
|
|
823
|
+
if (isCenturion && this.legion && this.legion.nodeId !== "root") {
|
|
824
|
+
throw new SubagentError(
|
|
825
|
+
`only the root session may dispatch a centurion; '${parentRole ?? this.legion.nodeId}' at '${this.legion.nodeId}' cannot`,
|
|
826
|
+
ErrorCodes.BUDGET_EXCEEDED,
|
|
827
|
+
);
|
|
828
|
+
}
|
|
775
829
|
// #214 D4: only centurion may hold worktree. Legion path still forces
|
|
776
830
|
// centurion→true and centurion-parent→member false; non-centurion
|
|
777
831
|
// requests from any source are demoted below (D1: warn, never throw).
|
|
@@ -794,19 +848,19 @@ export class Orchestrator {
|
|
|
794
848
|
this.warnWorktreeDenied(input.agent.name);
|
|
795
849
|
worktree = false;
|
|
796
850
|
}
|
|
797
|
-
// Spawn-mode arbitration
|
|
798
|
-
//
|
|
799
|
-
//
|
|
800
|
-
//
|
|
801
|
-
//
|
|
802
|
-
//
|
|
803
|
-
//
|
|
804
|
-
//
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
851
|
+
// Spawn-mode arbitration. Role cards no longer carry a `spawnMode` field:
|
|
852
|
+
// the backend is a property of the LAUNCH, not a role, so a card cannot pin
|
|
853
|
+
// itself to a process model. rpc exists for exactly one reason — it is the
|
|
854
|
+
// only backend that can host a worktree child — so the rule collapses to:
|
|
855
|
+
//
|
|
856
|
+
// worktree isolation ⇒ rpc; everything else ⇒ in-process.
|
|
857
|
+
//
|
|
858
|
+
// A centurion is the only role allowed to hold a worktree (#214), so it is
|
|
859
|
+
// also the only role that reaches rpc (#279). Nothing to deny here anymore:
|
|
860
|
+
// a non-centurion cannot request worktree in the first place (the guard
|
|
861
|
+
// above forces it false), and there is no card field left to smuggle a
|
|
862
|
+
// backend request through.
|
|
863
|
+
const mode: SpawnMode = worktree === true ? "rpc" : "inprocess";
|
|
810
864
|
const inProcess = mode === "inprocess";
|
|
811
865
|
// Downstream must see the arbitrated result, otherwise RoutingSupervisor
|
|
812
866
|
// re-resolves the omitted field to `inprocess` on its own and throws
|
|
@@ -822,12 +876,17 @@ export class Orchestrator {
|
|
|
822
876
|
// The `&& worktree` short-circuit keeps the rpc path returning the
|
|
823
877
|
// original object (invariant I3: zero diff on the RPC backend).
|
|
824
878
|
// reserveNode() and SpawnInput.agent below both receive this clone.
|
|
825
|
-
const agent: AgentConfig =
|
|
826
|
-
? input.agent
|
|
827
|
-
: { ...input.agent, spawnMode: mode, ...(worktree ? {} : { worktree: false }) };
|
|
879
|
+
const agent: AgentConfig = { ...input.agent, spawnMode: mode, ...(worktree ? {} : { worktree: false }) };
|
|
828
880
|
// A utility dispatch is a hard leaf, not a nested command-chain launch.
|
|
829
|
-
//
|
|
830
|
-
|
|
881
|
+
//
|
|
882
|
+
// #279: this check now covers EVERY backend. It used to be `!inProcess`,
|
|
883
|
+
// because #197 gave in-process its own `subagents.inprocess.*` buckets. But
|
|
884
|
+
// rpc is reserved for centurion, so every other role now runs in-process —
|
|
885
|
+
// leaving them unchecked here would mean "avoid rpc, escape the depth and
|
|
886
|
+
// per-session spawn ceilings", and a worker could nest without bound.
|
|
887
|
+
// The in-process supervisor still enforces its own `inprocess.*` limits;
|
|
888
|
+
// this is an additional floor, not a replacement.
|
|
889
|
+
if (!input.utilityDispatch) this.assertWithinBudgets(Boolean(previous));
|
|
831
890
|
if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
|
|
832
891
|
// D4: the name-occupancy check must cover QUEUED records too. `previous`
|
|
833
892
|
// deliberately ignores them (D3-a: its placeholder session path is not a resume
|
|
@@ -941,7 +1000,7 @@ export class Orchestrator {
|
|
|
941
1000
|
preCreateSessionFile(sessionFile);
|
|
942
1001
|
if (this.legion && nodeId) {
|
|
943
1002
|
const reservationRunId = createdRunId ?? (previous ? ledgerPrevious?.runId : undefined) ?? this.legion.runId;
|
|
944
|
-
reservedNode = this.reserveNode({ nodeId, name, agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
|
|
1003
|
+
reservedNode = this.reserveNode({ nodeId, name, agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models[0], utility: Boolean(input.utilityDispatch && input.agent.utility), inProcess });
|
|
945
1004
|
reserved = true;
|
|
946
1005
|
parentReservationCreated = await this.persistParentReservation({ nodeId, name, agent: input.agent, sessionFile, ...(models[0] ? { model: models[0] } : {}), ...(worktreePath ? { worktreePath } : {}) });
|
|
947
1006
|
}
|
|
@@ -994,6 +1053,17 @@ export class Orchestrator {
|
|
|
994
1053
|
allowNested: input.agent.allowNestedSubagents === true && !input.agent.utility,
|
|
995
1054
|
utility: Boolean(input.utilityDispatch && input.agent.utility),
|
|
996
1055
|
spawnMode: "inprocess" as const,
|
|
1056
|
+
// #295: the in-process child shares the HOST's process.env, so
|
|
1057
|
+
// `env` below never reaches its guard. Carry the budget here,
|
|
1058
|
+
// where the child context is the only channel that survives.
|
|
1059
|
+
...(() => {
|
|
1060
|
+
const budget = {
|
|
1061
|
+
...(agent.toolBudget?.maxToolCalls !== undefined ? { maxToolCalls: agent.toolBudget.maxToolCalls } : {}),
|
|
1062
|
+
...(agent.turnBudget?.maxTurns !== undefined ? { maxTurns: agent.turnBudget.maxTurns } : {}),
|
|
1063
|
+
...(agent.toolTimeoutMs !== undefined ? { toolTimeoutMs: agent.toolTimeoutMs } : {}),
|
|
1064
|
+
};
|
|
1065
|
+
return Object.keys(budget).length > 0 ? { budget } : {};
|
|
1066
|
+
})(),
|
|
997
1067
|
},
|
|
998
1068
|
}
|
|
999
1069
|
: {}),
|
|
@@ -1137,14 +1207,14 @@ export class Orchestrator {
|
|
|
1137
1207
|
* skips the *queue*, never `assertWithinLimits` / `withLaunchBudget` (I-O1). A
|
|
1138
1208
|
* launch that still loses the real gate is re-queued instead of failing (D2-c).
|
|
1139
1209
|
*/
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1210
|
+
|
|
1211
|
+
/**
|
|
1212
|
+
* The legion ledger gate, shared by the rpc and in-process admission paths
|
|
1213
|
+
* (#279). Read-only (`checkLaunchBudget`), never `withLaunchBudget` — a probe
|
|
1214
|
+
* must not insert a `starting` row (R3/F10) and must not emit
|
|
1215
|
+
* `budget_refused`, which belongs to `reserveNode` (D1-b).
|
|
1216
|
+
*/
|
|
1217
|
+
private probeLedgerAdmission(name: string, ctx: AdmissionProbeContext): ReturnType<Orchestrator["probeAdmission"]> {
|
|
1148
1218
|
// rpc/legion: the ledger gate. Read-only (`checkLaunchBudget`), never
|
|
1149
1219
|
// `withLaunchBudget` — a probe must not insert a `starting` row (R3/F10) and
|
|
1150
1220
|
// must not emit `budget_refused`, which belongs to `reserveNode` (D1-b).
|
|
@@ -1202,10 +1272,33 @@ export class Orchestrator {
|
|
|
1202
1272
|
}
|
|
1203
1273
|
return { admitted: true };
|
|
1204
1274
|
}
|
|
1205
|
-
|
|
1275
|
+
|
|
1206
1276
|
return { admitted: true };
|
|
1207
1277
|
}
|
|
1208
1278
|
|
|
1279
|
+
private probeAdmission(name: string, ctx: AdmissionProbeContext): AdmissionVerdict {
|
|
1280
|
+
if (ctx.inProcess) {
|
|
1281
|
+
// #279: the ledger floor applies to in-process launches too. It used to be
|
|
1282
|
+
// skipped entirely (#197 gave in-process unlimited ledger headroom), but
|
|
1283
|
+
// rpc is now reserved for centurion — so "skip the ledger" would
|
|
1284
|
+
// mean every non-centurion role escapes `maxChildrenPerNode` /
|
|
1285
|
+
// `maxActiveNodes`. `reserveNode` already charges these slots, so without
|
|
1286
|
+
// this probe the launch is REFUSED there after admission was granted here.
|
|
1287
|
+
//
|
|
1288
|
+
// Two gates now apply and the stricter wins: this ledger check (fanout /
|
|
1289
|
+
// active / depth) plus the `inprocess.*` pools probed below.
|
|
1290
|
+
const ledgerVerdict = this.probeLedgerAdmission(name, ctx);
|
|
1291
|
+
if (ledgerVerdict.admitted !== true) return ledgerVerdict;
|
|
1292
|
+
const probe = inProcessProbeOf(this.supervisor);
|
|
1293
|
+
// No readable counts (a test double) → nothing to probe.
|
|
1294
|
+
if (!probe) return { admitted: true };
|
|
1295
|
+
const counts = probe.admissionCounts(name);
|
|
1296
|
+
return evaluateInProcessAdmission(counts, this.inflightFor(counts.parentKey, ctx));
|
|
1297
|
+
}
|
|
1298
|
+
return this.probeLedgerAdmission(name, ctx);
|
|
1299
|
+
|
|
1300
|
+
}
|
|
1301
|
+
|
|
1209
1302
|
/**
|
|
1210
1303
|
* The process-level queue for this run directory (§13.6 / I-O6).
|
|
1211
1304
|
*
|
|
@@ -1955,7 +2048,7 @@ export class Orchestrator {
|
|
|
1955
2048
|
|
|
1956
2049
|
private requireChild(name: string): ChildRecord {
|
|
1957
2050
|
const child = this.children.get(name);
|
|
1958
|
-
if (!child) throw
|
|
2051
|
+
if (!child) throw unknownChildError(name);
|
|
1959
2052
|
return child;
|
|
1960
2053
|
}
|
|
1961
2054
|
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Renewal progress signal (subagent-renewal contract v1, W1 / D2 + D2-a + D8).
|
|
3
|
+
*
|
|
4
|
+
* Answers exactly one question: *since the last renewal baseline, did the child
|
|
5
|
+
* produce observable output?* Only output signals count (session JSONL rows and
|
|
6
|
+
* worktree file changes) — process liveness, CPU time and token spend are
|
|
7
|
+
* explicitly excluded (§7-3: they also grow while a child loops on failure).
|
|
8
|
+
*
|
|
9
|
+
* Measured session shape (`.pi-subagents/runs/<run>/<child>.jsonl`): every row
|
|
10
|
+
* is `{"type":"message","id","parentId","timestamp","message":{"role",...}}`
|
|
11
|
+
* where `message.role` is `assistant` / `toolResult` / `user` / `system`.
|
|
12
|
+
* Top-level `type` is `message`, so the row kind lives in `message.role`; a
|
|
13
|
+
* legacy flat `{"type":"toolResult"}` row is accepted too.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import * as fs from "node:fs";
|
|
17
|
+
|
|
18
|
+
/** A renewal point: when it was taken plus the session line count then (D8). */
|
|
19
|
+
export interface ProgressBaseline {
|
|
20
|
+
/** Unix ms when this baseline was taken (D8). */
|
|
21
|
+
readonly at: number;
|
|
22
|
+
/** Session JSONL line count at baseline time. */
|
|
23
|
+
readonly lines: number;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface ProgressMeasure {
|
|
27
|
+
/** New `toolResult` rows since the baseline (strongest evidence — a tool returned). */
|
|
28
|
+
readonly toolResults: number;
|
|
29
|
+
/** New assistant messages since the baseline. */
|
|
30
|
+
readonly assistantMessages: number;
|
|
31
|
+
/** Files created/modified in the worktree since the baseline, when measurable. */
|
|
32
|
+
readonly filesChanged: number | undefined;
|
|
33
|
+
/** D2-a: does this count as "real progress"? */
|
|
34
|
+
readonly progressed: boolean;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** D2-a thresholds, exported so tests and docs cannot drift. */
|
|
38
|
+
export const PROGRESS_MIN_TOOL_RESULTS = 3;
|
|
39
|
+
export const PROGRESS_MIN_FILES_CHANGED = 1;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Default line reader: the file's raw lines, or `undefined` when unreadable.
|
|
43
|
+
* Never throws — a child that was killed mid-write leaves a torn final line,
|
|
44
|
+
* and a missing file is a normal "nothing to measure" state.
|
|
45
|
+
*/
|
|
46
|
+
export function readSessionLines(file: string): string[] | undefined {
|
|
47
|
+
let text: string;
|
|
48
|
+
try {
|
|
49
|
+
text = fs.readFileSync(file, "utf8");
|
|
50
|
+
} catch {
|
|
51
|
+
return undefined;
|
|
52
|
+
}
|
|
53
|
+
return splitLines(text);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Split on `\n`, dropping the phantom element a trailing newline produces so
|
|
58
|
+
* the count matches "number of lines written". A torn tail without a trailing
|
|
59
|
+
* newline is kept (the parser skips it).
|
|
60
|
+
*/
|
|
61
|
+
function splitLines(text: string): string[] {
|
|
62
|
+
const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
|
|
63
|
+
if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
|
|
64
|
+
return lines;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Row kind, or `undefined` for non-message / malformed rows. */
|
|
68
|
+
function rowKind(line: string): "assistant" | "toolResult" | undefined {
|
|
69
|
+
const trimmed = line.trim();
|
|
70
|
+
if (!trimmed) return undefined;
|
|
71
|
+
let decoded: unknown;
|
|
72
|
+
try {
|
|
73
|
+
decoded = JSON.parse(trimmed);
|
|
74
|
+
} catch {
|
|
75
|
+
// Torn line, or a non-JSON header: skip, never throw.
|
|
76
|
+
return undefined;
|
|
77
|
+
}
|
|
78
|
+
if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) return undefined;
|
|
79
|
+
const event = decoded as Record<string, unknown>;
|
|
80
|
+
// Measured shape: {type:"message", message:{role}}.
|
|
81
|
+
const message = event.message;
|
|
82
|
+
if (message && typeof message === "object" && !Array.isArray(message)) {
|
|
83
|
+
const role = (message as Record<string, unknown>).role;
|
|
84
|
+
if (role === "assistant") return "assistant";
|
|
85
|
+
if (role === "toolResult") return "toolResult";
|
|
86
|
+
}
|
|
87
|
+
// Legacy flat shape: {type:"toolResult"} / {type:"assistant"}.
|
|
88
|
+
if (event.type === "assistant") return "assistant";
|
|
89
|
+
if (event.type === "toolResult") return "toolResult";
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** Non-negative integer, or `undefined` when the counter is not measurable. */
|
|
94
|
+
function normalizeCount(value: number | undefined): number | undefined {
|
|
95
|
+
if (value === undefined || !Number.isFinite(value)) return undefined;
|
|
96
|
+
return Math.max(0, Math.floor(value));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Measure progress since `baseline`. Rows at or before `baseline.lines` are
|
|
101
|
+
* history and are never counted (D8).
|
|
102
|
+
*
|
|
103
|
+
* `progressed` follows D2-a exactly:
|
|
104
|
+
* `toolResults >= PROGRESS_MIN_TOOL_RESULTS || filesChanged >= PROGRESS_MIN_FILES_CHANGED`,
|
|
105
|
+
* with an unmeasurable `filesChanged` dropping out of the comparison.
|
|
106
|
+
*/
|
|
107
|
+
export function measureProgress(input: {
|
|
108
|
+
sessionFile: string;
|
|
109
|
+
baseline: ProgressBaseline;
|
|
110
|
+
/** Injectable for tests: returns the session file's raw lines, or undefined when unreadable. */
|
|
111
|
+
readLines?: (file: string) => string[] | undefined;
|
|
112
|
+
/** Injectable: count of changed files in the worktree, or undefined when not measurable. */
|
|
113
|
+
countFilesChanged?: () => number | undefined;
|
|
114
|
+
}): ProgressMeasure {
|
|
115
|
+
const lines = (input.readLines ?? readSessionLines)(input.sessionFile);
|
|
116
|
+
const filesChanged = normalizeCount(input.countFilesChanged?.());
|
|
117
|
+
if (!lines) return { toolResults: 0, assistantMessages: 0, filesChanged, progressed: hasFileProgress(filesChanged) };
|
|
118
|
+
|
|
119
|
+
// Baseline beyond the current file (truncated/rotated): nothing is new.
|
|
120
|
+
const start = Math.max(0, Math.min(normalizeCount(input.baseline.lines) ?? 0, lines.length));
|
|
121
|
+
let toolResults = 0;
|
|
122
|
+
let assistantMessages = 0;
|
|
123
|
+
for (let i = start; i < lines.length; i += 1) {
|
|
124
|
+
const kind = rowKind(lines[i] ?? "");
|
|
125
|
+
if (kind === "toolResult") toolResults += 1;
|
|
126
|
+
else if (kind === "assistant") assistantMessages += 1;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
const progressed = toolResults >= PROGRESS_MIN_TOOL_RESULTS || hasFileProgress(filesChanged);
|
|
130
|
+
|
|
131
|
+
return { toolResults, assistantMessages, filesChanged, progressed };
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** D2-a's file half; an unmeasurable count never counts as progress. */
|
|
135
|
+
function hasFileProgress(filesChanged: number | undefined): boolean {
|
|
136
|
+
return filesChanged !== undefined && filesChanged >= PROGRESS_MIN_FILES_CHANGED;
|
|
137
|
+
}
|