@xzzpig/pi-subagents 0.14.0 → 0.15.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 (198) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +63 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  21. package/package.json +9 -4
  22. package/prompts/parallel-review.md +1 -1
  23. package/runner-peer-loader.mjs +24 -0
  24. package/runner-peer-preload.mjs +36 -0
  25. package/skills/pi-subagents/SKILL.md +34 -22
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  27. package/skills/pi-subagents/references/execution-controls.md +27 -8
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  31. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  32. package/src/agents/advertised-agent-prompt.ts +94 -0
  33. package/src/agents/agent-management.ts +71 -59
  34. package/src/agents/agent-serializer.ts +6 -3
  35. package/src/agents/agents.ts +198 -72
  36. package/src/agents/builtin-names.ts +1 -0
  37. package/src/agents/chain-serializer.ts +5 -0
  38. package/src/agents/runtime-agent-registry.ts +7 -6
  39. package/src/api/delegation.ts +4 -0
  40. package/src/api/preflight.ts +110 -71
  41. package/src/api/required-child-extensions.ts +6 -0
  42. package/src/api/shared-types.ts +3 -1
  43. package/src/api/workflow-resources.ts +6 -0
  44. package/src/extension/config.ts +14 -37
  45. package/src/extension/fanout-child.ts +68 -5
  46. package/src/extension/herdr-pi-bridge.ts +164 -0
  47. package/src/extension/index.ts +141 -51
  48. package/src/extension/public-execution.ts +7 -6
  49. package/src/extension/rpc.ts +8 -21
  50. package/src/extension/schemas.ts +86 -84
  51. package/src/extension/tool-description.ts +32 -79
  52. package/src/inspectors/actions.ts +148 -0
  53. package/src/inspectors/ghostty/actions.ts +74 -0
  54. package/src/inspectors/ghostty/plugin.ts +17 -0
  55. package/src/inspectors/herdr/actions.ts +99 -179
  56. package/src/inspectors/herdr/plugin.ts +20 -0
  57. package/src/inspectors/herdr/project-panes.ts +4 -1
  58. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  59. package/src/inspectors/plugins.ts +8 -0
  60. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  61. package/src/inspectors/types.ts +51 -0
  62. package/src/integrations/pi-web-session-liveness.ts +73 -0
  63. package/src/intercom/intercom-bridge.ts +50 -8
  64. package/src/intercom/native-supervisor-channel.ts +142 -115
  65. package/src/intercom/supervisor-ui.ts +3 -2
  66. package/src/missions/workflow-state.ts +37 -16
  67. package/src/policy/authority.ts +4 -0
  68. package/src/profiles/profiles.ts +12 -6
  69. package/src/runs/background/active-async-capacity.ts +22 -18
  70. package/src/runs/background/active-run-index.ts +17 -1
  71. package/src/runs/background/async-execution.ts +359 -176
  72. package/src/runs/background/async-job-tracker.ts +41 -7
  73. package/src/runs/background/async-resume.ts +19 -12
  74. package/src/runs/background/async-retention.ts +20 -0
  75. package/src/runs/background/async-status-snapshot.ts +10 -12
  76. package/src/runs/background/async-status.ts +32 -13
  77. package/src/runs/background/auto-drain.ts +59 -35
  78. package/src/runs/background/binary-bootstrap.ts +38 -0
  79. package/src/runs/background/chain-append.ts +1 -1
  80. package/src/runs/background/chain-root-attachment.ts +22 -33
  81. package/src/runs/background/control-channel.ts +78 -44
  82. package/src/runs/background/fleet-view.ts +30 -2
  83. package/src/runs/background/notify.ts +193 -19
  84. package/src/runs/background/owned-process-tree.ts +35 -8
  85. package/src/runs/background/process-terminal.ts +23 -23
  86. package/src/runs/background/result-files.ts +8 -4
  87. package/src/runs/background/result-watcher.ts +19 -2
  88. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  89. package/src/runs/background/run-child-session.ts +118 -41
  90. package/src/runs/background/run-status.ts +78 -5
  91. package/src/runs/background/runner-aliases.ts +22 -5
  92. package/src/runs/background/runner-child-launch.ts +93 -0
  93. package/src/runs/background/runner-child-sessions.ts +5 -4
  94. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  95. package/src/runs/background/scheduled-runs.ts +51 -18
  96. package/src/runs/background/stale-run-reconciler.ts +38 -12
  97. package/src/runs/background/steering.ts +20 -2
  98. package/src/runs/background/subagent-runner.ts +766 -432
  99. package/src/runs/background/subagent-wait.ts +179 -28
  100. package/src/runs/background/wait-completions.ts +79 -27
  101. package/src/runs/background/wait-subscriptions.ts +9 -3
  102. package/src/runs/background/wait-tool.ts +5 -3
  103. package/src/runs/foreground/async-steering-action.ts +37 -7
  104. package/src/runs/foreground/async-stop-action.ts +93 -3
  105. package/src/runs/foreground/execution.ts +174 -194
  106. package/src/runs/foreground/foreground-history.ts +5 -2
  107. package/src/runs/foreground/prompt-audit.ts +12 -6
  108. package/src/runs/foreground/subagent-executor.ts +896 -397
  109. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  110. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  111. package/src/runs/shared/acceptance.ts +54 -14
  112. package/src/runs/shared/agent-contract.ts +1 -1
  113. package/src/runs/shared/async-status-projection.ts +172 -78
  114. package/src/runs/shared/capability-ceiling.ts +2 -0
  115. package/src/runs/shared/child-hooks.ts +167 -3
  116. package/src/runs/shared/child-launch-plan.ts +15 -3
  117. package/src/runs/shared/child-launch.ts +44 -16
  118. package/src/runs/shared/child-lifecycle.ts +6 -3
  119. package/src/runs/shared/child-runtime-config.ts +8 -1
  120. package/src/runs/shared/child-session.ts +130 -24
  121. package/src/runs/shared/child-tool-plan.ts +145 -14
  122. package/src/runs/shared/completion-evidence.ts +2 -2
  123. package/src/runs/shared/completion-guard.ts +6 -3
  124. package/src/runs/shared/dynamic-fanout.ts +2 -2
  125. package/src/runs/shared/effective-system-prompt.ts +33 -0
  126. package/src/runs/shared/external-cli-contract.ts +11 -1
  127. package/src/runs/shared/external-cli-preflight.ts +6 -2
  128. package/src/runs/shared/external-cli-runner.ts +9 -7
  129. package/src/runs/shared/herdr-connection.ts +134 -0
  130. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  131. package/src/runs/shared/herdr-machine.ts +279 -0
  132. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  133. package/src/runs/shared/herdr-placed-run.ts +263 -0
  134. package/src/runs/shared/host-step-status.ts +11 -11
  135. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  136. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  137. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  138. package/src/runs/shared/model-scope.ts +1 -1
  139. package/src/runs/shared/nested-events.ts +19 -10
  140. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  141. package/src/runs/shared/parallel-handoff.ts +57 -12
  142. package/src/runs/shared/parallel-utils.ts +10 -4
  143. package/src/runs/shared/pi-spawn.ts +10 -0
  144. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  145. package/src/runs/shared/run-fanout-budget.ts +8 -8
  146. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  147. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  148. package/src/runs/shared/task-intent.ts +46 -13
  149. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  150. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  151. package/src/runs/shared/worktree-setup-command.ts +213 -0
  152. package/src/runs/shared/worktree.ts +437 -214
  153. package/src/shared/child-cache-retention.ts +43 -0
  154. package/src/shared/fork-context.ts +15 -72
  155. package/src/shared/launch-contract.ts +70 -8
  156. package/src/shared/model-response-aliases.ts +13 -0
  157. package/src/shared/opencode-session-headers.ts +30 -0
  158. package/src/shared/pruned-fork.ts +1 -1
  159. package/src/shared/required-child-extensions.ts +81 -0
  160. package/src/shared/settings.ts +5 -2
  161. package/src/shared/shortcuts.ts +0 -4
  162. package/src/shared/types.ts +163 -90
  163. package/src/shared/utils.ts +10 -2
  164. package/src/shared/watch-strategy.ts +2 -0
  165. package/src/shared/workflow-child-permit.ts +18 -13
  166. package/src/slash/delegation-adapters.ts +3 -1
  167. package/src/slash/delegation-request.ts +14 -0
  168. package/src/slash/slash-commands.ts +2 -7
  169. package/src/slash/subagents-admin.ts +31 -14
  170. package/src/tui/fleet-status.ts +165 -20
  171. package/src/tui/fleet.ts +30 -19
  172. package/src/tui/render.ts +210 -50
  173. package/src/watchdog/child-status.ts +28 -28
  174. package/src/watchdog/lsp-diagnostics.ts +1 -1
  175. package/src/watchdog/model-selection.ts +21 -1
  176. package/src/watchdog/permission-arbiter.ts +5 -2
  177. package/src/watchdog/register-child.ts +10 -2
  178. package/src/watchdog/register-main.ts +39 -35
  179. package/src/watchdog/render.ts +1 -1
  180. package/src/watchdog/review.ts +122 -74
  181. package/src/watchdog/rules.ts +1 -1
  182. package/src/watchdog/runtime.ts +100 -27
  183. package/src/watchdog/scope.ts +1 -1
  184. package/src/watchdog/settings.ts +3 -0
  185. package/src/watchdog/tool-actions.ts +13 -12
  186. package/src/watchdog/turn-delta.ts +23 -0
  187. package/src/watchdog/types.ts +5 -3
  188. package/src/watchdog/warning-format.ts +1 -1
  189. package/src/workflows/chat-progress.ts +3 -3
  190. package/src/workflows/scripted-workflow.ts +349 -26
  191. package/src/workflows/workflow-checklist.ts +17 -20
  192. package/src/workflows/workflow-child-summary.ts +57 -8
  193. package/src/workflows/workflow-preflight.ts +19 -19
  194. package/src/workflows/workflow-receipt.ts +24 -6
  195. package/src/workflows/workflow-resources.ts +108 -22
  196. package/src/workflows/workflow-settlement.ts +3 -0
  197. package/src/runs/shared/model-exclusions.ts +0 -373
  198. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -1,6 +1,6 @@
