@xzzpig/pi-subagents 0.2.0 → 0.4.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 (103) hide show
  1. package/CHANGELOG.md +96 -0
  2. package/README.md +2 -0
  3. package/agents/oracle.md +7 -5
  4. package/agents/researcher.md +1 -1
  5. package/agents/reviewer.md +2 -2
  6. package/agents/scout.md +1 -1
  7. package/agents/worker.md +1 -1
  8. package/docs/agents.md +3 -0
  9. package/docs/configuration.md +121 -10
  10. package/docs/extension-api.md +36 -0
  11. package/docs/missions.md +5 -3
  12. package/docs/observability.md +43 -3
  13. package/docs/tool-reference.md +20 -3
  14. package/docs/workflows.md +2 -2
  15. package/package.json +4 -4
  16. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  17. package/skills/pi-subagents/references/execution-controls.md +5 -4
  18. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  19. package/skills/pi-subagents/references/prompting-and-roles.md +31 -15
  20. package/src/agents/agent-serializer.ts +2 -0
  21. package/src/agents/agents.ts +46 -15
  22. package/src/api/external-runs.ts +174 -84
  23. package/src/api/preflight.ts +13 -7
  24. package/src/extension/config.ts +59 -0
  25. package/src/extension/doctor.ts +40 -0
  26. package/src/extension/index.ts +83 -9
  27. package/src/extension/public-execution.ts +37 -4
  28. package/src/extension/rpc.ts +8 -10
  29. package/src/extension/schemas.ts +12 -10
  30. package/src/extension/tool-description.ts +13 -9
  31. package/src/inspectors/herdr/actions.ts +13 -8
  32. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  33. package/src/inspectors/herdr/project-panes.ts +2 -6
  34. package/src/inspectors/herdr/shell-command.ts +16 -0
  35. package/src/intercom/intercom-bridge.ts +9 -5
  36. package/src/intercom/native-supervisor-channel.ts +19 -42
  37. package/src/missions/goal-driver.ts +3 -1
  38. package/src/missions/lifecycle.ts +4 -7
  39. package/src/missions/store.ts +12 -7
  40. package/src/missions/workflow-state.ts +6 -2
  41. package/src/runs/background/active-async-capacity.ts +431 -0
  42. package/src/runs/background/active-run-index.ts +77 -3
  43. package/src/runs/background/async-execution.ts +190 -72
  44. package/src/runs/background/async-job-tracker.ts +5 -0
  45. package/src/runs/background/async-resume.ts +21 -7
  46. package/src/runs/background/async-status-snapshot.ts +277 -0
  47. package/src/runs/background/async-status.ts +17 -6
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/chain-root-attachment.ts +2 -2
  50. package/src/runs/background/completion-replay.ts +11 -1
  51. package/src/runs/background/fleet-view.ts +21 -6
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-files.ts +437 -0
  55. package/src/runs/background/result-watcher.ts +188 -41
  56. package/src/runs/background/resume-guidance.ts +27 -7
  57. package/src/runs/background/retained-children.ts +75 -18
  58. package/src/runs/background/run-id-resolver.ts +30 -24
  59. package/src/runs/background/run-status.ts +106 -5
  60. package/src/runs/background/scheduled-runs.ts +54 -28
  61. package/src/runs/background/stale-run-reconciler.ts +30 -16
  62. package/src/runs/background/subagent-runner.ts +352 -62
  63. package/src/runs/background/subagent-wait.ts +2 -0
  64. package/src/runs/background/wait-completions.ts +5 -2
  65. package/src/runs/foreground/async-dismiss-action.ts +2 -1
  66. package/src/runs/foreground/chain-execution.ts +53 -2
  67. package/src/runs/foreground/execution.ts +309 -34
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/prompt-audit.ts +172 -0
  70. package/src/runs/foreground/subagent-executor.ts +936 -224
  71. package/src/runs/shared/acceptance.ts +13 -4
  72. package/src/runs/shared/completion-guard.ts +107 -1
  73. package/src/runs/shared/external-cli-runner.ts +4 -0
  74. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  75. package/src/runs/shared/model-fallback.ts +16 -2
  76. package/src/runs/shared/nested-events.ts +66 -62
  77. package/src/runs/shared/orca-progress-tabs.ts +375 -0
  78. package/src/runs/shared/parallel-utils.ts +4 -0
  79. package/src/runs/shared/pi-args.ts +44 -1
  80. package/src/runs/shared/run-fanout-budget.ts +280 -0
  81. package/src/runs/shared/single-output.ts +4 -2
  82. package/src/runs/shared/subagent-control.ts +15 -0
  83. package/src/runs/shared/subagent-prompt-runtime.ts +1 -9
  84. package/src/runs/shared/subagent-startup-retry.ts +12 -0
  85. package/src/runs/shared/task-intent.ts +19 -3
  86. package/src/runs/shared/tool-timeout.ts +93 -0
  87. package/src/runs/shared/worktree.ts +17 -5
  88. package/src/shared/agent-stream-options.ts +5 -0
  89. package/src/shared/artifacts.ts +2 -6
  90. package/src/shared/display-text.ts +50 -0
  91. package/src/shared/node-executable.ts +21 -0
  92. package/src/shared/types.ts +143 -5
  93. package/src/shared/utils.ts +3 -1
  94. package/src/slash/slash-commands.ts +34 -25
  95. package/src/slash/slash-live-state.ts +3 -0
  96. package/src/tui/fleet-status.ts +164 -47
  97. package/src/tui/fleet-transcript.ts +1 -48
  98. package/src/tui/fleet.ts +352 -27
  99. package/src/tui/render.ts +122 -44
  100. package/src/watchdog/permission-arbiter.ts +2 -1
  101. package/src/watchdog/review.ts +4 -3
  102. package/src/workflows/chat-progress.ts +10 -2
  103. package/src/workflows/scripted-workflow.ts +292 -79
