@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,328 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import * as fs from "node:fs";
3
+ import * as path from "node:path";
4
+ import { writeAtomicJson } from "../../shared/atomic-json.ts";
5
+ import { appendJsonl } from "../../shared/artifacts.ts";
6
+ import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
7
+ import { readStatus } from "../../shared/utils.ts";
8
+ import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep, RunnerCheckpointStep } from "../shared/parallel-utils.ts";
9
+ import { isCheckpointRunnerStep, isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
10
+
11
+ const APPEND_REQUESTS_DIR = "append-requests";
12
+
13
+ export interface ChainAppendRequest {
14
+ id: string;
15
+ createdAt: number;
16
+ steps: RunnerStep[];
17
+ }
18
+
19
+ export interface ChainAppendResult {
20
+ request: ChainAppendRequest;
21
+ pendingCount: number;
22
+ }
23
+
24
+ type StatusStep = NonNullable<AsyncStatus["steps"]>[number];
25
+
26
+ function appendDir(asyncDir: string): string {
27
+ return path.join(asyncDir, APPEND_REQUESTS_DIR);
28
+ }
29
+
30
+ function appendRequestPath(asyncDir: string, request: ChainAppendRequest): string {
31
+ return path.join(appendDir(asyncDir), `${request.createdAt}-${request.id}.json`);
32
+ }
33
+
34
+ function listAppendRequestFiles(asyncDir: string): string[] {
35
+ const dir = appendDir(asyncDir);
36
+ try {
37
+ return fs.readdirSync(dir)
38
+ .filter((entry) => entry.endsWith(".json"))
39
+ .map((entry) => path.join(dir, entry))
40
+ .sort();
41
+ } catch (error) {
42
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
43
+ throw error;
44
+ }
45
+ }
46
+
47
+ export function countPendingChainAppendRequests(asyncDir: string): number {
48
+ return listAppendRequestFiles(asyncDir).length;
49
+ }
50
+
51
+ export function runnerStepOutputNames(steps: RunnerStep[]): string[] {
52
+ const names: string[] = [];
53
+ for (const step of steps) {
54
+ if (isCheckpointRunnerStep(step)) {
55
+ continue;
56
+ } else if (isParallelGroup(step)) {
57
+ names.push(...step.parallel.map((task) => task.outputName).filter((name): name is string => Boolean(name)));
58
+ } else if (isDynamicRunnerGroup(step)) {
59
+ if (step.collect.as) names.push(step.collect.as);
60
+ } else if (step.outputName) {
61
+ names.push(step.outputName);
62
+ }
63
+ }
64
+ return names;
65
+ }
66
+
67
+ export function enqueueChainAppendRequest(input: {
68
+ asyncDir: string;
69
+ runId: string;
70
+ steps: RunnerStep[];
71
+ now?: number;
72
+ }): ChainAppendResult {
73
+ const status = readStatus(input.asyncDir);
74
+ if (!status) throw new Error(`No async run status found for '${input.runId}'.`);
75
+ if (status.runId !== input.runId) throw new Error(`Async run id mismatch: expected '${input.runId}', found '${status.runId}'.`);
76
+ if (status.mode !== "chain") throw new Error(`Run '${input.runId}' is ${status.mode}; only active chain runs accept appended steps.`);
77
+ if (status.state !== "running") throw new Error(`Run '${input.runId}' is ${status.state}; only running chain runs accept appended steps.`);
78
+ const stillInProgress = (status.steps ?? []).some((step) => step.status === "running" || step.status === "pending") || (status.pendingAppends ?? 0) > 0;
79
+ if (!stillInProgress) throw new Error(`Run '${input.runId}' has no running or pending chain steps left; append-step must target an in-progress chain.`);
80
+ if (input.steps.length === 0) throw new Error("append-step requires one chain step.");
81
+
82
+ const request: ChainAppendRequest = {
83
+ id: randomUUID(),
84
+ createdAt: input.now ?? Date.now(),
85
+ steps: input.steps,
86
+ };
87
+ fs.mkdirSync(appendDir(input.asyncDir), { recursive: true });
88
+ writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
89
+ const pendingCount = countPendingChainAppendRequests(input.asyncDir);
90
+ const statusPath = path.join(input.asyncDir, "status.json");
91
+ const updatedStatus = { ...status, pendingAppends: pendingCount, lastUpdate: request.createdAt };
92
+ writeAtomicJson(statusPath, updatedStatus);
93
+ appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
94
+ type: "subagent.chain.append.requested",
95
+ ts: request.createdAt,
96
+ runId: input.runId,
97
+ requestId: request.id,
98
+ stepCount: input.steps.length,
99
+ pendingAppends: pendingCount,
100
+ }));
101
+ return { request, pendingCount };
102
+ }
103
+
104
+ function readAppendRequest(filePath: string): ChainAppendRequest | undefined {
105
+ const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChainAppendRequest>;
106
+ if (!raw.id || typeof raw.id !== "string") return undefined;
107
+ const createdAt = raw.createdAt;
108
+ if (typeof createdAt !== "number" || !Number.isFinite(createdAt)) return undefined;
109
+ if (!Array.isArray(raw.steps) || raw.steps.length === 0) return undefined;
110
+ return { id: raw.id, createdAt, steps: raw.steps as RunnerStep[] };
111
+ }
112
+
113
+ export function readPendingChainAppendRequests(asyncDir: string): ChainAppendRequest[] {
114
+ return listAppendRequestFiles(asyncDir)
115
+ .map((filePath) => readAppendRequest(filePath))
116
+ .filter((request): request is ChainAppendRequest => Boolean(request))
117
+ .sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
118
+ }
119
+
120
+ export function consumeChainAppendRequests(asyncDir: string): ChainAppendRequest[] {
121
+ const requests: ChainAppendRequest[] = [];
122
+ for (const filePath of listAppendRequestFiles(asyncDir)) {
123
+ const request = readAppendRequest(filePath);
124
+ try {
125
+ fs.unlinkSync(filePath);
126
+ } catch {
127
+ // The runner should not execute a consumed request twice.
128
+ }
129
+ if (request) requests.push(request);
130
+ }
131
+ return requests.sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id));
132
+ }
133
+
134
+ const MAX_STATUS_STEP_DESCRIPTION_CHARS = 160;
135
+
136
+ /** Bounded one-line per-step task description persisted into status.json for fleet display. */
137
+ export function statusStepDescription(task: string | undefined): string | undefined {
138
+ const description = task?.replace(/\s+/g, " ").trim();
139
+ if (!description) return undefined;
140
+ return description.length > MAX_STATUS_STEP_DESCRIPTION_CHARS
141
+ ? `${description.slice(0, MAX_STATUS_STEP_DESCRIPTION_CHARS - 1)}…`
142
+ : description;
143
+ }
144
+
145
+ function statusStepForTask(task: RunnerSubagentStep): StatusStep {
146
+ const description = statusStepDescription(task.task);
147
+ return {
148
+ agent: task.agent,
149
+ ...(description ? { description } : {}),
150
+ ...(task.context ? { context: task.context } : {}),
151
+ phase: task.phase,
152
+ label: task.label,
153
+ outputName: task.outputName,
154
+ structured: task.structured,
155
+ status: "pending",
156
+ ...(task.sessionFile ? { sessionFile: task.sessionFile } : {}),
157
+ skills: task.skills,
158
+ model: task.model,
159
+ thinking: task.thinking,
160
+ attemptedModels: task.modelCandidates && task.modelCandidates.length > 0 ? task.modelCandidates : task.model ? [task.model] : undefined,
161
+ recentTools: [],
162
+ recentOutput: [],
163
+ };
164
+ }
165
+
166
+ function statusStepForCheckpoint(step: RunnerCheckpointStep, stepIndex: number): StatusStep {
167
+ return {
168
+ agent: `checkpoint:${step.checkpoint}`,
169
+ phase: step.phase,
170
+ label: step.label ?? step.checkpoint,
171
+ status: "pending",
172
+ checkpoint: { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: "pending", stepIndex },
173
+ recentTools: [],
174
+ recentOutput: [],
175
+ };
176
+ }
177
+
178
+ function statusStepsForRunnerStep(step: RunnerStep, stepIndex: number): StatusStep[] {
179
+ if (isCheckpointRunnerStep(step)) return [statusStepForCheckpoint(step, stepIndex)];
180
+ if (isParallelGroup(step)) return step.parallel.map(statusStepForTask);
181
+ if (isDynamicRunnerGroup(step)) {
182
+ return [{
183
+ agent: `expand:${step.parallel.agent}`,
184
+ ...(step.parallel.context ? { context: step.parallel.context } : {}),
185
+ phase: step.phase ?? step.parallel.phase,
186
+ label: step.label ?? step.parallel.label ?? `Dynamic fanout (${step.collect.as})`,
187
+ outputName: step.collect.as,
188
+ structured: Boolean(step.collect.outputSchema),
189
+ status: "pending",
190
+ recentTools: [],
191
+ recentOutput: [],
192
+ }];
193
+ }
194
+ return [statusStepForTask(step)];
195
+ }
196
+
197
+ function pushPhase(graph: WorkflowGraphSnapshot, phase: string | undefined, nodeId: string): void {
198
+ if (!phase) return;
199
+ let group = graph.phases.find((candidate) => candidate.title === phase);
200
+ if (!group) {
201
+ group = { title: phase, nodeIds: [] };
202
+ graph.phases.push(group);
203
+ }
204
+ group.nodeIds.push(nodeId);
205
+ }
206
+
207
+ function graphNodeForSequential(step: RunnerSubagentStep, stepIndex: number, flatIndex: number): WorkflowGraphNode {
208
+ return {
209
+ id: `step-${stepIndex}`,
210
+ kind: "step",
211
+ agent: step.agent,
212
+ phase: step.phase,
213
+ label: step.label?.trim() || step.agent || `Step ${stepIndex + 1}`,
214
+ status: "pending",
215
+ flatIndex,
216
+ stepIndex,
217
+ outputName: step.outputName,
218
+ structured: step.structured,
219
+ };
220
+ }
221
+
222
+ function graphNodeForParallel(step: ParallelStepGroup, stepIndex: number, flatIndex: number, graph: WorkflowGraphSnapshot): WorkflowGraphNode {
223
+ const children = step.parallel.map((task, taskIndex) => {
224
+ const childId = `step-${stepIndex}-agent-${taskIndex}`;
225
+ pushPhase(graph, task.phase, childId);
226
+ return {
227
+ id: childId,
228
+ kind: "agent" as const,
229
+ agent: task.agent,
230
+ phase: task.phase,
231
+ label: task.label?.trim() || task.agent || `Agent ${taskIndex + 1}`,
232
+ status: "pending" as const,
233
+ flatIndex: flatIndex + taskIndex,
234
+ stepIndex,
235
+ outputName: task.outputName,
236
+ structured: task.structured,
237
+ };
238
+ });
239
+ return {
240
+ id: `step-${stepIndex}`,
241
+ kind: "parallel-group",
242
+ label: step.parallel.length === 1 ? "Parallel task" : `Parallel group (${step.parallel.length})`,
243
+ status: "pending",
244
+ stepIndex,
245
+ children,
246
+ };
247
+ }
248
+
249
+ function graphNodeForDynamic(step: DynamicRunnerGroup, stepIndex: number): WorkflowGraphNode {
250
+ return {
251
+ id: `step-${stepIndex}`,
252
+ kind: "dynamic-parallel-group",
253
+ label: step.label?.trim() || step.parallel.label?.trim() || `Dynamic fanout (${step.collect.as})`,
254
+ status: "pending",
255
+ stepIndex,
256
+ outputName: step.collect.as,
257
+ structured: Boolean(step.collect.outputSchema),
258
+ dynamic: {
259
+ sourceOutput: step.expand.from.output,
260
+ sourcePath: step.expand.from.path,
261
+ itemName: step.expand.item ?? "item",
262
+ maxItems: step.expand.maxItems,
263
+ collectAs: step.collect.as,
264
+ },
265
+ children: [],
266
+ };
267
+ }
268
+
269
+ function appendWorkflowNode(graph: WorkflowGraphSnapshot | undefined, step: RunnerStep, stepIndex: number, flatIndex: number): void {
270
+ if (!graph) return;
271
+ if (isCheckpointRunnerStep(step)) {
272
+ const node: WorkflowGraphNode = {
273
+ id: `step-${stepIndex}`,
274
+ kind: "checkpoint",
275
+ phase: step.phase,
276
+ label: step.label?.trim() || step.checkpoint,
277
+ status: "pending",
278
+ flatIndex,
279
+ stepIndex,
280
+ checkpoint: { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: "pending", stepIndex },
281
+ };
282
+ graph.nodes.push(node);
283
+ pushPhase(graph, step.phase, node.id);
284
+ return;
285
+ }
286
+ if (isParallelGroup(step)) {
287
+ graph.nodes.push(graphNodeForParallel(step, stepIndex, flatIndex, graph));
288
+ return;
289
+ }
290
+ if (isDynamicRunnerGroup(step)) {
291
+ graph.nodes.push(graphNodeForDynamic(step, stepIndex));
292
+ return;
293
+ }
294
+ const node = graphNodeForSequential(step, stepIndex, flatIndex);
295
+ graph.nodes.push(node);
296
+ pushPhase(graph, step.phase, node.id);
297
+ }
298
+
299
+ export function appendRunnerStepsToStatus(input: {
300
+ status: AsyncStatus;
301
+ steps: RunnerStep[];
302
+ now?: number;
303
+ pendingAppends?: number;
304
+ }): { addedChainSteps: number; addedFlatSteps: number } {
305
+ let addedChainSteps = 0;
306
+ let addedFlatSteps = 0;
307
+ for (const step of input.steps) {
308
+ const stepIndex = input.status.chainStepCount ?? input.status.steps?.length ?? 0;
309
+ const flatIndex = input.status.steps?.length ?? 0;
310
+ const statusSteps = statusStepsForRunnerStep(step, stepIndex);
311
+ input.status.steps ??= [];
312
+ input.status.steps.push(...statusSteps);
313
+ if (isParallelGroup(step)) {
314
+ input.status.parallelGroups ??= [];
315
+ input.status.parallelGroups.push({ start: flatIndex, count: step.parallel.length, stepIndex });
316
+ } else if (isDynamicRunnerGroup(step)) {
317
+ input.status.parallelGroups ??= [];
318
+ input.status.parallelGroups.push({ start: flatIndex, count: 1, stepIndex });
319
+ }
320
+ appendWorkflowNode(input.status.workflowGraph, step, stepIndex, flatIndex);
321
+ input.status.chainStepCount = stepIndex + 1;
322
+ addedChainSteps++;
323
+ addedFlatSteps += statusSteps.length;
324
+ }
325
+ input.status.pendingAppends = input.pendingAppends ?? 0;
326
+ input.status.lastUpdate = input.now ?? Date.now();
327
+ return { addedChainSteps, addedFlatSteps };
328
+ }
@@ -0,0 +1,199 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import type { AcceptanceLedger, AsyncStatus, CostSummary, ModelAttempt } from "../../shared/types.ts";
4
+ import { readStatus } from "../../shared/utils.ts";
5
+
6
+ export interface ImportedAsyncRoot {
7
+ runId: string;
8
+ asyncDir: string;
9
+ resultPath: string;
10
+ index: number;
11
+ }
12
+
13
+ export interface ImportedAsyncRootResult {
14
+ agent: string;
15
+ output: string;
16
+ success: boolean;
17
+ exitCode: number;
18
+ error?: string;
19
+ sessionFile?: string;
20
+ intercomTarget?: string;
21
+ model?: string;
22
+ attemptedModels?: string[];
23
+ modelAttempts?: ModelAttempt[];
24
+ totalCost?: CostSummary;
25
+ structuredOutput?: unknown;
26
+ structuredOutputPath?: string;
27
+ structuredOutputSchemaPath?: string;
28
+ acceptance?: AcceptanceLedger;
29
+ timedOut?: boolean;
30
+ stopped?: boolean;
31
+ }
32
+
33
+ interface AsyncResultFile {
34
+ state?: string;
35
+ success?: boolean;
36
+ summary?: string;
37
+ error?: string;
38
+ timedOut?: boolean;
39
+ stopped?: boolean;
40
+ results?: Array<{
41
+ agent?: string;
42
+ output?: string;
43
+ error?: string;
44
+ success?: boolean;
45
+ timedOut?: boolean;
46
+ stopped?: boolean;
47
+ sessionFile?: string;
48
+ intercomTarget?: string;
49
+ model?: string;
50
+ attemptedModels?: string[];
51
+ modelAttempts?: ModelAttempt[];
52
+ totalCost?: CostSummary;
53
+ structuredOutput?: unknown;
54
+ structuredOutputPath?: string;
55
+ structuredOutputSchemaPath?: string;
56
+ acceptance?: AcceptanceLedger;
57
+ }>;
58
+ }
59
+
60
+ const TERMINAL_STATES = new Set(["complete", "failed", "paused", "stopped"]);
61
+ const TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "paused", "stopped"]);
62
+
63
+ function readResultFile(resultPath: string): AsyncResultFile | undefined {
64
+ try {
65
+ return JSON.parse(fs.readFileSync(resultPath, "utf-8")) as AsyncResultFile;
66
+ } catch (error) {
67
+ if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
68
+ return undefined;
69
+ }
70
+ throw error;
71
+ }
72
+ }
73
+
74
+ function selectedStatusStep(status: AsyncStatus | null, index: number): NonNullable<AsyncStatus["steps"]>[number] | undefined {
75
+ return status?.steps?.[index];
76
+ }
77
+
78
+ function isTerminalStatus(status: AsyncStatus | null, index: number): boolean {
79
+ if (!status) return false;
80
+ const step = selectedStatusStep(status, index);
81
+ if (step && TERMINAL_STEP_STATUSES.has(step.status)) return true;
82
+ return TERMINAL_STATES.has(status.state);
83
+ }
84
+
85
+ function resultState(result: AsyncResultFile | undefined, child: NonNullable<AsyncResultFile["results"]>[number] | undefined): "complete" | "failed" | "paused" | "stopped" | undefined {
86
+ if (!result) return undefined;
87
+ if (child?.stopped === true) return "stopped";
88
+ if (child?.success === true) return "complete";
89
+ if (child?.success === false) return result.state === "stopped" ? "stopped" : result.state === "paused" ? "paused" : "failed";
90
+ if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "stopped") return result.state;
91
+ if (result.success === true) return "complete";
92
+ if (result.success === false) return "failed";
93
+ return undefined;
94
+ }
95
+
96
+ function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus, step: NonNullable<AsyncStatus["steps"]>[number] | undefined): ImportedAsyncRootResult {
97
+ const agent = step?.agent ?? status.steps?.[root.index]?.agent ?? "subagent";
98
+ const timedOut = step?.timedOut === true || status.timedOut === true;
99
+ const stopped = step?.stopped === true || status.stopped === true || status.state === "stopped";
100
+ const message = step?.error ?? status.error ?? (stopped ? "Subagent stopped by user." : `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`);
101
+ return {
102
+ agent,
103
+ output: message,
104
+ success: false,
105
+ exitCode: 1,
106
+ error: message,
107
+ ...(timedOut ? { timedOut: true } : {}),
108
+ ...(stopped ? { stopped: true } : {}),
109
+ ...(step?.sessionFile ?? status.sessionFile ? { sessionFile: step?.sessionFile ?? status.sessionFile } : {}),
110
+ ...(step?.model ? { model: step.model } : {}),
111
+ ...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
112
+ ...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
113
+ ...(step?.totalCost ? { totalCost: step.totalCost } : {}),
114
+ ...(step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
115
+ ...(step?.structuredOutputPath ? { structuredOutputPath: step.structuredOutputPath } : {}),
116
+ ...(step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: step.structuredOutputSchemaPath } : {}),
117
+ ...(step?.acceptance ? { acceptance: step.acceptance } : {}),
118
+ };
119
+ }
120
+
121
+ function outputFromTimeout(root: ImportedAsyncRoot, status: AsyncStatus | null, message: string): ImportedAsyncRootResult {
122
+ const step = selectedStatusStep(status, root.index);
123
+ return {
124
+ agent: step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent",
125
+ output: message,
126
+ success: false,
127
+ exitCode: 1,
128
+ error: message,
129
+ timedOut: true,
130
+ ...(step?.sessionFile ?? status?.sessionFile ? { sessionFile: step?.sessionFile ?? status?.sessionFile } : {}),
131
+ ...(step?.model ? { model: step.model } : {}),
132
+ ...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
133
+ ...(step?.modelAttempts ? { modelAttempts: step.modelAttempts } : {}),
134
+ ...(step?.totalCost ? { totalCost: step.totalCost } : {}),
135
+ };
136
+ }
137
+
138
+ function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null, result: AsyncResultFile): ImportedAsyncRootResult {
139
+ const child = result.results?.[root.index];
140
+ const step = selectedStatusStep(status, root.index);
141
+ const state = resultState(result, child);
142
+ const agent = child?.agent ?? step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent";
143
+ const output = child?.output ?? result.summary ?? "";
144
+ const timedOut = child?.timedOut === true || step?.timedOut === true || result.timedOut === true || status?.timedOut === true;
145
+ const stopped = child?.stopped === true || step?.stopped === true || result.stopped === true || status?.stopped === true || state === "stopped";
146
+ const success = state === "complete" && !timedOut && !stopped;
147
+ const error = child?.error ?? (success ? undefined : stopped ? "Subagent stopped by user." : result.error ?? result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
148
+ return {
149
+ agent,
150
+ output: success ? output : (output || error || ""),
151
+ success,
152
+ exitCode: success ? 0 : 1,
153
+ ...(error ? { error } : {}),
154
+ ...(timedOut ? { timedOut: true } : {}),
155
+ ...(stopped ? { stopped: true } : {}),
156
+ ...(child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile ? { sessionFile: child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile } : {}),
157
+ ...(child?.intercomTarget ? { intercomTarget: child.intercomTarget } : {}),
158
+ ...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),
159
+ ...(child?.attemptedModels ?? step?.attemptedModels ? { attemptedModels: child?.attemptedModels ?? step?.attemptedModels } : {}),
160
+ ...(child?.modelAttempts ?? step?.modelAttempts ? { modelAttempts: child?.modelAttempts ?? step?.modelAttempts } : {}),
161
+ ...(child?.totalCost ?? step?.totalCost ? { totalCost: child?.totalCost ?? step?.totalCost } : {}),
162
+ ...(child?.structuredOutput !== undefined ? { structuredOutput: child.structuredOutput } : step?.structuredOutput !== undefined ? { structuredOutput: step.structuredOutput } : {}),
163
+ ...(child?.structuredOutputPath ?? step?.structuredOutputPath ? { structuredOutputPath: child?.structuredOutputPath ?? step?.structuredOutputPath } : {}),
164
+ ...(child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath ? { structuredOutputSchemaPath: child?.structuredOutputSchemaPath ?? step?.structuredOutputSchemaPath } : {}),
165
+ ...(child?.acceptance ?? step?.acceptance ? { acceptance: child?.acceptance ?? step?.acceptance } : {}),
166
+ };
167
+ }
168
+
169
+ export async function waitForImportedAsyncRoot(
170
+ root: ImportedAsyncRoot,
171
+ options: { pollIntervalMs?: number; terminalResultGraceMs?: number; now?: () => number; shouldAbort?: () => boolean; timeoutMessage?: string } = {},
172
+ ): Promise<ImportedAsyncRootResult> {
173
+ const pollIntervalMs = options.pollIntervalMs ?? 500;
174
+ const terminalResultGraceMs = options.terminalResultGraceMs ?? 1_000;
175
+ const now = options.now ?? Date.now;
176
+ let terminalSince: number | undefined;
177
+ for (;;) {
178
+ const status = readStatus(root.asyncDir);
179
+ if (options.shouldAbort?.()) return outputFromTimeout(root, status, options.timeoutMessage ?? "Subagent timed out.");
180
+ const result = readResultFile(root.resultPath);
181
+ if (result) return buildImportedResult(root, status, result);
182
+ if (isTerminalStatus(status, root.index)) {
183
+ terminalSince ??= now();
184
+ if (now() - terminalSince >= terminalResultGraceMs) {
185
+ return outputFromTerminalStatus(root, status!, selectedStatusStep(status, root.index));
186
+ }
187
+ } else {
188
+ terminalSince = undefined;
189
+ }
190
+ if (!status && !fs.existsSync(root.asyncDir)) {
191
+ throw new Error(`Attached async root '${root.runId}' directory does not exist: ${root.asyncDir}`);
192
+ }
193
+ await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
194
+ }
195
+ }
196
+
197
+ export function resolveAsyncRootResultPath(resultsDir: string, runId: string): string {
198
+ return path.join(resultsDir, `${runId}.json`);
199
+ }
@@ -0,0 +1,168 @@
1
+ /**
2
+ * Smart completion batching with straggler handling.
3
+ *
4
+ * Holds successful async-completion notifications briefly so sibling jobs that
5
+ * finish within a short window arrive as a single grouped message. A hard
6
+ * max-wait cap (measured from the first item in a group) prevents holding
7
+ * notifications indefinitely. After a group is emitted, late-finishing
8
+ * siblings that arrive within the straggler window join a shorter "straggler"
9
+ * group with reduced debounce and max-wait timers.
10
+ *
11
+ * Failure and attention signals bypass this batcher entirely. Callers must
12
+ * flush() held items and emit those signals immediately so failures and
13
+ * needs-attention notices are never delayed.
14
+ */
15
+
16
+ import type { CompletionBatchConfig } from "../../shared/types.ts";
17
+
18
+ export type { CompletionBatchConfig };
19
+
20
+ export interface ResolvedCompletionBatchConfig {
21
+ enabled: boolean;
22
+ debounceMs: number;
23
+ maxWaitMs: number;
24
+ stragglerDebounceMs: number;
25
+ stragglerMaxWaitMs: number;
26
+ stragglerWindowMs: number;
27
+ }
28
+
29
+ export const DEFAULT_COMPLETION_BATCH_CONFIG: ResolvedCompletionBatchConfig = {
30
+ enabled: true,
31
+ debounceMs: 150,
32
+ maxWaitMs: 1000,
33
+ stragglerDebounceMs: 75,
34
+ stragglerMaxWaitMs: 400,
35
+ stragglerWindowMs: 2000,
36
+ };
37
+
38
+ function parsePositiveInt(value: unknown): number | undefined {
39
+ if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
40
+ return value;
41
+ }
42
+
43
+ export function resolveCompletionBatchConfig(
44
+ globalConfig?: CompletionBatchConfig,
45
+ override?: CompletionBatchConfig,
46
+ ): ResolvedCompletionBatchConfig {
47
+ const enabled = typeof override?.enabled === "boolean"
48
+ ? override.enabled
49
+ : typeof globalConfig?.enabled === "boolean"
50
+ ? globalConfig.enabled
51
+ : DEFAULT_COMPLETION_BATCH_CONFIG.enabled;
52
+ return {
53
+ enabled,
54
+ debounceMs: parsePositiveInt(override?.debounceMs) ?? parsePositiveInt(globalConfig?.debounceMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.debounceMs,
55
+ maxWaitMs: parsePositiveInt(override?.maxWaitMs) ?? parsePositiveInt(globalConfig?.maxWaitMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.maxWaitMs,
56
+ stragglerDebounceMs: parsePositiveInt(override?.stragglerDebounceMs) ?? parsePositiveInt(globalConfig?.stragglerDebounceMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerDebounceMs,
57
+ stragglerMaxWaitMs: parsePositiveInt(override?.stragglerMaxWaitMs) ?? parsePositiveInt(globalConfig?.stragglerMaxWaitMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerMaxWaitMs,
58
+ stragglerWindowMs: parsePositiveInt(override?.stragglerWindowMs) ?? parsePositiveInt(globalConfig?.stragglerWindowMs) ?? DEFAULT_COMPLETION_BATCH_CONFIG.stragglerWindowMs,
59
+ };
60
+ }
61
+
62
+ type TimerHandle = unknown;
63
+
64
+ interface TimerApi {
65
+ setTimeout(handler: () => void, delayMs: number): TimerHandle;
66
+ clearTimeout(handle: TimerHandle): void;
67
+ }
68
+
69
+ const defaultTimers: TimerApi = {
70
+ setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
71
+ clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
72
+ };
73
+
74
+ function unrefHandle(handle: TimerHandle): void {
75
+ if (handle && typeof handle === "object" && "unref" in handle && typeof (handle as { unref: unknown }).unref === "function") {
76
+ (handle as { unref: () => void }).unref();
77
+ }
78
+ }
79
+
80
+ export interface CompletionBatcherOptions<T> {
81
+ config: ResolvedCompletionBatchConfig;
82
+ emit: (items: T[]) => void;
83
+ timers?: TimerApi;
84
+ now?: () => number;
85
+ }
86
+
87
+ export interface CompletionBatcher<T> {
88
+ /** Add a batchable item. Emits immediately when batching is disabled. */
89
+ push(item: T): void;
90
+ /** Emit any held items immediately as a single group. */
91
+ flush(): void;
92
+ /** Clear timers and return items that were never emitted. */
93
+ dispose(): T[];
94
+ }
95
+
96
+ /**
97
+ * Create a completion batcher. The batcher is single-use per registration: it
98
+ * holds at most one open group. `flush` forces emission; `dispose` tears down
99
+ * timers for reload/shutdown without emitting.
100
+ */
101
+ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
102
+ const timers = options.timers ?? defaultTimers;
103
+ const now = options.now ?? Date.now;
104
+ const config = options.config;
105
+
106
+ if (!config.enabled) {
107
+ return {
108
+ push(item: T) {
109
+ options.emit([item]);
110
+ },
111
+ flush() {},
112
+ dispose() { return []; },
113
+ };
114
+ }
115
+
116
+ let pending: T[] = [];
117
+ let debounceTimer: TimerHandle | null = null;
118
+ let maxWaitTimer: TimerHandle | null = null;
119
+ let straggler = false;
120
+ let lastEmitAt: number | null = null;
121
+
122
+ const clearTimers = () => {
123
+ if (debounceTimer) {
124
+ timers.clearTimeout(debounceTimer);
125
+ debounceTimer = null;
126
+ }
127
+ if (maxWaitTimer) {
128
+ timers.clearTimeout(maxWaitTimer);
129
+ maxWaitTimer = null;
130
+ }
131
+ };
132
+
133
+ const emitGroup = () => {
134
+ clearTimers();
135
+ if (pending.length === 0) return;
136
+ const items = pending;
137
+ pending = [];
138
+ lastEmitAt = now();
139
+ options.emit(items);
140
+ };
141
+
142
+ return {
143
+ push(item: T) {
144
+ if (pending.length === 0) {
145
+ straggler = lastEmitAt !== null && (now() - lastEmitAt) < config.stragglerWindowMs;
146
+ }
147
+ pending.push(item);
148
+
149
+ if (debounceTimer) timers.clearTimeout(debounceTimer);
150
+ const debounceDelay = straggler ? config.stragglerDebounceMs : config.debounceMs;
151
+ debounceTimer = timers.setTimeout(emitGroup, debounceDelay);
152
+ unrefHandle(debounceTimer);
153
+
154
+ if (!maxWaitTimer) {
155
+ const maxWaitDelay = straggler ? config.stragglerMaxWaitMs : config.maxWaitMs;
156
+ maxWaitTimer = timers.setTimeout(emitGroup, maxWaitDelay);
157
+ unrefHandle(maxWaitTimer);
158
+ }
159
+ },
160
+ flush: emitGroup,
161
+ dispose() {
162
+ clearTimers();
163
+ const abandoned = pending;
164
+ pending = [];
165
+ return abandoned;
166
+ }
167
+ };
168
+ }