1
1
  import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
2
2
  import { formatModelThinking } from "../../shared/formatters.ts";
3
- import type { AsyncJobState, AsyncJobStep, HostStepFreshnessV1, HostStepMonitorKind, HostStepNodeV1, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../../shared/types.ts";
3
+ import type { AsyncJobState, AsyncJobStep, HostStepFreshness, HostStepMonitorKind, HostStepNode, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLane, WorkflowPreflight } from "../../shared/types.ts";
4
4
  import { HOST_STEP_MAX_COUNT, HOST_STEP_MAX_DETAIL_CHARS, HOST_STEP_MAX_LABEL_CHARS, HOST_STEP_MAX_PROVIDER_CHARS, HOST_STEP_MAX_REASON_CHARS, HOST_STEP_MAX_REF_CHARS, HOST_STEP_MAX_ROLE_CHARS, HOST_STEP_MAX_TARGET_CHARS, hostStepReportName, parseHostStepNode, validHostStepNodes } from "./host-step-status.ts";
5
5
  import { workflowPreflightLaneForRuntimeKey } from "../../workflows/workflow-preflight.ts";
6
6
  import { workflowGraphStageNodes } from "./workflow-graph.ts";
@@ -32,7 +32,7 @@ function isAsyncStatusSnapshotState(value: string): value is AsyncStatusSnapshot
32
32
  return Object.hasOwn(ASYNC_STATUS_SNAPSHOT_STATES, value);
33
33
  }
