pi-legion 0.16.0 → 2.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/CONTRIBUTING.md +58 -0
- package/README.md +313 -640
- package/agents/advisor.md +7 -5
- package/agents/centurion.md +53 -0
- package/agents/designer.md +33 -33
- package/agents/planner.md +1 -2
- package/agents/prototype.md +2 -2
- package/agents/reviewer.md +67 -31
- package/agents/scout.md +6 -2
- package/agents/worker.md +12 -3
- package/docs/contracts/esc-abort-v1.md +131 -0
- package/docs/contracts/esc-cascade-v2.md +100 -0
- package/docs/design.md +44 -25
- package/docs/legion-v2-contract.md +461 -0
- package/docs/legion-v2-delivery.md +62 -0
- package/docs/retire-hardening-contract.md +125 -0
- package/docs/subagents-teams.md +76 -0
- package/docs/tui-viewer-contract.md +276 -0
- package/docs/vexillatio-contract.md +162 -0
- package/index.ts +1462 -286
- package/package.json +12 -9
- package/skills/pi-legion/SKILL.md +74 -96
- package/src/agents/agents.ts +6 -11
- package/src/agents/overrides.ts +2 -1
- package/src/agents/paths.ts +1 -1
- package/src/agents/settings.ts +268 -20
- package/src/api.ts +47 -48
- package/src/{herdr → backends/legacy}/client.ts +14 -69
- package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
- package/src/{herdr → backends/legacy}/runner.ts +22 -9
- package/src/backends/legacy/types.ts +138 -0
- package/src/extension/auto-doctor.ts +144 -0
- package/src/extension/budget.ts +2 -2
- package/src/extension/child-guard.ts +214 -201
- package/src/extension/event-bus.ts +263 -0
- package/src/extension/legion-commands.ts +719 -0
- package/src/extension/legion-doctor.ts +888 -0
- package/src/extension/legion-stop.ts +150 -0
- package/src/extension/legion-tools.ts +816 -0
- package/src/extension/notify.ts +24 -19
- package/src/extension/playbook.ts +20 -89
- package/src/extension/recycle.ts +2 -7
- package/src/extension/runtime.ts +655 -105
- package/src/extension/scout-guard.ts +483 -0
- package/src/extension/slash.ts +89 -438
- package/src/extension/spawn-hints.ts +79 -0
- package/src/extension/summary.ts +17 -58
- package/src/legion/budget.ts +165 -0
- package/src/legion/db.ts +242 -0
- package/src/legion/events.ts +150 -0
- package/src/legion/mail.ts +412 -0
- package/src/legion/nodes.ts +461 -0
- package/src/legion/rebuild.ts +533 -0
- package/src/legion/state-machine.ts +313 -0
- package/src/legion/usage.ts +101 -0
- package/src/runs/acceptance.ts +82 -25
- package/src/runs/args.ts +51 -5
- package/src/runs/hygiene.ts +335 -0
- package/src/runs/orchestrator.ts +790 -1683
- package/src/runs/owner.ts +61 -0
- package/src/runs/provision.ts +135 -0
- package/src/runs/store.ts +44 -17
- package/src/runs/verify-queue.ts +195 -0
- package/src/shared/name.ts +29 -0
- package/src/shared/output-cap.ts +57 -0
- package/src/shared/progress.ts +57 -135
- package/src/shared/session.ts +243 -171
- package/src/shared/types.ts +107 -208
- package/src/supervisor/child-memory.ts +140 -0
- package/src/supervisor/proc-tree.ts +103 -0
- package/src/supervisor/rpc-supervisor.ts +1033 -0
- package/src/supervisor/types.ts +153 -0
- package/src/supervisor/ui-proxy.ts +226 -0
- package/src/tui/chat-items.ts +330 -0
- package/src/tui/live-overlay.ts +874 -0
- package/src/tui/status.ts +553 -27
- package/src/tui/tree-view.ts +808 -0
- package/src/tui/viz/canvas.ts +119 -0
- package/src/tui/viz/layout.ts +111 -0
- package/src/tui/viz/model.ts +123 -0
- package/src/tui/viz/palette.ts +188 -0
- package/src/tui/viz/panels.ts +530 -0
- package/src/tui/viz/railway.ts +313 -0
- package/src/tui/viz/rate.ts +211 -0
- package/src/tui/viz/view.ts +228 -0
- package/src/extension/parent-label.ts +0 -115
- package/src/profiles/classify.ts +0 -375
- package/src/profiles/profiles.ts +0 -730
- package/src/runs/layout.ts +0 -258
package/src/runs/orchestrator.ts
CHANGED
|
@@ -1,29 +1,26 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Single-run orchestration over the RPC supervisor.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* F8 — `agent wait` covers a turn
|
|
8
|
-
* F11 — clean exit is ctrl+d, NOT ctrl+c
|
|
9
|
-
* F15 — `tab close` reaps everything atomically
|
|
10
|
-
* F19 — `agent_pane_busy` race after a split; retry with backoff
|
|
11
|
-
* F21 — errors arrive on stderr
|
|
12
|
-
* F22 — a missing binary looks like a start timeout
|
|
13
|
-
* F26 — `agent_status` cannot tell success from failure
|
|
14
|
-
* F27 — after exit the agent is gone; collect BEFORE recycle or lose the outcome
|
|
15
|
-
* F29 — a hard kill leaves no assistant message
|
|
4
|
+
* Process lifecycle belongs to LegionSupervisor. Session JSONL remains the
|
|
5
|
+
* sole source of execution outcomes; this module owns run records, budgets,
|
|
6
|
+
* lineage, acceptance and worktree setup.
|
|
16
7
|
*/
|
|
17
8
|
|
|
18
9
|
import * as fs from "node:fs";
|
|
19
10
|
import { randomBytes } from "node:crypto";
|
|
20
11
|
import * as path from "node:path";
|
|
21
|
-
import {
|
|
22
|
-
import {
|
|
23
|
-
import {
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
} from "
|
|
12
|
+
import { modelCandidates } from "../agents/model-resolution.ts";
|
|
13
|
+
import { DEFAULT_TEAM, TEAM_ENV, type ActiveTeam } from "../agents/teams.ts";
|
|
14
|
+
import type { LegionSettings } from "../shared/types.ts";
|
|
15
|
+
import { LEGION_DB_ENV, LEGION_IDENTITY_ENV_KEYS, LEGION_NODE_ID_ENV, legionIdentityEnv } from "./args.ts";
|
|
16
|
+
import type { DatabaseSync } from "../legion/db.ts";
|
|
17
|
+
import type { RunStore } from "./store.ts";
|
|
18
|
+
import type { LegionEventBus, LegionProcessEventType } from "../extension/event-bus.ts";
|
|
19
|
+
import { appendEvent } from "../legion/events.ts";
|
|
20
|
+
import { withLaunchBudget, type LegionBudgetLimits } from "../legion/budget.ts";
|
|
21
|
+
import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode } from "../legion/nodes.ts";
|
|
22
|
+
import { upsertUsage } from "../legion/usage.ts";
|
|
23
|
+
import { evaluatePhaseTransition, isLegionPhase, isTerminalPhase } from "../legion/state-machine.ts";
|
|
27
24
|
import { CHILD_ACCEPTANCE_ROLE_ENV, CHILD_ROLE_ENV } from "../extension/child-guard.ts";
|
|
28
25
|
import {
|
|
29
26
|
ALLOW_NESTED_ENV,
|
|
@@ -31,134 +28,88 @@ import {
|
|
|
31
28
|
MAX_TURNS_ENV,
|
|
32
29
|
TOOL_TIMEOUT_MS_ENV,
|
|
33
30
|
} from "../extension/budget.ts";
|
|
34
|
-
import {
|
|
35
|
-
import {
|
|
36
|
-
DEFAULT_TEAM,
|
|
37
|
-
TEAM_ENV,
|
|
38
|
-
type ActiveTeam,
|
|
39
|
-
} from "../agents/teams.ts";
|
|
40
|
-
import { nativeModelFor } from "./kind.ts";
|
|
31
|
+
import { canUseCachedCollect } from "../extension/recycle.ts";
|
|
41
32
|
import {
|
|
42
33
|
countAssistantMessages,
|
|
43
34
|
deriveOutcome,
|
|
44
|
-
isLastTurnComplete,
|
|
45
|
-
parseSessionFile,
|
|
46
35
|
emptyParsedSession,
|
|
47
36
|
extractVerdict,
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
stripPromptEcho,
|
|
37
|
+
isLastTurnComplete,
|
|
38
|
+
isTransientConnectionFailure,
|
|
39
|
+
parseSessionFile,
|
|
52
40
|
} from "../shared/session.ts";
|
|
41
|
+
import { encodeNestedPath, parseNestedPathEnv } from "../shared/nested-path.ts";
|
|
42
|
+
import { makeName } from "../shared/name.ts";
|
|
53
43
|
import {
|
|
54
|
-
cursorTurnSettled,
|
|
55
|
-
findCursorChatDir,
|
|
56
|
-
parseCursorChat,
|
|
57
|
-
} from "../shared/cursor-chat.ts";
|
|
58
|
-
import {
|
|
59
|
-
type AgentConfig,
|
|
60
|
-
type AgentKind,
|
|
61
44
|
type AcceptanceResult,
|
|
45
|
+
type AgentConfig,
|
|
62
46
|
type ChildRecord,
|
|
63
47
|
DEFAULTS,
|
|
64
48
|
ErrorCodes,
|
|
65
49
|
type Execution,
|
|
66
50
|
type Handle,
|
|
67
|
-
type HerdrClient,
|
|
68
51
|
MAX_NESTED_PATH_ENTRIES,
|
|
69
52
|
type ModelOrigin,
|
|
70
53
|
type NestedPathEntry,
|
|
71
|
-
type Placement,
|
|
72
54
|
type RunRecord,
|
|
73
55
|
SubagentError,
|
|
74
56
|
type Usage,
|
|
75
57
|
} from "../shared/types.ts";
|
|
76
|
-
import {
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
progressFromSession,
|
|
81
|
-
type LiveProgress,
|
|
82
|
-
} from "../shared/progress.ts";
|
|
58
|
+
import { RpcSupervisor } from "../supervisor/rpc-supervisor.ts";
|
|
59
|
+
import type { LegionSupervisor, SettleResult, SpawnInput } from "../supervisor/types.ts";
|
|
60
|
+
import type { PendingUIRequest, UIProxy } from "../supervisor/ui-proxy.ts";
|
|
61
|
+
import { nativeModelFor } from "./kind.ts";
|
|
83
62
|
import { applyVerification, type VerifyRunner } from "./acceptance.ts";
|
|
84
|
-
import { planKindStart } from "./kind.ts";
|
|
85
|
-
import { canUseCachedCollect } from "../extension/recycle.ts";
|
|
86
63
|
import {
|
|
87
64
|
createChildWorktree,
|
|
88
65
|
removeChildWorktree,
|
|
89
66
|
resolveLaunchWorktree,
|
|
90
67
|
} from "./worktree.ts";
|
|
91
|
-
import {
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
type
|
|
95
|
-
|
|
96
|
-
|
|
68
|
+
import { provisionWorktree } from "./provision.ts";
|
|
69
|
+
|
|
70
|
+
export interface BudgetRefusedEvent {
|
|
71
|
+
type: "budget_refused";
|
|
72
|
+
requestedMaxDepth: number;
|
|
73
|
+
effectiveMaxDepth: number;
|
|
74
|
+
reason: string;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export interface OrchestratorLegionContext {
|
|
78
|
+
db: DatabaseSync;
|
|
79
|
+
dbPath: string;
|
|
80
|
+
nodeId: string;
|
|
81
|
+
parentNodeId?: string | null;
|
|
82
|
+
parentRunId?: string | null;
|
|
83
|
+
runId?: string;
|
|
84
|
+
runStore?: RunStore;
|
|
85
|
+
settings?: LegionSettings;
|
|
86
|
+
eventBus?: Pick<LegionEventBus, "emit">;
|
|
87
|
+
}
|
|
97
88
|
|
|
98
89
|
export interface OrchestratorDeps {
|
|
99
|
-
|
|
100
|
-
|
|
90
|
+
supervisor?: LegionSupervisor;
|
|
91
|
+
uiProxy?: UIProxy;
|
|
101
92
|
runDir: string;
|
|
102
|
-
/** Working directory for child agents. */
|
|
103
93
|
cwd: string;
|
|
104
|
-
|
|
94
|
+
legion?: OrchestratorLegionContext;
|
|
105
95
|
onChildUpdate?: (child: ChildRecord) => void;
|
|
106
|
-
/** Injected for tests. */
|
|
107
96
|
now?: () => number;
|
|
108
97
|
sleep?: (ms: number) => Promise<void>;
|
|
109
|
-
startRetries?: number;
|
|
110
|
-
startRetryBackoffMs?: number;
|
|
111
|
-
startTimeoutMs?: number;
|
|
112
|
-
/**
|
|
113
|
-
* Lineage of THIS process, read from the environment when running as a
|
|
114
|
-
* child. Appended to when spawning children so a grandchild knows its full
|
|
115
|
-
* ancestry (design §4.2).
|
|
116
|
-
*/
|
|
117
98
|
parentPath?: NestedPathEntry[];
|
|
118
|
-
/** Hard ceiling on nesting depth; launches beyond it are refused. */
|
|
119
99
|
maxDepth?: number;
|
|
120
|
-
/**
|
|
121
|
-
* Maximum children this orchestrator may spawn. Enforces
|
|
122
|
-
* `subagents.maxSubagentSpawnsPerSession` so a runaway fan-out cannot
|
|
123
|
-
* exhaust the machine. `null`/undefined means unlimited.
|
|
124
|
-
*/
|
|
125
100
|
maxSpawns?: number | null;
|
|
126
|
-
/**
|
|
127
|
-
* Session-wide tab/name registry. Same agent type shares one tab (each
|
|
128
|
-
* child a pane). The extension passes one instance so parallel tool calls
|
|
129
|
-
* cannot each create a tab; tests omit it and get an isolated registry.
|
|
130
|
-
*/
|
|
131
|
-
layout?: SessionLayout;
|
|
132
|
-
/** Injected so tests do not actually run `npm test`. */
|
|
133
101
|
verifyRunner?: VerifyRunner;
|
|
134
|
-
/**
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
*/
|
|
138
|
-
workspaceId?: string;
|
|
139
|
-
/**
|
|
140
|
-
* Parent Pi's herdr pane (`HERDR_PANE_ID`). Scopes the type-tab label so
|
|
141
|
-
* another parent in the same Space does not adopt this tab.
|
|
142
|
-
*/
|
|
143
|
-
parentPaneId?: string;
|
|
144
|
-
/** Active team selection to inherit into child panes. */
|
|
102
|
+
/** Post-create bootstrap for child worktrees (legion.worktreeBootstrap). */
|
|
103
|
+
worktreeBootstrap?: string;
|
|
104
|
+
worktreeBootstrapTimeoutMs?: number;
|
|
145
105
|
team?: ActiveTeam;
|
|
146
|
-
/**
|
|
147
|
-
* Extra child-side context from `subagents.childContext`, appended to
|
|
148
|
-
* every child's system prompt after the role prompt.
|
|
149
|
-
*/
|
|
150
106
|
childContext?: string;
|
|
151
|
-
|
|
152
|
-
* Root of the cursor chat stores, overriding `~/.cursor/chats` — injects
|
|
153
|
-
* the fake's store root in tests.
|
|
154
|
-
*/
|
|
155
|
-
cursorChatsRoot?: string;
|
|
107
|
+
onBudgetRefused?: (event: BudgetRefusedEvent) => void;
|
|
156
108
|
}
|
|
157
109
|
|
|
158
110
|
export interface CollectResult {
|
|
159
111
|
execution: Execution;
|
|
160
112
|
output: string;
|
|
161
|
-
/** Full output persisted to disk (`.output.md` in the run dir), when any. */
|
|
162
113
|
outputFile?: string;
|
|
163
114
|
usage: Usage | null;
|
|
164
115
|
model: string | null;
|
|
@@ -166,75 +117,38 @@ export interface CollectResult {
|
|
|
166
117
|
blocked?: boolean;
|
|
167
118
|
}
|
|
168
119
|
|
|
169
|
-
/**
|
|
170
|
-
* How many times a collect may push its deadline past the caller's timeout when
|
|
171
|
-
* the child's artifact is still growing (D). Total wait ≤ (1 + N) × timeoutMs.
|
|
172
|
-
*
|
|
173
|
-
* A hard-killed child writes nothing (F29), so a growing file is positive
|
|
174
|
-
* evidence of a live, still-writing turn — reporting `running` for it was the
|
|
175
|
-
* false-timeout that made the parent think a healthy worker had stalled.
|
|
176
|
-
*/
|
|
177
120
|
export const COLLECT_GRACE_EXTENSIONS = 2;
|
|
178
|
-
|
|
179
|
-
|
|
121
|
+
/** Shown when the launch-time collect budget elapses and the child is still in-turn. */
|
|
122
|
+
export const COLLECT_DEADLINE_REASON = "collect deadline (cumulative since launch) exceeded; child still alive";
|
|
123
|
+
/** Shown when a live child's session ends on an OpenAI/GPT connection blip. */
|
|
124
|
+
export const TRANSIENT_CONNECTION_REASON = "transient connection error; RPC child still alive";
|
|
180
125
|
const LINEAGE_ENV = "PI_SUBAGENT_PARENT_PATH";
|
|
181
|
-
/** Environment variable carrying the depth ceiling into a child process. */
|
|
182
126
|
const MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
|
|
183
|
-
|
|
127
|
+
const UTILITY_CHILD_ENV = "PI_SUBAGENT_UTILITY_CHILD";
|
|
184
128
|
const CHILD_ENV = "PI_SUBAGENT_CHILD";
|
|
129
|
+
const POLL_INTERVAL_MS = 500;
|
|
185
130
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
* Whether an `agent get` result definitively reports the agent as gone.
|
|
191
|
-
*
|
|
192
|
-
* ONLY `NOT_FOUND` counts. A transport failure, a wedged or timed-out CLI
|
|
193
|
-
* (HERDR_ERROR from the command timeout) says nothing about the child: the
|
|
194
|
-
* agent may be perfectly alive while our control channel is broken. Callers
|
|
195
|
-
* that act on "gone" (aborted verdicts, retire, relaunch) MUST use this, or a
|
|
196
|
-
* host-side incident retires a live child (hw 2026-10-09).
|
|
197
|
-
*/
|
|
198
|
-
function agentGone(
|
|
199
|
-
res: { ok: true } | { ok: false; error: { code: string } },
|
|
200
|
-
): boolean {
|
|
201
|
-
return !res.ok && res.error.code === ErrorCodes.NOT_FOUND;
|
|
202
|
-
}
|
|
203
|
-
|
|
204
|
-
/**
|
|
205
|
-
* Await a teardown call whose failure is genuinely ignorable.
|
|
206
|
-
*
|
|
207
|
-
* Recycling is best-effort by design: a pane may already be gone, and the
|
|
208
|
-
* session file survives either way (F12). Spelling that intent once keeps the
|
|
209
|
-
* call sites free of `await x.catch(...)` chains, which mix two async styles
|
|
210
|
-
* and hide which failures matter.
|
|
211
|
-
*/
|
|
212
|
-
async function bestEffort(work: Promise<unknown>): Promise<void> {
|
|
213
|
-
try {
|
|
214
|
-
await work;
|
|
215
|
-
} catch {
|
|
216
|
-
/* teardown is best-effort */
|
|
217
|
-
}
|
|
131
|
+
function parseDepthCeiling(raw: string | undefined): number | undefined {
|
|
132
|
+
if (raw === undefined || !/^\d+$/.test(raw.trim())) return undefined;
|
|
133
|
+
const value = Number(raw.trim());
|
|
134
|
+
return Number.isInteger(value) && value >= 0 ? value : undefined;
|
|
218
135
|
}
|
|
219
136
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
return (
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
137
|
+
/** Root/process ceiling: inherited env, settings, and the saturated path cap. */
|
|
138
|
+
export function effectiveMaxDepth(settingsMaxDepth?: number): number {
|
|
139
|
+
return Math.min(
|
|
140
|
+
parseDepthCeiling(process.env[MAX_DEPTH_ENV]) ?? Number.POSITIVE_INFINITY,
|
|
141
|
+
settingsMaxDepth ?? Number.POSITIVE_INFINITY,
|
|
142
|
+
MAX_NESTED_PATH_ENTRIES,
|
|
226
143
|
);
|
|
227
144
|
}
|
|
228
145
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
* Crypto-safe: this token is the ownership proof persisted in run.json.
|
|
232
|
-
*/
|
|
146
|
+
const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
|
|
147
|
+
|
|
233
148
|
function ownerToken(): string {
|
|
234
149
|
return randomBytes(8).toString("hex");
|
|
235
150
|
}
|
|
236
151
|
|
|
237
|
-
/** Size of a collect artifact in bytes; 0 when missing or unreadable. */
|
|
238
152
|
function artifactSize(file: string): number {
|
|
239
153
|
try {
|
|
240
154
|
return fs.statSync(file).size;
|
|
@@ -243,17 +157,10 @@ function artifactSize(file: string): number {
|
|
|
243
157
|
}
|
|
244
158
|
}
|
|
245
159
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
* is exactly the signal that cannot be trusted (F32), so a self-report can only
|
|
251
|
-
* ever reach `attested` — never `verified`.
|
|
252
|
-
*
|
|
253
|
-
* L3 criteria are SEMANTIC (`must: "tests pass"`), so the runtime cannot decide
|
|
254
|
-
* them. Rather than silently dropping the checklist, it is carried forward for
|
|
255
|
-
* the caller to confirm; that is also why `verified` is never claimed here.
|
|
256
|
-
*/
|
|
160
|
+
function isApprovalRequest(request: PendingUIRequest): boolean {
|
|
161
|
+
return request.request.method === "confirm";
|
|
162
|
+
}
|
|
163
|
+
|
|
257
164
|
function deriveAcceptance(
|
|
258
165
|
parsed: ReturnType<typeof parseSessionFile>,
|
|
259
166
|
execution: Execution,
|
|
@@ -261,12 +168,7 @@ function deriveAcceptance(
|
|
|
261
168
|
opts: { completionGuard?: boolean } = {},
|
|
262
169
|
): AcceptanceResult {
|
|
263
170
|
let acceptance: AcceptanceResult = { status: "unknown", level: "none" };
|
|
264
|
-
// MUST read `lastTurnOutput`, not `output`: `output` is the last non-empty text
|
|
265
|
-
// anywhere in the session, so it survives into a turn that produced none — and
|
|
266
|
-
// a stale "ok" from an earlier turn would then be reported as
|
|
267
|
-
// accepted/attested while `execution` says aborted (F39).
|
|
268
171
|
const verdict = extractVerdict(parsed.lastTurnOutput ?? "");
|
|
269
|
-
|
|
270
172
|
if (verdict) {
|
|
271
173
|
acceptance = {
|
|
272
174
|
status: verdict.ok ? "accepted" : "rejected",
|
|
@@ -275,56 +177,20 @@ function deriveAcceptance(
|
|
|
275
177
|
};
|
|
276
178
|
} else if (execution.status === "success") {
|
|
277
179
|
acceptance = opts.completionGuard
|
|
278
|
-
? {
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
}
|
|
283
|
-
: {
|
|
284
|
-
status: "unknown",
|
|
285
|
-
level: "none",
|
|
286
|
-
reason: "no machine-readable verdict",
|
|
287
|
-
};
|
|
288
|
-
} else if (
|
|
289
|
-
execution.status === "unknown" ||
|
|
290
|
-
execution.status === "running"
|
|
291
|
-
) {
|
|
292
|
-
acceptance = {
|
|
293
|
-
status: "unknown",
|
|
294
|
-
level: "none",
|
|
295
|
-
reason: execution.reason ?? execution.status,
|
|
296
|
-
};
|
|
180
|
+
? { status: "rejected", level: "none", reason: 'completionGuard: missing {"ok": true|false} verdict' }
|
|
181
|
+
: { status: "unknown", level: "none", reason: "no machine-readable verdict" };
|
|
182
|
+
} else if (execution.status === "unknown" || execution.status === "running") {
|
|
183
|
+
acceptance = { status: "unknown", level: "none", reason: execution.reason ?? execution.status };
|
|
297
184
|
} else {
|
|
298
|
-
acceptance = {
|
|
299
|
-
status: "rejected",
|
|
300
|
-
level: "none",
|
|
301
|
-
reason: execution.reason ?? execution.status,
|
|
302
|
-
};
|
|
185
|
+
acceptance = { status: "rejected", level: "none", reason: execution.reason ?? execution.status };
|
|
303
186
|
}
|
|
304
|
-
|
|
305
187
|
if (pendingCriteria?.length) {
|
|
306
|
-
acceptance = {
|
|
307
|
-
...acceptance,
|
|
308
|
-
pendingCriteria: pendingCriteria.map((c) => ({ ...c })),
|
|
309
|
-
};
|
|
188
|
+
acceptance = { ...acceptance, pendingCriteria: pendingCriteria.map((criterion) => ({ ...criterion })) };
|
|
310
189
|
}
|
|
311
|
-
|
|
312
190
|
return acceptance;
|
|
313
191
|
}
|
|
314
192
|
|
|
315
|
-
/**
|
|
316
|
-
* Pre-create the session file (F4).
|
|
317
|
-
*
|
|
318
|
-
* pi creates session files lazily: a child that dies before its first flush
|
|
319
|
-
* leaves NO file, so there is nothing to resume. Creating it up front closes
|
|
320
|
-
* that window and is verified to not interfere with normal writes.
|
|
321
|
-
*/
|
|
322
|
-
/**
|
|
323
|
-
* Pre-create an empty session file (F4) so pi cannot lose the first turn.
|
|
324
|
-
*
|
|
325
|
-
* Reports a clear error when the directory is unusable: a bare `mkdirSync`
|
|
326
|
-
* surfaces as an opaque `ENOTDIR`/`EACCES` from deep inside the launcher.
|
|
327
|
-
*/
|
|
193
|
+
/** Pre-create an empty session file so the first Pi turn cannot be lost. */
|
|
328
194
|
export function preCreateSessionFile(file: string): void {
|
|
329
195
|
const dir = path.dirname(file);
|
|
330
196
|
try {
|
|
@@ -334,1705 +200,946 @@ export function preCreateSessionFile(file: string): void {
|
|
|
334
200
|
const code = (error as NodeJS.ErrnoException).code ?? "UNKNOWN";
|
|
335
201
|
throw new SubagentError(
|
|
336
202
|
`cannot write run artifacts to ${dir} (${code}). ` +
|
|
337
|
-
|
|
338
|
-
`to the subagent tool, or run from a checkout you can write to.`,
|
|
203
|
+
"Subagent runs need a writable cwd to write session data.",
|
|
339
204
|
ErrorCodes.INVALID_PARAMS,
|
|
340
205
|
{ dir },
|
|
341
206
|
);
|
|
342
207
|
}
|
|
343
208
|
}
|
|
344
209
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
210
|
+
function canFallbackStart(error: unknown): boolean {
|
|
211
|
+
return error instanceof SubagentError &&
|
|
212
|
+
error.code !== ErrorCodes.NOT_FOUND &&
|
|
213
|
+
error.code !== ErrorCodes.BUDGET_EXCEEDED &&
|
|
214
|
+
error.code !== ErrorCodes.NAME_TAKEN;
|
|
215
|
+
}
|
|
216
|
+
|
|
349
217
|
// pi-lens-ignore: large-class
|
|
350
218
|
export class Orchestrator {
|
|
351
|
-
private readonly
|
|
219
|
+
private readonly supervisor: LegionSupervisor;
|
|
220
|
+
private readonly uiProxy?: UIProxy;
|
|
352
221
|
private readonly runDir: string;
|
|
353
222
|
private readonly cwd: string;
|
|
354
|
-
/** Overridden in tests: the cursor chat-store root (`~/.cursor/chats`). */
|
|
355
|
-
private readonly cursorChatsRoot?: string;
|
|
356
223
|
private readonly onChildUpdate: (child: ChildRecord) => void;
|
|
357
224
|
private readonly now: () => number;
|
|
358
225
|
private readonly sleep: (ms: number) => Promise<void>;
|
|
359
|
-
private readonly startRetries: number;
|
|
360
|
-
private readonly startBackoff: number;
|
|
361
|
-
private readonly startTimeoutMs: number;
|
|
362
|
-
/** Poll interval while waiting for a turn to produce its first output. */
|
|
363
|
-
private readonly pollIntervalMs = 500;
|
|
364
|
-
/**
|
|
365
|
-
* Slice length for `agent wait`. A single remaining-timeout wait can hang
|
|
366
|
-
* after F15 `tab close` reaps the agent; slicing lets collect notice
|
|
367
|
-
* `agent_not_found` and abort instead of sitting until timeoutMs.
|
|
368
|
-
*/
|
|
369
|
-
private readonly waitSliceMs = 2_000;
|
|
370
|
-
/**
|
|
371
|
-
* Minimum gap between paste-submit Enters for one non-pi child. A swallowed
|
|
372
|
-
* nudge must be retried, but the TUI needs time to ingest the paste first —
|
|
373
|
-
* pressing faster than this just queues noise (measured on a live pane).
|
|
374
|
-
*/
|
|
375
|
-
private readonly nudgeIntervalMs = 1_500;
|
|
376
|
-
/** Per-child timestamp of the last paste-submit Enter. */
|
|
377
|
-
private readonly nudgeTimestamps = new Map<string, number>();
|
|
378
226
|
private readonly parentPath: NestedPathEntry[];
|
|
379
|
-
private readonly
|
|
227
|
+
private readonly maxDepthValue: number;
|
|
380
228
|
private readonly maxSpawns: number | null;
|
|
381
|
-
private readonly layout: SessionLayout;
|
|
382
229
|
private readonly verifyRunner?: VerifyRunner;
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
* places the tab in the UI-focused Space.
|
|
386
|
-
*/
|
|
387
|
-
private readonly workspaceId?: string;
|
|
388
|
-
/** Parent pane id used to uniquify type-tab labels across parent Pis. */
|
|
389
|
-
private readonly parentPaneId?: string;
|
|
230
|
+
private readonly worktreeBootstrap?: string;
|
|
231
|
+
private readonly worktreeBootstrapTimeoutMs?: number;
|
|
390
232
|
private readonly team?: ActiveTeam;
|
|
391
|
-
/** Extra child-side context from `subagents.childContext`. */
|
|
392
233
|
private readonly childContext?: string;
|
|
393
|
-
|
|
394
|
-
private readonly
|
|
395
|
-
|
|
396
|
-
private
|
|
234
|
+
private readonly onBudgetRefused?: (event: BudgetRefusedEvent) => void;
|
|
235
|
+
private readonly legion?: OrchestratorLegionContext;
|
|
236
|
+
private readonly requestedDepthCap?: number;
|
|
237
|
+
private depthWarningEmitted = false;
|
|
397
238
|
private spawned = 0;
|
|
398
239
|
private readonly children = new Map<string, ChildRecord>();
|
|
399
|
-
private readonly
|
|
240
|
+
private readonly nameCounter = new Map<string, number>();
|
|
241
|
+
private readonly pendingWaits = new Map<string, Promise<SettleResult>>();
|
|
400
242
|
|
|
401
243
|
constructor(deps: OrchestratorDeps) {
|
|
402
|
-
this.
|
|
244
|
+
this.supervisor = deps.supervisor ?? new RpcSupervisor();
|
|
245
|
+
const proxy = (this.supervisor as LegionSupervisor & { uiProxy?: UIProxy }).uiProxy;
|
|
246
|
+
this.uiProxy = deps.uiProxy ?? proxy;
|
|
403
247
|
this.runDir = deps.runDir;
|
|
404
248
|
this.cwd = deps.cwd;
|
|
405
|
-
this.cursorChatsRoot = deps.cursorChatsRoot;
|
|
406
249
|
this.onChildUpdate = deps.onChildUpdate ?? (() => {});
|
|
407
|
-
this.now = deps.now ??
|
|
250
|
+
this.now = deps.now ?? Date.now;
|
|
408
251
|
this.sleep = deps.sleep ?? defaultSleep;
|
|
409
|
-
this.
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
this.
|
|
415
|
-
|
|
416
|
-
this.maxDepth =
|
|
417
|
-
deps.maxDepth ??
|
|
418
|
-
Number(process.env[MAX_DEPTH_ENV]) ??
|
|
419
|
-
MAX_NESTED_PATH_ENTRIES;
|
|
420
|
-
if (!Number.isFinite(this.maxDepth) || this.maxDepth < 1)
|
|
421
|
-
this.maxDepth = MAX_NESTED_PATH_ENTRIES;
|
|
252
|
+
this.parentPath = deps.parentPath ?? parseNestedPathEnv(process.env[LINEAGE_ENV]);
|
|
253
|
+
const envDepth = parseDepthCeiling(process.env[MAX_DEPTH_ENV]);
|
|
254
|
+
const oversized = [deps.maxDepth, envDepth].filter(
|
|
255
|
+
(value): value is number => value !== undefined && value > MAX_NESTED_PATH_ENTRIES,
|
|
256
|
+
);
|
|
257
|
+
this.requestedDepthCap = oversized.length ? Math.max(...oversized) : undefined;
|
|
258
|
+
this.maxDepthValue = effectiveMaxDepth(deps.maxDepth);
|
|
422
259
|
this.maxSpawns = deps.maxSpawns ?? null;
|
|
423
|
-
this.layout = deps.layout ?? createSessionLayout();
|
|
424
260
|
this.verifyRunner = deps.verifyRunner;
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
this.workspaceId = rawWorkspaceId?.trim() || undefined;
|
|
428
|
-
const rawParentPaneId =
|
|
429
|
-
deps.parentPaneId ?? process.env.HERDR_PANE_ID;
|
|
430
|
-
this.parentPaneId = rawParentPaneId?.trim() || undefined;
|
|
261
|
+
this.worktreeBootstrap = deps.worktreeBootstrap?.trim() || undefined;
|
|
262
|
+
this.worktreeBootstrapTimeoutMs = deps.worktreeBootstrapTimeoutMs;
|
|
431
263
|
this.team = deps.team;
|
|
432
264
|
this.childContext = deps.childContext?.trim() || undefined;
|
|
265
|
+
this.onBudgetRefused = deps.onBudgetRefused;
|
|
266
|
+
this.legion = deps.legion;
|
|
433
267
|
}
|
|
434
268
|
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
return [
|
|
438
|
-
...this.parentPath,
|
|
439
|
-
{ runId: path.basename(this.runDir), agent: agentName },
|
|
440
|
-
].slice(-MAX_NESTED_PATH_ENTRIES);
|
|
441
|
-
}
|
|
269
|
+
get maxDepth(): number { return this.maxDepthValue; }
|
|
270
|
+
get depth(): number { return this.parentPath.length; }
|
|
442
271
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
272
|
+
childPath(agentName: string): NestedPathEntry[] {
|
|
273
|
+
return [...this.parentPath, { runId: path.basename(this.runDir), agent: agentName }]
|
|
274
|
+
.slice(-MAX_NESTED_PATH_ENTRIES);
|
|
446
275
|
}
|
|
447
276
|
|
|
448
277
|
sessionFileFor(name: string): string {
|
|
449
278
|
return path.join(this.runDir, `${name}.jsonl`);
|
|
450
279
|
}
|
|
451
280
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
*/
|
|
460
|
-
private async activeAgentNames(): Promise<Set<string>> {
|
|
461
|
-
const res = await this.client.agentList();
|
|
462
|
-
if (!res.ok) return new Set(); // best-effort: the retry path still covers us
|
|
463
|
-
const names = new Set<string>();
|
|
464
|
-
for (const agent of res.value) {
|
|
465
|
-
if (agent.name) names.add(agent.name);
|
|
281
|
+
allocateName(agentName: string): string {
|
|
282
|
+
const seen = this.nameCounter.get(agentName) ?? 0;
|
|
283
|
+
for (let index = seen; index < seen + 1000; index += 1) {
|
|
284
|
+
const candidate = makeName(agentName, index);
|
|
285
|
+
if (this.children.has(candidate) || this.supervisor.isAlive(candidate)) continue;
|
|
286
|
+
this.nameCounter.set(agentName, index + 1);
|
|
287
|
+
return candidate;
|
|
466
288
|
}
|
|
467
|
-
|
|
289
|
+
const fallback = makeName(agentName, seen);
|
|
290
|
+
this.nameCounter.set(agentName, seen + 1);
|
|
291
|
+
return fallback;
|
|
468
292
|
}
|
|
469
293
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
this.counter.set(agent, i + 1);
|
|
480
|
-
return candidate;
|
|
481
|
-
}
|
|
294
|
+
private allocateLegionName(agentName: string): string {
|
|
295
|
+
const legion = this.legion;
|
|
296
|
+
if (!legion) return this.allocateName(agentName);
|
|
297
|
+
const seen = this.nameCounter.get(agentName) ?? 0;
|
|
298
|
+
for (let index = seen; index < seen + 1_000; index += 1) {
|
|
299
|
+
const candidate = makeName(agentName, index);
|
|
300
|
+
if (this.children.has(candidate) || getChildByName(legion.db, legion.nodeId, candidate) || this.supervisor.isAlive(candidate)) continue;
|
|
301
|
+
this.nameCounter.set(agentName, index + 1);
|
|
302
|
+
return candidate;
|
|
482
303
|
}
|
|
483
|
-
|
|
484
|
-
return makeName(agent, seen);
|
|
304
|
+
throw new SubagentError(`could not allocate a unique child name for ${agentName}`, ErrorCodes.NAME_TAKEN);
|
|
485
305
|
}
|
|
486
306
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
307
|
+
private legionLocalName(name: string): string {
|
|
308
|
+
const prefix = `${this.legion?.nodeId}.`;
|
|
309
|
+
const local = name.startsWith(prefix) ? name.slice(prefix.length) : name;
|
|
310
|
+
return sanitizeNodeSlug(local);
|
|
490
311
|
}
|
|
491
312
|
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
*
|
|
499
|
-
* After a reload the in-memory registry is empty; we re-adopt by herdr
|
|
500
|
-
* tab label so a second scout still joins the scout tab.
|
|
501
|
-
*/
|
|
502
|
-
private async ensureTypeTab(
|
|
503
|
-
agentType: string,
|
|
504
|
-
env?: Record<string, string>,
|
|
505
|
-
cwd: string = this.cwd,
|
|
506
|
-
): Promise<{ tabId: string; rootPaneId: string }> {
|
|
507
|
-
const slot = await this.layout.acquireTypeTab(agentType, () =>
|
|
508
|
-
this.createOrAdoptTypeTab(agentType, env, cwd),
|
|
509
|
-
);
|
|
510
|
-
this.lastTypeTabId = slot.tabId;
|
|
511
|
-
return { tabId: slot.tabId, rootPaneId: slot.rootPaneId };
|
|
313
|
+
private childFromNode(name: string, node: LegionNode): ChildRecord {
|
|
314
|
+
if (node.status === "failed" || ["done", "failed", "aborted"].includes(node.phase ?? "")) {
|
|
315
|
+
throw new SubagentError(`legion child is terminal and cannot be resumed: ${node.id}`, ErrorCodes.BUDGET_EXCEEDED);
|
|
316
|
+
}
|
|
317
|
+
if (!node.sessionFile) throw new SubagentError(`legion child has no session to resume: ${node.id}`, ErrorCodes.NOT_FOUND);
|
|
318
|
+
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 } : {}) };
|
|
512
319
|
}
|
|
513
320
|
|
|
514
|
-
private
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
const
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
const res = await this.client.tabCreate({
|
|
524
|
-
cwd,
|
|
525
|
-
label,
|
|
526
|
-
...(env ? { env } : {}),
|
|
527
|
-
focus: false,
|
|
528
|
-
...(this.workspaceId ? { workspaceId: this.workspaceId } : {}),
|
|
529
|
-
});
|
|
530
|
-
if (!res.ok) {
|
|
531
|
-
throw new SubagentError(
|
|
532
|
-
`tab create failed: ${res.error.message}`,
|
|
533
|
-
res.error.code,
|
|
534
|
-
);
|
|
321
|
+
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 {
|
|
322
|
+
const legion = this.legion;
|
|
323
|
+
if (!legion) return null;
|
|
324
|
+
const parent = getNode(legion.db, legion.nodeId);
|
|
325
|
+
if (!parent) throw new SubagentError(`legion parent node not found: ${legion.nodeId}`, ErrorCodes.BUDGET_EXCEEDED);
|
|
326
|
+
const previous = getNode(legion.db, input.nodeId);
|
|
327
|
+
if (!previous && getChildByName(legion.db, legion.nodeId, input.name)) {
|
|
328
|
+
throw new SubagentError(`legion child already exists: ${input.name}`, ErrorCodes.NAME_TAKEN);
|
|
535
329
|
}
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
330
|
+
if (previous && (previous.status === "failed" || ["done", "failed", "aborted"].includes(previous.phase ?? ""))) {
|
|
331
|
+
throw new SubagentError(`legion child is terminal and cannot be resumed: ${input.nodeId}`, ErrorCodes.BUDGET_EXCEEDED);
|
|
332
|
+
}
|
|
333
|
+
const team = input.team ?? input.agent.extraFields?.team ?? this.team?.name;
|
|
334
|
+
// A utility node is a hard leaf and does not consume the recursive depth
|
|
335
|
+
// budget. Keep the real ledger depth, but allow this one generation.
|
|
336
|
+
const depthCeiling = input.utility
|
|
337
|
+
? parent.depth + 1
|
|
338
|
+
: Math.min(legion.settings?.maxDepth ?? this.maxDepthValue, MAX_NESTED_PATH_ENTRIES);
|
|
339
|
+
const childCount = Number(legion.db.prepare("SELECT COUNT(*) AS count FROM nodes WHERE parent_id = ?").get(legion.nodeId)?.count ?? 0);
|
|
340
|
+
const maxChildren = previous ? Math.max(legion.settings?.maxChildrenPerNode ?? 8, childCount + 1) : legion.settings?.maxChildrenPerNode;
|
|
341
|
+
const activeReservation = previous && (previous.status === "starting" || previous.status === "running") ? 1 : 0;
|
|
342
|
+
const limits: LegionBudgetLimits = { maxDepth: depthCeiling, maxChildrenPerNode: maxChildren, maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation };
|
|
343
|
+
const gate = withLaunchBudget(legion.db, { parentId: legion.nodeId, depth: parent.depth + 1, nodeId: input.nodeId }, () => {
|
|
344
|
+
if (previous) {
|
|
345
|
+
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);
|
|
346
|
+
return previous;
|
|
347
|
+
}
|
|
348
|
+
if (!input.runId) throw new SubagentError(`node run reservation is missing: ${input.nodeId}`, ErrorCodes.START_FAILED);
|
|
349
|
+
insertNode(legion.db, {
|
|
350
|
+
id: input.nodeId,
|
|
351
|
+
parentId: legion.nodeId,
|
|
352
|
+
name: input.name,
|
|
353
|
+
role: input.agent.name,
|
|
354
|
+
kind: input.agent.kind,
|
|
355
|
+
runId: input.runId,
|
|
356
|
+
sessionFile: input.sessionFile,
|
|
357
|
+
worktreePath: input.worktreePath ?? null,
|
|
358
|
+
model: input.model ?? null,
|
|
359
|
+
team: team && team !== DEFAULT_TEAM ? team : null,
|
|
360
|
+
status: "starting",
|
|
361
|
+
...(input.agent.name === "centurion" ? { phase: "planning", phaseSince: this.now() } : {}),
|
|
362
|
+
taskSummary: input.task.slice(0, 2_000),
|
|
363
|
+
}, this.now);
|
|
364
|
+
return null;
|
|
365
|
+
}, { limits, now: this.now });
|
|
366
|
+
if (!gate.allowed) {
|
|
367
|
+
this.legion?.eventBus?.emit({ nodeId: input.nodeId, type: "budget_refused", data: { reason: gate.decision.reason, message: gate.decision.message, depth: gate.decision.depth, activeNodes: gate.decision.activeNodes, children: gate.decision.children, limits: gate.decision.limits }, ts: this.now() });
|
|
368
|
+
throw new SubagentError(`legion launch refused (${gate.decision.reason}): ${gate.decision.message}`, ErrorCodes.BUDGET_EXCEEDED);
|
|
369
|
+
}
|
|
370
|
+
return gate.value;
|
|
540
371
|
}
|
|
541
372
|
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
373
|
+
private async persistParentReservation(input: { nodeId: string; name: string; agent: AgentConfig; sessionFile: string; team?: string; model?: string; worktreePath?: string }): Promise<boolean> {
|
|
374
|
+
const legion = this.legion;
|
|
375
|
+
const parentRunId = legion?.runId;
|
|
376
|
+
if (!legion?.runStore || !parentRunId) return false;
|
|
377
|
+
const run = legion.runStore.readRun(parentRunId);
|
|
378
|
+
if (!run) throw new SubagentError(`parent run record not found: ${parentRunId}`, ErrorCodes.NOT_FOUND);
|
|
379
|
+
const previous = run.children.find((child) => child.name === input.name);
|
|
380
|
+
if (previous) {
|
|
381
|
+
if (previous.nodeId !== input.nodeId) throw new SubagentError(`child name is already assigned to ${previous.nodeId ?? previous.name}`, ErrorCodes.NAME_TAKEN);
|
|
382
|
+
await legion.runStore.updateChild(parentRunId, input.name, (child) => {
|
|
383
|
+
child.sessionFile = input.sessionFile;
|
|
384
|
+
child.state = "launching";
|
|
385
|
+
child.spawnedAt = new Date(this.now()).toISOString();
|
|
386
|
+
child.agent = input.agent.name;
|
|
387
|
+
child.kind = input.agent.kind;
|
|
388
|
+
child.nodeId = input.nodeId;
|
|
389
|
+
if (input.model) child.model = input.model;
|
|
390
|
+
if (input.worktreePath) child.worktreePath = input.worktreePath;
|
|
391
|
+
});
|
|
392
|
+
return false;
|
|
393
|
+
}
|
|
394
|
+
await legion.runStore.addChild(parentRunId, {
|
|
395
|
+
name: input.name,
|
|
396
|
+
nodeId: input.nodeId,
|
|
397
|
+
sessionFile: input.sessionFile,
|
|
398
|
+
ownerToken: `legion-${input.nodeId}`,
|
|
399
|
+
state: "launching",
|
|
400
|
+
spawnedAt: new Date(this.now()).toISOString(),
|
|
401
|
+
agent: input.agent.name,
|
|
402
|
+
kind: input.agent.kind,
|
|
403
|
+
...(input.model ? { model: input.model } : {}),
|
|
404
|
+
...(input.worktreePath ? { worktreePath: input.worktreePath } : {}),
|
|
405
|
+
});
|
|
406
|
+
return true;
|
|
407
|
+
}
|
|
559
408
|
|
|
560
|
-
|
|
561
|
-
if (!
|
|
562
|
-
const
|
|
563
|
-
const
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
rootPaneId: root.pane_id,
|
|
568
|
-
rootOccupied: true,
|
|
569
|
-
panes: inTab.map((p) => p.pane_id),
|
|
570
|
-
};
|
|
409
|
+
private recordLegionLaunch(child: ChildRecord, agent: AgentConfig, task: string, teamOverride: string | undefined, resumed: boolean): void {
|
|
410
|
+
if (!this.legion || !child.nodeId) return;
|
|
411
|
+
const team = teamOverride ?? agent.extraFields?.team ?? this.team?.name;
|
|
412
|
+
const current = getNode(this.legion.db, child.nodeId);
|
|
413
|
+
const childRun = current?.runId ?? this.legion.runId ?? path.basename(this.runDir);
|
|
414
|
+
updateNode(this.legion.db, child.nodeId, { status: "running", runId: childRun, sessionFile: child.sessionFile, worktreePath: child.worktreePath ?? null, model: child.model ?? null, team: team && team !== DEFAULT_TEAM ? team : null, taskSummary: task.slice(0, 2_000) }, this.now);
|
|
415
|
+
this.emitStored(child.nodeId, resumed ? "node_resumed" : "node_launched", { parentId: this.legion.nodeId, runId: childRun, sessionFile: child.sessionFile, role: agent.name, kind: agent.kind });
|
|
571
416
|
}
|
|
572
417
|
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
placement: Placement,
|
|
584
|
-
agentType: string,
|
|
585
|
-
env?: Record<string, string>,
|
|
586
|
-
cwd: string = this.cwd,
|
|
587
|
-
): Promise<{ paneId: string; tabId?: string }> {
|
|
588
|
-
if (placement === "new-tab") {
|
|
589
|
-
const res = await this.client.tabCreate({
|
|
590
|
-
cwd,
|
|
591
|
-
label: `task:${agentType}`,
|
|
592
|
-
...(env ? { env } : {}),
|
|
593
|
-
focus: false,
|
|
594
|
-
...(this.workspaceId ? { workspaceId: this.workspaceId } : {}),
|
|
595
|
-
});
|
|
596
|
-
if (!res.ok) {
|
|
597
|
-
throw new SubagentError(
|
|
598
|
-
`tab create failed: ${res.error.message}`,
|
|
599
|
-
res.error.code,
|
|
600
|
-
);
|
|
601
|
-
}
|
|
602
|
-
return { paneId: res.value.rootPaneId, tabId: res.value.tab.tab_id };
|
|
418
|
+
private recordSettled(child: ChildRecord, execution: Execution): void {
|
|
419
|
+
if (!this.legion || !child.nodeId || execution.status === "running" || child.state === "retired") return;
|
|
420
|
+
const status = execution.status === "success" ? "settled" : execution.status === "failed" || execution.status === "truncated" ? "failed" : "retired";
|
|
421
|
+
const current = getNode(this.legion.db, child.nodeId);
|
|
422
|
+
if (!current || current.status === status) return;
|
|
423
|
+
updateNode(this.legion.db, child.nodeId, { status }, this.now);
|
|
424
|
+
const eventType = status === "settled" ? "node_settled" : status === "failed" ? "node_failed" : "node_retired";
|
|
425
|
+
this.emitStored(child.nodeId, eventType, { execution: execution.status, reason: execution.reason });
|
|
426
|
+
if (execution.usage) {
|
|
427
|
+
upsertUsage(this.legion.db, { nodeId: child.nodeId, tokensIn: execution.usage.input + execution.usage.cacheRead + execution.usage.cacheWrite, tokensOut: execution.usage.output, costUsd: execution.usage.cost }, this.now);
|
|
603
428
|
}
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
const res = await this.client.paneSplit({
|
|
608
|
-
target: plan.target,
|
|
609
|
-
direction: plan.direction,
|
|
610
|
-
cwd,
|
|
611
|
-
...(env ? { env } : {}),
|
|
612
|
-
focus: false,
|
|
613
|
-
});
|
|
614
|
-
if (!res.ok) {
|
|
615
|
-
this.layout.dropTypeTab(agentType);
|
|
616
|
-
throw new SubagentError(
|
|
617
|
-
`pane split failed: ${res.error.message}`,
|
|
618
|
-
res.error.code,
|
|
619
|
-
);
|
|
620
|
-
}
|
|
621
|
-
return res.value.pane_id;
|
|
622
|
-
});
|
|
429
|
+
void this.supervisor.stats(child.name).then((usage) => {
|
|
430
|
+
if (usage) upsertUsage(this.legion!.db, { nodeId: child.nodeId!, tokensIn: usage.tokensIn, tokensOut: usage.tokensOut, costUsd: usage.costUsd }, this.now);
|
|
431
|
+
}).catch(() => {});
|
|
623
432
|
}
|
|
624
433
|
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
args: string[];
|
|
641
|
-
/** Supplies a replacement name when the current one is taken. */
|
|
642
|
-
reallocate?: () => string;
|
|
643
|
-
}): Promise<string> {
|
|
644
|
-
let name = input.name;
|
|
645
|
-
let lastMessage = "start failed";
|
|
646
|
-
|
|
647
|
-
for (let attempt = 0; attempt < this.startRetries; attempt += 1) {
|
|
648
|
-
const res = await this.client.agentStart({
|
|
649
|
-
name,
|
|
650
|
-
kind: input.kind,
|
|
651
|
-
paneId: input.paneId,
|
|
652
|
-
args: input.args,
|
|
653
|
-
timeoutMs: this.startTimeoutMs,
|
|
654
|
-
});
|
|
655
|
-
if (res.ok) return name;
|
|
434
|
+
private abortLegionPhase(nodeId: string): void {
|
|
435
|
+
if (!this.legion) return;
|
|
436
|
+
const node = getNode(this.legion.db, nodeId);
|
|
437
|
+
if (!node || !isLegionPhase(node.phase) || isTerminalPhase(node.phase)) return;
|
|
438
|
+
const decision = evaluatePhaseTransition({
|
|
439
|
+
from: node.phase,
|
|
440
|
+
to: "aborted",
|
|
441
|
+
reworkCount: node.reworkCount,
|
|
442
|
+
terminalReason: "parent_retire",
|
|
443
|
+
actorRole: "supervisor",
|
|
444
|
+
}, this.now);
|
|
445
|
+
if (!decision.allowed) return;
|
|
446
|
+
updateNode(this.legion.db, nodeId, { phase: decision.to, phaseSince: decision.phaseSince }, this.now);
|
|
447
|
+
this.emitStored(nodeId, "phase_change", decision.event.data);
|
|
448
|
+
}
|
|
656
449
|
|
|
657
|
-
|
|
450
|
+
private emitProcess(type: LegionProcessEventType, nodeId: string, data: unknown): void {
|
|
451
|
+
this.legion?.eventBus?.emit({ nodeId, type, data: data as Record<string, unknown> | null, ts: this.now() });
|
|
452
|
+
}
|
|
658
453
|
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
await this.sleep(this.startBackoff + attempt * 50);
|
|
664
|
-
continue;
|
|
665
|
-
}
|
|
454
|
+
private emitStored(nodeId: string, type: Parameters<typeof appendEvent>[2], data: unknown): void {
|
|
455
|
+
if (!this.legion) return;
|
|
456
|
+
this.legion.eventBus?.emit(appendEvent(this.legion.db, nodeId, type, data, { now: this.now }));
|
|
457
|
+
}
|
|
666
458
|
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
throw new SubagentError(
|
|
672
|
-
`agent start failed (${res.error.code}): ${res.error.message}${
|
|
673
|
-
diagnostic ? `\n--- pane output ---\n${diagnostic}` : ""
|
|
674
|
-
}`,
|
|
675
|
-
res.error.code,
|
|
676
|
-
{ paneId: input.paneId },
|
|
677
|
-
);
|
|
678
|
-
}
|
|
679
|
-
await this.sleep(this.startBackoff + attempt * 50);
|
|
680
|
-
}
|
|
681
|
-
throw new SubagentError(
|
|
682
|
-
`agent start exhausted ${this.startRetries} retries: ${lastMessage}`,
|
|
683
|
-
ErrorCodes.START_FAILED,
|
|
684
|
-
);
|
|
459
|
+
private rollbackReservation(nodeId: string, previous: LegionNode | null): void {
|
|
460
|
+
if (!this.legion) return;
|
|
461
|
+
if (!previous) { this.legion.db.prepare("DELETE FROM nodes WHERE id = ?").run(nodeId); return; }
|
|
462
|
+
updateNode(this.legion.db, nodeId, { status: previous.status, runId: previous.runId, sessionFile: previous.sessionFile, worktreePath: previous.worktreePath, model: previous.model, team: previous.team, taskSummary: previous.taskSummary }, this.now);
|
|
685
463
|
}
|
|
686
464
|
|
|
687
|
-
/** Spawn-budget snapshot, for reporting and for tests. */
|
|
688
465
|
budget(): { used: number; limit: number | null; remaining: number | null } {
|
|
689
466
|
return {
|
|
690
467
|
used: this.spawned,
|
|
691
468
|
limit: this.maxSpawns,
|
|
692
|
-
remaining:
|
|
693
|
-
this.maxSpawns === null ? null : Math.max(0, this.maxSpawns - this.spawned),
|
|
469
|
+
remaining: this.maxSpawns === null ? null : Math.max(0, this.maxSpawns - this.spawned),
|
|
694
470
|
};
|
|
695
471
|
}
|
|
696
472
|
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
473
|
+
private warnDepthCap(): void {
|
|
474
|
+
if (this.depthWarningEmitted || this.requestedDepthCap === undefined) return;
|
|
475
|
+
this.depthWarningEmitted = true;
|
|
476
|
+
const event: BudgetRefusedEvent = {
|
|
477
|
+
type: "budget_refused",
|
|
478
|
+
requestedMaxDepth: this.requestedDepthCap,
|
|
479
|
+
effectiveMaxDepth: this.maxDepthValue,
|
|
480
|
+
reason: `maxDepth is capped at ${MAX_NESTED_PATH_ENTRIES}`,
|
|
481
|
+
};
|
|
482
|
+
console.warn(
|
|
483
|
+
`[pi-legion] requested maxDepth ${event.requestedMaxDepth} exceeds the hard cap ${MAX_NESTED_PATH_ENTRIES}; using effective maxDepth ${event.effectiveMaxDepth}.`,
|
|
484
|
+
);
|
|
485
|
+
this.onBudgetRefused?.(event);
|
|
486
|
+
}
|
|
487
|
+
|
|
701
488
|
async launch(input: {
|
|
702
489
|
agent: AgentConfig;
|
|
703
490
|
task: string;
|
|
704
491
|
name?: string;
|
|
492
|
+
team?: string;
|
|
705
493
|
model?: string;
|
|
706
494
|
thinking?: string | false;
|
|
707
|
-
placement?: Placement;
|
|
708
|
-
/** Parent override; when omitted, the role's `worktree` flag is used. */
|
|
709
495
|
worktree?: boolean;
|
|
710
|
-
/**
|
|
711
|
-
* How `model` was chosen. Decides whether a model the target CLI cannot
|
|
712
|
-
* accept is refused or dropped (see `planModelCandidates`).
|
|
713
|
-
*
|
|
714
|
-
* Defaults to `"explicit"` when `model` was passed and `"inherited"`
|
|
715
|
-
* otherwise. Callers that resolved a model themselves (the subagent tool)
|
|
716
|
-
* MUST pass the real origin, or an inherited parent model will be
|
|
717
|
-
* misreported as an explicit choice and refused.
|
|
718
|
-
*/
|
|
719
496
|
modelOrigin?: ModelOrigin;
|
|
497
|
+
/** Vexillatio launch: bypass nested-depth gates while recording its parent-side Legion node. */
|
|
498
|
+
utilityDispatch?: boolean;
|
|
499
|
+
/** Mask inherited Legion identity from the spawned child process. */
|
|
500
|
+
stripLegionIdentity?: boolean;
|
|
720
501
|
}): Promise<Handle> {
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
input.name ??
|
|
727
|
-
this.layout.claimName(
|
|
728
|
-
input.agent.name,
|
|
729
|
-
(n) => this.children.has(n) || reserved.has(n),
|
|
502
|
+
this.warnDepthCap();
|
|
503
|
+
if (input.agent.kind !== "pi") {
|
|
504
|
+
throw new SubagentError(
|
|
505
|
+
`RPC supervisor only supports pi children (received kind '${input.agent.kind}'); migrate the role to kind: pi or pin pi-legion v0.16.x`,
|
|
506
|
+
ErrorCodes.INVALID_PARAMS,
|
|
730
507
|
);
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
this.
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
508
|
+
}
|
|
509
|
+
const generated = input.name ?? (this.legion ? this.allocateLegionName(input.agent.name) : this.allocateName(input.agent.name));
|
|
510
|
+
const name = this.legion ? this.legionLocalName(generated) : generated;
|
|
511
|
+
const nodeId = this.legion ? nodeIdForChild(this.legion.nodeId, name) : undefined;
|
|
512
|
+
const ledgerPrevious = nodeId ? getNode(this.legion!.db, nodeId) : null;
|
|
513
|
+
const previous = this.children.get(name) ?? (ledgerPrevious ? this.childFromNode(name, ledgerPrevious) : undefined);
|
|
514
|
+
if (previous && !this.children.has(name)) this.children.set(name, previous);
|
|
515
|
+
// A utility dispatch is a hard leaf, not a nested command-chain launch.
|
|
516
|
+
// The frozen contract therefore skips assertWithinBudgets entirely.
|
|
517
|
+
if (!input.utilityDispatch) this.assertWithinBudgets(Boolean(previous));
|
|
518
|
+
if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
|
|
519
|
+
const models = this.planModelCandidates({
|
|
739
520
|
agent: input.agent,
|
|
740
521
|
...(input.model !== undefined ? { model: input.model } : {}),
|
|
741
|
-
origin: input.modelOrigin ??
|
|
522
|
+
origin: input.modelOrigin ?? (input.model !== undefined ? "explicit" : input.agent.modelSource?.type === "subagents.defaultModel" ? "inherited" : input.agent.model ? "explicit" : "inherited"),
|
|
742
523
|
...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
|
|
743
524
|
});
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
let
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
roleDefault: input.agent.worktree,
|
|
761
|
-
launch: input.worktree,
|
|
762
|
-
});
|
|
763
|
-
|
|
764
|
-
let paneId: string | null = null;
|
|
765
|
-
let worktreePath: string | undefined;
|
|
766
|
-
let worktreeBranch: string | undefined;
|
|
525
|
+
let sessionFile = previous?.sessionFile ?? this.sessionFileFor(name);
|
|
526
|
+
const tempDir = this.runDir;
|
|
527
|
+
const parentRole = this.legion ? getNode(this.legion.db, this.legion.nodeId)?.role : undefined;
|
|
528
|
+
const worktree = this.legion && input.agent.name === "centurion"
|
|
529
|
+
? true
|
|
530
|
+
: this.legion && parentRole === "centurion"
|
|
531
|
+
? false
|
|
532
|
+
: resolveLaunchWorktree({ roleDefault: input.agent.worktree, launch: input.worktree });
|
|
533
|
+
let worktreePath = previous?.worktreePath;
|
|
534
|
+
let worktreeBranch = previous?.worktreeBranch;
|
|
535
|
+
let createdWorktree = false;
|
|
536
|
+
let spawned = false;
|
|
537
|
+
let reservedNode: LegionNode | null = null;
|
|
538
|
+
let reserved = false;
|
|
539
|
+
let createdRunId: string | undefined;
|
|
540
|
+
let parentReservationCreated = false;
|
|
767
541
|
try {
|
|
768
|
-
if (
|
|
769
|
-
const tree = createChildWorktree({
|
|
770
|
-
repoCwd: this.cwd,
|
|
771
|
-
runDir: this.runDir,
|
|
772
|
-
name,
|
|
773
|
-
});
|
|
542
|
+
if (worktree && !worktreePath) {
|
|
543
|
+
const tree = createChildWorktree({ repoCwd: this.cwd, runDir: this.runDir, name });
|
|
774
544
|
worktreePath = tree.path;
|
|
775
545
|
worktreeBranch = tree.branch;
|
|
546
|
+
createdWorktree = true;
|
|
547
|
+
// Provision before any spawn: the child's first command and any
|
|
548
|
+
// plugin-run verify command would otherwise fail on a bare checkout.
|
|
549
|
+
// Failure throws through the existing rollback below (tree removed).
|
|
550
|
+
provisionWorktree({
|
|
551
|
+
worktreePath,
|
|
552
|
+
mode: this.worktreeBootstrap,
|
|
553
|
+
timeoutMs: this.worktreeBootstrapTimeoutMs,
|
|
554
|
+
});
|
|
776
555
|
}
|
|
777
|
-
const
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
}
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
556
|
+
const effectiveModel = models.candidates;
|
|
557
|
+
if (this.legion && nodeId && !previous && this.legion.runStore) {
|
|
558
|
+
const roleDepth = input.agent.maxSubagentDepth === undefined
|
|
559
|
+
? Number.POSITIVE_INFINITY
|
|
560
|
+
: Number.isInteger(input.agent.maxSubagentDepth) && input.agent.maxSubagentDepth >= 1
|
|
561
|
+
? input.agent.maxSubagentDepth
|
|
562
|
+
: 1;
|
|
563
|
+
const run = this.legion.runStore.createRun({
|
|
564
|
+
task: input.task,
|
|
565
|
+
cwd: worktreePath ?? this.cwd,
|
|
566
|
+
path: this.childPath(name),
|
|
567
|
+
maxDepth: input.utilityDispatch
|
|
568
|
+
? this.depth + 1
|
|
569
|
+
: Math.min(this.maxDepthValue, this.depth + roleDepth, MAX_NESTED_PATH_ENTRIES),
|
|
570
|
+
nodeId,
|
|
571
|
+
herdr: { supervisor: "rpc", node_id: nodeId },
|
|
572
|
+
});
|
|
573
|
+
createdRunId = run.runId;
|
|
574
|
+
sessionFile = this.legion.runStore.sessionFileFor(run.runId, name);
|
|
575
|
+
}
|
|
576
|
+
preCreateSessionFile(sessionFile);
|
|
577
|
+
if (this.legion && nodeId) {
|
|
578
|
+
const reservationRunId = createdRunId ?? (previous ? ledgerPrevious?.runId : undefined) ?? this.legion.runId;
|
|
579
|
+
reservedNode = this.reserveNode({ nodeId, name, agent: input.agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models.candidates[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
|
|
580
|
+
reserved = true;
|
|
581
|
+
parentReservationCreated = await this.persistParentReservation({ nodeId, name, agent: input.agent, sessionFile, ...(models.candidates[0] ? { model: models.candidates[0] } : {}), ...(worktreePath ? { worktreePath } : {}) });
|
|
582
|
+
}
|
|
583
|
+
const childEnv = this.lineageEnv(name, input.agent, input.team, nodeId);
|
|
584
|
+
if (input.stripLegionIdentity) {
|
|
585
|
+
for (const key of LEGION_IDENTITY_ENV_KEYS) delete childEnv[key];
|
|
586
|
+
}
|
|
587
|
+
let result: Awaited<ReturnType<LegionSupervisor["spawnChild"]>> | undefined;
|
|
588
|
+
let startedModel: string | undefined;
|
|
589
|
+
let lastError: unknown;
|
|
590
|
+
for (let index = 0; index < effectiveModel.length; index += 1) {
|
|
591
|
+
const model = effectiveModel[index];
|
|
592
|
+
const spawnInput: SpawnInput = {
|
|
593
|
+
name,
|
|
594
|
+
task: input.task,
|
|
595
|
+
agent: input.agent,
|
|
596
|
+
sessionFile,
|
|
597
|
+
tempDir,
|
|
598
|
+
cwd: worktreePath ?? this.cwd,
|
|
599
|
+
env: childEnv,
|
|
600
|
+
...(model ? { model } : {}),
|
|
601
|
+
...(input.stripLegionIdentity ? { stripLegionIdentity: true } : {}),
|
|
602
|
+
...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
|
|
603
|
+
...(input.agent.allowNestedSubagents !== undefined && !input.agent.utility ? { allowNestedSubagents: input.agent.allowNestedSubagents } : {}),
|
|
604
|
+
...(worktreeBranch ? { worktreeBranch } : {}),
|
|
605
|
+
...(this.childContext ? { childContext: this.childContext } : {}),
|
|
606
|
+
};
|
|
607
|
+
try {
|
|
608
|
+
result = await this.supervisor.spawnChild(spawnInput);
|
|
609
|
+
startedModel = model;
|
|
610
|
+
spawned = true;
|
|
611
|
+
break;
|
|
612
|
+
} catch (error) {
|
|
613
|
+
lastError = error;
|
|
614
|
+
if (!canFallbackStart(error) || index === effectiveModel.length - 1) throw error;
|
|
615
|
+
}
|
|
616
|
+
}
|
|
617
|
+
if (!result) throw lastError ?? new SubagentError("RPC child start failed", ErrorCodes.START_FAILED);
|
|
618
|
+
if (previous) {
|
|
619
|
+
previous.state = "working";
|
|
620
|
+
previous.spawnedAt = new Date(this.now()).toISOString();
|
|
621
|
+
previous.retiredAt = undefined;
|
|
622
|
+
previous.execution = undefined;
|
|
623
|
+
previous.acceptance = undefined;
|
|
624
|
+
previous.outputFile = undefined;
|
|
625
|
+
previous.model = startedModel;
|
|
626
|
+
this.children.set(name, previous);
|
|
627
|
+
}
|
|
628
|
+
const child = previous ?? this.recordChild({
|
|
629
|
+
name: result.name,
|
|
630
|
+
...(nodeId ? { nodeId } : {}),
|
|
815
631
|
agent: input.agent,
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
...(usedModel ? { model: usedModel } : {}),
|
|
820
|
-
...(thinking !== undefined ? { thinking } : {}),
|
|
821
|
-
...(modelPlan.dropped.length ? { modelDropped: modelPlan.dropped } : {}),
|
|
632
|
+
sessionFile: result.sessionFile,
|
|
633
|
+
...(startedModel ? { model: startedModel } : {}),
|
|
634
|
+
...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
|
|
822
635
|
...(worktreePath ? { worktreePath } : {}),
|
|
823
636
|
...(worktreeBranch ? { worktreeBranch } : {}),
|
|
824
|
-
promptText: started.promptText,
|
|
825
637
|
});
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
);
|
|
830
|
-
|
|
638
|
+
if (previous) this.onChildUpdate(child);
|
|
639
|
+
if (this.legion && nodeId) this.recordLegionLaunch(child, input.agent, input.task, input.team, Boolean(reservedNode));
|
|
640
|
+
this.emitProcess("node_launched", nodeId ?? name, { name, agent: input.agent.name, pid: result.pid });
|
|
831
641
|
return {
|
|
832
|
-
name,
|
|
833
|
-
|
|
834
|
-
sessionFile,
|
|
642
|
+
name: result.name,
|
|
643
|
+
sessionFile: result.sessionFile,
|
|
835
644
|
runId: path.basename(this.runDir),
|
|
836
645
|
agent: input.agent.name,
|
|
837
646
|
kind: input.agent.kind,
|
|
838
647
|
child,
|
|
839
648
|
};
|
|
840
649
|
} catch (error) {
|
|
841
|
-
|
|
842
|
-
if (
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
await this.reapTypeTabIfEmpty(input.agent.name, paneId, undefined);
|
|
846
|
-
}
|
|
650
|
+
if (spawned) await this.supervisor.retire(name).catch(() => {});
|
|
651
|
+
if (reserved && nodeId) this.rollbackReservation(nodeId, reservedNode);
|
|
652
|
+
if (parentReservationCreated && this.legion?.runStore) {
|
|
653
|
+
try { await this.legion.runStore.removeChild(this.legion.runId!, name, nodeId); } catch { /* rollback is best effort */ }
|
|
847
654
|
}
|
|
848
|
-
if (
|
|
849
|
-
|
|
655
|
+
if (createdRunId && this.legion?.runStore) {
|
|
656
|
+
try { fs.rmSync(this.legion.runStore.runDir(createdRunId), { recursive: true, force: true }); } catch { /* rollback is best effort */ }
|
|
850
657
|
}
|
|
658
|
+
if (createdWorktree && worktreePath) removeChildWorktree({ repoCwd: this.cwd, dest: worktreePath });
|
|
851
659
|
throw error;
|
|
852
|
-
} finally {
|
|
853
|
-
fs.rmSync(tempDir, { recursive: true, force: true });
|
|
854
660
|
}
|
|
855
661
|
}
|
|
856
662
|
|
|
857
|
-
/**
|
|
858
|
-
* How to classify the model when the caller did not say.
|
|
859
|
-
*
|
|
860
|
-
* A per-run `model` param is the caller's own choice, so it is explicit. When
|
|
861
|
-
* only `agent.model` is set, `agent.modelSource` separates the two ways that
|
|
862
|
-
* field gets filled: `applyDefaultModel` stamps
|
|
863
|
-
* `subagents.defaultModel` (a global fallback → inherited), while frontmatter
|
|
864
|
-
* and `agentOverrides` leave it unset (a deliberate per-role value →
|
|
865
|
-
* explicit). The subagent tool always passes the real origin, so this default
|
|
866
|
-
* only serves direct `Orchestrator.launch` callers.
|
|
867
|
-
*/
|
|
868
|
-
private defaultModelOrigin(input: {
|
|
869
|
-
agent: AgentConfig;
|
|
870
|
-
model?: string;
|
|
871
|
-
}): ModelOrigin {
|
|
872
|
-
if (input.model !== undefined) return "explicit";
|
|
873
|
-
const source = input.agent.modelSource?.type;
|
|
874
|
-
if (source === "subagents.defaultModel") return "inherited";
|
|
875
|
-
if (input.agent.model !== undefined) return "explicit";
|
|
876
|
-
return "inherited";
|
|
877
|
-
}
|
|
878
|
-
|
|
879
|
-
/**
|
|
880
|
-
* Build the model chain for a launch and decide what to do when the target
|
|
881
|
-
* CLI cannot accept a candidate.
|
|
882
|
-
*
|
|
883
|
-
* `nativeModelFor` returns `undefined` for a model the kind cannot express
|
|
884
|
-
* (e.g. a pi-shaped `provider/id` handed to cursor), which silently omits
|
|
885
|
-
* `--model` and leaves the child on the CLI's own default. Whether that is a
|
|
886
|
-
* bug or the intended outcome depends ENTIRELY on how the model was chosen:
|
|
887
|
-
*
|
|
888
|
-
* explicit — frontmatter / agentOverrides / preset / per-run `model`.
|
|
889
|
-
* Someone deliberately named this model, so dropping it is a
|
|
890
|
-
* mistake: refuse before any resource is allocated.
|
|
891
|
-
* inherited — `subagents.defaultModel` or the parent session's model. The
|
|
892
|
-
* parent is usually a different kind (pi), so its model is
|
|
893
|
-
* simply not applicable and dropping it is the documented
|
|
894
|
-
* behaviour (see `cursorModel`'s comment in kind.ts). Reported
|
|
895
|
-
* via `dropped` instead of failing.
|
|
896
|
-
*
|
|
897
|
-
* Unacceptable candidates are REMOVED from the chain used for launching, for
|
|
898
|
-
* both origins: leaving one in would make it the first attempt, and since a
|
|
899
|
-
* dropped model yields no `--model` flag at all, the child would start on the
|
|
900
|
-
* CLI default instead of falling through to the next candidate. An impossible
|
|
901
|
-
* chain (`fallbackModels` where nothing fits) is refused only when the caller
|
|
902
|
-
* chose explicitly; an inherited chain just becomes model-less.
|
|
903
|
-
*/
|
|
904
663
|
private planModelCandidates(input: {
|
|
905
664
|
agent: AgentConfig;
|
|
906
665
|
model?: string;
|
|
907
666
|
origin: ModelOrigin;
|
|
908
667
|
thinking?: string | false;
|
|
909
668
|
}): { candidates: Array<string | undefined>; dropped: string[] } {
|
|
910
|
-
const requested = modelCandidates(
|
|
911
|
-
input.model ?? input.agent.model,
|
|
912
|
-
input.agent.fallbackModels,
|
|
913
|
-
);
|
|
669
|
+
const requested = modelCandidates(input.model ?? input.agent.model, input.agent.fallbackModels);
|
|
914
670
|
const thinking = input.thinking ?? input.agent.thinking;
|
|
915
|
-
const
|
|
916
|
-
|
|
917
|
-
const usable: Array<string | undefined> = [];
|
|
671
|
+
const candidates: Array<string | undefined> = [];
|
|
918
672
|
const dropped: string[] = [];
|
|
919
|
-
for (const
|
|
920
|
-
if (!
|
|
921
|
-
|
|
922
|
-
continue;
|
|
923
|
-
}
|
|
924
|
-
if (nativeModelFor(kind, candidate, thinking) !== undefined) {
|
|
925
|
-
usable.push(candidate);
|
|
926
|
-
} else {
|
|
927
|
-
dropped.push(candidate);
|
|
928
|
-
}
|
|
929
|
-
}
|
|
930
|
-
|
|
931
|
-
// A model the kind cannot express is only a hard error when someone
|
|
932
|
-
// deliberately named it AND nothing viable is left to fall back to.
|
|
933
|
-
if (dropped.length > 0 && input.origin === "explicit" && usable.length === 0) {
|
|
934
|
-
throw new SubagentError(
|
|
935
|
-
`model '${dropped.join(", ")}' cannot be used with kind '${kind}' ` +
|
|
936
|
-
`(it would be silently dropped and the child would run on the ` +
|
|
937
|
-
`CLI default). Pick a model this CLI accepts, or remove it.`,
|
|
938
|
-
ErrorCodes.INVALID_PARAMS,
|
|
939
|
-
);
|
|
673
|
+
for (const model of requested) {
|
|
674
|
+
if (!model || nativeModelFor("pi", model, thinking) !== undefined) candidates.push(model);
|
|
675
|
+
else dropped.push(model);
|
|
940
676
|
}
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
// to make its start attempt, and a model-less start is exactly the
|
|
944
|
-
// intended outcome here, so keep the `[undefined]` shape that
|
|
945
|
-
// `modelCandidates` guarantees for an empty chain.
|
|
946
|
-
if (usable.length === 0) return { candidates: [undefined], dropped };
|
|
947
|
-
|
|
948
|
-
return { candidates: usable, dropped };
|
|
949
|
-
}
|
|
950
|
-
|
|
951
|
-
/**
|
|
952
|
-
* Try each model candidate on the same pane. A start that fails for a
|
|
953
|
-
* reason other than "name taken" / "not found" falls through to the next
|
|
954
|
-
* id; NAME_TAKEN is already reallocated inside `startWithRetry`.
|
|
955
|
-
*/
|
|
956
|
-
private async startWithModelFallback(input: {
|
|
957
|
-
name: string;
|
|
958
|
-
kind: AgentConfig["kind"];
|
|
959
|
-
paneId: string;
|
|
960
|
-
agent: AgentConfig;
|
|
961
|
-
task: string;
|
|
962
|
-
sessionFile: string;
|
|
963
|
-
thinking?: string | false;
|
|
964
|
-
tempDir: string;
|
|
965
|
-
cwd: string;
|
|
966
|
-
candidates: Array<string | undefined>;
|
|
967
|
-
worktreeBranch?: string;
|
|
968
|
-
reallocate: () => string;
|
|
969
|
-
}): Promise<{
|
|
970
|
-
name: string;
|
|
971
|
-
sessionFile: string;
|
|
972
|
-
model?: string;
|
|
973
|
-
promptText: string;
|
|
974
|
-
}> {
|
|
975
|
-
let name = input.name;
|
|
976
|
-
let sessionFile = input.sessionFile;
|
|
977
|
-
let lastError: unknown;
|
|
978
|
-
for (let i = 0; i < input.candidates.length; i += 1) {
|
|
979
|
-
const model = input.candidates[i];
|
|
980
|
-
const plan = planKindStart({
|
|
981
|
-
agent: input.agent,
|
|
982
|
-
task: input.task,
|
|
983
|
-
sessionFile,
|
|
984
|
-
model,
|
|
985
|
-
thinking: input.thinking,
|
|
986
|
-
tempDir: input.tempDir,
|
|
987
|
-
cwd: input.cwd,
|
|
988
|
-
allowNestedSubagents: input.agent.allowNestedSubagents,
|
|
989
|
-
includeTask: false,
|
|
990
|
-
childContext: this.childContext,
|
|
991
|
-
...(input.worktreeBranch
|
|
992
|
-
? { worktreeBranch: input.worktreeBranch }
|
|
993
|
-
: {}),
|
|
994
|
-
});
|
|
995
|
-
try {
|
|
996
|
-
name = await this.startWithRetry({
|
|
997
|
-
name,
|
|
998
|
-
kind: input.kind,
|
|
999
|
-
paneId: input.paneId,
|
|
1000
|
-
args: plan.args,
|
|
1001
|
-
reallocate: () => {
|
|
1002
|
-
const next = input.reallocate();
|
|
1003
|
-
sessionFile = this.sessionFileFor(next);
|
|
1004
|
-
return next;
|
|
1005
|
-
},
|
|
1006
|
-
});
|
|
1007
|
-
const prompted = await this.client.agentPrompt(name, plan.taskText);
|
|
1008
|
-
if (!prompted.ok) {
|
|
1009
|
-
throw new SubagentError(
|
|
1010
|
-
`agent prompt failed (${prompted.error.code}): ${prompted.error.message}`,
|
|
1011
|
-
prompted.error.code,
|
|
1012
|
-
{ paneId: input.paneId },
|
|
1013
|
-
);
|
|
1014
|
-
}
|
|
1015
|
-
return {
|
|
1016
|
-
name,
|
|
1017
|
-
sessionFile,
|
|
1018
|
-
promptText: plan.taskText,
|
|
1019
|
-
...(plan.recordModel ? { model: plan.recordModel } : {}),
|
|
1020
|
-
};
|
|
1021
|
-
} catch (error) {
|
|
1022
|
-
lastError = error;
|
|
1023
|
-
if (!canFallbackStart(error) || i === input.candidates.length - 1) {
|
|
1024
|
-
throw error;
|
|
1025
|
-
}
|
|
1026
|
-
}
|
|
677
|
+
if (dropped.length && input.origin === "explicit" && candidates.length === 0) {
|
|
678
|
+
throw new SubagentError(`model '${dropped.join(", ")}' cannot be used with kind 'pi'.`, ErrorCodes.INVALID_PARAMS);
|
|
1027
679
|
}
|
|
1028
|
-
|
|
1029
|
-
? lastError
|
|
1030
|
-
: new SubagentError("agent start failed", ErrorCodes.START_FAILED);
|
|
680
|
+
return { candidates: candidates.length ? candidates : [undefined], dropped };
|
|
1031
681
|
}
|
|
1032
682
|
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
*
|
|
1036
|
-
* Both are checked BEFORE any resource is created, so a refusal never leaks a
|
|
1037
|
-
* pane; without the depth guard the lineage tree would be decorative and
|
|
1038
|
-
* nesting could recurse forever.
|
|
1039
|
-
*/
|
|
1040
|
-
private assertWithinBudgets(): void {
|
|
1041
|
-
if (this.depth + 1 > this.maxDepth) {
|
|
683
|
+
private assertWithinBudgets(existingChild = false): void {
|
|
684
|
+
if (this.depth + 1 > this.maxDepthValue) {
|
|
1042
685
|
throw new SubagentError(
|
|
1043
|
-
`subagent nesting limit reached (depth ${this.depth}, max ${this.
|
|
1044
|
-
`raise maxSubagentDepth to allow deeper nesting`,
|
|
686
|
+
`subagent nesting limit reached (depth ${this.depth}, max ${this.maxDepthValue}); raise maxSubagentDepth to allow deeper nesting`,
|
|
1045
687
|
ErrorCodes.BUDGET_EXCEEDED,
|
|
1046
688
|
);
|
|
1047
689
|
}
|
|
1048
|
-
if (this.maxSpawns !== null && this.spawned >= this.maxSpawns) {
|
|
690
|
+
if (!existingChild && this.maxSpawns !== null && this.spawned >= this.maxSpawns) {
|
|
1049
691
|
throw new SubagentError(
|
|
1050
|
-
`subagent spawn budget exhausted (${this.spawned}/${this.maxSpawns});
|
|
1051
|
-
`raise subagents.maxSubagentSpawnsPerSession to allow more`,
|
|
692
|
+
`subagent spawn budget exhausted (${this.spawned}/${this.maxSpawns}); raise subagents.maxSubagentSpawnsPerSession to allow more`,
|
|
1052
693
|
ErrorCodes.BUDGET_EXCEEDED,
|
|
1053
694
|
);
|
|
1054
695
|
}
|
|
1055
696
|
}
|
|
1056
697
|
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
698
|
+
private lineageEnv(name: string, agent: AgentConfig, teamOverride?: string, nodeId?: string): Record<string, string> {
|
|
699
|
+
const roleDepth = agent.maxSubagentDepth === undefined
|
|
700
|
+
? Number.POSITIVE_INFINITY
|
|
701
|
+
: Number.isInteger(agent.maxSubagentDepth) && agent.maxSubagentDepth >= 1
|
|
702
|
+
? agent.maxSubagentDepth
|
|
703
|
+
: 1;
|
|
704
|
+
const env: Record<string, string> = {
|
|
705
|
+
[LINEAGE_ENV]: encodeNestedPath(this.childPath(name)),
|
|
706
|
+
[MAX_DEPTH_ENV]: String(Math.min(this.maxDepthValue, this.depth + roleDepth, MAX_NESTED_PATH_ENTRIES)),
|
|
707
|
+
[CHILD_ENV]: "1",
|
|
708
|
+
[CHILD_ROLE_ENV]: agent.name,
|
|
709
|
+
};
|
|
710
|
+
const team = teamOverride ?? agent.extraFields?.team ?? this.team?.name;
|
|
711
|
+
if (team !== undefined && (team !== DEFAULT_TEAM || teamOverride === DEFAULT_TEAM || this.team?.source === "env")) env[TEAM_ENV] = team;
|
|
712
|
+
if (this.legion && nodeId) Object.assign(env, legionIdentityEnv(this.legion.dbPath, nodeId));
|
|
713
|
+
if (agent.acceptance?.role) env[CHILD_ACCEPTANCE_ROLE_ENV] = agent.acceptance.role;
|
|
714
|
+
if (agent.toolBudget?.maxToolCalls !== undefined) env[MAX_TOOL_CALLS_ENV] = String(agent.toolBudget.maxToolCalls);
|
|
715
|
+
if (agent.turnBudget?.maxTurns !== undefined) env[MAX_TURNS_ENV] = String(agent.turnBudget.maxTurns);
|
|
716
|
+
if (agent.toolTimeoutMs !== undefined) env[TOOL_TIMEOUT_MS_ENV] = String(agent.toolTimeoutMs);
|
|
717
|
+
if (agent.utility) env[UTILITY_CHILD_ENV] = "1";
|
|
718
|
+
// Utility identity takes precedence even when a role was misconfigured
|
|
719
|
+
// with allowNestedSubagents: utility children are always hard leaves.
|
|
720
|
+
if (agent.allowNestedSubagents && !agent.utility) env[ALLOW_NESTED_ENV] = "1";
|
|
721
|
+
return env;
|
|
722
|
+
}
|
|
1071
723
|
|
|
1072
|
-
/**
|
|
1073
|
-
* Ensure the herdr integration hook exists for a hook-dependent kind.
|
|
1074
|
-
*
|
|
1075
|
-
* The cursor collection path reads the SQLite chat store herdr locates via
|
|
1076
|
-
* the sessionStart hook (`~/.cursor/herdr-agent-state.sh` reporting
|
|
1077
|
-
* `agent_session.source = "herdr:cursor"`). Without the hook the child
|
|
1078
|
-
* still runs — but every completion is misreported
|
|
1079
|
-
* `failed: no session jsonl; collected from pane` even when the turn fully
|
|
1080
|
-
* succeeded (nj-hw 2026-09-28: planner/advisor all "failed", all actually
|
|
1081
|
-
* succeeded with multi-MB chat stores on disk).
|
|
1082
|
-
*
|
|
1083
|
-
* Contract:
|
|
1084
|
-
* - hook present ("current") → proceed, remember per kind
|
|
1085
|
-
* - hook missing → `herdr integration install <kind>` (idempotent, verified
|
|
1086
|
-
* md5-stable on reinstall), re-check, then proceed
|
|
1087
|
-
* - herdr cannot tell (`integration status` unsupported/errored) → proceed
|
|
1088
|
-
* silently: an older herdr must not brick launches; the pane path then
|
|
1089
|
-
* collects as before (F7 semantics)
|
|
1090
|
-
* - install refused (e.g. cursor CLI absent) → refuse the launch with the
|
|
1091
|
-
* fix in the message, BEFORE any pane/worktree is allocated — same
|
|
1092
|
-
* leak-free invariant as `planModelCandidates` above
|
|
1093
|
-
*/
|
|
1094
|
-
private async ensureIntegrationHook(kind: AgentKind): Promise<void> {
|
|
1095
|
-
if (kind === "pi") return;
|
|
1096
|
-
const table: Partial<Record<AgentKind, string>> =
|
|
1097
|
-
Orchestrator.INTEGRATION_DEPENDENT_KINDS;
|
|
1098
|
-
const target = table[kind];
|
|
1099
|
-
if (!target) return;
|
|
1100
|
-
if (this.integrationChecked.get(kind)) return;
|
|
1101
|
-
|
|
1102
|
-
const status = await this.client.integrationStatus(target);
|
|
1103
|
-
if (!status.ok || status.value === null) return; // cannot tell → proceed (F7 pane path)
|
|
1104
|
-
if (!status.value.startsWith("not installed")) {
|
|
1105
|
-
this.integrationChecked.set(kind, true);
|
|
1106
|
-
return;
|
|
1107
|
-
}
|
|
1108
|
-
|
|
1109
|
-
const installed = await this.client.integrationInstall(target);
|
|
1110
|
-
if (!installed.ok) {
|
|
1111
|
-
throw new SubagentError(
|
|
1112
|
-
`herdr's ${target} integration hook is missing and auto-install failed: ` +
|
|
1113
|
-
`${installed.error.message}. Without the hook, ${target} children always ` +
|
|
1114
|
-
`report "failed: no session jsonl" even when they succeed. ` +
|
|
1115
|
-
`Fix: run \`herdr integration install ${target}\` manually, or use a pi-kind role.`,
|
|
1116
|
-
ErrorCodes.START_FAILED,
|
|
1117
|
-
);
|
|
1118
|
-
}
|
|
1119
|
-
// Re-check: a hook that reports "not installed" after a successful install
|
|
1120
|
-
// (config dir mismatch, wrong user) would silently degrade every launch.
|
|
1121
|
-
const verify = await this.client.integrationStatus(target);
|
|
1122
|
-
if (verify.ok && verify.value !== null && verify.value.startsWith("not installed")) {
|
|
1123
|
-
throw new SubagentError(
|
|
1124
|
-
`herdr's ${target} integration hook still reports "not installed" after ` +
|
|
1125
|
-
`install (${installed.value.slice(0, 120)}). Check herdr's integration ` +
|
|
1126
|
-
`paths for this user, or run \`herdr integration install ${target}\` manually.`,
|
|
1127
|
-
ErrorCodes.START_FAILED,
|
|
1128
|
-
);
|
|
1129
|
-
}
|
|
1130
|
-
this.integrationChecked.set(kind, true);
|
|
1131
|
-
}
|
|
1132
|
-
|
|
1133
|
-
/**
|
|
1134
|
-
* Lineage env for a child pane (design §4.2): a grandchild learns its full
|
|
1135
|
-
* ancestry and is bounded by the same ceiling.
|
|
1136
|
-
*/
|
|
1137
|
-
private lineageEnv(
|
|
1138
|
-
name: string,
|
|
1139
|
-
agent?: AgentConfig,
|
|
1140
|
-
): Record<string, string> {
|
|
1141
|
-
const env: Record<string, string> = {
|
|
1142
|
-
[LINEAGE_ENV]: encodeNestedPath(this.childPath(name)),
|
|
1143
|
-
[MAX_DEPTH_ENV]: String(this.maxDepth),
|
|
1144
|
-
[CHILD_ENV]: "1",
|
|
1145
|
-
[CHILD_ROLE_ENV]: agent?.name ?? "",
|
|
1146
|
-
};
|
|
1147
|
-
if (
|
|
1148
|
-
this.team &&
|
|
1149
|
-
(this.team.name !== DEFAULT_TEAM || this.team.source === "env")
|
|
1150
|
-
) {
|
|
1151
|
-
env[TEAM_ENV] = this.team.name;
|
|
1152
|
-
}
|
|
1153
|
-
if (agent?.acceptance?.role) {
|
|
1154
|
-
env[CHILD_ACCEPTANCE_ROLE_ENV] = agent.acceptance.role;
|
|
1155
|
-
}
|
|
1156
|
-
if (agent?.toolBudget?.maxToolCalls !== undefined) {
|
|
1157
|
-
env[MAX_TOOL_CALLS_ENV] = String(agent.toolBudget.maxToolCalls);
|
|
1158
|
-
}
|
|
1159
|
-
if (agent?.turnBudget?.maxTurns !== undefined) {
|
|
1160
|
-
env[MAX_TURNS_ENV] = String(agent.turnBudget.maxTurns);
|
|
1161
|
-
}
|
|
1162
|
-
if (agent?.toolTimeoutMs !== undefined) {
|
|
1163
|
-
env[TOOL_TIMEOUT_MS_ENV] = String(agent.toolTimeoutMs);
|
|
1164
|
-
}
|
|
1165
|
-
if (agent?.allowNestedSubagents) {
|
|
1166
|
-
env[ALLOW_NESTED_ENV] = "1";
|
|
1167
|
-
}
|
|
1168
|
-
return env;
|
|
1169
|
-
}
|
|
1170
|
-
|
|
1171
|
-
/**
|
|
1172
|
-
* Move a child's session file to follow a mid-launch rename so the resume
|
|
1173
|
-
* credential stays valid; fall back to creating it if the rename cannot.
|
|
1174
|
-
*/
|
|
1175
|
-
private rehomeSessionFile(from: string, toName: string): string {
|
|
1176
|
-
const next = this.sessionFileFor(toName);
|
|
1177
|
-
try {
|
|
1178
|
-
fs.renameSync(from, next);
|
|
1179
|
-
} catch {
|
|
1180
|
-
preCreateSessionFile(next);
|
|
1181
|
-
}
|
|
1182
|
-
return next;
|
|
1183
|
-
}
|
|
1184
|
-
|
|
1185
|
-
/** Build the child record, register it, and publish the update. */
|
|
1186
724
|
private recordChild(input: {
|
|
1187
725
|
name: string;
|
|
726
|
+
nodeId?: string;
|
|
1188
727
|
agent: AgentConfig;
|
|
1189
|
-
paneId: string;
|
|
1190
|
-
tabId: string | undefined;
|
|
1191
728
|
sessionFile: string;
|
|
1192
729
|
model?: string;
|
|
1193
730
|
thinking?: string | false;
|
|
1194
|
-
modelDropped?: string[];
|
|
1195
731
|
worktreePath?: string;
|
|
1196
732
|
worktreeBranch?: string;
|
|
1197
|
-
promptText?: string;
|
|
1198
733
|
}): ChildRecord {
|
|
1199
|
-
const { name, agent, sessionFile } = input;
|
|
1200
734
|
const child: ChildRecord = {
|
|
1201
|
-
name,
|
|
1202
|
-
|
|
1203
|
-
sessionFile,
|
|
735
|
+
name: input.name,
|
|
736
|
+
...(input.nodeId ? { nodeId: input.nodeId } : {}),
|
|
737
|
+
sessionFile: input.sessionFile,
|
|
1204
738
|
ownerToken: ownerToken(),
|
|
1205
739
|
state: "working",
|
|
1206
740
|
spawnedAt: new Date(this.now()).toISOString(),
|
|
1207
|
-
agent: agent.name,
|
|
1208
|
-
kind: agent.kind,
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
...(agent.
|
|
1212
|
-
? {
|
|
1213
|
-
pendingCriteria: agent.acceptance.criteria.map((c) => ({
|
|
1214
|
-
...c,
|
|
1215
|
-
})),
|
|
1216
|
-
}
|
|
1217
|
-
: {}),
|
|
1218
|
-
...(agent.onBlocked ? { onBlocked: agent.onBlocked } : {}),
|
|
1219
|
-
...(agent.completionGuard ? { completionGuard: true } : {}),
|
|
1220
|
-
...(input.tabId ? { tabId: input.tabId } : {}),
|
|
741
|
+
agent: input.agent.name,
|
|
742
|
+
kind: input.agent.kind,
|
|
743
|
+
...(input.agent.acceptance?.criteria?.length ? { pendingCriteria: input.agent.acceptance.criteria.map((criterion) => ({ ...criterion })) } : {}),
|
|
744
|
+
...(input.agent.onBlocked ? { onBlocked: input.agent.onBlocked } : {}),
|
|
745
|
+
...(input.agent.completionGuard ? { completionGuard: true } : {}),
|
|
1221
746
|
...(input.model ? { model: input.model } : {}),
|
|
1222
747
|
...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
|
|
1223
|
-
...(input.modelDropped?.length
|
|
1224
|
-
? { modelDropped: [...input.modelDropped] }
|
|
1225
|
-
: {}),
|
|
1226
748
|
...(input.worktreePath ? { worktreePath: input.worktreePath } : {}),
|
|
1227
749
|
...(input.worktreeBranch ? { worktreeBranch: input.worktreeBranch } : {}),
|
|
1228
|
-
...(input.promptText ? { promptText: input.promptText } : {}),
|
|
1229
750
|
};
|
|
1230
|
-
this.children.set(name, child);
|
|
751
|
+
this.children.set(input.name, child);
|
|
1231
752
|
this.spawned += 1;
|
|
1232
753
|
this.onChildUpdate(child);
|
|
1233
754
|
return child;
|
|
1234
755
|
}
|
|
1235
756
|
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
): Promise<void> {
|
|
1242
|
-
if (!child.paneId) return;
|
|
1243
|
-
await this.client.paneReportMetadata({
|
|
1244
|
-
paneId: child.paneId,
|
|
1245
|
-
source: "pi-legion",
|
|
1246
|
-
displayAgent: agentName,
|
|
1247
|
-
tokens: {
|
|
1248
|
-
agent: agentName,
|
|
1249
|
-
model: model ?? "inherit",
|
|
1250
|
-
...(typeof child.thinking === "string"
|
|
1251
|
-
? { thinking: child.thinking }
|
|
1252
|
-
: {}),
|
|
1253
|
-
run: path.basename(this.runDir),
|
|
1254
|
-
},
|
|
1255
|
-
});
|
|
757
|
+
async steer(name: string, text: string): Promise<void> {
|
|
758
|
+
const child = this.requireChild(name);
|
|
759
|
+
await this.supervisor.steer(name, text);
|
|
760
|
+
this.emitProcess("node_steered", child.nodeId ?? name, { name, text });
|
|
761
|
+
this.clearBlocked(child);
|
|
1256
762
|
}
|
|
1257
763
|
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
throw new SubagentError(
|
|
1263
|
-
`steer failed: ${res.error.message}`,
|
|
1264
|
-
res.error.code,
|
|
1265
|
-
);
|
|
1266
|
-
}
|
|
764
|
+
async followUp(name: string, text: string): Promise<void> {
|
|
765
|
+
const child = this.requireChild(name);
|
|
766
|
+
await this.supervisor.followUp(name, text);
|
|
767
|
+
this.clearBlocked(child);
|
|
1267
768
|
}
|
|
1268
769
|
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
* only a richer parser when the child actually wrote turns (pi). Otherwise
|
|
1274
|
-
* the pane transcript is the result. `agent_status` is never success/failure
|
|
1275
|
-
* (F26): it reports "done" for successes, LLM errors, and kills alike.
|
|
1276
|
-
*/
|
|
1277
|
-
async collect(
|
|
1278
|
-
name: string,
|
|
1279
|
-
opts: { timeoutMs?: number } = {},
|
|
1280
|
-
): Promise<CollectResult> {
|
|
1281
|
-
const child = this.children.get(name);
|
|
1282
|
-
if (!child)
|
|
1283
|
-
throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
|
|
1284
|
-
|
|
1285
|
-
if (await this.isAgentBlocked(name)) return this.blockedResult(child);
|
|
1286
|
-
|
|
1287
|
-
const timeoutMs = opts.timeoutMs ?? DEFAULTS.turnTimeoutMs;
|
|
1288
|
-
let deadline = this.now() + timeoutMs;
|
|
1289
|
-
// The chat dir may not exist yet at launch (cursor creates it lazily),
|
|
1290
|
-
// so it is resolved per read, not cached — a launch-time null must not
|
|
1291
|
-
// pin the whole collect to the pane path.
|
|
1292
|
-
const chatDirNow = () => this.cursorChatDirOf(child);
|
|
1293
|
-
const cursorChat = await chatDirNow();
|
|
1294
|
-
const initial = cursorChat
|
|
1295
|
-
? parseCursorChat(cursorChat)
|
|
1296
|
-
: parseSessionFile(child.sessionFile);
|
|
1297
|
-
|
|
1298
|
-
const alreadySettled =
|
|
1299
|
-
cursorChat && cursorTurnSettled(initial)
|
|
1300
|
-
? true
|
|
1301
|
-
: isLastTurnComplete(initial);
|
|
1302
|
-
let wait = alreadySettled
|
|
1303
|
-
? "settled"
|
|
1304
|
-
: initial.turns.length > 0
|
|
1305
|
-
? await this.awaitTurn(child, initial, deadline, await chatDirNow())
|
|
1306
|
-
: await this.awaitHerdrSettle(child, deadline);
|
|
1307
|
-
// D: a timeout is only a verdict when the child's artifact is QUIET.
|
|
1308
|
-
// While the session jsonl (or cursor store) is still growing the agent is
|
|
1309
|
-
// demonstrably working, so grant a bounded extension instead of reporting
|
|
1310
|
-
// `running` at the exact deadline. Fully sequential — no second waiter —
|
|
1311
|
-
// so there is no race with the wait above.
|
|
1312
|
-
for (
|
|
1313
|
-
let grace = 0;
|
|
1314
|
-
wait === "timeout" && grace < COLLECT_GRACE_EXTENSIONS;
|
|
1315
|
-
grace += 1
|
|
1316
|
-
) {
|
|
1317
|
-
const chatForProbe = await chatDirNow();
|
|
1318
|
-
if (!(await this.collectArtifactGrowing(child, chatForProbe))) break;
|
|
1319
|
-
// Extend by a full slice off the EXISTING deadline rather than
|
|
1320
|
-
// re-basing on `now`: the probe already consumed one poll interval,
|
|
1321
|
-
// so `now + timeoutMs` would drift past the (1+N)×timeoutMs bound.
|
|
1322
|
-
deadline += timeoutMs;
|
|
1323
|
-
wait =
|
|
1324
|
-
initial.turns.length > 0
|
|
1325
|
-
? await this.awaitTurn(child, initial, deadline, chatForProbe)
|
|
1326
|
-
: await this.awaitHerdrSettle(child, deadline);
|
|
1327
|
-
}
|
|
1328
|
-
if (wait === "blocked") return this.blockedResult(child);
|
|
1329
|
-
const timedOut = wait === "timeout";
|
|
1330
|
-
|
|
1331
|
-
// Re-resolve after the wait: the store appears (and the answer lands in
|
|
1332
|
-
// it) while the child runs, so the initial read above is stale by now.
|
|
1333
|
-
const chatAtCollect = await chatDirNow();
|
|
1334
|
-
const parsed = chatAtCollect
|
|
1335
|
-
? parseCursorChat(chatAtCollect)
|
|
1336
|
-
: parseSessionFile(child.sessionFile);
|
|
1337
|
-
if (parsed.turns.length > 0) {
|
|
1338
|
-
return this.finishCollect(
|
|
1339
|
-
child,
|
|
1340
|
-
parsed,
|
|
1341
|
-
await this.resolveExecution(name, parsed, timedOut, timeoutMs),
|
|
1342
|
-
deadline,
|
|
1343
|
-
);
|
|
1344
|
-
}
|
|
1345
|
-
|
|
1346
|
-
if (wait === "gone") {
|
|
1347
|
-
return this.finishCollect(
|
|
1348
|
-
child,
|
|
1349
|
-
parsed,
|
|
1350
|
-
{
|
|
1351
|
-
status: "aborted",
|
|
1352
|
-
reason: "herdr agent gone (tab or pane closed)",
|
|
1353
|
-
model: child.model ?? null,
|
|
1354
|
-
},
|
|
1355
|
-
deadline,
|
|
1356
|
-
await this.readPaneOutput(child),
|
|
1357
|
-
);
|
|
1358
|
-
}
|
|
1359
|
-
|
|
1360
|
-
return this.finishCollect(
|
|
1361
|
-
child,
|
|
1362
|
-
parsed,
|
|
1363
|
-
await this.executionFromPane(child, timedOut, timeoutMs),
|
|
1364
|
-
deadline,
|
|
1365
|
-
await this.readPaneOutput(child),
|
|
1366
|
-
);
|
|
770
|
+
async abort(name: string): Promise<void> {
|
|
771
|
+
const child = this.requireChild(name);
|
|
772
|
+
await this.supervisor.abort(name);
|
|
773
|
+
this.emitProcess("node_aborted", child.nodeId ?? name, { name });
|
|
1367
774
|
}
|
|
1368
775
|
|
|
1369
|
-
private
|
|
1370
|
-
child
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
deadline: number,
|
|
1374
|
-
paneOutput?: string,
|
|
1375
|
-
): Promise<CollectResult> {
|
|
1376
|
-
const output = paneOutput ?? parsed.output;
|
|
1377
|
-
const lastTurnOutput =
|
|
1378
|
-
paneOutput !== undefined
|
|
1379
|
-
? stripPromptEcho(paneOutput, child.promptText)
|
|
1380
|
-
: parsed.lastTurnOutput;
|
|
1381
|
-
const forVerdict =
|
|
1382
|
-
paneOutput !== undefined
|
|
1383
|
-
? { ...parsed, lastTurnOutput, output: paneOutput }
|
|
1384
|
-
: parsed;
|
|
1385
|
-
const acceptance = await applyVerification(
|
|
1386
|
-
deriveAcceptance(forVerdict, execution, child.pendingCriteria, {
|
|
1387
|
-
...(child.completionGuard ? { completionGuard: true } : {}),
|
|
1388
|
-
}),
|
|
1389
|
-
{
|
|
1390
|
-
cwd: child.worktreePath ?? this.cwd,
|
|
1391
|
-
criteria: child.pendingCriteria,
|
|
1392
|
-
run: this.verifyRunner,
|
|
1393
|
-
timeoutMs: Math.max(5_000, deadline - this.now()),
|
|
1394
|
-
},
|
|
1395
|
-
);
|
|
1396
|
-
|
|
1397
|
-
// C: only a real terminal outcome retires the child into `awaiting`. A
|
|
1398
|
-
// `running` snapshot means collect timed out while the agent is still
|
|
1399
|
-
// alive (F29) — flipping the record to `awaiting` made the parent read
|
|
1400
|
-
// `status` as "turn over, just needs wrapping up". Keep it working so
|
|
1401
|
-
// watch()'s re-arm (A) and any later collect still treat it as live.
|
|
1402
|
-
if (execution.status !== "running") child.state = "awaiting";
|
|
1403
|
-
child.execution = execution;
|
|
1404
|
-
child.acceptance = acceptance;
|
|
1405
|
-
this.onChildUpdate(child);
|
|
1406
|
-
|
|
1407
|
-
// Persist the FULL output next to the session file. The parent's
|
|
1408
|
-
// completion notice carries only a bounded preview; without a durable
|
|
1409
|
-
// full-text artifact the parent must re-derive the text from the session
|
|
1410
|
-
// jsonl (pi) or the SQLite chat store (cursor) by hand — every time.
|
|
1411
|
-
// A `running` snapshot is a mid-turn partial, not a result: skip it so
|
|
1412
|
-
// the file on disk is always a terminal answer. An EMPTY terminal output
|
|
1413
|
-
// must also clear any EARLIER turn's artifact (stale vintage would hand
|
|
1414
|
-
// the previous answer to a later cached collect as this turn's result).
|
|
1415
|
-
let outputFile: string | undefined;
|
|
1416
|
-
if (execution.status === "running") {
|
|
1417
|
-
child.outputFile = undefined;
|
|
1418
|
-
} else {
|
|
1419
|
-
outputFile = this.writeOutputFile(child, output);
|
|
1420
|
-
// Record the truth on the child: cachedCollect reads this, never a
|
|
1421
|
-
// bare existsSync (which cannot tell turns apart).
|
|
1422
|
-
child.outputFile = outputFile;
|
|
1423
|
-
}
|
|
1424
|
-
this.onChildUpdate(child);
|
|
1425
|
-
|
|
1426
|
-
return {
|
|
1427
|
-
execution,
|
|
1428
|
-
output,
|
|
1429
|
-
...(outputFile ? { outputFile } : {}),
|
|
1430
|
-
usage: parsed.usage,
|
|
1431
|
-
model: parsed.model ?? child.model ?? null,
|
|
1432
|
-
acceptance,
|
|
1433
|
-
};
|
|
1434
|
-
}
|
|
1435
|
-
|
|
1436
|
-
/** Path of a child's persisted full-output artifact. */
|
|
1437
|
-
private outputFileFor(name: string): string {
|
|
1438
|
-
return path.join(this.runDir, `${name}.output.md`);
|
|
1439
|
-
}
|
|
1440
|
-
|
|
1441
|
-
/** Write the terminal output to disk; undefined when empty or unwritable.
|
|
1442
|
-
*
|
|
1443
|
-
* A terminal-but-empty output returns undefined AFTER removing a stale
|
|
1444
|
-
* artifact from an earlier turn, so the run dir and ChildRecord agree. */
|
|
1445
|
-
private writeOutputFile(
|
|
1446
|
-
child: ChildRecord,
|
|
1447
|
-
output: string,
|
|
1448
|
-
): string | undefined {
|
|
1449
|
-
const file = this.outputFileFor(child.name);
|
|
1450
|
-
const trimmed = output.trim();
|
|
1451
|
-
if (!trimmed) {
|
|
1452
|
-
try {
|
|
1453
|
-
fs.rmSync(file, { force: true });
|
|
1454
|
-
} catch {
|
|
1455
|
-
// best-effort: the record no longer names it either way
|
|
1456
|
-
}
|
|
1457
|
-
return undefined;
|
|
1458
|
-
}
|
|
1459
|
-
try {
|
|
1460
|
-
fs.writeFileSync(file, `${trimmed}\n`, { mode: 0o600 });
|
|
1461
|
-
return file;
|
|
1462
|
-
} catch {
|
|
1463
|
-
// Best-effort: the preview still carries the text head, and the
|
|
1464
|
-
// session file remains the fallback source.
|
|
1465
|
-
return undefined;
|
|
1466
|
-
}
|
|
1467
|
-
}
|
|
1468
|
-
|
|
1469
|
-
private async readPaneOutput(child: ChildRecord): Promise<string> {
|
|
1470
|
-
if (!child.paneId) return "";
|
|
1471
|
-
const read = await this.client.paneRead(child.paneId, {
|
|
1472
|
-
source: "recent-unwrapped",
|
|
1473
|
-
lines: 200,
|
|
1474
|
-
});
|
|
1475
|
-
return read.ok ? read.value : "";
|
|
776
|
+
private requireChild(name: string): ChildRecord {
|
|
777
|
+
const child = this.children.get(name);
|
|
778
|
+
if (!child) throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
|
|
779
|
+
return child;
|
|
1476
780
|
}
|
|
1477
781
|
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
*
|
|
1481
|
-
* herdr reports the chat id as `agent_session.value` for cursor children;
|
|
1482
|
-
* the id is the directory name under `~/.cursor/chats/<project>/<id>/`.
|
|
1483
|
-
* Returns null for pi kinds, unreadable ids, or a chat not yet on disk —
|
|
1484
|
-
* the caller then falls back to the pane path.
|
|
1485
|
-
*/
|
|
1486
|
-
private async cursorChatDirOf(child: ChildRecord): Promise<string | null> {
|
|
1487
|
-
if (child.kind !== "cursor") return null;
|
|
1488
|
-
const agentState = await this.client.agentGet(child.name);
|
|
1489
|
-
if (!agentState.ok) return null;
|
|
1490
|
-
const chatId = agentState.value.agent_session?.value;
|
|
1491
|
-
if (!chatId) return null;
|
|
1492
|
-
return findCursorChatDir(chatId, {
|
|
1493
|
-
cwd: child.worktreePath ?? this.cwd,
|
|
1494
|
-
...(this.cursorChatsRoot ? { chatsRoot: this.cursorChatsRoot } : {}),
|
|
1495
|
-
});
|
|
782
|
+
private pendingDialogs(name: string): PendingUIRequest[] {
|
|
783
|
+
return (this.uiProxy?.pending() ?? []).filter((request) => request.childName === name && isApprovalRequest(request));
|
|
1496
784
|
}
|
|
1497
785
|
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
* The design contract (design.md §802, F7) pins non-pi kinds to `unknown`:
|
|
1502
|
-
* without a session stopReason there is no authoritative success signal, and
|
|
1503
|
-
* a pane reply is not one. Do NOT promote this to `success` — the lying part
|
|
1504
|
-
* is elsewhere (see notify.completionStatusOf).
|
|
1505
|
-
*/
|
|
1506
|
-
private async executionFromPane(
|
|
1507
|
-
child: ChildRecord,
|
|
1508
|
-
timedOut: boolean,
|
|
1509
|
-
timeoutMs: number,
|
|
1510
|
-
): Promise<Execution> {
|
|
1511
|
-
if (!timedOut) {
|
|
1512
|
-
return {
|
|
1513
|
-
status: "unknown",
|
|
1514
|
-
reason: "no session jsonl; collected from pane",
|
|
1515
|
-
model: child.model ?? null,
|
|
1516
|
-
};
|
|
1517
|
-
}
|
|
1518
|
-
const agentState = await this.client.agentGet(child.name);
|
|
1519
|
-
if (agentState.ok || !agentGone(agentState)) {
|
|
1520
|
-
// Not found means gone; any OTHER failure (a wedged/timed-out CLI,
|
|
1521
|
-
// transport error) says nothing about the child, so assume alive.
|
|
1522
|
-
// Reporting `aborted` here would retire a LIVE child (F29 is only a
|
|
1523
|
-
// verdict for a genuinely missing agent).
|
|
1524
|
-
return {
|
|
1525
|
-
status: "running",
|
|
1526
|
-
reason: agentState.ok
|
|
1527
|
-
? `collect timed out after ${timeoutMs}ms; the agent is still alive`
|
|
1528
|
-
: `collect timed out after ${timeoutMs}ms; agent status unavailable (${agentState.error.code}), assuming alive`,
|
|
1529
|
-
model: child.model ?? null,
|
|
1530
|
-
};
|
|
786
|
+
async approveBlocked(name: string): Promise<void> {
|
|
787
|
+
for (const request of this.pendingDialogs(name)) {
|
|
788
|
+
if (request.request.method === "confirm") this.uiProxy?.respond(request.id, { confirmed: true });
|
|
1531
789
|
}
|
|
1532
|
-
return {
|
|
1533
|
-
status: "aborted",
|
|
1534
|
-
reason: "herdr agent gone (tab or pane closed)",
|
|
1535
|
-
model: child.model ?? null,
|
|
1536
|
-
};
|
|
1537
|
-
}
|
|
1538
|
-
|
|
1539
|
-
/**
|
|
1540
|
-
* Return a previously collected snapshot without waiting on the child.
|
|
1541
|
-
*
|
|
1542
|
-
* Used when the parent model calls `collect` after auto-watch already
|
|
1543
|
-
* derived the outcome (and possibly recycled the pane).
|
|
1544
|
-
*/
|
|
1545
|
-
cachedCollect(name: string): CollectResult | undefined {
|
|
1546
790
|
const child = this.children.get(name);
|
|
1547
|
-
if (
|
|
1548
|
-
if (!canUseCachedCollect(child.state)) return undefined;
|
|
1549
|
-
const parsed = fs.existsSync(child.sessionFile)
|
|
1550
|
-
? parseSessionFile(child.sessionFile)
|
|
1551
|
-
: emptyParsedSession();
|
|
1552
|
-
// Read the recorded truth, not existsSync: the file on disk may be an
|
|
1553
|
-
// EARLIER turn's artifact (this turn's collect wrote none), and a fresh
|
|
1554
|
-
// `running` snapshot must not resurrect it either.
|
|
1555
|
-
const cached: CollectResult = {
|
|
1556
|
-
execution: child.execution,
|
|
1557
|
-
output: parsed.output,
|
|
1558
|
-
usage: parsed.usage ?? child.execution.usage ?? null,
|
|
1559
|
-
model: parsed.model ?? child.execution.model ?? null,
|
|
1560
|
-
acceptance:
|
|
1561
|
-
child.acceptance ?? { status: "unknown", level: "none" },
|
|
1562
|
-
...(child.state === "blocked" ? { blocked: true } : {}),
|
|
1563
|
-
};
|
|
1564
|
-
if (child.outputFile) cached.outputFile = child.outputFile;
|
|
1565
|
-
return cached;
|
|
1566
|
-
}
|
|
1567
|
-
|
|
1568
|
-
/** Unblock a child after the parent approved the pending tool. */
|
|
1569
|
-
async approveBlocked(name: string): Promise<void> {
|
|
1570
|
-
this.clearBlocked(name);
|
|
1571
|
-
await bestEffort(this.client.agentSendKeys(name, "y"));
|
|
791
|
+
if (child) this.clearBlocked(child);
|
|
1572
792
|
}
|
|
1573
793
|
|
|
1574
|
-
/** Unblock a child after the parent denied the pending tool. */
|
|
1575
794
|
async rejectBlocked(name: string): Promise<void> {
|
|
1576
|
-
this.
|
|
1577
|
-
|
|
795
|
+
for (const request of this.pendingDialogs(name)) {
|
|
796
|
+
if (request.request.method === "confirm") this.uiProxy?.respond(request.id, { confirmed: false });
|
|
797
|
+
}
|
|
798
|
+
const child = this.children.get(name);
|
|
799
|
+
if (child) this.clearBlocked(child);
|
|
1578
800
|
}
|
|
1579
801
|
|
|
1580
|
-
|
|
1581
|
-
|
|
1582
|
-
|
|
1583
|
-
|
|
1584
|
-
|
|
1585
|
-
* Slices rather than one remaining-timeout wait so F15 `tab close` surfaces
|
|
1586
|
-
* as `gone` instead of hanging until the worker timeout.
|
|
1587
|
-
*/
|
|
1588
|
-
private async awaitHerdrSettle(
|
|
1589
|
-
child: ChildRecord,
|
|
1590
|
-
deadline: number,
|
|
1591
|
-
): Promise<"settled" | "timeout" | "blocked" | "gone"> {
|
|
1592
|
-
while (this.now() < deadline) {
|
|
1593
|
-
const presence = await this.agentPresence(child.name);
|
|
1594
|
-
if (presence === "blocked") return "blocked";
|
|
1595
|
-
if (presence === "gone") return "gone";
|
|
1596
|
-
const remaining = Math.max(1, deadline - this.now());
|
|
1597
|
-
const waited = await this.client.agentWait(child.name, {
|
|
1598
|
-
timeoutMs: Math.min(remaining, this.waitSliceMs),
|
|
1599
|
-
});
|
|
1600
|
-
if (waited.ok) {
|
|
1601
|
-
if (child.kind === "pi") {
|
|
1602
|
-
await this.waitForQuiet(child.sessionFile, deadline);
|
|
1603
|
-
}
|
|
1604
|
-
const after = await this.agentPresence(child.name);
|
|
1605
|
-
if (after === "blocked") return "blocked";
|
|
1606
|
-
if (after === "gone") return "gone";
|
|
1607
|
-
if (await this.nonPiPaneStillWorking(child)) {
|
|
1608
|
-
continue;
|
|
1609
|
-
}
|
|
1610
|
-
return "settled";
|
|
1611
|
-
}
|
|
1612
|
-
// `agent wait` failed. Distinguish "agent gone" from a transient CLI
|
|
1613
|
-
// failure (a wedged/timed-out command surfaces as a generic error):
|
|
1614
|
-
// ONE extra agentGet answers both presence questions, instead of two
|
|
1615
|
-
// calls that — under a wedged CLI — each burn the full command
|
|
1616
|
-
// timeout and stretch one loop iteration past the deadline.
|
|
1617
|
-
const afterFailure = await this.agentPresence(child.name);
|
|
1618
|
-
if (afterFailure === "gone") return "gone";
|
|
1619
|
-
if (afterFailure === "blocked") return "blocked";
|
|
1620
|
-
if (this.now() >= deadline) return "timeout";
|
|
1621
|
-
await this.sleep(this.pollIntervalMs);
|
|
1622
|
-
}
|
|
1623
|
-
return "timeout";
|
|
802
|
+
private clearBlocked(child: ChildRecord): void {
|
|
803
|
+
if (child.state !== "blocked") return;
|
|
804
|
+
child.state = "working";
|
|
805
|
+
child.execution = undefined;
|
|
806
|
+
this.onChildUpdate(child);
|
|
1624
807
|
}
|
|
1625
808
|
|
|
1626
|
-
|
|
1627
|
-
|
|
1628
|
-
|
|
1629
|
-
|
|
1630
|
-
|
|
1631
|
-
|
|
1632
|
-
|
|
1633
|
-
|
|
1634
|
-
|
|
1635
|
-
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
|
-
|
|
1647
|
-
|
|
1648
|
-
// Structured channel first: when the cursor chat store already shows a
|
|
1649
|
-
// settled turn, the reply is in hand and the pane's rendering is
|
|
1650
|
-
// irrelevant (it can lag the store or wrap the text).
|
|
1651
|
-
const chatDir = await this.cursorChatDirOf(child);
|
|
1652
|
-
const structured = chatDir ? parseCursorChat(chatDir) : null;
|
|
1653
|
-
if (structured && cursorTurnSettled(structured)) {
|
|
1654
|
-
return false;
|
|
809
|
+
async collect(name: string, opts: { timeoutMs?: number; signal?: AbortSignal } = {}): Promise<CollectResult> {
|
|
810
|
+
const child = this.requireChild(name);
|
|
811
|
+
const abortedSnapshot = (): CollectResult => this.interruptedCollect(child, parseSessionFile(child.sessionFile));
|
|
812
|
+
if (opts.signal?.aborted) return abortedSnapshot();
|
|
813
|
+
if (this.pendingDialogs(name).length) return this.blockedResult(child);
|
|
814
|
+
const timeoutMs = opts.timeoutMs ?? DEFAULTS.turnTimeoutMs;
|
|
815
|
+
let deadline = this.now() + timeoutMs;
|
|
816
|
+
const initial = parseSessionFile(child.sessionFile);
|
|
817
|
+
// A connection blip writes stopReason "error" before the client retries.
|
|
818
|
+
// That looks like a finished turn, but the RPC child is still in it.
|
|
819
|
+
// Skipping the supervisor wait here is what retired a live worker.
|
|
820
|
+
let wait: "settled" | "timeout" | "blocked" | "gone" | "aborted" = isLastTurnComplete(initial) && !this.liveConnectionBlip(child, initial)
|
|
821
|
+
? "settled"
|
|
822
|
+
: await this.awaitSupervisor(child, deadline, opts.signal);
|
|
823
|
+
if (wait === "aborted" || opts.signal?.aborted) return abortedSnapshot();
|
|
824
|
+
for (let attempt = 0; wait === "timeout" && attempt < COLLECT_GRACE_EXTENSIONS; attempt += 1) {
|
|
825
|
+
if (opts.signal?.aborted) return abortedSnapshot();
|
|
826
|
+
if (!(await this.collectArtifactGrowing(child, opts.signal))) break;
|
|
827
|
+
if (opts.signal?.aborted) return abortedSnapshot();
|
|
828
|
+
deadline += timeoutMs;
|
|
829
|
+
wait = await this.awaitSupervisor(child, deadline, opts.signal);
|
|
830
|
+
if (wait === "aborted" || opts.signal?.aborted) return abortedSnapshot();
|
|
1655
831
|
}
|
|
1656
|
-
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
if (paneIsBusy(paneOutput)) {
|
|
1662
|
-
await this.sleep(this.pollIntervalMs);
|
|
1663
|
-
return true;
|
|
832
|
+
if (wait === "blocked") return this.blockedResult(child);
|
|
833
|
+
let parsed = parseSessionFile(child.sessionFile);
|
|
834
|
+
if (wait === "settled" && countAssistantMessages(parsed) > 0) {
|
|
835
|
+
await this.waitForQuiet(child.sessionFile, deadline, opts.signal);
|
|
836
|
+
if (opts.signal?.aborted) return abortedSnapshot();
|
|
1664
837
|
}
|
|
1665
|
-
|
|
1666
|
-
|
|
1667
|
-
|
|
1668
|
-
|
|
1669
|
-
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
838
|
+
if (opts.signal?.aborted) return abortedSnapshot();
|
|
839
|
+
parsed = parseSessionFile(child.sessionFile);
|
|
840
|
+
let execution = deriveOutcome(parsed);
|
|
841
|
+
if (wait === "timeout" && this.supervisor.isAlive(name) && !isLastTurnComplete(parsed)) {
|
|
842
|
+
// `timeoutMs` is the budget from launch, not the length of this status check.
|
|
843
|
+
execution = { ...execution, status: "running", reason: COLLECT_DEADLINE_REASON };
|
|
844
|
+
} else if (wait === "gone" && parsed.turns.length === 0) {
|
|
845
|
+
execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };
|
|
846
|
+
} else if (this.supervisor.isAlive(name) && isTransientConnectionFailure(execution)) {
|
|
847
|
+
// Same non-terminal signal as the deadline path: watch() re-arms on
|
|
848
|
+
// `running` and does not retire. An already-settled blip has to keep
|
|
849
|
+
// waiting here, or the next collect would reproduce it instantly.
|
|
850
|
+
if (wait !== "timeout") {
|
|
851
|
+
const held = await this.waitOutTransientConnection(child, deadline, opts.signal);
|
|
852
|
+
if (held === "aborted" || opts.signal?.aborted) return abortedSnapshot();
|
|
853
|
+
if (held === "blocked") return this.blockedResult(child);
|
|
854
|
+
parsed = parseSessionFile(child.sessionFile);
|
|
855
|
+
execution = deriveOutcome(parsed);
|
|
1673
856
|
}
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
|
-
|
|
1677
|
-
|
|
1678
|
-
if (paneNeedsSubmitNudge(paneOutput)) {
|
|
1679
|
-
if (this.now() - this.lastNudgeAt(child.name) >= this.nudgeIntervalMs) {
|
|
1680
|
-
this.nudgeTimestamps.set(child.name, this.now());
|
|
1681
|
-
await bestEffort(this.client.agentSendKeys(child.name, "enter"));
|
|
857
|
+
if (this.supervisor.isAlive(name) && (isTransientConnectionFailure(execution) || !isLastTurnComplete(parsed))) {
|
|
858
|
+
execution = { ...execution, status: "running", reason: TRANSIENT_CONNECTION_REASON };
|
|
859
|
+
} else if (!this.supervisor.isAlive(name) && parsed.turns.length === 0) {
|
|
860
|
+
execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };
|
|
1682
861
|
}
|
|
1683
862
|
}
|
|
1684
|
-
|
|
1685
|
-
return true;
|
|
863
|
+
return this.finishCollect(child, parsed, execution, deadline);
|
|
1686
864
|
}
|
|
1687
865
|
|
|
1688
|
-
/**
|
|
1689
|
-
private
|
|
1690
|
-
return this.
|
|
866
|
+
/** True when the session's latest outcome is a connection blip and the process is up. */
|
|
867
|
+
private liveConnectionBlip(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>): boolean {
|
|
868
|
+
return this.supervisor.isAlive(child.name) && isTransientConnectionFailure(deriveOutcome(parsed));
|
|
1691
869
|
}
|
|
1692
870
|
|
|
1693
871
|
/**
|
|
1694
|
-
*
|
|
1695
|
-
*
|
|
1696
|
-
* Two phases, because they answer different questions: phase 1 asks "did the
|
|
1697
|
-
* turn produce anything at all?" (a collect issued right after launch would
|
|
1698
|
-
* otherwise read the previous, empty state and report "unknown"), phase 2
|
|
1699
|
-
* waits for that turn to stop growing.
|
|
872
|
+
* Hold a live child whose session currently ends on a connection blip.
|
|
1700
873
|
*
|
|
1701
|
-
*
|
|
1702
|
-
*
|
|
1703
|
-
*
|
|
1704
|
-
* @returns whether the turn settled, timed out, hit a tool approval, or the
|
|
1705
|
-
* herdr agent disappeared (tab/pane close).
|
|
874
|
+
* Returns once the session moves past that blip, the process exits, a UI
|
|
875
|
+
* approval arrives, the parent aborts, or the cumulative deadline passes.
|
|
1706
876
|
*/
|
|
1707
|
-
private async
|
|
877
|
+
private async waitOutTransientConnection(
|
|
1708
878
|
child: ChildRecord,
|
|
1709
|
-
initial: ReturnType<typeof parseSessionFile>,
|
|
1710
879
|
deadline: number,
|
|
1711
|
-
|
|
1712
|
-
): Promise<"
|
|
1713
|
-
const
|
|
1714
|
-
const timeoutMs = deadline - this.now();
|
|
1715
|
-
const maxPolls = Math.max(1, Math.ceil(timeoutMs / this.pollIntervalMs)) + 10;
|
|
1716
|
-
|
|
1717
|
-
let progressed = false;
|
|
880
|
+
signal?: AbortSignal,
|
|
881
|
+
): Promise<"aborted" | "blocked" | "done"> {
|
|
882
|
+
const maxPolls = Math.max(1, Math.ceil(Math.max(0, deadline - this.now()) / POLL_INTERVAL_MS));
|
|
1718
883
|
for (let poll = 0; poll < maxPolls; poll += 1) {
|
|
1719
|
-
|
|
1720
|
-
if (
|
|
1721
|
-
if (
|
|
1722
|
-
|
|
1723
|
-
|
|
1724
|
-
|
|
1725
|
-
if (countAssistantMessages(parsed) > before) {
|
|
1726
|
-
progressed = true;
|
|
1727
|
-
break;
|
|
1728
|
-
}
|
|
1729
|
-
if (this.now() >= deadline) break;
|
|
1730
|
-
await this.sleep(this.pollIntervalMs);
|
|
1731
|
-
}
|
|
1732
|
-
|
|
1733
|
-
// Nothing ever appeared: gone is an abort; otherwise the caller gave up.
|
|
1734
|
-
if (!progressed) {
|
|
1735
|
-
if (await this.isAgentGone(child.name)) return "gone";
|
|
1736
|
-
return "timeout";
|
|
884
|
+
if (signal?.aborted) return "aborted";
|
|
885
|
+
if (this.pendingDialogs(child.name).length) return "blocked";
|
|
886
|
+
if (!this.supervisor.isAlive(child.name)) return "done";
|
|
887
|
+
if (!isTransientConnectionFailure(deriveOutcome(parseSessionFile(child.sessionFile)))) return "done";
|
|
888
|
+
if (this.now() >= deadline) return "done";
|
|
889
|
+
if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return "aborted";
|
|
1737
890
|
}
|
|
1738
|
-
|
|
1739
|
-
return this.awaitHerdrSettle(child, deadline);
|
|
891
|
+
return "done";
|
|
1740
892
|
}
|
|
1741
893
|
|
|
1742
|
-
private
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
894
|
+
private interruptedCollect(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>): CollectResult {
|
|
895
|
+
return {
|
|
896
|
+
execution: { status: "running", reason: "aborted by parent" },
|
|
897
|
+
output: parsed.output,
|
|
898
|
+
usage: parsed.usage,
|
|
899
|
+
model: parsed.model ?? child.model ?? null,
|
|
900
|
+
acceptance: { status: "unknown", level: "none", reason: "aborted by parent" },
|
|
901
|
+
};
|
|
1750
902
|
}
|
|
1751
903
|
|
|
1752
|
-
private async
|
|
1753
|
-
|
|
904
|
+
private async awaitSupervisor(
|
|
905
|
+
child: ChildRecord,
|
|
906
|
+
deadline: number,
|
|
907
|
+
signal?: AbortSignal,
|
|
908
|
+
): Promise<"settled" | "timeout" | "blocked" | "gone" | "aborted"> {
|
|
909
|
+
if (signal?.aborted) return "aborted";
|
|
910
|
+
if (this.pendingDialogs(child.name).length) return "blocked";
|
|
911
|
+
let pending = signal ? undefined : this.pendingWaits.get(child.name);
|
|
912
|
+
if (!pending) {
|
|
913
|
+
const wait = this.supervisor.waitSettled(
|
|
914
|
+
child.name,
|
|
915
|
+
Math.max(1, deadline - this.now()),
|
|
916
|
+
...(signal ? [signal] : []),
|
|
917
|
+
);
|
|
918
|
+
pending = wait;
|
|
919
|
+
if (!signal) {
|
|
920
|
+
this.pendingWaits.set(child.name, pending);
|
|
921
|
+
const current = pending;
|
|
922
|
+
void current.then(
|
|
923
|
+
() => { if (this.pendingWaits.get(child.name) === current) this.pendingWaits.delete(child.name); },
|
|
924
|
+
() => { if (this.pendingWaits.get(child.name) === current) this.pendingWaits.delete(child.name); },
|
|
925
|
+
);
|
|
926
|
+
}
|
|
927
|
+
}
|
|
928
|
+
let unsubscribe: (() => void) | undefined;
|
|
929
|
+
let removeAbortListener: (() => void) | undefined;
|
|
930
|
+
try {
|
|
931
|
+
const waitForSettle = pending.then((settled) =>
|
|
932
|
+
settled.reason === "aborted by parent"
|
|
933
|
+
? "aborted" as const
|
|
934
|
+
: this.settleDisposition(settled, child.name),
|
|
935
|
+
);
|
|
936
|
+
if (!this.uiProxy && !signal) return await waitForSettle;
|
|
937
|
+
const waitForChildEvent = waitForSettle.then((result) => {
|
|
938
|
+
if (result === "settled" && child.state === "retired") return "gone" as const;
|
|
939
|
+
return result;
|
|
940
|
+
});
|
|
941
|
+
const blocked = new Promise<"blocked">((resolve) => {
|
|
942
|
+
if (!this.uiProxy) return;
|
|
943
|
+
unsubscribe = this.uiProxy.onRequest((request) => {
|
|
944
|
+
if (request.childName !== child.name || !isApprovalRequest(request) || child.state === "retired") return;
|
|
945
|
+
child.state = "blocked";
|
|
946
|
+
this.onChildUpdate(child);
|
|
947
|
+
resolve("blocked");
|
|
948
|
+
});
|
|
949
|
+
});
|
|
950
|
+
if (this.pendingDialogs(child.name).length) return "blocked";
|
|
951
|
+
const races: Array<Promise<"settled" | "timeout" | "blocked" | "gone" | "aborted">> = [waitForChildEvent];
|
|
952
|
+
if (this.uiProxy) races.push(blocked);
|
|
953
|
+
if (signal) {
|
|
954
|
+
races.push(new Promise((resolve) => {
|
|
955
|
+
const onAbort = () => resolve("aborted");
|
|
956
|
+
removeAbortListener = () => signal.removeEventListener("abort", onAbort);
|
|
957
|
+
if (signal.aborted) onAbort();
|
|
958
|
+
else signal.addEventListener("abort", onAbort, { once: true });
|
|
959
|
+
}));
|
|
960
|
+
}
|
|
961
|
+
return await Promise.race(races);
|
|
962
|
+
} finally {
|
|
963
|
+
unsubscribe?.();
|
|
964
|
+
removeAbortListener?.();
|
|
965
|
+
}
|
|
1754
966
|
}
|
|
1755
967
|
|
|
1756
|
-
private
|
|
1757
|
-
|
|
968
|
+
private settleDisposition(result: SettleResult, name: string): "settled" | "timeout" | "gone" {
|
|
969
|
+
if (result.settled) return "settled";
|
|
970
|
+
if (result.reason === "timeout" || (!result.abnormal && this.supervisor.isAlive(name))) return "timeout";
|
|
971
|
+
// A connection blip reported as an abnormal settle must not look like
|
|
972
|
+
// the process exited while that process is still alive.
|
|
973
|
+
if (this.supervisor.isAlive(name) && isTransientConnectionFailure(result.reason)) return "timeout";
|
|
974
|
+
return "gone";
|
|
1758
975
|
}
|
|
1759
976
|
|
|
1760
977
|
private blockedResult(child: ChildRecord): CollectResult {
|
|
1761
978
|
const parsed = parseSessionFile(child.sessionFile);
|
|
1762
|
-
const execution: Execution = {
|
|
1763
|
-
|
|
1764
|
-
|
|
1765
|
-
};
|
|
1766
|
-
|
|
1767
|
-
|
|
1768
|
-
execution
|
|
1769
|
-
child.
|
|
1770
|
-
|
|
1771
|
-
|
|
1772
|
-
|
|
979
|
+
const execution: Execution = { status: "running", reason: "blocked: waiting for a child UI approval" };
|
|
980
|
+
const acceptance = deriveAcceptance(parsed, execution, child.pendingCriteria, {
|
|
981
|
+
...(child.completionGuard ? { completionGuard: true } : {}),
|
|
982
|
+
});
|
|
983
|
+
if (child.state !== "retired") {
|
|
984
|
+
child.state = "blocked";
|
|
985
|
+
child.execution = execution;
|
|
986
|
+
child.acceptance = acceptance;
|
|
987
|
+
this.onChildUpdate(child);
|
|
988
|
+
}
|
|
989
|
+
return { execution, output: parsed.output, usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance, blocked: true };
|
|
990
|
+
}
|
|
991
|
+
|
|
992
|
+
private async finishCollect(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>, execution: Execution, deadline: number): Promise<CollectResult> {
|
|
993
|
+
const acceptance = await applyVerification(
|
|
994
|
+
deriveAcceptance(parsed, execution, child.pendingCriteria, { ...(child.completionGuard ? { completionGuard: true } : {}) }),
|
|
995
|
+
{ cwd: child.worktreePath ?? this.cwd, criteria: child.pendingCriteria, run: this.verifyRunner, timeoutMs: Math.max(5_000, deadline - this.now()) },
|
|
1773
996
|
);
|
|
1774
|
-
child.state
|
|
997
|
+
const isRetired = () => child.state === "retired";
|
|
998
|
+
// A running child can finish its in-flight collect while an explicit stop
|
|
999
|
+
// is retiring it. Record the result, but never demote a retired lifecycle
|
|
1000
|
+
// state back to awaiting; only a later launch/resume may revive that child.
|
|
1001
|
+
if (execution.status !== "running" && !isRetired()) child.state = "awaiting";
|
|
1775
1002
|
child.execution = execution;
|
|
1776
1003
|
child.acceptance = acceptance;
|
|
1777
|
-
this.
|
|
1778
|
-
|
|
1779
|
-
|
|
1780
|
-
|
|
1781
|
-
usage: parsed.usage,
|
|
1782
|
-
|
|
1783
|
-
|
|
1784
|
-
|
|
1785
|
-
|
|
1004
|
+
if (execution.status !== "running") this.recordSettled(child, execution);
|
|
1005
|
+
if (!isRetired()) this.onChildUpdate(child);
|
|
1006
|
+
const output = execution.status !== "running" && parsed.lastTurnOutput === null ? "" : parsed.output;
|
|
1007
|
+
if (isRetired()) {
|
|
1008
|
+
return { execution, output, usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance };
|
|
1009
|
+
}
|
|
1010
|
+
let outputFile: string | undefined;
|
|
1011
|
+
if (execution.status === "running") child.outputFile = undefined;
|
|
1012
|
+
else {
|
|
1013
|
+
outputFile = this.writeOutputFile(child, output);
|
|
1014
|
+
child.outputFile = outputFile;
|
|
1015
|
+
}
|
|
1016
|
+
if (!isRetired()) this.onChildUpdate(child);
|
|
1017
|
+
return { execution, output, ...(outputFile ? { outputFile } : {}), usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance };
|
|
1786
1018
|
}
|
|
1787
1019
|
|
|
1788
|
-
private
|
|
1789
|
-
const child = this.children.get(name);
|
|
1790
|
-
if (!child) return;
|
|
1791
|
-
child.state = "working";
|
|
1792
|
-
child.execution = undefined;
|
|
1793
|
-
this.onChildUpdate(child);
|
|
1794
|
-
}
|
|
1020
|
+
private outputFileFor(name: string): string { return path.join(this.runDir, `${name}.output.md`); }
|
|
1795
1021
|
|
|
1796
|
-
|
|
1797
|
-
|
|
1798
|
-
|
|
1799
|
-
|
|
1800
|
-
|
|
1801
|
-
|
|
1802
|
-
* gone + no reply -> aborted (killed mid-turn)
|
|
1803
|
-
*/
|
|
1804
|
-
private async resolveExecution(
|
|
1805
|
-
name: string,
|
|
1806
|
-
parsed: ReturnType<typeof parseSessionFile>,
|
|
1807
|
-
timedOut: boolean,
|
|
1808
|
-
timeoutMs: number,
|
|
1809
|
-
): Promise<Execution> {
|
|
1810
|
-
const execution = deriveOutcome(parsed);
|
|
1811
|
-
if (!timedOut || execution.status !== "aborted") return execution;
|
|
1812
|
-
|
|
1813
|
-
const agentState = await this.client.agentGet(name);
|
|
1814
|
-
// Only a definitive NOT_FOUND means the agent is gone. Any other error
|
|
1815
|
-
// (a wedged/timed-out CLI) must NOT flip `aborted` back — but it also
|
|
1816
|
-
// must not CONFIRM it: agentStatus.ok means alive (the running branch),
|
|
1817
|
-
// while a transport failure leaves the derived outcome standing, which
|
|
1818
|
-
// is the pre-timeout behaviour for a hard kill (F29).
|
|
1819
|
-
if (!agentState.ok) {
|
|
1820
|
-
return agentGone(agentState)
|
|
1821
|
-
? execution
|
|
1822
|
-
: {
|
|
1823
|
-
...execution,
|
|
1824
|
-
status: "running",
|
|
1825
|
-
reason: `collect timed out after ${timeoutMs}ms; agent status unavailable (${agentState.error.code}), assuming alive`,
|
|
1826
|
-
};
|
|
1022
|
+
private writeOutputFile(child: ChildRecord, output: string): string | undefined {
|
|
1023
|
+
const file = this.outputFileFor(child.name);
|
|
1024
|
+
const trimmed = output.trim();
|
|
1025
|
+
if (!trimmed) {
|
|
1026
|
+
try { fs.rmSync(file, { force: true }); } catch { /* stale output is best-effort cleanup */ }
|
|
1027
|
+
return undefined;
|
|
1827
1028
|
}
|
|
1828
|
-
|
|
1829
|
-
|
|
1830
|
-
|
|
1831
|
-
|
|
1832
|
-
reason: `collect timed out after ${timeoutMs}ms; the agent is still alive`,
|
|
1833
|
-
};
|
|
1029
|
+
try {
|
|
1030
|
+
fs.writeFileSync(file, `${trimmed}\n`, { mode: 0o600 });
|
|
1031
|
+
return file;
|
|
1032
|
+
} catch { return undefined; }
|
|
1834
1033
|
}
|
|
1835
1034
|
|
|
1836
|
-
|
|
1837
|
-
|
|
1838
|
-
|
|
1839
|
-
|
|
1840
|
-
|
|
1841
|
-
* session jsonl, waits one poll interval, and samples again. A delta means
|
|
1842
|
-
* the agent is mid-write — a live turn, not a stalled one. `waitForQuiet`
|
|
1843
|
-
* itself is not reusable here: it returns on QUIET and would needlessly
|
|
1844
|
-
* discard the "still growing" answer we actually want.
|
|
1845
|
-
*
|
|
1846
|
-
* Deliberately returns `false` once the file is gone/unreadable (size 0 both
|
|
1847
|
-
* samples): no signal means no grace, so the caller keeps the plain timeout.
|
|
1848
|
-
*/
|
|
1849
|
-
private async collectArtifactGrowing(
|
|
1850
|
-
child: ChildRecord,
|
|
1851
|
-
cursorChat: string | null,
|
|
1852
|
-
): Promise<boolean> {
|
|
1853
|
-
const target = cursorChat
|
|
1854
|
-
? path.join(cursorChat, "store.db")
|
|
1855
|
-
: child.sessionFile;
|
|
1856
|
-
const before = artifactSize(target);
|
|
1857
|
-
if (before <= 0) return false;
|
|
1858
|
-
await this.sleep(this.pollIntervalMs);
|
|
1859
|
-
return artifactSize(target) > before;
|
|
1035
|
+
private async collectArtifactGrowing(child: ChildRecord, signal?: AbortSignal): Promise<boolean> {
|
|
1036
|
+
const before = artifactSize(child.sessionFile);
|
|
1037
|
+
if (before <= 0 || signal?.aborted) return false;
|
|
1038
|
+
if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return false;
|
|
1039
|
+
return artifactSize(child.sessionFile) > before;
|
|
1860
1040
|
}
|
|
1861
1041
|
|
|
1862
|
-
|
|
1863
|
-
|
|
1864
|
-
|
|
1865
|
-
|
|
1866
|
-
|
|
1867
|
-
|
|
1868
|
-
|
|
1869
|
-
|
|
1870
|
-
|
|
1871
|
-
|
|
1872
|
-
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
|
-
|
|
1876
|
-
|
|
1877
|
-
|
|
1878
|
-
|
|
1879
|
-
|
|
1880
|
-
|
|
1881
|
-
|
|
1882
|
-
|
|
1883
|
-
|
|
1884
|
-
|
|
1885
|
-
size = fs.statSync(sessionFile).size;
|
|
1886
|
-
} catch {
|
|
1887
|
-
size = 0;
|
|
1888
|
-
}
|
|
1889
|
-
|
|
1890
|
-
if (size !== lastSize) {
|
|
1891
|
-
lastSize = size;
|
|
1892
|
-
quietSince = this.now();
|
|
1893
|
-
} else if (this.now() - quietSince >= DEFAULTS.settleQuietMs) {
|
|
1042
|
+
private async sleepOrAbort(ms: number, signal?: AbortSignal): Promise<boolean> {
|
|
1043
|
+
if (!signal) {
|
|
1044
|
+
await this.sleep(ms);
|
|
1045
|
+
return false;
|
|
1046
|
+
}
|
|
1047
|
+
if (signal.aborted) return true;
|
|
1048
|
+
return new Promise<boolean>((resolve) => {
|
|
1049
|
+
let settled = false;
|
|
1050
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
1051
|
+
const cleanup = () => {
|
|
1052
|
+
signal.removeEventListener("abort", onAbort);
|
|
1053
|
+
if (timer) clearTimeout(timer);
|
|
1054
|
+
};
|
|
1055
|
+
const finish = (aborted: boolean) => {
|
|
1056
|
+
if (settled) return;
|
|
1057
|
+
settled = true;
|
|
1058
|
+
cleanup();
|
|
1059
|
+
resolve(aborted);
|
|
1060
|
+
};
|
|
1061
|
+
const onAbort = () => finish(true);
|
|
1062
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
1063
|
+
if (signal.aborted) {
|
|
1064
|
+
onAbort();
|
|
1894
1065
|
return;
|
|
1895
1066
|
}
|
|
1067
|
+
timer = setTimeout(() => finish(false), ms);
|
|
1068
|
+
});
|
|
1069
|
+
}
|
|
1896
1070
|
|
|
1071
|
+
private async waitForQuiet(sessionFile: string, deadline: number, signal?: AbortSignal): Promise<void> {
|
|
1072
|
+
let previous = -1;
|
|
1073
|
+
let quietSince = this.now();
|
|
1074
|
+
const maxPolls = Math.max(1, Math.ceil(DEFAULTS.turnTimeoutMs / POLL_INTERVAL_MS));
|
|
1075
|
+
for (let poll = 0; poll < maxPolls; poll += 1) {
|
|
1076
|
+
if (signal?.aborted) return;
|
|
1077
|
+
const size = artifactSize(sessionFile);
|
|
1078
|
+
if (size !== previous) { previous = size; quietSince = this.now(); }
|
|
1079
|
+
else if (this.now() - quietSince >= DEFAULTS.settleQuietMs) return;
|
|
1897
1080
|
if (this.now() >= deadline) return;
|
|
1898
|
-
await this.
|
|
1081
|
+
if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return;
|
|
1899
1082
|
}
|
|
1900
1083
|
}
|
|
1901
1084
|
|
|
1902
|
-
|
|
1903
|
-
* Recycle a child.
|
|
1904
|
-
*
|
|
1905
|
-
* ORDER IS MANDATORY (F27): snapshot the outcome BEFORE the agent disappears,
|
|
1906
|
-
* because `agent get` returns `agent_not_found` once it exits.
|
|
1907
|
-
*/
|
|
1908
|
-
async retire(name: string): Promise<ChildRecord> {
|
|
1085
|
+
cachedCollect(name: string): CollectResult | undefined {
|
|
1909
1086
|
const child = this.children.get(name);
|
|
1910
|
-
if (!child)
|
|
1911
|
-
|
|
1912
|
-
|
|
1913
|
-
|
|
1914
|
-
|
|
1915
|
-
|
|
1916
|
-
child.execution
|
|
1917
|
-
|
|
1087
|
+
if (!child?.execution || !canUseCachedCollect(child.state)) return undefined;
|
|
1088
|
+
const parsed = fs.existsSync(child.sessionFile) ? parseSessionFile(child.sessionFile) : emptyParsedSession();
|
|
1089
|
+
const cached: CollectResult = {
|
|
1090
|
+
execution: child.execution,
|
|
1091
|
+
output: child.execution.status !== "running" && parsed.lastTurnOutput === null ? "" : parsed.output,
|
|
1092
|
+
usage: parsed.usage ?? child.execution.usage ?? null,
|
|
1093
|
+
model: parsed.model ?? child.execution.model ?? child.model ?? null,
|
|
1094
|
+
acceptance: child.acceptance ?? { status: "unknown", level: "none" },
|
|
1095
|
+
...(child.state === "blocked" ? { blocked: true } : {}),
|
|
1096
|
+
};
|
|
1097
|
+
if (child.outputFile) cached.outputFile = child.outputFile;
|
|
1098
|
+
return cached;
|
|
1099
|
+
}
|
|
1918
1100
|
|
|
1919
|
-
|
|
1920
|
-
const
|
|
1921
|
-
|
|
1922
|
-
if (
|
|
1923
|
-
|
|
1924
|
-
|
|
1925
|
-
|
|
1926
|
-
|
|
1927
|
-
|
|
1928
|
-
|
|
1929
|
-
|
|
1930
|
-
|
|
1931
|
-
await bestEffort(this.client.agentSendKeys(name, "ctrl+d"));
|
|
1932
|
-
await this.sleep(1_200);
|
|
1101
|
+
async retire(name: string): Promise<ChildRecord> {
|
|
1102
|
+
const child = this.requireChild(name);
|
|
1103
|
+
if (child.state === "retired") return child;
|
|
1104
|
+
if (!child.execution && fs.existsSync(child.sessionFile)) child.execution = deriveOutcome(parseSessionFile(child.sessionFile));
|
|
1105
|
+
if (this.supervisor.isAlive(name)) await this.supervisor.retire(name);
|
|
1106
|
+
if (child.nodeId && this.legion) {
|
|
1107
|
+
if (child.execution && child.execution.status !== "unknown" && child.execution.status !== "running") {
|
|
1108
|
+
this.recordSettled(child, child.execution);
|
|
1109
|
+
if (child.execution.status !== "aborted") this.emitStored(child.nodeId, "node_retired", { parentId: this.legion.nodeId, execution: child.execution.status });
|
|
1110
|
+
} else {
|
|
1111
|
+
updateNode(this.legion.db, child.nodeId, { status: "retired" }, this.now);
|
|
1112
|
+
this.emitStored(child.nodeId, "node_retired", { parentId: this.legion.nodeId });
|
|
1933
1113
|
}
|
|
1934
|
-
|
|
1935
|
-
await bestEffort(this.client.paneClose(paneId));
|
|
1936
|
-
await this.reapTypeTabIfEmpty(child.agent ?? "", paneId, tabId);
|
|
1114
|
+
this.abortLegionPhase(child.nodeId);
|
|
1937
1115
|
}
|
|
1938
|
-
|
|
1939
1116
|
child.state = "retired";
|
|
1940
1117
|
child.retiredAt = new Date(this.now()).toISOString();
|
|
1941
|
-
child.
|
|
1118
|
+
this.emitProcess("node_retired", child.nodeId ?? name, { name });
|
|
1942
1119
|
this.onChildUpdate(child);
|
|
1943
1120
|
return child;
|
|
1944
1121
|
}
|
|
1945
1122
|
|
|
1946
|
-
|
|
1947
|
-
|
|
1948
|
-
*
|
|
1949
|
-
* Same-type agents share a tab; leaving an empty tab behind is the leftover
|
|
1950
|
-
* the parent used to have to close by hand.
|
|
1951
|
-
*/
|
|
1952
|
-
private async reapTypeTabIfEmpty(
|
|
1953
|
-
agentType: string,
|
|
1954
|
-
paneId: string,
|
|
1955
|
-
tabId: string | undefined,
|
|
1956
|
-
): Promise<void> {
|
|
1957
|
-
const released = agentType
|
|
1958
|
-
? this.layout.releasePane(agentType, paneId)
|
|
1959
|
-
: { tabId: undefined, empty: true };
|
|
1960
|
-
if (!released.empty) return;
|
|
1961
|
-
|
|
1962
|
-
const candidate = released.tabId ?? tabId;
|
|
1963
|
-
if (!candidate) return;
|
|
1964
|
-
|
|
1965
|
-
// Another parent (or another Orchestrator of the same parent) may have
|
|
1966
|
-
// panes in this tab that our in-memory layout never tracked. Closing on
|
|
1967
|
-
// "our map is empty" would kill those (F15 is atomic). Ask herdr first.
|
|
1968
|
-
const panes = await this.client.paneList();
|
|
1969
|
-
if (!panes.ok) return;
|
|
1970
|
-
const left = panes.value.filter(
|
|
1971
|
-
(p) => p.tab_id === candidate && p.pane_id !== paneId,
|
|
1972
|
-
);
|
|
1973
|
-
if (left.length > 0) return;
|
|
1974
|
-
await bestEffort(this.client.tabClose(candidate));
|
|
1975
|
-
}
|
|
1976
|
-
|
|
1977
|
-
/** Retire every known child; optionally reap the whole tab (F15). */
|
|
1978
|
-
async retireAll(opts: { tabId?: string } = {}): Promise<ChildRecord[]> {
|
|
1979
|
-
const retired: ChildRecord[] = [];
|
|
1123
|
+
async retireAll(): Promise<ChildRecord[]> {
|
|
1124
|
+
const results: ChildRecord[] = [];
|
|
1980
1125
|
for (const name of [...this.children.keys()]) {
|
|
1981
|
-
try {
|
|
1982
|
-
retired.push(await this.retire(name));
|
|
1983
|
-
} catch {
|
|
1984
|
-
// Keep going: one bad child must not block the rest.
|
|
1985
|
-
}
|
|
1126
|
+
try { results.push(await this.retire(name)); } catch { /* continue with other child processes */ }
|
|
1986
1127
|
}
|
|
1987
|
-
|
|
1988
|
-
return retired;
|
|
1128
|
+
return results;
|
|
1989
1129
|
}
|
|
1990
1130
|
|
|
1991
|
-
|
|
1992
|
-
* Audit for orphan panes: panes present in our tab but absent from our tree.
|
|
1993
|
-
* herdr enforces no isolation (F23-F25), so this detects — never prevents —
|
|
1994
|
-
* out-of-band pane creation.
|
|
1995
|
-
*/
|
|
1996
|
-
async auditOrphans(tabId: string): Promise<string[]> {
|
|
1997
|
-
const res = await this.client.paneList();
|
|
1998
|
-
if (!res.ok) return [];
|
|
1999
|
-
const known = new Set(
|
|
2000
|
-
[...this.children.values()].flatMap((c) => (c.paneId ? [c.paneId] : [])),
|
|
2001
|
-
);
|
|
2002
|
-
return res.value.flatMap((p) =>
|
|
2003
|
-
p.tab_id === tabId && !known.has(p.pane_id) ? [p.pane_id] : [],
|
|
2004
|
-
);
|
|
2005
|
-
}
|
|
2006
|
-
|
|
2007
|
-
/**
|
|
2008
|
-
* Best-effort live fields for the parent status widget.
|
|
2009
|
-
*
|
|
2010
|
-
* Pi children are covered by session jsonl. Non-pi kinds (F7) have no
|
|
2011
|
-
* session ref, so this also reads `agent get` / pane title and maps
|
|
2012
|
-
* whatever labels, tokens, or model-like title those CLIs expose.
|
|
2013
|
-
*/
|
|
2014
|
-
async probeProgress(name: string): Promise<LiveProgress> {
|
|
2015
|
-
const child = this.children.get(name);
|
|
2016
|
-
if (!child) return {};
|
|
2017
|
-
const parts: LiveProgress[] = [];
|
|
2018
|
-
if (child.paneId) {
|
|
2019
|
-
const pane = await this.client.paneGet(child.paneId);
|
|
2020
|
-
if (pane.ok) parts.push(progressFromPaneInfo(pane.value));
|
|
2021
|
-
}
|
|
2022
|
-
const agentState = await this.client.agentGet(name);
|
|
2023
|
-
if (agentState.ok) parts.push(progressFromAgentInfo(agentState.value));
|
|
2024
|
-
parts.push(progressFromSession(parseSessionFile(child.sessionFile)));
|
|
2025
|
-
return mergeProgress(...parts);
|
|
2026
|
-
}
|
|
1131
|
+
childrenSnapshot(): ChildRecord[] { return [...this.children.values()]; }
|
|
2027
1132
|
|
|
2028
|
-
|
|
2029
|
-
|
|
1133
|
+
/** Whether the RPC process for this child is still running. */
|
|
1134
|
+
isChildAlive(name: string): boolean {
|
|
1135
|
+
return this.supervisor.isAlive(name);
|
|
2030
1136
|
}
|
|
2031
1137
|
|
|
2032
|
-
/** Rehydrate from a persisted run record (crash recovery). */
|
|
2033
1138
|
restore(record: RunRecord): void {
|
|
2034
1139
|
for (const child of record.children) {
|
|
2035
|
-
this.
|
|
1140
|
+
const node = this.legion && !child.nodeId ? getChildByName(this.legion.db, this.legion.nodeId, child.name) : null;
|
|
1141
|
+
this.children.set(child.name, { ...child, ...(node ? { nodeId: node.id } : {}) });
|
|
2036
1142
|
}
|
|
1143
|
+
this.spawned = Math.max(this.spawned, record.budget.spawned);
|
|
2037
1144
|
}
|
|
2038
1145
|
}
|