@xzzpig/pi-subagents 0.1.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.
Files changed (196) hide show
  1. package/CHANGELOG.md +1621 -0
  2. package/LICENSE +21 -0
  3. package/README.md +118 -0
  4. package/agents/delegate.md +14 -0
  5. package/agents/oracle.md +74 -0
  6. package/agents/researcher.md +52 -0
  7. package/agents/reviewer.md +79 -0
  8. package/agents/scout.md +50 -0
  9. package/agents/worker.md +58 -0
  10. package/index.ts +1 -0
  11. package/inspector-runner.mjs +11 -0
  12. package/install.mjs +93 -0
  13. package/package.json +105 -0
  14. package/prompts/gather-context-and-clarify.md +13 -0
  15. package/prompts/parallel-cleanup.md +59 -0
  16. package/prompts/parallel-research.md +50 -0
  17. package/prompts/parallel-review.md +54 -0
  18. package/prompts/review-loop.md +43 -0
  19. package/skills/pi-subagents/SKILL.md +41 -0
  20. package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
  21. package/skills/pi-subagents/references/execution-controls.md +428 -0
  22. package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
  24. package/src/agents/agent-management.ts +1256 -0
  25. package/src/agents/agent-memory.ts +254 -0
  26. package/src/agents/agent-refinements.ts +624 -0
  27. package/src/agents/agent-scope.ts +6 -0
  28. package/src/agents/agent-selection.ts +25 -0
  29. package/src/agents/agent-serializer.ts +163 -0
  30. package/src/agents/agents.ts +1889 -0
  31. package/src/agents/chain-serializer.ts +280 -0
  32. package/src/agents/frontmatter.ts +149 -0
  33. package/src/agents/identity.ts +30 -0
  34. package/src/agents/proactive-skills.ts +194 -0
  35. package/src/agents/skills.ts +761 -0
  36. package/src/api/background-work.ts +197 -0
  37. package/src/api/capability-ceiling.ts +17 -0
  38. package/src/api/control-channel.ts +4 -0
  39. package/src/api/delegation.ts +119 -0
  40. package/src/api/external-runs.ts +129 -0
  41. package/src/api/intercom-bridge.ts +3 -0
  42. package/src/api/pi-args.ts +5 -0
  43. package/src/api/preflight.ts +403 -0
  44. package/src/api/shared-types.ts +19 -0
  45. package/src/extension/config.ts +76 -0
  46. package/src/extension/control-notices.ts +58 -0
  47. package/src/extension/doctor.ts +230 -0
  48. package/src/extension/fanout-child.ts +201 -0
  49. package/src/extension/index.ts +805 -0
  50. package/src/extension/public-execution.ts +71 -0
  51. package/src/extension/rpc.ts +653 -0
  52. package/src/extension/schemas.ts +375 -0
  53. package/src/extension/steering-notices.ts +35 -0
  54. package/src/extension/tool-description.ts +164 -0
  55. package/src/inspectors/herdr/actions.ts +229 -0
  56. package/src/inspectors/herdr/client.ts +130 -0
  57. package/src/inspectors/herdr/inspector-runner.ts +141 -0
  58. package/src/inspectors/herdr/project-panes.ts +154 -0
  59. package/src/integrations/herdr-status.ts +330 -0
  60. package/src/intercom/intercom-bridge.ts +187 -0
  61. package/src/intercom/native-supervisor-channel.ts +715 -0
  62. package/src/intercom/result-intercom.ts +421 -0
  63. package/src/missions/actions.ts +410 -0
  64. package/src/missions/goal-driver.ts +162 -0
  65. package/src/missions/lifecycle.ts +346 -0
  66. package/src/missions/store.ts +507 -0
  67. package/src/missions/types.ts +157 -0
  68. package/src/missions/workflow-state.ts +250 -0
  69. package/src/policy/authority.ts +46 -0
  70. package/src/profiles/profiles.ts +661 -0
  71. package/src/runs/background/async-execution.ts +1574 -0
  72. package/src/runs/background/async-job-tracker.ts +511 -0
  73. package/src/runs/background/async-resume.ts +539 -0
  74. package/src/runs/background/async-status.ts +542 -0
  75. package/src/runs/background/auto-drain.ts +67 -0
  76. package/src/runs/background/chain-append.ts +328 -0
  77. package/src/runs/background/chain-root-attachment.ts +199 -0
  78. package/src/runs/background/completion-batcher.ts +168 -0
  79. package/src/runs/background/completion-dedupe.ts +54 -0
  80. package/src/runs/background/control-channel.ts +692 -0
  81. package/src/runs/background/fleet-view.ts +540 -0
  82. package/src/runs/background/notify.ts +332 -0
  83. package/src/runs/background/parallel-groups.ts +45 -0
  84. package/src/runs/background/process-terminal.ts +280 -0
  85. package/src/runs/background/result-watcher.ts +414 -0
  86. package/src/runs/background/retained-children.ts +68 -0
  87. package/src/runs/background/run-id-resolver.ts +167 -0
  88. package/src/runs/background/run-status.ts +504 -0
  89. package/src/runs/background/scheduled-runs.ts +753 -0
  90. package/src/runs/background/stale-run-reconciler.ts +396 -0
  91. package/src/runs/background/steering.ts +239 -0
  92. package/src/runs/background/subagent-runner.ts +4718 -0
  93. package/src/runs/background/subagent-wait.ts +661 -0
  94. package/src/runs/background/top-level-async.ts +14 -0
  95. package/src/runs/background/wait-completions.ts +112 -0
  96. package/src/runs/background/wait-config.ts +36 -0
  97. package/src/runs/background/wait-subscriptions.ts +253 -0
  98. package/src/runs/background/wait-tool.ts +34 -0
  99. package/src/runs/foreground/async-steering-action.ts +256 -0
  100. package/src/runs/foreground/async-stop-action.ts +65 -0
  101. package/src/runs/foreground/chain-clarify.ts +1354 -0
  102. package/src/runs/foreground/chain-execution.ts +1527 -0
  103. package/src/runs/foreground/execution.ts +1868 -0
  104. package/src/runs/foreground/foreground-control.ts +132 -0
  105. package/src/runs/foreground/subagent-executor.ts +5532 -0
  106. package/src/runs/shared/acceptance.ts +1365 -0
  107. package/src/runs/shared/agent-contract.ts +38 -0
  108. package/src/runs/shared/capability-ceiling.ts +209 -0
  109. package/src/runs/shared/chain-outputs.ts +118 -0
  110. package/src/runs/shared/child-protocol.ts +401 -0
  111. package/src/runs/shared/completion-guard.ts +95 -0
  112. package/src/runs/shared/context-mode.ts +44 -0
  113. package/src/runs/shared/dynamic-fanout.ts +297 -0
  114. package/src/runs/shared/external-cli-runner.ts +130 -0
  115. package/src/runs/shared/long-running-guard.ts +220 -0
  116. package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
  117. package/src/runs/shared/model-fallback.ts +336 -0
  118. package/src/runs/shared/model-scope.ts +128 -0
  119. package/src/runs/shared/nested-events.ts +1076 -0
  120. package/src/runs/shared/nested-path.ts +52 -0
  121. package/src/runs/shared/nested-render.ts +123 -0
  122. package/src/runs/shared/parallel-handoff.ts +238 -0
  123. package/src/runs/shared/parallel-utils.ts +256 -0
  124. package/src/runs/shared/permissions.ts +95 -0
  125. package/src/runs/shared/pi-args.ts +808 -0
  126. package/src/runs/shared/pi-spawn.ts +163 -0
  127. package/src/runs/shared/process-signal.ts +19 -0
  128. package/src/runs/shared/run-history.ts +181 -0
  129. package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
  130. package/src/runs/shared/session-lease.ts +299 -0
  131. package/src/runs/shared/single-output.ts +235 -0
  132. package/src/runs/shared/spawn-budget.ts +128 -0
  133. package/src/runs/shared/structured-output.ts +182 -0
  134. package/src/runs/shared/subagent-control.ts +231 -0
  135. package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
  136. package/src/runs/shared/subagent-startup-retry.ts +104 -0
  137. package/src/runs/shared/task-intent.ts +181 -0
  138. package/src/runs/shared/tool-availability.ts +83 -0
  139. package/src/runs/shared/tool-budget.ts +80 -0
  140. package/src/runs/shared/turn-budget.ts +98 -0
  141. package/src/runs/shared/usage-budget.ts +65 -0
  142. package/src/runs/shared/workflow-graph.ts +231 -0
  143. package/src/runs/shared/worktree.ts +759 -0
  144. package/src/shared/accessible-dir.ts +47 -0
  145. package/src/shared/artifacts.ts +285 -0
  146. package/src/shared/atomic-json.ts +61 -0
  147. package/src/shared/child-transcript.ts +264 -0
  148. package/src/shared/file-coalescer.ts +40 -0
  149. package/src/shared/file-system-retry.ts +47 -0
  150. package/src/shared/fork-context.ts +213 -0
  151. package/src/shared/formatters.ts +133 -0
  152. package/src/shared/jsonl-writer.ts +81 -0
  153. package/src/shared/launch-contract.ts +124 -0
  154. package/src/shared/model-info.ts +81 -0
  155. package/src/shared/post-exit-stdio-guard.ts +85 -0
  156. package/src/shared/session-identity.ts +10 -0
  157. package/src/shared/session-tokens.ts +44 -0
  158. package/src/shared/settings.ts +501 -0
  159. package/src/shared/status-format.ts +55 -0
  160. package/src/shared/types.ts +2069 -0
  161. package/src/shared/utils.ts +613 -0
  162. package/src/slash/delegation-adapters.ts +434 -0
  163. package/src/slash/delegation-json.ts +108 -0
  164. package/src/slash/delegation-request.ts +166 -0
  165. package/src/slash/prompt-template-bridge.ts +383 -0
  166. package/src/slash/prompt-workflows.ts +300 -0
  167. package/src/slash/selector.ts +147 -0
  168. package/src/slash/slash-bridge.ts +192 -0
  169. package/src/slash/slash-commands.ts +994 -0
  170. package/src/slash/slash-live-state.ts +296 -0
  171. package/src/slash/subagents-admin.ts +432 -0
  172. package/src/tui/fleet-status.ts +564 -0
  173. package/src/tui/fleet-transcript.ts +577 -0
  174. package/src/tui/fleet.ts +879 -0
  175. package/src/tui/render-helpers.ts +80 -0
  176. package/src/tui/render.ts +2029 -0
  177. package/src/types/pi-runtime-compat.d.ts +8 -0
  178. package/src/watchdog/change-signature.ts +220 -0
  179. package/src/watchdog/child-status.ts +205 -0
  180. package/src/watchdog/emission-guard.ts +123 -0
  181. package/src/watchdog/lsp-diagnostics.ts +537 -0
  182. package/src/watchdog/model-selection.ts +167 -0
  183. package/src/watchdog/permission-arbiter.ts +145 -0
  184. package/src/watchdog/register-child.ts +117 -0
  185. package/src/watchdog/register-main.ts +440 -0
  186. package/src/watchdog/render.ts +54 -0
  187. package/src/watchdog/review.ts +302 -0
  188. package/src/watchdog/runtime.ts +868 -0
  189. package/src/watchdog/scope.ts +62 -0
  190. package/src/watchdog/settings.ts +568 -0
  191. package/src/watchdog/tool-actions.ts +155 -0
  192. package/src/watchdog/turn-delta.ts +161 -0
  193. package/src/watchdog/types.ts +198 -0
  194. package/src/watchdog/warning-format.ts +73 -0
  195. package/src/workflows/chat-progress.ts +140 -0
  196. package/src/workflows/scripted-workflow.ts +506 -0