@@ -5,8 +5,10 @@ import type { AgentConfig } from "../../agents/agents.ts";
5
5
  import { validateAcceptanceInput } from "../shared/acceptance.ts";
6
6
  import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
7
7
  import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
8
+ import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
8
9
  import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
9
10
  import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
11
+ import { resultFilePath } from "./result-files.ts";
10
12
 
11
13
  export interface AsyncResumeParams {
12
14
  id?: string;
@@ -171,7 +173,7 @@ function prefixedRunIds(dir: string, prefix: string, suffix = ""): string[] {
171
173
  }
172
174
 
173
175
  function exactResultPath(resultsDir: string, runId: string): string | null {
174
- const resultPath = path.join(resultsDir, `${runId}.json`);
176
+ const resultPath = resultFilePath(resultsDir, runId);
175
177
  assertInsideRoot(resultsDir, resultPath, "Async result file");
176
178
  return fs.existsSync(resultPath) ? resultPath : null;
177
179
  }
@@ -181,10 +183,7 @@ export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string,
181
183
  if (!requestedId) return [];
182
184
  const asyncRoot = path.resolve(asyncDirRoot);
183
185
  const resultRoot = path.resolve(resultsDir);
184
- const matchingIds = [...new Set([
185
- ...prefixedRunIds(asyncRoot, requestedId),
186
- ...prefixedRunIds(resultRoot, requestedId, ".json"),
187
- ])].sort();
186
+ const matchingIds = prefixedRunIds(asyncRoot, requestedId).sort();
188
187
  return matchingIds.map((id) => {
189
188
  const asyncDir = path.join(asyncRoot, id);
190
189
  assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
@@ -306,8 +305,8 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
306
305
  "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
307
306
  "subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
308
307
  "skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
309
- "artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
310
- "launchResolvedExtensions",
308
+ "artifactsDir", "maxOutput", "controlConfig", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
309
+ "launchResolvedExtensions", "runFanoutBudget",
311
310
  ]);
312
311
  for (const field of Object.keys(parsed)) {
313
312
  if (!allowedFields.has(field)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);
@@ -317,6 +316,11 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
317
316
  if (typeof parsed[field] !== "string" || !(parsed[field] as string).trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
318
317
  }
319
318
  if (parsed.version !== 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);
319
+ try {
320
+ parsed.runFanoutBudget = validateRunFanoutBudgetDescriptor(parsed.runFanoutBudget);
321
+ } catch (error) {
322
+ throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
323
+ }
320
324
  if (parsed.capabilityCeiling !== undefined) parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
321
325
  if (parsed.agentContract !== undefined) {
322
326
  if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
@@ -368,6 +372,16 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
368
372
  if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
369
373
  if (!Number.isInteger(artifact.cleanupDays) || (artifact.cleanupDays as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
370
374
  }
375
+ if (parsed.intercomBridge !== undefined) {
376
+ if (!parsed.intercomBridge || typeof parsed.intercomBridge !== "object" || Array.isArray(parsed.intercomBridge)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge must be an object.`);
377
+ const bridge = parsed.intercomBridge as Record<string, unknown>;
378
+ for (const field of Object.keys(bridge)) {
379
+ if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.${field} is not supported.`);
380
+ }
381
+ if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.mode is invalid.`);
382
+ if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.instructionFile must be a string.`);
383
+ if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.resultDelivery must be a boolean.`);
384
+ }
371
385
  if (parsed.controlConfig !== undefined) {
372
386
  if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
373
387
  const control = parsed.controlConfig as Record<string, unknown>;
@@ -0,0 +1,277 @@
1
+ import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
2
+ import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary, SubagentRunMode, SubagentState } from "../../shared/types.ts";
3
+
4
+ export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
5
+ export const ASYNC_STATUS_SNAPSHOT_VERSION = 1;
6
+ export const ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX = "PI_SUBAGENT_ASYNC_JSON:";
7
+
8
+ const DEFAULT_MAX_RUNS = 20;
9
+ const DEFAULT_MAX_CHILDREN_PER_NODE = 8;
10
+ const DEFAULT_MAX_DEPTH = 3;
11
+ const DEFAULT_MAX_STRING_LENGTH = 160;
12
+ const DEFAULT_MAX_SERIALIZED_BYTES = 32 * 1024;
13
+
14
+ export type AsyncStatusSnapshotState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
15
+ export type AsyncStatusSnapshotKind = "subagent" | "workflow" | "step";
16
+
17
+ export interface AsyncStatusSnapshotActivityV1 {
18
+ state?: string;
19
+ currentTool?: string;
20
+ lastActivityAt?: number;
21
+ currentToolStartedAt?: number;
22
+ turnCount?: number;
23
+ toolCount?: number;
24
+ }
25
+
26
+ export interface AsyncStatusSnapshotNodeV1 {
27
+ id: string;
28
+ kind: AsyncStatusSnapshotKind;
29
+ label: string;
30
+ state: AsyncStatusSnapshotState;
31
+ startedAt?: number;
32
+ updatedAt?: number;
33
+ endedAt?: number;
34
+ activity?: AsyncStatusSnapshotActivityV1;
35
+ children?: AsyncStatusSnapshotNodeV1[];
36
+ }
37
+
38
+ export interface AsyncStatusSnapshotCapsV1 {
39
+ maxRuns: number;
40
+ maxChildrenPerNode: number;
41
+ maxDepth: number;
42
+ maxStringLength: number;
43
+ maxSerializedBytes: number;
44
+ }
45
+
46
+ export interface AsyncStatusSnapshotOmittedV1 {
47
+ runs: number;
48
+ children: number;
49
+ byteLimitExceeded: boolean;
50
+ }
51
+
52
+ export interface AsyncStatusSnapshotV1 {
53
+ kind: typeof ASYNC_STATUS_SNAPSHOT_KIND;
54
+ version: typeof ASYNC_STATUS_SNAPSHOT_VERSION;
55
+ generatedAt: number;
56
+ caps: AsyncStatusSnapshotCapsV1;
57
+ omitted: AsyncStatusSnapshotOmittedV1;
58
+ runs: AsyncStatusSnapshotNodeV1[];
59
+ }
60
+
61
+ export interface AsyncStatusSnapshotOptions {
62
+ generatedAt?: number;
63
+ maxRuns?: number;
64
+ maxChildrenPerNode?: number;
65
+ maxDepth?: number;
66
+ maxStringLength?: number;
67
+ maxSerializedBytes?: number;
68
+ }
69
+
70
+ interface BuildContext {
71
+ caps: AsyncStatusSnapshotCapsV1;
72
+ omitted: AsyncStatusSnapshotOmittedV1;
73
+ }
74
+
75
+ function resolveCaps(options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotCapsV1 {
76
+ return {
77
+ maxRuns: Math.max(0, Math.floor(options.maxRuns ?? DEFAULT_MAX_RUNS)),
78
+ maxChildrenPerNode: Math.max(0, Math.floor(options.maxChildrenPerNode ?? DEFAULT_MAX_CHILDREN_PER_NODE)),
79
+ maxDepth: Math.max(0, Math.floor(options.maxDepth ?? DEFAULT_MAX_DEPTH)),
80
+ maxStringLength: Math.max(0, Math.floor(options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH)),
81
+ maxSerializedBytes: Math.max(256, Math.floor(options.maxSerializedBytes ?? DEFAULT_MAX_SERIALIZED_BYTES)),
82
+ };
83
+ }
84
+
85
+ function publicText(value: unknown, fallback: string, maxLength: number): string {
86
+ if (typeof value !== "string") return fallback;
87
+ const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
88
+ return truncateDisplayText(normalized || fallback, maxLength);
89
+ }
90
+
91
+ function publicOptionalText(value: unknown, maxLength: number): string | undefined {
92
+ if (typeof value !== "string") return undefined;
93
+ const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
94
+ return normalized ? truncateDisplayText(normalized, maxLength) : undefined;
95
+ }
96
+
97
+ function publicTime(value: unknown): number | undefined {
98
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
99
+ }
100
+
101
+ function publicCount(value: unknown): number | undefined {
102
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
103
+ }
104
+
105
+ function normalizeState(value: string): AsyncStatusSnapshotState {
106
+ if (value === "completed") return "complete";
107
+ if (value === "pending") return "queued";
108
+ return value as AsyncStatusSnapshotState;
109
+ }
110
+
111
+ function terminalState(state: AsyncStatusSnapshotState): boolean {
112
+ return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
113
+ }
114
+
115
+ function kindForMode(mode: SubagentRunMode | undefined): AsyncStatusSnapshotKind {
116
+ return mode === "workflow" ? "workflow" : "subagent";
117
+ }
118
+
119
+ function labelForAgents(agents: readonly string[] | undefined, fallback: string, maxLength: number): string {
120
+ if (!agents?.length) return publicText(fallback, fallback, maxLength);
121
+ const visible = agents.slice(0, 3).map((agent) => publicText(agent, "agent", maxLength)).join(", ");
122
+ const suffix = agents.length > 3 ? `, +${agents.length - 3} more` : "";
123
+ return truncateDisplayText(`${visible}${suffix}`, maxLength);
124
+ }
125
+
126
+ function activityFor(source: {
127
+ activityState?: unknown;
128
+ currentTool?: unknown;
129
+ lastActivityAt?: unknown;
130
+ currentToolStartedAt?: unknown;
131
+ turnCount?: unknown;
132
+ toolCount?: unknown;
133
+ }, ctx: BuildContext): AsyncStatusSnapshotActivityV1 | undefined {
134
+ const activity: AsyncStatusSnapshotActivityV1 = {
135
+ ...(typeof source.activityState === "string" ? { state: publicText(source.activityState, "unknown", ctx.caps.maxStringLength) } : {}),
136
+ ...(publicOptionalText(source.currentTool, ctx.caps.maxStringLength) ? { currentTool: publicOptionalText(source.currentTool, ctx.caps.maxStringLength) } : {}),
137
+ ...(publicTime(source.lastActivityAt) !== undefined ? { lastActivityAt: publicTime(source.lastActivityAt) } : {}),
138
+ ...(publicTime(source.currentToolStartedAt) !== undefined ? { currentToolStartedAt: publicTime(source.currentToolStartedAt) } : {}),
139
+ ...(publicCount(source.turnCount) !== undefined ? { turnCount: publicCount(source.turnCount) } : {}),
140
+ ...(publicCount(source.toolCount) !== undefined ? { toolCount: publicCount(source.toolCount) } : {}),
141
+ };
142
+ return Object.keys(activity).length ? activity : undefined;
143
+ }
144
+
145
+ function appendBoundedChildren(children: AsyncStatusSnapshotNodeV1[], source: readonly AsyncStatusSnapshotNodeV1[], ctx: BuildContext): void {
146
+ const remaining = Math.max(0, ctx.caps.maxChildrenPerNode - children.length);
147
+ children.push(...source.slice(0, remaining));
148
+ ctx.omitted.children += Math.max(0, source.length - remaining);
149
+ }
150
+
151
+ function buildStepNode(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
152
+ const state = normalizeState(step.status);
153
+ const updatedAt = publicTime(step.endedAt) ?? publicTime(step.lastActivityAt) ?? publicTime(step.startedAt);
154
+ const node: AsyncStatusSnapshotNodeV1 = {
155
+ id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
156
+ kind: "step",
157
+ label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
158
+ state,
159
+ ...(publicTime(step.startedAt) !== undefined ? { startedAt: publicTime(step.startedAt) } : {}),
160
+ ...(updatedAt !== undefined ? { updatedAt } : {}),
161
+ ...(terminalState(state) && publicTime(step.endedAt) !== undefined ? { endedAt: publicTime(step.endedAt) } : {}),
162
+ ...(activityFor(step, ctx) ? { activity: activityFor(step, ctx) } : {}),
163
+ };
164
+ if (depth < ctx.caps.maxDepth && step.children?.length) {
165
+ const nested = step.children.map((child, childIndex) => buildNestedNode(child, childIndex, depth + 1, ctx));
166
+ const bounded: AsyncStatusSnapshotNodeV1[] = [];
167
+ appendBoundedChildren(bounded, nested, ctx);
168
+ if (bounded.length) node.children = bounded;
169
+ } else if (step.children?.length) {
170
+ ctx.omitted.children += step.children.length;
171
+ }
172
+ return node;
173
+ }
174
+
175
+ function buildNestedNode(child: NestedRunSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
176
+ const state = normalizeState(child.state);
177
+ const updatedAt = publicTime(child.lastUpdate) ?? publicTime(child.endedAt) ?? publicTime(child.lastActivityAt) ?? publicTime(child.startedAt);
178
+ const node: AsyncStatusSnapshotNodeV1 = {
179
+ id: publicText(child.id, `nested:${index}`, ctx.caps.maxStringLength),
180
+ kind: kindForMode(child.mode),
181
+ label: child.agent ? publicText(child.agent, "subagent", ctx.caps.maxStringLength) : labelForAgents(child.agents, child.mode ?? "subagent", ctx.caps.maxStringLength),
182
+ state,
183
+ ...(publicTime(child.startedAt) !== undefined ? { startedAt: publicTime(child.startedAt) } : {}),
184
+ ...(updatedAt !== undefined ? { updatedAt } : {}),
185
+ ...(terminalState(state) && publicTime(child.endedAt) !== undefined ? { endedAt: publicTime(child.endedAt) } : {}),
186
+ ...(activityFor(child, ctx) ? { activity: activityFor(child, ctx) } : {}),
187
+ };
188
+ if (depth < ctx.caps.maxDepth) {
189
+ const nestedSteps = child.steps?.map((step, stepIndex) => buildStepNode(step, stepIndex, depth + 1, ctx)) ?? [];
190
+ const nestedChildren = child.children?.map((nested, childIndex) => buildNestedNode(nested, childIndex, depth + 1, ctx)) ?? [];
191
+ const bounded: AsyncStatusSnapshotNodeV1[] = [];
192
+ appendBoundedChildren(bounded, [...nestedSteps, ...nestedChildren], ctx);
193
+ if (bounded.length) node.children = bounded;
194
+ } else {
195
+ ctx.omitted.children += (child.steps?.length ?? 0) + (child.children?.length ?? 0);
196
+ }
197
+ return node;
198
+ }
199
+
200
+ function buildRunNode(job: AsyncJobState, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
201
+ const state = normalizeState(job.status);
202
+ const updatedAt = publicTime(job.updatedAt) ?? publicTime(job.startedAt);
203
+ const node: AsyncStatusSnapshotNodeV1 = {
204
+ id: publicText(job.asyncId, "async", ctx.caps.maxStringLength),
205
+ kind: kindForMode(job.mode),
206
+ label: labelForAgents(job.agents, job.mode ?? "subagent", ctx.caps.maxStringLength),
207
+ state,
208
+ ...(publicTime(job.startedAt) !== undefined ? { startedAt: publicTime(job.startedAt) } : {}),
209
+ ...(updatedAt !== undefined ? { updatedAt } : {}),
210
+ ...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
211
+ ...(activityFor(job, ctx) ? { activity: activityFor(job, ctx) } : {}),
212
+ };
213
+ if (ctx.caps.maxDepth > 0) {
214
+ const stepChildren = job.steps?.map((step, index) => buildStepNode(step, step.index ?? index, 1, ctx)) ?? [];
215
+ const nestedChildren = job.nestedChildren?.map((child, index) => buildNestedNode(child, index, 1, ctx)) ?? [];
216
+ const bounded: AsyncStatusSnapshotNodeV1[] = [];
217
+ appendBoundedChildren(bounded, [...stepChildren, ...nestedChildren], ctx);
218
+ if (bounded.length) node.children = bounded;
219
+ } else {
220
+ ctx.omitted.children += (job.steps?.length ?? 0) + (job.nestedChildren?.length ?? 0);
221
+ }
222
+ return node;
223
+ }
224
+
225
+ function snapshotBytes(snapshot: AsyncStatusSnapshotV1): number {
226
+ return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
227
+ }
228
+
229
+ function enforceByteLimit(snapshot: AsyncStatusSnapshotV1): void {
230
+ while (snapshot.runs.length > 0 && snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) {
231
+ snapshot.runs.pop();
232
+ snapshot.omitted.runs += 1;
233
+ snapshot.omitted.byteLimitExceeded = true;
234
+ }
235
+ if (snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) snapshot.omitted.byteLimitExceeded = true;
236
+ }
237
+
238
+ export function buildAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
239
+ const caps = resolveCaps(options);
240
+ const ctx: BuildContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
241
+ const sorted = [...jobs].sort((left, right) => {
242
+ const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
243
+ const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
244
+ return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
245
+ });
246
+ ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
247
+ const snapshot: AsyncStatusSnapshotV1 = {
248
+ kind: ASYNC_STATUS_SNAPSHOT_KIND,
249
+ version: ASYNC_STATUS_SNAPSHOT_VERSION,
250
+ generatedAt: options.generatedAt ?? Date.now(),
251
+ caps,
252
+ omitted: ctx.omitted,
253
+ runs: sorted.slice(0, caps.maxRuns).map((job) => buildRunNode(job, ctx)),
254
+ };
255
+ enforceByteLimit(snapshot);
256
+ return snapshot;
257
+ }
258
+
259
+ export function asyncStatusSnapshotJobsForState(state: SubagentState | undefined, sessionId: string | null | undefined): AsyncJobState[] {
260
+ if (!state || !sessionId || state.currentSessionId !== sessionId) return [];
261
+ const jobs = new Map<string, AsyncJobState>();
262
+ for (const job of state.asyncJobs.values()) {
263
+ if (job.sessionId === sessionId) jobs.set(job.asyncId, job);
264
+ }
265
+ for (const job of state.fleetJobs?.values() ?? []) {
266
+ if (job.sessionId === sessionId && !jobs.has(job.asyncId)) jobs.set(job.asyncId, job);
267
+ }
268
+ return [...jobs.values()];
269
+ }
270
+
271
+ export function buildAsyncStatusSnapshotForState(state: SubagentState | undefined, sessionId: string | null | undefined, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
272
+ return buildAsyncStatusSnapshot(asyncStatusSnapshotJobsForState(state, sessionId), options);
273
+ }
274
+
275
+ export function encodeAsyncStatusSnapshotWidget(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): string[] {
276
+ return [`${ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX}${JSON.stringify(buildAsyncStatusSnapshot(jobs, options))}`];
277
+ }
@@ -7,11 +7,12 @@ import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from
7
7
  import { pruneStatusCacheForAsyncRoot, readStatus } from "../../shared/utils.ts";
8
8
  import { attachRootChildrenToSteps, buildNestedRouteIndex, findNestedRouteForRootId, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
9
9
  import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
10
+ import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
10
11
  import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
11
12
  import { contextModeLabel, summarizeContextModes, type ContextMode, type ContextSummary } from "../shared/context-mode.ts";
12
13
  import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
13
14
  import { readProcessTerminal, sanitizeProcessTerminal } from "./process-terminal.ts";
14
- import { ACTIVE_RUN_INDEX_DIR, isActiveAsyncState, readActiveRunIndex, updateActiveRunIndex } from "./active-run-index.ts";
15
+ import { ACTIVE_RUN_INDEX_DIR, DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, activeRunMarkerAgeMs, isActiveAsyncState, readActiveRunIndex, releaseActiveRunIndex, updateActiveRunIndex } from "./active-run-index.ts";
15
16
 
16
17
  interface AsyncRunStepSummary {
17
18
  index: number;
@@ -24,6 +25,7 @@ interface AsyncRunStepSummary {
24
25
  structured?: boolean;
25
26
  checkpoint?: ChainCheckpointState;
26
27
  status: AsyncJobStep["status"];
28
+ runner?: AsyncJobStep["runner"];
27
29
  activityState?: ActivityState;
28
30
  lastActivityAt?: number;
29
31
  currentTool?: string;
@@ -106,6 +108,7 @@ export interface AsyncRunSummary {
106
108
  nestedChildren?: NestedRunSummary[];
107
109
  nestedWarnings?: string[];
108
110
  processTerminal?: AsyncStatus["processTerminal"];
111
+ runFanoutBudget?: AsyncStatus["runFanoutBudget"];
109
112
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
110
113
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
111
114
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -126,6 +129,7 @@ interface AsyncRunListOptions {
126
129
  now?: () => number;
127
130
  reconcile?: boolean;
128
131
  runId?: string;
132
+ includeNested?: boolean;
129
133
  }
130
134
 
131
135
  function getErrorMessage(error: unknown): string {
@@ -222,6 +226,8 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
222
226
  const { activityState, lastActivityAt } = deriveAsyncActivityState(asyncDir, status);
223
227
  const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId })
224
228
  ?? sanitizeProcessTerminal(status.processTerminal, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId }, path.join(asyncDir, "status.json"));
229
+ const runFanoutBudgetDescriptor = readRunFanoutBudgetDescriptor(asyncDir);
230
+ const runFanoutBudget = runFanoutBudgetDescriptor ? getRunFanoutBudgetSnapshot(runFanoutBudgetDescriptor) : status.runFanoutBudget;
225
231
  const steps = status.steps ?? [];
226
232
  const chainStepCount = status.chainStepCount ?? steps.length;
227
233
  const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
@@ -249,6 +255,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
249
255
  ...(step.structured ? { structured: step.structured } : {}),
250
256
  ...(step.checkpoint ? { checkpoint: step.checkpoint } : {}),
251
257
  status: step.status,
258
+ ...(step.runner ? { runner: step.runner } : {}),
252
259
  ...(stepActivityState ? { activityState: stepActivityState } : {}),
253
260
  ...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
254
261
  ...(step.currentTool ? { currentTool: step.currentTool } : {}),
@@ -327,6 +334,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
327
334
  ...(nestedChildren.length ? { nestedChildren } : {}),
328
335
  ...(nestedWarnings.length ? { nestedWarnings } : {}),
329
336
  ...(processTerminal ? { processTerminal } : {}),
337
+ ...(runFanoutBudget ? { runFanoutBudget } : {}),
330
338
  ...(status.launchContractDigest ? { launchContractDigest: status.launchContractDigest } : {}),
331
339
  ...(status.launchResolvedExtensions ? { launchResolvedExtensions: status.launchResolvedExtensions } : {}),
332
340
  ...(status.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: status.runtimeAcknowledgedExtensions } : {}),
@@ -378,6 +386,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
378
386
  && options.states !== undefined
379
387
  && options.states.length > 0
380
388
  && options.states.every(isActiveAsyncState);
389
+ const includeNested = options.includeNested !== false;
381
390
  try {
382
391
  if (options.runId !== undefined) {
383
392
  const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
@@ -438,6 +447,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
438
447
  // entirely when no active runs match.
439
448
  let nestedRouteIndex: Map<string, NestedRoute> | undefined;
440
449
  const resolveNestedRoute = (rootRunId: string): NestedRoute | undefined => {
450
+ if (!includeNested) return undefined;
441
451
  if (usedActiveIndex) return findNestedRouteForRootId(rootRunId);
442
452
  if (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
443
453
  return nestedRouteIndex.get(rootRunId);
@@ -452,11 +462,11 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
452
462
  if (usedActiveIndex) updateActiveRunIndex(asyncDir, "failed");
453
463
  continue;
454
464
  }
455
- if (status.displayDismissedAt !== undefined) {
456
- if (usedActiveIndex) updateActiveRunIndex(asyncDir, "complete");
457
- continue;
465
+ if (usedActiveIndex && !isActiveAsyncState(status.state)) {
466
+ const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId });
467
+ if (processTerminal?.state === "observed" || (activeRunMarkerAgeMs(asyncDir, options.now?.()) ?? 0) > DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS) releaseActiveRunIndex(asyncDir);
458
468
  }
459
- if (usedActiveIndex && !isActiveAsyncState(status.state)) updateActiveRunIndex(asyncDir, status.state);
469
+ if (status.displayDismissedAt !== undefined) continue;
460
470
  // Filter before the nested-route lookup: the lookup builds an index over
461
471
  // the nested-events directory, so deferring it for filtered-out runs keeps
462
472
  // restoration at load from scanning that directory when no active runs
@@ -465,7 +475,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
465
475
  if (options.sessionId && status.sessionId !== options.sessionId) continue;
466
476
  const nestedWarnings: string[] = [];
467
477
  let nestedRoute: NestedRoute | undefined;
468
- if (options.reconcile !== false) {
478
+ if (options.reconcile !== false && includeNested) {
469
479
  try {
470
480
  nestedRoute = resolveNestedRoute(status.runId || path.basename(asyncDir));
471
481
  if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
@@ -559,6 +569,7 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
559
569
  const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
560
570
  const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
561
571
  lines.push(...formatNestedRunStatusLines(unattached, { indent: " ", maxLines: 12 }));
572
+ if (run.runFanoutBudget) lines.push(` ${formatRunFanoutBudget(run.runFanoutBudget)}`);
562
573
  if (run.error) lines.push(` Error: ${run.error}`);
563
574
  for (const warning of run.nestedWarnings ?? []) lines.push(` Warning: ${warning}`);
564
575
  const outputPath = formatAsyncRunOutputPath(run);
@@ -4,7 +4,7 @@ import * as path from "node:path";
4
4
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
5
5
  import { appendJsonl } from "../../shared/artifacts.ts";
6
6
  import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
7
- import { readStatus } from "../../shared/utils.ts";
7
+ import { PROMPT_REDACTED, readStatus } from "../../shared/utils.ts";
8
8
  import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep, RunnerCheckpointStep } from "../shared/parallel-utils.ts";
9
9
  import { isCheckpointRunnerStep, isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
10
10
 
@@ -19,6 +19,7 @@ export interface ChainAppendRequest {
19
19
  export interface ChainAppendResult {
20
20
  request: ChainAppendRequest;
21
21
  pendingCount: number;
22
+ bookkeepingError?: string;
22
23
  }
23
24
 
24
25
  type StatusStep = NonNullable<AsyncStatus["steps"]>[number];
@@ -69,6 +70,7 @@ export function enqueueChainAppendRequest(input: {
69
70
  runId: string;
70
71
  steps: RunnerStep[];
71
72
  now?: number;
73
+ admit?: (persist: () => void) => void;
72
74
  }): ChainAppendResult {
73
75
  const status = readStatus(input.asyncDir);
74
76
  if (!status) throw new Error(`No async run status found for '${input.runId}'.`);
@@ -85,20 +87,36 @@ export function enqueueChainAppendRequest(input: {
85
87
  steps: input.steps,
86
88
  };
87
89
  fs.mkdirSync(appendDir(input.asyncDir), { recursive: true });
88
- writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
89
- const pendingCount = countPendingChainAppendRequests(input.asyncDir);
90
+ const persist = () => writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
91
+ if (input.admit) input.admit(persist);
92
+ else persist();
93
+ let pendingCount = 1;
94
+ const bookkeepingErrors: string[] = [];
95
+ try {
96
+ pendingCount = countPendingChainAppendRequests(input.asyncDir);
97
+ } catch (error) {
98
+ bookkeepingErrors.push(`pending append count failed: ${error instanceof Error ? error.message : String(error)}`);
99
+ }
90
100
  const statusPath = path.join(input.asyncDir, "status.json");
91
101
  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
+ try {
103
+ writeAtomicJson(statusPath, updatedStatus);
104
+ } catch (error) {
105
+ bookkeepingErrors.push(`status update failed: ${error instanceof Error ? error.message : String(error)}`);
106
+ }
107
+ try {
108
+ appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
109
+ type: "subagent.chain.append.requested",
110
+ ts: request.createdAt,
111
+ runId: input.runId,
112
+ requestId: request.id,
113
+ stepCount: input.steps.length,
114
+ pendingAppends: pendingCount,
115
+ }));
116
+ } catch (error) {
117
+ bookkeepingErrors.push(`event append failed: ${error instanceof Error ? error.message : String(error)}`);
118
+ }
119
+ return { request, pendingCount, ...(bookkeepingErrors.length > 0 ? { bookkeepingError: bookkeepingErrors.join("; ") } : {}) };
102
120
  }
103
121
 
104
122
  function readAppendRequest(filePath: string): ChainAppendRequest | undefined {
@@ -135,8 +153,8 @@ const MAX_STATUS_STEP_DESCRIPTION_CHARS = 160;
135
153
 
136
154
  /** Bounded one-line per-step task description persisted into status.json for fleet display. */
137
155
  export function statusStepDescription(task: string | undefined): string | undefined {
138
- const description = task?.replace(/\s+/g, " ").trim();
139
- if (!description) return undefined;
156
+ if (!task?.trim()) return undefined;
157
+ const description = PROMPT_REDACTED;
140
158
  return description.length > MAX_STATUS_STEP_DESCRIPTION_CHARS
141
159
  ? `${description.slice(0, MAX_STATUS_STEP_DESCRIPTION_CHARS - 1)}…`
142
160
  : description;
@@ -1,5 +1,5 @@
1
1
  import * as fs from "node:fs";
2
- import * as path from "node:path";
2
+ import { resultFilePath } from "./result-files.ts";
3
3
  import type { AcceptanceLedger, AsyncStatus, CostSummary, ModelAttempt } from "../../shared/types.ts";
4
4
  import { readStatus } from "../../shared/utils.ts";
5
5
 
@@ -195,5 +195,5 @@ export async function waitForImportedAsyncRoot(
195
195
  }
196
196
 
197
197
  export function resolveAsyncRootResultPath(resultsDir: string, runId: string): string {
198
- return path.join(resultsDir, `${runId}.json`);
198
+ return resultFilePath(resultsDir, runId);
199
199
  }
@@ -9,6 +9,8 @@ const ARCHIVE_VERSION = 1;
9
9
  const ARCHIVE_TEXT_LIMIT_BYTES = 64 * 1024;
10
10
  const REPLAY_DIR_NAME = "completion-replay";
11
11
  const ARCHIVE_DIR_NAME = "output-archives";
12
+ const CLEANUP_INTERVAL_MS = 60_000;
13
+ const lastCleanupByResultsDir = new Map<string, number>();
12
14
 
13
15
  export interface CompletionArchiveEntry {
14
16
  agent?: string;
@@ -194,7 +196,7 @@ export function writeCompletionReplay(input: {
194
196
  archivePath,
195
197
  };
196
198
  writePrivateAtomicJson(completionReplayPath(input.resultsDir, input.runId), record);
197
- cleanupCompletionReplay(input.resultsDir, input.now, input.ttlMs);
199
+ cleanupCompletionReplayIfDue(input.resultsDir, input.now, input.ttlMs);
198
200
  return record;
199
201
  }
200
202
 
@@ -233,6 +235,14 @@ export function readCompletionArchive(archivePath: string): CompletionArchive |
233
235
  }
234
236
  }
235
237
 
238
+ export function cleanupCompletionReplayIfDue(resultsDir: string, now: number, maxAgeMs: number, intervalMs = CLEANUP_INTERVAL_MS): boolean {
239
+ const last = lastCleanupByResultsDir.get(resultsDir);
240
+ if (last !== undefined && now - last < intervalMs) return false;
241
+ lastCleanupByResultsDir.set(resultsDir, now);
242
+ cleanupCompletionReplay(resultsDir, now, maxAgeMs);
243
+ return true;
244
+ }
245
+
236
246
  /** Opportunistically remove expired replay and orphan archive files without affecting delivery. */
237
247
  export function cleanupCompletionReplay(resultsDir: string, now: number, maxAgeMs: number): void {
238
248
  const replayDir = path.join(resultsDir, REPLAY_DIR_NAME);