34
34
 
35
- export interface AsyncStatusSnapshotActivityV1 {
35
+ export interface AsyncStatusSnapshotActivity {
36
36
  state?: string;
37
37
  currentTool?: string;
38
38
  lastActivityAt?: number;
@@ -41,7 +41,7 @@ export interface AsyncStatusSnapshotActivityV1 {
41
41
  toolCount?: number;
42
42
  }
43
43
 
44
- export interface AsyncStatusSnapshotHostStepV1 {
44
+ export interface AsyncStatusSnapshotHostStep {
45
45
  kind: HostStepMonitorKind;
46
46
  provider?: string;
47
47
  role?: string;
@@ -54,7 +54,7 @@ export interface AsyncStatusSnapshotHostStepV1 {
54
54
  report?: string;
55
55
  }
56
56
 
57
- export interface AsyncStatusSnapshotNodeV1 {
57
+ export interface AsyncStatusSnapshotNode {
58
58
  id: string;
59
59
  kind: AsyncStatusSnapshotKind | "host-step";
60
60
  label: string;
@@ -62,12 +62,12 @@ export interface AsyncStatusSnapshotNodeV1 {
62
62
  startedAt?: number;
63
63
  updatedAt?: number;
64
64
  endedAt?: number;
65
- activity?: AsyncStatusSnapshotActivityV1;
66
- hostStep?: AsyncStatusSnapshotHostStepV1;
67
- children?: AsyncStatusSnapshotNodeV1[];
65
+ activity?: AsyncStatusSnapshotActivity;
66
+ hostStep?: AsyncStatusSnapshotHostStep;
67
+ children?: AsyncStatusSnapshotNode[];
68
68
  }
69
69
 
70
- export interface AsyncStatusSnapshotCapsV1 {
70
+ export interface AsyncStatusSnapshotCaps {
71
71
  maxRuns: number;
72
72
  maxChildrenPerNode: number;
73
73
  maxDepth: number;
@@ -75,19 +75,19 @@ export interface AsyncStatusSnapshotCapsV1 {
75
75
  maxSerializedBytes: number;
76
76
  }
77
77
 
78
- export interface AsyncStatusSnapshotOmittedV1 {
78
+ export interface AsyncStatusSnapshotOmitted {
79
79
  runs: number;
80
80
  children: number;
81
81
  byteLimitExceeded: boolean;
82
82
  }
83
83
 
84
- export interface AsyncStatusSnapshotV1 {
84
+ export interface AsyncStatusSnapshot {
85
85
  kind: typeof ASYNC_STATUS_SNAPSHOT_KIND;
86
86
  version: typeof ASYNC_STATUS_SNAPSHOT_VERSION;
87
87
  generatedAt: number;
88
- caps: AsyncStatusSnapshotCapsV1;
89
- omitted: AsyncStatusSnapshotOmittedV1;
90
- runs: AsyncStatusSnapshotNodeV1[];
88
+ caps: AsyncStatusSnapshotCaps;
89
+ omitted: AsyncStatusSnapshotOmitted;
90
+ runs: AsyncStatusSnapshotNode[];
91
91
  }
92
92
 
93
93
  export interface AsyncStatusSnapshotOptions {
@@ -108,6 +108,8 @@ export interface AsyncStatusWorkflowRow {
108
108
  modelThinking?: string;
109
109
  activity?: string;
110
110
  startedAt?: number;
111
+ endedAt?: number;
112
+ durationMs?: number;
111
113
  tokens?: number;
112
114
  window?: number;
113
115
  overflow?: number;
@@ -117,19 +119,19 @@ export interface AsyncStatusWorkflowRow {
117
119
  reasonCode?: string;
118
120
  detail?: string;
119
121
  target?: string;
120
- freshness?: HostStepFreshnessV1;
122
+ freshness?: HostStepFreshness;
121
123
  reportPath?: string;
122
- preflight?: WorkflowPreflightLaneV1;
124
+ preflight?: WorkflowPreflightLane;
123
125
  }
124
126
 
125
127
  interface ProjectionContext {
126
- caps: AsyncStatusSnapshotCapsV1;
127
- omitted: AsyncStatusSnapshotOmittedV1;
128
+ caps: AsyncStatusSnapshotCaps;
129
+ omitted: AsyncStatusSnapshotOmitted;
128
130
  }
129
131
 
130
- function validHostStepList(source: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | undefined): HostStepNodeV1[] {
132
+ function validHostStepList(source: readonly HostStepNode[] | WorkflowGraphSnapshot | undefined): HostStepNode[] {
131
133
  if (source && "nodes" in source) return validHostStepNodes(source);
132
- const hostSteps: HostStepNodeV1[] = [];
134
+ const hostSteps: HostStepNode[] = [];
133
135
  for (const [index, value] of (source ?? []).slice(0, HOST_STEP_MAX_COUNT).entries()) {
134
136
  try {
135
137
  hostSteps.push(parseHostStepNode(value, `hostSteps[${index}]`));
@@ -140,7 +142,7 @@ function validHostStepList(source: readonly HostStepNodeV1[] | WorkflowGraphSnap
140
142
  return hostSteps;
141
143
  }
142
144
 
143
- function resolveCaps(options: AsyncStatusSnapshotOptions): AsyncStatusSnapshotCapsV1 {
145
+ function resolveCaps(options: AsyncStatusSnapshotOptions): AsyncStatusSnapshotCaps {
144
146
  return {
145
147
  maxRuns: Math.max(0, Math.floor(options.maxRuns ?? DEFAULT_MAX_RUNS)),
146
148
  maxChildrenPerNode: Math.max(0, Math.floor(options.maxChildrenPerNode ?? DEFAULT_MAX_CHILDREN_PER_NODE)),
@@ -199,13 +201,13 @@ function activityFor(source: {
199
201
  currentToolStartedAt?: unknown;
200
202
  turnCount?: unknown;
201
203
  toolCount?: unknown;
202
- }, ctx: ProjectionContext): AsyncStatusSnapshotActivityV1 | undefined {
204
+ }, ctx: ProjectionContext): AsyncStatusSnapshotActivity | undefined {
203
205
  const currentTool = publicOptionalText(source.currentTool, ctx.caps.maxStringLength);
204
206
  const lastActivityAt = publicTime(source.lastActivityAt);
205
207
  const currentToolStartedAt = publicTime(source.currentToolStartedAt);
206
208
  const turnCount = publicCount(source.turnCount);
207
209
  const toolCount = publicCount(source.toolCount);
208
- const activity: AsyncStatusSnapshotActivityV1 = {
210
+ const activity: AsyncStatusSnapshotActivity = {
209
211
  ...(typeof source.activityState === "string" ? { state: publicText(source.activityState, "unknown", ctx.caps.maxStringLength) } : {}),
210
212
  ...(currentTool ? { currentTool } : {}),
211
213
  ...(lastActivityAt !== undefined ? { lastActivityAt } : {}),
@@ -216,22 +218,31 @@ function activityFor(source: {
216
218
  return Object.keys(activity).length ? activity : undefined;
217
219
  }
218
220
 
219
- function appendBoundedChildren(children: AsyncStatusSnapshotNodeV1[], source: readonly AsyncStatusSnapshotNodeV1[], ctx: ProjectionContext): void {
221
+ function appendBoundedChildren(children: AsyncStatusSnapshotNode[], source: readonly AsyncStatusSnapshotNode[], ctx: ProjectionContext): void {
220
222
  const remaining = Math.max(0, ctx.caps.maxChildrenPerNode - children.length);
221
223
  children.push(...source.slice(0, remaining));
222
224
  ctx.omitted.children += Math.max(0, source.length - remaining);
223
225
  }
224
226
 
225
- function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
227
+ function stepIdentity(step: AsyncJobStep | NestedStepSummary, index: number, ctx: ProjectionContext) {
228
+ return {
229
+ id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
230
+ label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
231
+ };
232
+ }
233
+
234
+ function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNode {
226
235
  const state = normalizeState(step.status);
227
236
  const startedAt = publicTime(step.startedAt);
228
- const endedAt = publicTime(step.endedAt);
237
+ const durationMs = "durationMs" in step ? publicTime(step.durationMs) : undefined;
238
+ const endedAt = publicTime(step.endedAt) ?? (terminalState(state) && startedAt !== undefined && durationMs !== undefined ? publicTime(startedAt + durationMs) : undefined);
229
239
  const updatedAt = endedAt ?? publicTime(step.lastActivityAt) ?? startedAt;
230
240
  const activity = activityFor(step, ctx);
231
- const node: AsyncStatusSnapshotNodeV1 = {
232
- id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
241
+ const { id, label } = stepIdentity(step, index, ctx);
242
+ const node: AsyncStatusSnapshotNode = {
243
+ id,
233
244
  kind: "step",
234
- label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
245
+ label,
235
246
  state,
236
247
  ...(startedAt !== undefined ? { startedAt } : {}),
237
248
  ...(updatedAt !== undefined ? { updatedAt } : {}),
@@ -240,7 +251,7 @@ function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, dept
240
251
  };
241
252
  if (depth < ctx.caps.maxDepth && step.children?.length) {
242
253
  const nested = step.children.map((child, childIndex) => projectNestedRun(child, childIndex, depth + 1, ctx));
243
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
254
+ const bounded: AsyncStatusSnapshotNode[] = [];
244
255
  appendBoundedChildren(bounded, nested, ctx);
245
256
  if (bounded.length) node.children = bounded;
246
257
  } else if (step.children?.length) {
@@ -249,23 +260,13 @@ function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, dept
249
260
  return node;
250
261
  }
251
262
 
252
- function projectWorkflowGraphNode(node: WorkflowGraphSnapshot["nodes"][number], index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
253
- const step: AsyncJobStep = {
254
- agent: node.agent ?? node.label,
255
- status: workflowGraphStepStatus(node.status),
256
- workflowKey: node.id,
257
- label: node.label,
258
- };
259
- return projectStep(step, node.flatIndex ?? index, depth, ctx);
260
- }
261
-
262
- function projectNestedRun(child: NestedRunSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
263
+ function projectNestedRun(child: NestedRunSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNode {
263
264
  const state = normalizeState(child.state);
264
265
  const startedAt = publicTime(child.startedAt);
265
266
  const endedAt = publicTime(child.endedAt);
266
267
  const updatedAt = publicTime(child.lastUpdate) ?? endedAt ?? publicTime(child.lastActivityAt) ?? startedAt;
267
268
  const activity = activityFor(child, ctx);
268
- const node: AsyncStatusSnapshotNodeV1 = {
269
+ const node: AsyncStatusSnapshotNode = {
269
270
  id: publicText(child.id, `nested:${index}`, ctx.caps.maxStringLength),
270
271
  kind: kindForMode(child.mode),
271
272
  label: child.agent ? publicText(child.agent, "subagent", ctx.caps.maxStringLength) : labelForAgents(child.agents, child.mode ?? "subagent", ctx.caps.maxStringLength),
@@ -278,7 +279,7 @@ function projectNestedRun(child: NestedRunSummary, index: number, depth: number,
278
279
  if (depth < ctx.caps.maxDepth) {
279
280
  const nestedSteps = child.steps?.map((step, stepIndex) => projectStep(step, stepIndex, depth + 1, ctx)) ?? [];
280
281
  const nestedChildren = child.children?.map((nested, childIndex) => projectNestedRun(nested, childIndex, depth + 1, ctx)) ?? [];
281
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
282
+ const bounded: AsyncStatusSnapshotNode[] = [];
282
283
  appendBoundedChildren(bounded, [...nestedSteps, ...nestedChildren], ctx);
283
284
  if (bounded.length) node.children = bounded;
284
285
  } else {
@@ -295,11 +296,11 @@ function hostStepSnapshotState(state: HostStepState, verdict: HostStepVerdict |
295
296
  return verdict === undefined || verdict === "inconclusive" ? "partial" : "complete";
296
297
  }
297
298
 
298
- function projectHostStep(hostStep: HostStepNodeV1, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
299
+ function projectHostStep(hostStep: HostStepNode, ctx: ProjectionContext): AsyncStatusSnapshotNode {
299
300
  const state = hostStepSnapshotState(hostStep.state, hostStep.verdict);
300
301
  const detail = publicOptionalText(hostStep.detail, ctx.caps.maxStringLength);
301
302
  const report = publicOptionalText(hostStepReportName(hostStep.reportPath), ctx.caps.maxStringLength);
302
- const hostMetadata: AsyncStatusSnapshotHostStepV1 = {
303
+ const hostMetadata: AsyncStatusSnapshotHostStep = {
303
304
  kind: hostStep.monitorKind,
304
305
  state: hostStep.state,
305
306
  ...(hostStep.provider ? { provider: publicText(hostStep.provider, "provider", ctx.caps.maxStringLength) } : {}),
@@ -322,12 +323,91 @@ function projectHostStep(hostStep: HostStepNodeV1, ctx: ProjectionContext): Asyn
322
323
  };
323
324
  }
324
325
 
325
- function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnapshotNodeV1 {
326
+ type MaterializedChildren = Map<string, AsyncJobState[]>;
327
+
328
+ function asyncJobOrder(left: AsyncJobState, right: AsyncJobState): number {
329
+ const leftRank = left.status === "running" ? 0 : left.status === "queued" ? 1 : 2;
330
+ const rightRank = right.status === "running" ? 0 : right.status === "queued" ? 1 : 2;
331
+ const leftTime = left.updatedAt ?? left.startedAt ?? 0;
332
+ const rightTime = right.updatedAt ?? right.startedAt ?? 0;
333
+ return leftRank - rightRank || rightTime - leftTime || left.asyncId.localeCompare(right.asyncId);
334
+ }
335
+
336
+ function hasCyclicWorkflowParent(job: AsyncJobState, parents: ReadonlyMap<string, AsyncJobState>): boolean {
337
+ const seen = new Set([job.asyncId]);
338
+ let parentId = job.parentWorkflowRunId;
339
+ while (parentId) {
340
+ if (seen.has(parentId)) return true;
341
+ seen.add(parentId);
342
+ parentId = parents.get(parentId)?.parentWorkflowRunId;
343
+ }
344
+ return false;
345
+ }
346
+
347
+ function groupMaterializedChildren(jobs: readonly AsyncJobState[]) {
348
+ const parents = new Map(jobs.filter((job) => job.mode === "workflow").map((job) => [job.asyncId, job]));
349
+ const childrenByParent: MaterializedChildren = new Map();
350
+ const liveRoots = new Set<AsyncJobState>();
351
+ const roots: AsyncJobState[] = [];
352
+ for (const job of jobs) {
353
+ const parent = job.parentWorkflowRunId ? parents.get(job.parentWorkflowRunId) : undefined;
354
+ const keepLiveRoot = (job.status === "running" || job.status === "queued") && parent?.status !== "running";
355
+ if (parent && !hasCyclicWorkflowParent(job, parents)) {
356
+ const siblings = childrenByParent.get(parent.asyncId) ?? [];
357
+ siblings.push(job);
358
+ childrenByParent.set(parent.asyncId, siblings);
359
+ if (keepLiveRoot) {
360
+ liveRoots.add(job);
361
+ roots.push(job);
362
+ }
363
+ } else {
364
+ roots.push(job);
365
+ }
366
+ }
367
+ for (const children of childrenByParent.values()) children.sort(asyncJobOrder);
368
+ return { roots, childrenByParent, liveRoots };
369
+ }
370
+
371
+ function assignMaterializedChildren(steps: readonly AsyncJobStep[], children: readonly AsyncJobState[]): Map<AsyncJobStep, AsyncJobState> {
372
+ const assigned = new Map<AsyncJobStep, AsyncJobState>();
373
+ const claimed = new Set<AsyncJobState>();
374
+ for (const step of steps) {
375
+ if (!step.runId) continue;
376
+ const child = children.find((candidate) => !claimed.has(candidate) && candidate.asyncId === step.runId);
377
+ if (child) {
378
+ assigned.set(step, child);
379
+ claimed.add(child);
380
+ }
381
+ }
382
+ for (const step of steps) {
383
+ if (assigned.has(step) || !step.workflowKey) continue;
384
+ const child = children.find((candidate) => !claimed.has(candidate) && candidate.workflowKey === step.workflowKey);
385
+ if (child) {
386
+ assigned.set(step, child);
387
+ claimed.add(child);
388
+ }
389
+ }
390
+ return assigned;
391
+ }
392
+
393
+ function projectMaterializedStep(step: AsyncJobStep, index: number, child: AsyncJobState, depth: number, ctx: ProjectionContext, childrenByParent: MaterializedChildren, liveRoots: ReadonlySet<AsyncJobState>): AsyncStatusSnapshotNode {
394
+ const { id, label } = stepIdentity(step, index, ctx);
395
+ const selfStep = child.mode === undefined || child.mode === "single" ? child.steps?.[0] : undefined;
396
+ const live = projectRun(child, ctx, depth, childrenByParent, liveRoots, selfStep !== undefined);
397
+ const laneActivity = activityFor(step, ctx);
398
+ const selfActivity = selfStep ? activityFor(selfStep, ctx) : undefined;
399
+ const activity = laneActivity || selfActivity || live.activity ? { ...laneActivity, ...selfActivity, ...live.activity } : undefined;
400
+ const node: AsyncStatusSnapshotNode = { ...live, id, kind: "step", label };
401
+ if (activity) node.activity = activity;
402
+ return node;
403
+ }
404
+
405
+ function projectRun(job: AsyncJobState, ctx: ProjectionContext, depth: number, childrenByParent: MaterializedChildren, liveRoots: ReadonlySet<AsyncJobState>, omitSteps = false): AsyncStatusSnapshotNode {
326
406
  const state = normalizeState(job.status);
327
407
  const startedAt = publicTime(job.startedAt);
328
408
  const updatedAt = publicTime(job.updatedAt) ?? startedAt;
329
409
  const activity = activityFor(job, ctx);
330
- const node: AsyncStatusSnapshotNodeV1 = {
410
+ const node: AsyncStatusSnapshotNode = {
331
411
  id: publicText(job.asyncId, "async", ctx.caps.maxStringLength),
332
412
  kind: kindForMode(job.mode),
333
413
  label: labelForAgents(job.agents, job.mode ?? "subagent", ctx.caps.maxStringLength),
@@ -337,36 +417,51 @@ function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnap
337
417
  ...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
338
418
  ...(activity ? { activity } : {}),
339
419
  };
340
- if (ctx.caps.maxDepth > 0) {
341
- const stepChildren = job.steps?.map((step, index) => projectStep(step, step.index ?? index, 1, ctx)) ?? [];
342
- const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
343
- const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
344
- const graphChildren = graphStages
345
- .filter((graphNode) => !loadedKeys.has(graphNode.id))
346
- .map((graphNode, index) => projectWorkflowGraphNode(graphNode, index, 1, ctx));
347
- const nestedChildren = job.nestedChildren?.map((child, index) => projectNestedRun(child, index, 1, ctx)) ?? [];
420
+ const steps = omitSteps ? [] : job.steps ?? [];
421
+ const materialized = childrenByParent.get(job.asyncId) ?? [];
422
+ const nestedSummaries = (job.nestedChildren ?? []).filter((child) => !materialized.some((live) => live.asyncId === child.id));
423
+ const loadedKeys = new Set(steps.flatMap((step) => step.workflowKey ? [step.workflowKey] : []));
424
+ const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph).filter((graphNode) => !loadedKeys.has(graphNode.id)) : [];
425
+ const graphSteps = graphStages.map((node, index) => ({
426
+ step: { agent: node.agent ?? node.label, status: workflowGraphStepStatus(node.status), workflowKey: node.id, label: node.label },
427
+ index: node.flatIndex ?? index,
428
+ }));
429
+ const lanes = [...steps, ...graphSteps.map(({ step }) => step)];
430
+ const assigned = assignMaterializedChildren(lanes, materialized);
431
+ const claimed = new Set(assigned.values());
432
+ if (depth < ctx.caps.maxDepth) {
433
+ const childDepth = depth + 1;
434
+ const projectLane = (step: AsyncJobStep, index: number): AsyncStatusSnapshotNode | undefined => {
435
+ const child = assigned.get(step);
436
+ if (!child) return projectStep(step, index, childDepth, ctx);
437
+ if (liveRoots.has(child)) return undefined;
438
+ return projectMaterializedStep(step, index, child, childDepth, ctx, childrenByParent, liveRoots);
439
+ };
440
+ const stepChildren = steps.map((step, index) => projectLane(step, step.index ?? index)).filter((child): child is AsyncStatusSnapshotNode => child !== undefined);
441
+ const graphChildren = graphSteps.map(({ step, index }) => projectLane(step, index)).filter((child): child is AsyncStatusSnapshotNode => child !== undefined);
442
+ const nestedChildren = nestedSummaries.map((child, index) => projectNestedRun(child, index, childDepth, ctx));
443
+ const unclaimedChildren = materialized.filter((child) => !claimed.has(child) && !liveRoots.has(child)).map((child) => projectRun(child, ctx, childDepth, childrenByParent, liveRoots));
348
444
  const hostStepChildren = validHostStepList(job.hostSteps).map((hostStep) => projectHostStep(hostStep, ctx));
349
- const ordinaryChildren = [...stepChildren, ...graphChildren, ...nestedChildren];
445
+ const ordinaryChildren = [...stepChildren, ...graphChildren, ...nestedChildren, ...unclaimedChildren];
350
446
  const retainedHostSteps = hostStepChildren.slice(0, ctx.caps.maxChildrenPerNode);
351
447
  const retainedOrdinaryChildren = ordinaryChildren.slice(0, ctx.caps.maxChildrenPerNode - retainedHostSteps.length);
352
- const bounded: AsyncStatusSnapshotNodeV1[] = [];
448
+ const bounded: AsyncStatusSnapshotNode[] = [];
353
449
  bounded.push(...retainedOrdinaryChildren, ...retainedHostSteps);
354
450
  ctx.omitted.children += ordinaryChildren.length - retainedOrdinaryChildren.length + hostStepChildren.length - retainedHostSteps.length;
355
451
  if (bounded.length) node.children = bounded;
356
452
  } else {
357
- const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
358
- const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
359
- const graphCount = graphStages.filter((graphNode) => !loadedKeys.has(graphNode.id)).length;
360
- ctx.omitted.children += (job.steps?.length ?? 0) + graphCount + (job.nestedChildren?.length ?? 0) + validHostStepList(job.hostSteps).length;
453
+ const rootAssignments = [...assigned.values()].filter((child) => liveRoots.has(child)).length;
454
+ const unclaimedChildren = materialized.filter((child) => !claimed.has(child) && !liveRoots.has(child)).length;
455
+ ctx.omitted.children += lanes.length - rootAssignments + nestedSummaries.length + unclaimedChildren + validHostStepList(job.hostSteps).length;
361
456
  }
362
457
  return node;
363
458
  }
364
459
 
365
- function snapshotBytes(snapshot: AsyncStatusSnapshotV1): number {
460
+ function snapshotBytes(snapshot: AsyncStatusSnapshot): number {
366
461
  return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
367
462
  }
368
463
 
369
- function enforceByteLimit(snapshot: AsyncStatusSnapshotV1): void {
464
+ function enforceByteLimit(snapshot: AsyncStatusSnapshot): void {
370
465
  if (snapshotBytes(snapshot) <= snapshot.caps.maxSerializedBytes) return;
371
466
  snapshot.omitted.byteLimitExceeded = true;
372
467
  const runs = snapshot.runs;
@@ -401,7 +496,7 @@ function workflowStepName(step: AsyncJobStep, index: number): string {
401
496
  return `${phase}${key}${label} (${step.agent})`;
402
497
  }
403
498
 
404
- function hostStepRow(hostStep: HostStepNodeV1): AsyncStatusWorkflowRow {
499
+ function hostStepRow(hostStep: HostStepNode): AsyncStatusWorkflowRow {
405
500
  const freshness = hostStep.freshness
406
501
  ? {
407
502
  expectedRef: publicText(hostStep.freshness.expectedRef, "ref", HOST_STEP_MAX_REF_CHARS),
@@ -425,11 +520,11 @@ function hostStepRow(hostStep: HostStepNodeV1): AsyncStatusWorkflowRow {
425
520
  }
426
521
 
427
522
 
428
- function isWorkflowPreflight(value: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1 | undefined): value is WorkflowPreflightV1 {
523
+ function isWorkflowPreflight(value: readonly HostStepNode[] | WorkflowGraphSnapshot | WorkflowPreflight | undefined): value is WorkflowPreflight {
429
524
  return value !== undefined && !Array.isArray(value) && "lanes" in value;
430
525
  }
431
526
 
432
- function isWorkflowGraph(value: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1 | undefined): value is WorkflowGraphSnapshot {
527
+ function isWorkflowGraph(value: readonly HostStepNode[] | WorkflowGraphSnapshot | WorkflowPreflight | undefined): value is WorkflowGraphSnapshot {
433
528
  return value !== undefined && !Array.isArray(value) && "nodes" in value;
434
529
  }
435
530
 
@@ -465,7 +560,7 @@ function workflowGraphRowName(node: WorkflowGraphSnapshot["nodes"][number]): str
465
560
  return `${phase ? `${phase}: ` : ""}${key}${label && label !== node.id ? ` · ${label}` : ""}${agent ? ` (${agent})` : ""}`;
466
561
  }
467
562
 
468
- function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], preflight?: WorkflowPreflightLaneV1): AsyncStatusWorkflowRow {
563
+ function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], preflight?: WorkflowPreflightLane): AsyncStatusWorkflowRow {
469
564
  return {
470
565
  name: workflowGraphRowName(node),
471
566
  state: workflowGraphRowState(node.status),
@@ -476,14 +571,14 @@ function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], p
476
571
  /** Project authoritative workflow facts into compact rows, annotated by preflight hints. */
477
572
  export function projectAsyncWorkflowRows(
478
573
  steps: readonly AsyncJobStep[] | undefined,
479
- hostStepsOrPreflight?: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1,
480
- preflightOverride?: WorkflowPreflightV1,
574
+ hostStepsOrPreflight?: readonly HostStepNode[] | WorkflowGraphSnapshot | WorkflowPreflight,
575
+ preflightOverride?: WorkflowPreflight,
481
576
  ): AsyncStatusWorkflowRow[] {
482
577
  const preflight = preflightOverride ?? (isWorkflowPreflight(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined);
483
578
  const graph = isWorkflowGraph(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined;
484
579
  const hostSteps = isWorkflowPreflight(hostStepsOrPreflight) || graph ? undefined : hostStepsOrPreflight;
485
580
  const loaded = steps ?? [];
486
- const preflightForKey = (key: string, groupKeys: readonly (string | undefined)[] = []): WorkflowPreflightLaneV1 | undefined =>
581
+ const preflightForKey = (key: string, groupKeys: readonly (string | undefined)[] = []): WorkflowPreflightLane | undefined =>
487
582
  workflowPreflightLaneForRuntimeKey(preflight, key, groupKeys);
488
583
  if (graph) {
489
584
  const loadedIndexesByKey = new Map<string, number[]>();
@@ -526,7 +621,7 @@ export function projectAsyncWorkflowRows(
526
621
  ];
527
622
  }
528
623
 
529
- function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?: WorkflowPreflightLaneV1): AsyncStatusWorkflowRow {
624
+ function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?: WorkflowPreflightLane): AsyncStatusWorkflowRow {
530
625
  const modelThinking = formatModelThinking(step.model, step.thinking) || undefined;
531
626
  const activity = workflowStepActivity(step);
532
627
  return {
@@ -536,6 +631,8 @@ function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?:
536
631
  ...(modelThinking ? { modelThinking } : {}),
537
632
  ...(activity ? { activity } : {}),
538
633
  ...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
634
+ ...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
635
+ ...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
539
636
  ...(step.tokens?.total !== undefined ? { tokens: step.tokens.total } : {}),
540
637
  ...(step.tokens?.window !== undefined ? { window: step.tokens.window } : {}),
541
638
  ...(preflight ? { preflight } : {}),
@@ -543,22 +640,19 @@ function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?:
543
640
  }
544
641
 
545
642
  /** Project already-loaded async status facts into the bounded public snapshot shape. */
546
- export function projectAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
643
+ export function projectAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshot {
547
644
  const caps = resolveCaps(options);
548
645
  const ctx: ProjectionContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
549
- const sorted = [...jobs].sort((left, right) => {
550
- const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
551
- const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
552
- return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
553
- });
646
+ const { roots, childrenByParent, liveRoots } = groupMaterializedChildren([...jobs]);
647
+ const sorted = roots.sort(asyncJobOrder);
554
648
  ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
555
- const snapshot: AsyncStatusSnapshotV1 = {
649
+ const snapshot: AsyncStatusSnapshot = {
556
650
  kind: ASYNC_STATUS_SNAPSHOT_KIND,
557
651
  version: ASYNC_STATUS_SNAPSHOT_VERSION,
558
652
  generatedAt: options.generatedAt ?? Date.now(),
559
653
  caps,
560
654
  omitted: ctx.omitted,
561
- runs: sorted.slice(0, caps.maxRuns).map((job) => projectRun(job, ctx)),
655
+ runs: sorted.slice(0, caps.maxRuns).map((job) => projectRun(job, ctx, 0, childrenByParent, liveRoots)),
562
656
  };
563
657
  enforceByteLimit(snapshot);
564
658
  return snapshot;
@@ -29,6 +29,8 @@ export interface SubagentCapabilityAudit {
29
29
  effectiveMcpTools: string[];
30
30
  agentAllowed: boolean;
31
31
  agentRestrictionSources?: string[];
32
+ /** Builtin tools declared but unavailable on the host runtime. */
33
+ unavailableHostBuiltins?: string[];
32
34
  }
33
35
 
34
36
  export interface RegisterSubagentCapabilityCeilingOptions {