@@ -0,0 +1,396 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { writeAtomicJson } from "../../shared/atomic-json.ts";
4
+ import { DIRS, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode } from "../../shared/types.ts";
5
+ import { resolveEffectiveThinking } from "../../shared/model-info.ts";
6
+ import { normalizeParallelGroups } from "./parallel-groups.ts";
7
+ import { nestedSummaryFromAsyncStatus, projectNestedEvents, resolveNestedAsyncDir, writeNestedEvent, type NestedRoute } from "../shared/nested-events.ts";
8
+
9
+ export type PidLiveness = "alive" | "dead" | "unknown";
10
+
11
+ type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
12
+
13
+ interface StartedRunMetadata {
14
+ runId: string;
15
+ pid?: number;
16
+ sessionId?: string;
17
+ mode?: SubagentRunMode;
18
+ agents?: string[];
19
+ chainStepCount?: number;
20
+ parallelGroups?: AsyncParallelGroupStatus[];
21
+ startedAt?: number;
22
+ sessionFile?: string;
23
+ }
24
+
25
+ interface ReconcileAsyncRunOptions {
26
+ resultsDir?: string;
27
+ kill?: KillFn;
28
+ now?: () => number;
29
+ startedRun?: StartedRunMetadata;
30
+ missingStatusGraceMs?: number;
31
+ staleAlivePidMs?: number;
32
+ }
33
+
34
+ interface ReconcileAsyncRunResult {
35
+ status: AsyncStatus | null;
36
+ repaired: boolean;
37
+ resultPath?: string;
38
+ message?: string;
39
+ }
40
+
41
+ function getErrorMessage(error: unknown): string {
42
+ return error instanceof Error ? error.message : String(error);
43
+ }
44
+
45
+ function readRunnerStartupDiagnostics(asyncDir: string): string | undefined {
46
+ const stderrPath = path.join(asyncDir, "runner.stderr.log");
47
+ const maxBytes = 64 * 1024;
48
+ let content: string;
49
+ try {
50
+ const stat = fs.statSync(stderrPath);
51
+ if (stat.size <= 0) return undefined;
52
+ const fd = fs.openSync(stderrPath, "r");
53
+ try {
54
+ const bytesToRead = Math.min(stat.size, maxBytes);
55
+ const start = Math.max(0, stat.size - bytesToRead);
56
+ const buffer = Buffer.alloc(bytesToRead);
57
+ fs.readSync(fd, buffer, 0, bytesToRead, start);
58
+ content = buffer.toString("utf-8").trim();
59
+ } finally {
60
+ fs.closeSync(fd);
61
+ }
62
+ } catch {
63
+ return undefined;
64
+ }
65
+ if (!content) return undefined;
66
+ const lines = content.split(/\r?\n/).slice(-30).join("\n");
67
+ return lines.length > 4000 ? `${lines.slice(-4000)}\n[stderr tail truncated]` : lines;
68
+ }
69
+
70
+ function isNotFoundError(error: unknown): boolean {
71
+ return typeof error === "object"
72
+ && error !== null
73
+ && "code" in error
74
+ && (error as NodeJS.ErrnoException).code === "ENOENT";
75
+ }
76
+
77
+ function appendJsonlBestEffort(filePath: string, payload: object): void {
78
+ try {
79
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
80
+ fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`, "utf-8");
81
+ } catch {
82
+ // Repair status/result writes are the important path. A broken or full
83
+ // diagnostic event log must not make stale-run reconciliation fail.
84
+ }
85
+ }
86
+
87
+ function readStatusFile(asyncDir: string): AsyncStatus | null {
88
+ const statusPath = path.join(asyncDir, "status.json");
89
+ let content: string;
90
+ try {
91
+ content = fs.readFileSync(statusPath, "utf-8");
92
+ } catch (error) {
93
+ if (isNotFoundError(error)) return null;
94
+ throw new Error(`Failed to read async status file '${statusPath}': ${getErrorMessage(error)}`, {
95
+ cause: error instanceof Error ? error : undefined,
96
+ });
97
+ }
98
+ try {
99
+ return JSON.parse(content) as AsyncStatus;
100
+ } catch (error) {
101
+ throw new Error(`Failed to parse async status file '${statusPath}': ${getErrorMessage(error)}`, {
102
+ cause: error instanceof Error ? error : undefined,
103
+ });
104
+ }
105
+ }
106
+
107
+ interface ResultChildOutcome {
108
+ agent?: string;
109
+ success?: boolean;
110
+ error?: string;
111
+ sessionFile?: string;
112
+ model?: string;
113
+ thinking?: string;
114
+ attemptedModels?: string[];
115
+ modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
116
+ }
117
+
118
+ interface ResultRepairData {
119
+ state: "complete" | "failed" | "paused" | "stopped";
120
+ results?: ResultChildOutcome[];
121
+ }
122
+
123
+ function readResultRepairData(resultPath: string): ResultRepairData | undefined {
124
+ try {
125
+ const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as { success?: boolean; state?: string; exitCode?: number; results?: unknown };
126
+ const state = data.success ? "complete" : data.state === "stopped" ? "stopped" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
127
+ const results = Array.isArray(data.results)
128
+ ? data.results.map((entry, index) => {
129
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) return {};
130
+ const child = entry as ResultChildOutcome;
131
+ if (child.model !== undefined && typeof child.model !== "string") throw new Error(`Invalid async result file '${resultPath}': results[${index}].model must be a string.`);
132
+ if (child.thinking !== undefined && typeof child.thinking !== "string") throw new Error(`Invalid async result file '${resultPath}': results[${index}].thinking must be a string.`);
133
+ return child;
134
+ })
135
+ : undefined;
136
+ return { state, ...(results ? { results } : {}) };
137
+ } catch (error) {
138
+ if (isNotFoundError(error)) return undefined;
139
+ throw new Error(`Failed to read async result file '${resultPath}': ${getErrorMessage(error)}`, {
140
+ cause: error instanceof Error ? error : undefined,
141
+ });
142
+ }
143
+ }
144
+
145
+ function childState(overallState: ResultRepairData["state"], child: ResultChildOutcome | undefined): "complete" | "failed" | "paused" | "stopped" {
146
+ if (child?.success === true) return "complete";
147
+ if (child?.success === false) return "failed";
148
+ return overallState;
149
+ }
150
+
151
+ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now: number): AsyncStatus | undefined {
152
+ const repair = readResultRepairData(resultPath);
153
+ if (!repair) return undefined;
154
+ const steps = (status.steps ?? []).map((step, index) => {
155
+ if (step.status !== "running" && step.status !== "pending") return step;
156
+ const child = repair.results?.[index];
157
+ const state = childState(repair.state, child);
158
+ const model = child?.model ?? step.model;
159
+ const thinking = resolveEffectiveThinking(model, child?.thinking ?? step.thinking);
160
+ return {
161
+ ...step,
162
+ status: state === "complete" ? "complete" as const : state,
163
+ endedAt: step.endedAt ?? now,
164
+ durationMs: step.startedAt !== undefined && step.durationMs === undefined ? Math.max(0, now - step.startedAt) : step.durationMs,
165
+ exitCode: step.exitCode ?? (state === "complete" || state === "paused" ? 0 : 1),
166
+ error: state === "failed" || state === "stopped" ? step.error ?? child?.error : step.error,
167
+ stopped: state === "stopped" ? true : step.stopped,
168
+ sessionFile: step.sessionFile ?? child?.sessionFile,
169
+ model,
170
+ thinking,
171
+ attemptedModels: child?.attemptedModels ?? step.attemptedModels,
172
+ modelAttempts: child?.modelAttempts ?? step.modelAttempts,
173
+ };
174
+ });
175
+ return {
176
+ ...status,
177
+ state: repair.state,
178
+ ...(status.lifecycleArtifactVersion === 3 && (!status.processTerminal || status.processTerminal.state === "pending") ? {
179
+ processTerminal: { version: 1 as const, state: "unknown" as const, runId: status.runId, runnerProcessInstanceId: "observer-unavailable", reason: "observer-unavailable" as const },
180
+ } : {}),
181
+ ...(repair.state === "stopped" ? { stopped: true } : {}),
182
+ activityState: undefined,
183
+ lastUpdate: now,
184
+ endedAt: status.endedAt ?? now,
185
+ steps,
186
+ };
187
+ }
188
+
189
+ function buildStartedStatus(asyncDir: string, startedRun: StartedRunMetadata, now: number): AsyncStatus {
190
+ const startedAt = startedRun.startedAt ?? now;
191
+ const agents = startedRun.agents?.length ? startedRun.agents : ["subagent"];
192
+ const chainStepCount = startedRun.chainStepCount;
193
+ const parallelGroups = chainStepCount !== undefined
194
+ ? normalizeParallelGroups(startedRun.parallelGroups, agents.length, chainStepCount)
195
+ : [];
196
+ return {
197
+ runId: startedRun.runId || path.basename(asyncDir),
198
+ ...(startedRun.sessionId ? { sessionId: startedRun.sessionId } : {}),
199
+ mode: startedRun.mode ?? "single",
200
+ state: "running",
201
+ pid: startedRun.pid,
202
+ startedAt,
203
+ lastUpdate: now,
204
+ currentStep: 0,
205
+ ...(chainStepCount !== undefined ? { chainStepCount } : {}),
206
+ ...(parallelGroups.length ? { parallelGroups } : {}),
207
+ steps: agents.map((agent) => ({
208
+ agent,
209
+ status: "running" as const,
210
+ startedAt,
211
+ })),
212
+ ...(startedRun.sessionFile ? { sessionFile: startedRun.sessionFile } : {}),
213
+ };
214
+ }
215
+
216
+ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, reason?: string): { status: AsyncStatus; result: object; message: string } {
217
+ const runId = status.runId || path.basename(asyncDir);
218
+ const pid = typeof status.pid === "number" ? status.pid : "unknown";
219
+ const baseMessage = reason ?? `Async runner process ${pid} exited or disappeared before writing a result. Marked run failed by stale-run reconciliation.`;
220
+ const diagnostics = readRunnerStartupDiagnostics(asyncDir);
221
+ const message = diagnostics ? `${baseMessage}\n\nRunner stderr tail:\n${diagnostics}` : baseMessage;
222
+ const steps = status.steps?.length ? status.steps : [{ agent: "subagent", status: "running" as const }];
223
+ const repairedSteps = steps.map((step) => step.status === "running" || step.status === "pending"
224
+ ? {
225
+ ...step,
226
+ status: "failed" as const,
227
+ activityState: undefined,
228
+ endedAt: step.endedAt ?? now,
229
+ durationMs: step.startedAt !== undefined && step.durationMs === undefined ? Math.max(0, now - step.startedAt) : step.durationMs,
230
+ exitCode: step.exitCode ?? 1,
231
+ error: step.error ?? message,
232
+ }
233
+ : step);
234
+ const repairedStatus: AsyncStatus = {
235
+ ...status,
236
+ state: "failed",
237
+ ...(status.lifecycleArtifactVersion === 3 && (!status.processTerminal || status.processTerminal.state === "pending") ? {
238
+ processTerminal: { version: 1 as const, state: "unknown" as const, runId, runnerProcessInstanceId: "observer-unavailable", reason: "stale-repair" as const },
239
+ } : {}),
240
+ activityState: undefined,
241
+ lastUpdate: now,
242
+ endedAt: now,
243
+ steps: repairedSteps,
244
+ };
245
+ const resultAgent = repairedSteps[status.currentStep ?? 0]?.agent ?? repairedSteps[0]?.agent ?? "subagent";
246
+ return {
247
+ status: repairedStatus,
248
+ message,
249
+ result: {
250
+ id: runId,
251
+ agent: resultAgent,
252
+ mode: status.mode,
253
+ success: false,
254
+ state: "failed",
255
+ summary: message,
256
+ results: repairedSteps.map((step) => ({
257
+ agent: step.agent,
258
+ output: step.status === "complete" || step.status === "completed" ? "" : message,
259
+ error: step.status === "complete" || step.status === "completed" ? undefined : step.error ?? message,
260
+ success: step.status === "complete" || step.status === "completed",
261
+ model: step.model,
262
+ attemptedModels: step.attemptedModels,
263
+ modelAttempts: step.modelAttempts,
264
+ sessionFile: step.sessionFile,
265
+ })),
266
+ exitCode: 1,
267
+ timestamp: now,
268
+ durationMs: Math.max(0, now - status.startedAt),
269
+ asyncDir,
270
+ sessionId: status.sessionId,
271
+ sessionFile: status.sessionFile,
272
+ },
273
+ };
274
+ }
275
+
276
+ function writeFailedRepair(asyncDir: string, status: AsyncStatus, resultPath: string, now: number, reason?: string): ReconcileAsyncRunResult {
277
+ const repair = buildFailedRepair(status, asyncDir, now, reason);
278
+ writeAtomicJson(resultPath, repair.result);
279
+ writeAtomicJson(path.join(asyncDir, "status.json"), repair.status);
280
+ appendJsonlBestEffort(path.join(asyncDir, "events.jsonl"), {
281
+ type: "subagent.run.repaired_stale",
282
+ ts: now,
283
+ runId: repair.status.runId,
284
+ pid: status.pid,
285
+ resultPath,
286
+ message: repair.message,
287
+ });
288
+ return { status: repair.status, repaired: true, resultPath, message: repair.message };
289
+ }
290
+
291
+ function terminal(state: AsyncStatus["state"]): boolean {
292
+ return state === "complete" || state === "failed" || state === "paused" || state === "stopped";
293
+ }
294
+
295
+ function* nestedRuns(children: NestedRunSummary[] | undefined): Generator<NestedRunSummary> {
296
+ for (const child of children ?? []) {
297
+ yield child;
298
+ yield* nestedRuns(child.children);
299
+ yield* nestedRuns(child.steps?.flatMap((step) => step.children ?? []));
300
+ }
301
+ }
302
+
303
+ export function reconcileNestedAsyncDescendants(route: NestedRoute, options: ReconcileAsyncRunOptions = {}): void {
304
+ const registry = projectNestedEvents(route);
305
+ for (const run of nestedRuns(registry.children)) {
306
+ if (run.state !== "running" && run.state !== "queued") continue;
307
+ const asyncDir = resolveNestedAsyncDir(route.rootRunId, run);
308
+ if (!asyncDir) continue;
309
+ const result = reconcileAsyncRun(asyncDir, {
310
+ ...options,
311
+ resultsDir: path.join(options.resultsDir ?? DIRS.results, "nested", route.rootRunId),
312
+ });
313
+ const status = result.status;
314
+ if (!status) continue;
315
+ if (!result.repaired && !terminal(status.state)) continue;
316
+ const ts = options.now?.() ?? Date.now();
317
+ writeNestedEvent(route, {
318
+ type: terminal(status.state) ? "subagent.nested.completed" : "subagent.nested.updated",
319
+ ts,
320
+ parentRunId: run.parentRunId,
321
+ parentStepIndex: run.parentStepIndex,
322
+ child: nestedSummaryFromAsyncStatus(status, asyncDir, {
323
+ id: run.id,
324
+ parentRunId: run.parentRunId,
325
+ parentStepIndex: run.parentStepIndex,
326
+ depth: run.depth,
327
+ path: run.path,
328
+ mode: run.mode,
329
+ ts,
330
+ }),
331
+ });
332
+ }
333
+ }
334
+
335
+ export function checkPidLiveness(pid: number, kill: KillFn = process.kill): PidLiveness {
336
+ try {
337
+ kill(pid, 0);
338
+ return "alive";
339
+ } catch (error) {
340
+ const code = typeof error === "object" && error !== null && "code" in error
341
+ ? (error as NodeJS.ErrnoException).code
342
+ : undefined;
343
+ if (code === "ESRCH") return "dead";
344
+ if (code === "EPERM") return "unknown";
345
+ return "unknown";
346
+ }
347
+ }
348
+
349
+ export function reconcileAsyncRun(asyncDir: string, options: ReconcileAsyncRunOptions = {}): ReconcileAsyncRunResult {
350
+ const now = options.now?.() ?? Date.now();
351
+ const status = readStatusFile(asyncDir);
352
+ const startedStatus = !status && options.startedRun ? buildStartedStatus(asyncDir, options.startedRun, now) : undefined;
353
+ const effectiveStatus = status ?? startedStatus;
354
+ if (!effectiveStatus) return { status: null, repaired: false };
355
+ const statusPath = path.join(asyncDir, "status.json");
356
+ for (const [index, step] of (effectiveStatus.steps ?? []).entries()) {
357
+ const stepRecord = step as Record<string, unknown>;
358
+ if (stepRecord.model !== undefined && typeof stepRecord.model !== "string") throw new Error(`Invalid async status file '${statusPath}': steps[${index}].model must be a string.`);
359
+ if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string") throw new Error(`Invalid async status file '${statusPath}': steps[${index}].thinking must be a string.`);
360
+ }
361
+
362
+ const runId = effectiveStatus.runId || path.basename(asyncDir);
363
+ const resultPath = path.join(options.resultsDir ?? DIRS.results, `${runId}.json`);
364
+ if (fs.existsSync(resultPath)) {
365
+ const terminalStatus = effectiveStatus.state === "running" || effectiveStatus.state === "queued"
366
+ ? terminalStatusFromResult(effectiveStatus, resultPath, now)
367
+ : undefined;
368
+ if (terminalStatus) {
369
+ writeAtomicJson(path.join(asyncDir, "status.json"), terminalStatus);
370
+ return { status: terminalStatus, repaired: true, resultPath, message: "Existing async result file was used to repair stale running status." };
371
+ }
372
+ return { status: effectiveStatus, repaired: false, resultPath };
373
+ }
374
+
375
+ if (effectiveStatus.state !== "running" || typeof effectiveStatus.pid !== "number") {
376
+ return { status: status ?? null, repaired: false, resultPath };
377
+ }
378
+
379
+ if (!status) {
380
+ const startedAt = options.startedRun?.startedAt ?? effectiveStatus.startedAt;
381
+ if (now - startedAt < (options.missingStatusGraceMs ?? 1000)) {
382
+ return { status: null, repaired: false, resultPath };
383
+ }
384
+ }
385
+
386
+ const liveness = checkPidLiveness(effectiveStatus.pid, options.kill);
387
+ if (liveness !== "dead") {
388
+ const staleAfterMs = options.staleAlivePidMs ?? 24 * 60 * 60 * 1000;
389
+ const lastUpdate = effectiveStatus.lastUpdate ?? effectiveStatus.startedAt;
390
+ if (now - lastUpdate <= staleAfterMs) return { status: status ?? null, repaired: false, resultPath };
391
+ const message = `Async runner process ${effectiveStatus.pid} still has a live PID, but status has not updated for ${now - lastUpdate}ms. Marked run failed by stale-run reconciliation because PID ownership cannot be verified.`;
392
+ return writeFailedRepair(asyncDir, effectiveStatus, resultPath, now, message);
393
+ }
394
+
395
+ return writeFailedRepair(asyncDir, effectiveStatus, resultPath, now);
396
+ }
@@ -0,0 +1,239 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
4
+ import type {
5
+ AsyncStatus,
6
+ ResolvedToolBudget,
7
+ ResolvedTurnBudget,
8
+ SteerActionResult,
9
+ SteeringRecoveryDescriptor,
10
+ SteeringRequestStatus,
11
+ SteeringStatus,
12
+ SteeringTargetState,
13
+ SteeringTargetStatus,
14
+ } from "../../shared/types.ts";
15
+ import { readStatus } from "../../shared/utils.ts";
16
+
17
+ export const MAX_STEERING_REQUESTS = 20;
18
+ export const STEERING_MESSAGE_PREVIEW_LIMIT = 160;
19
+
20
+ export function createSteeringStatus(): SteeringStatus {
21
+ return { requested: 0, scheduled: 0, pending: 0, delivered: 0, failed: 0, recovered: 0, recent: [] };
22
+ }
23
+
24
+ export function steeringStatus(status: Pick<AsyncStatus, "steering">): SteeringStatus {
25
+ return status.steering ?? createSteeringStatus();
26
+ }
27
+
28
+ export function recordSteeringRequest(
29
+ status: SteeringStatus,
30
+ input: { id: string; requestedAt: number; source?: string; message: string; targets: Array<{ index: number; state: SteeringTargetState; reason?: string }> },
31
+ ): SteeringRequestStatus {
32
+ const existing = status.recent.find((request) => request.id === input.id);
33
+ if (existing) return existing;
34
+ const request: SteeringRequestStatus = {
35
+ id: input.id,
36
+ requestedAt: input.requestedAt,
37
+ ...(input.source ? { source: input.source } : {}),
38
+ messagePreview: input.message.slice(0, STEERING_MESSAGE_PREVIEW_LIMIT),
39
+ targets: input.targets.map((target) => ({ index: target.index, state: target.state, ...(target.reason ? { reason: target.reason } : {}) })),
40
+ };
41
+ status.requested++;
42
+ status.lastRequestedAt = input.requestedAt;
43
+ status.recent = [...status.recent, request].slice(-MAX_STEERING_REQUESTS);
44
+ for (const target of request.targets) incrementStateCount(status, target.state);
45
+ return request;
46
+ }
47
+
48
+ function incrementStateCount(status: SteeringStatus, state: SteeringTargetState): void {
49
+ if (state === "scheduled") status.scheduled++;
50
+ else if (state === "routed" || state === "queued") status.pending++;
51
+ else if (state === "delivered" || state === "late") status.delivered++;
52
+ else if (state === "failed") status.failed++;
53
+ else if (state === "recovered") status.recovered++;
54
+ }
55
+
56
+ export function updateSteeringTarget(
57
+ status: SteeringStatus,
58
+ requestId: string,
59
+ index: number,
60
+ state: SteeringTargetState,
61
+ now: number,
62
+ fields: Pick<SteeringTargetStatus, "reason" | "replacementRunId"> = {},
63
+ ): SteeringTargetStatus | undefined {
64
+ const request = status.recent.find((candidate) => candidate.id === requestId);
65
+ const target = request?.targets.find((candidate) => candidate.index === index);
66
+ if (!target) return undefined;
67
+ if (state === "late" && target.state === "recovered") {
68
+ if (target.lateDeliveredAt === undefined) {
69
+ target.lateDeliveredAt = now;
70
+ status.delivered++;
71
+ status.lastDeliveredAt = now;
72
+ }
73
+ if (fields.reason) target.reason = fields.reason;
74
+ return target;
75
+ }
76
+ if (target.state === state) {
77
+ if (state === "routed" && target.routedAt === undefined) target.routedAt = now;
78
+ if (state === "delivered" && target.deliveredAt === undefined) target.deliveredAt = now;
79
+ if (state === "late" && target.lateDeliveredAt === undefined) target.lateDeliveredAt = now;
80
+ if (fields.reason) target.reason = fields.reason;
81
+ if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
82
+ return target;
83
+ }
84
+ if ((target.state === "routed" || target.state === "queued") && state !== "routed" && state !== "queued") status.pending = Math.max(0, status.pending - 1);
85
+ target.state = state;
86
+ if (state === "routed") target.routedAt = now;
87
+ if (state === "delivered") {
88
+ target.deliveredAt = now;
89
+ status.lastDeliveredAt = now;
90
+ }
91
+ if (state === "late") {
92
+ target.lateDeliveredAt = now;
93
+ status.lastDeliveredAt = now;
94
+ }
95
+ if (state === "failed") target.failedAt = now;
96
+ if (state === "recovered") target.recoveredAt = now;
97
+ if (fields.reason) target.reason = fields.reason;
98
+ if (fields.replacementRunId) target.replacementRunId = fields.replacementRunId;
99
+ incrementStateCount(status, state);
100
+ return target;
101
+ }
102
+
103
+ export function findSteeringRequest(status: SteeringStatus, requestId: string): SteeringRequestStatus | undefined {
104
+ return status.recent.find((request) => request.id === requestId);
105
+ }
106
+
107
+ export function actionResultFromSteeringStatus(status: SteeringStatus, sourceRunId: string, requestId: string, replacementRunId?: string): SteerActionResult | undefined {
108
+ const request = findSteeringRequest(status, requestId);
109
+ if (!request) return undefined;
110
+ const targets = request.targets.map((target) => ({
111
+ index: target.index,
112
+ state: target.state,
113
+ ...(target.deliveredAt !== undefined ? { deliveredAt: target.deliveredAt } : {}),
114
+ ...(target.lateDeliveredAt !== undefined ? { lateDeliveredAt: target.lateDeliveredAt } : {}),
115
+ ...(target.reason ? { reason: target.reason } : {}),
116
+ ...(target.replacementRunId ? { replacementRunId: target.replacementRunId } : {}),
117
+ }));
118
+ const states = targets.map((target) => target.state);
119
+ let state: SteerActionResult["state"] = "pending";
120
+ if (states.length > 0 && states.every((candidate) => candidate === "delivered")) state = "delivered";
121
+ else if (states.length > 0 && states.every((candidate) => candidate === "scheduled")) state = "scheduled";
122
+ else if (states.length > 0 && states.every((candidate) => candidate === "recovered")) state = "recovered";
123
+ else if (states.length > 0 && states.every((candidate) => candidate === "failed" || candidate === "late")) state = "failed";
124
+ else if (states.some((candidate) => candidate === "failed" || candidate === "late") && states.some((candidate) => candidate !== "failed" && candidate !== "late")) state = "partial";
125
+ const effectiveReplacementRunId = replacementRunId ?? request.targets.find((target) => target.replacementRunId)?.replacementRunId;
126
+ const deliveryStatus = states.length > 0 && states.every((candidate) => candidate === "delivered" || candidate === "recovered") ? "delivered" as const : "queued" as const;
127
+ return { requestId, state, deliveryStatus, sourceRunId, ...(effectiveReplacementRunId ? { replacementRunId: effectiveReplacementRunId } : {}), targets };
128
+ }
129
+
130
+ export function steeringActionIsTerminal(result: SteerActionResult | undefined): boolean {
131
+ return (result?.targets.length ?? 0) > 0 && result?.targets.every((target) => target.state === "queued" || target.state === "delivered") === true
132
+ || result?.state === "delivered" || result?.state === "scheduled" || result?.state === "partial" || result?.state === "recovered" || result?.state === "failed";
133
+ }
134
+
135
+ export function terminalSteeringNoticeState(status: SteeringStatus, requestId: string): "failed" | "partial" | undefined {
136
+ const request = status.recent.find((candidate) => candidate.id === requestId);
137
+ if (!request || request.targets.some((target) => target.state === "routed" || target.state === "queued" || target.state === "scheduled")) return undefined;
138
+ const hasSuccess = request.targets.some((target) => target.state === "delivered" || target.state === "recovered");
139
+ const hasFailure = request.targets.some((target) => target.state === "failed" || target.state === "late");
140
+ if (hasSuccess && hasFailure) return "partial";
141
+ return hasFailure ? "failed" : undefined;
142
+ }
143
+
144
+ export function claimSteeringRecovery(
145
+ asyncDir: string,
146
+ input: { requestId: string; sourceRunId: string; committedAt: number },
147
+ ): { claimPath: string; markerPath: string } {
148
+ const recoveryDir = path.join(asyncDir, "control", "steer-recovery");
149
+ fs.mkdirSync(recoveryDir, { recursive: true, mode: 0o700 });
150
+ const claimPath = path.join(recoveryDir, "claim.json");
151
+ let fd: number;
152
+ try {
153
+ fd = fs.openSync(claimPath, "wx", 0o600);
154
+ } catch (error) {
155
+ if ((error as NodeJS.ErrnoException).code === "EEXIST") {
156
+ throw new Error("Another steering recovery is already committed for this source run.");
157
+ }
158
+ throw error;
159
+ }
160
+ let writeError: unknown;
161
+ try {
162
+ fs.writeFileSync(fd, JSON.stringify({ version: 1, ...input }, null, 2), "utf-8");
163
+ fs.fsyncSync(fd);
164
+ } catch (error) {
165
+ writeError = error;
166
+ } finally {
167
+ fs.closeSync(fd);
168
+ }
169
+ if (writeError !== undefined) {
170
+ fs.rmSync(claimPath, { force: true });
171
+ throw writeError;
172
+ }
173
+ const markerPath = path.join(recoveryDir, `${Buffer.from(input.requestId).toString("base64url")}.json`);
174
+ try {
175
+ writePrivateAtomicJson(markerPath, { version: 1, ...input });
176
+ } catch (error) {
177
+ fs.rmSync(claimPath, { force: true });
178
+ throw error;
179
+ }
180
+ return { claimPath, markerPath };
181
+ }
182
+
183
+ export function readSteeringStatus(asyncDir: string): SteeringStatus | undefined {
184
+ return readStatus(asyncDir)?.steering;
185
+ }
186
+
187
+ export function remainingSteeringRecoveryLimits(
188
+ descriptor: Pick<SteeringRecoveryDescriptor, "absoluteDeadlineAt" | "initialTurnBudget" | "initialToolBudget">,
189
+ status: Pick<AsyncStatus, "turnBudget" | "turnCount" | "toolBudget" | "toolCount">,
190
+ now = Date.now(),
191
+ ): { timeoutMs?: number; absoluteDeadlineAt?: number; turnBudget?: ResolvedTurnBudget; toolBudget?: ResolvedToolBudget } {
192
+ const limits: { timeoutMs?: number; absoluteDeadlineAt?: number; turnBudget?: ResolvedTurnBudget; toolBudget?: ResolvedToolBudget } = {};
193
+ if (descriptor.absoluteDeadlineAt !== undefined) {
194
+ const timeoutMs = descriptor.absoluteDeadlineAt - now;
195
+ if (timeoutMs <= 0) throw new Error("Source run has no remaining deadline budget; it remains paused.");
196
+ limits.timeoutMs = timeoutMs;
197
+ limits.absoluteDeadlineAt = descriptor.absoluteDeadlineAt;
198
+ }
199
+ if (descriptor.initialTurnBudget) {
200
+ const consumed = status.turnBudget?.turnCount ?? status.turnCount ?? 0;
201
+ const totalRemaining = descriptor.initialTurnBudget.maxTurns + descriptor.initialTurnBudget.graceTurns - consumed;
202
+ if (totalRemaining <= 0) throw new Error("Source run has no remaining turn budget; it remains paused.");
203
+ const softRemaining = Math.max(0, descriptor.initialTurnBudget.maxTurns - consumed);
204
+ limits.turnBudget = softRemaining > 0
205
+ ? { maxTurns: softRemaining, graceTurns: totalRemaining - softRemaining }
206
+ : { maxTurns: 1, graceTurns: totalRemaining - 1 };
207
+ }
208
+ if (descriptor.initialToolBudget) {
209
+ const consumed = status.toolBudget?.toolCount ?? status.toolCount ?? 0;
210
+ const hard = descriptor.initialToolBudget.hard - consumed;
211
+ if (hard <= 0) throw new Error("Source run has no remaining tool budget; it remains paused.");
212
+ const soft = descriptor.initialToolBudget.soft === undefined ? undefined : descriptor.initialToolBudget.soft - consumed;
213
+ limits.toolBudget = {
214
+ hard,
215
+ ...(soft !== undefined && soft > 0 && soft < hard ? { soft } : {}),
216
+ block: descriptor.initialToolBudget.block,
217
+ };
218
+ }
219
+ return limits;
220
+ }
221
+
222
+ export async function waitForSteeringAction(input: {
223
+ asyncDir: string;
224
+ sourceRunId: string;
225
+ requestId: string;
226
+ timeoutMs: number;
227
+ signal?: AbortSignal;
228
+ }): Promise<SteerActionResult | undefined> {
229
+ const deadline = Date.now() + input.timeoutMs;
230
+ while (Date.now() <= deadline) {
231
+ if (input.signal?.aborted) return undefined;
232
+ const status = readSteeringStatus(input.asyncDir);
233
+ const result = status ? actionResultFromSteeringStatus(status, input.sourceRunId, input.requestId) : undefined;
234
+ if (steeringActionIsTerminal(result)) return result;
235
+ await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
236
+ }
237
+ const status = readSteeringStatus(input.asyncDir);
238
+ return status ? actionResultFromSteeringStatus(status, input.sourceRunId, input.requestId) : undefined;
239
+ }