@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -16,20 +16,11 @@ import {
16
16
  type SubagentRunMode,
17
17
  type SubagentState,
18
18
  } from "../../shared/types.ts";
19
- import { isSafeNestedPathId, parseNestedPathEnv, sanitizeNestedPath, type NestedPathEntry } from "./nested-path.ts";
20
- import {
21
- SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV,
22
- SUBAGENT_PARENT_CHILD_INDEX_ENV,
23
- SUBAGENT_PARENT_CONTROL_INBOX_ENV,
24
- SUBAGENT_PARENT_DEPTH_ENV,
25
- SUBAGENT_PARENT_EVENT_SINK_ENV,
26
- SUBAGENT_PARENT_PATH_ENV,
27
- SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
28
- SUBAGENT_PARENT_RUN_ID_ENV,
29
- } from "./pi-args.ts";
19
+ import { isSafeNestedPathId, sanitizeNestedPath, type NestedPathEntry } from "./nested-path.ts";
30
20
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
31
21
  import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
32
22
  import { THINKING_LEVELS } from "../../shared/model-info.ts";
23
+ import { validateSandboxProfileName } from "../../shared/sandbox-profile.ts";
33
24
 
34
25
  export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
35
26
  const ROUTE_FILE = "route.json";
@@ -141,40 +132,60 @@ export function createNestedRoute(rootRunId: string): NestedRoute {
141
132
  return { rootRunId, eventSink, controlInbox, capabilityToken };
142
133
  }
143
134
 
144
- export function resolveNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
145
- const rootRunId = env[SUBAGENT_PARENT_ROOT_RUN_ID_ENV];
146
- const eventSink = env[SUBAGENT_PARENT_EVENT_SINK_ENV];
147
- const controlInbox = env[SUBAGENT_PARENT_CONTROL_INBOX_ENV];
148
- const capabilityToken = env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV];
149
- if (!rootRunId || !eventSink || !controlInbox || !capabilityToken) return undefined;
150
- const route = { rootRunId, eventSink, controlInbox, capabilityToken };
135
+ /** Validate a route handed to an in-process child against its on-disk metadata. */
136
+ export function resolveNestedRoute(route: NestedRoute): NestedRoute {
137
+ const { rootRunId, capabilityToken } = route;
151
138
  validateRouteShape(route);
152
139
  const routeFile = path.join(commonRouteRoot(route), ROUTE_FILE);
153
- const metadata = JSON.parse(fs.readFileSync(routeFile, "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
140
+ let metadata: { rootRunId?: unknown; capabilityToken?: unknown };
141
+ try {
142
+ const parsed: unknown = JSON.parse(fs.readFileSync(routeFile, "utf-8"));
143
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
144
+ throw new Error("route metadata must be an object");
145
+ }
146
+ metadata = parsed as { rootRunId?: unknown; capabilityToken?: unknown };
147
+ } catch (error) {
148
+ const message = error instanceof Error ? error.message : String(error);
149
+ throw new Error(`Nested event route metadata is unreadable: ${message}`);
150
+ }
154
151
  if (metadata.rootRunId !== rootRunId || metadata.capabilityToken !== capabilityToken) {
155
152
  throw new Error("Nested event route metadata does not match the provided root id and capability token.");
156
153
  }
157
154
  return route;
158
155
  }
159
156
 
160
- export function resolveInheritedNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
157
+ export function resolveInheritedNestedRoute(route: NestedRoute): NestedRoute | undefined {
161
158
  try {
162
- return resolveNestedRouteFromEnv(env);
159
+ return resolveNestedRoute(route);
163
160
  } catch (error) {
164
161
  console.error("Ignoring invalid nested subagent event route:", error);
165
162
  return undefined;
166
163
  }
167
164
  }
168
165
 
169
- export function resolveNestedParentAddressFromEnv(env: NodeJS.ProcessEnv = process.env): { parentRunId: string; parentStepIndex?: number; depth: number; path: NestedPathEntry[] } | undefined {
170
- const parentRunId = env[SUBAGENT_PARENT_RUN_ID_ENV];
171
- if (!isSafeNestedId(parentRunId)) return undefined;
172
- const rawIndex = env[SUBAGENT_PARENT_CHILD_INDEX_ENV];
173
- const parentStepIndex = rawIndex && /^\d+$/.test(rawIndex) ? Number(rawIndex) : undefined;
174
- const depth = Math.min(Math.max(1, clampNumber(Number(env[SUBAGENT_PARENT_DEPTH_ENV])) ?? 1), MAX_DEPTH);
175
- const parsedPath = parseNestedPathEnv(env[SUBAGENT_PARENT_PATH_ENV]);
176
- const nestedPath = parsedPath.length ? parsedPath : [{ runId: parentRunId, ...(parentStepIndex !== undefined ? { stepIndex: parentStepIndex } : {}) }];
177
- return { parentRunId, ...(parentStepIndex !== undefined ? { parentStepIndex } : {}), depth, path: nestedPath };
166
+ export interface NestedParentAddress {
167
+ parentRunId: string;
168
+ parentStepIndex?: number;
169
+ depth: number;
170
+ path: NestedPathEntry[];
171
+ }
172
+
173
+ /** The nested route an executor inherited from its own child runtime, validated against disk. */
174
+ export function inheritedNestedRouteOf(runtime: { nestedRoute?: NestedRoute } | undefined): NestedRoute | undefined {
175
+ return runtime?.nestedRoute ? resolveInheritedNestedRoute(runtime.nestedRoute) : undefined;
176
+ }
177
+
178
+ /** The executor's own position in the nested run tree, from its child runtime. */
179
+ export function inheritedNestedParentAddressOf(runtime: { nestedParent?: { parentRunId: string; parentChildIndex?: number; depth: number; path: NestedPathEntry[] } } | undefined): NestedParentAddress | undefined {
180
+ const parent = runtime?.nestedParent;
181
+ if (!parent || !isSafeNestedId(parent.parentRunId)) return undefined;
182
+ const depth = Math.min(Math.max(1, clampNumber(parent.depth) ?? 1), MAX_DEPTH);
183
+ return {
184
+ parentRunId: parent.parentRunId,
185
+ ...(parent.parentChildIndex !== undefined ? { parentStepIndex: parent.parentChildIndex } : {}),
186
+ depth,
187
+ path: parent.path.length ? parent.path : [{ runId: parent.parentRunId, ...(parent.parentChildIndex !== undefined ? { stepIndex: parent.parentChildIndex } : {}) }],
188
+ };
178
189
  }
179
190
 
180
191
  export function resolveNestedAsyncDir(rootRunId: string, run: NestedRunSummary): string | undefined {
@@ -199,8 +210,10 @@ function sanitizeTokenUsage(value: unknown): NestedRunSummary["totalTokens"] | u
199
210
  const input = clampNumber(raw.input);
200
211
  const output = clampNumber(raw.output);
201
212
  const total = clampNumber(raw.total);
213
+ const window = clampNumber(raw.window);
214
+ const windowPeak = clampNumber(raw.windowPeak);
202
215
  return input !== undefined && output !== undefined && total !== undefined
203
- ? { input, output, total }
216
+ ? { input, output, total, ...(window !== undefined ? { window } : {}), ...(windowPeak !== undefined ? { windowPeak } : {}) }
204
217
  : undefined;
205
218
  }
206
219
 
@@ -284,11 +297,19 @@ function sanitizeTurnBudget(value: unknown): TurnBudgetState | undefined {
284
297
  }
285
298
 
286
299
  function sanitizeState(value: unknown, fallback: NestedRunState): NestedRunState {
287
- return value === "queued" || value === "running" || value === "complete" || value === "failed" || value === "paused" || value === "stopped"
300
+ return value === "queued" || value === "running" || value === "complete" || value === "failed" || value === "partial" || value === "paused" || value === "stopped"
288
301
  ? value
289
302
  : fallback;
290
303
  }
291
304
 
305
+ function sandboxProfileValue(value: unknown): string | undefined {
306
+ try {
307
+ return validateSandboxProfileName(value);
308
+ } catch {
309
+ return undefined;
310
+ }
311
+ }
312
+
292
313
  function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefined {
293
314
  if (!input || typeof input !== "object") return undefined;
294
315
  const raw = input as Record<string, unknown>;
@@ -299,11 +320,14 @@ function sanitizeStep(input: unknown, depth: number): NestedStepSummary | undefi
299
320
  : "pending";
300
321
  const model = stringValue(raw.model);
301
322
  const thinking = THINKING_LEVELS.find((level) => level === raw.thinking);
323
+ const sandbox = sandboxProfileValue(raw.sandbox);
302
324
  return {
303
325
  agent,
304
326
  status,
305
327
  ...(model ? { model } : {}),
306
328
  ...(thinking ? { thinking } : {}),
329
+ ...(stringValue(raw.sessionName, 256) ? { sessionName: stringValue(raw.sessionName, 256) } : {}),
330
+ ...(sandbox ? { sandbox } : {}),
307
331
  ...(stringValue(raw.sessionFile, 2048) ? { sessionFile: stringValue(raw.sessionFile, 2048) } : {}),
308
332
  ...(raw.activityState === "active_long_running" || raw.activityState === "needs_attention" ? { activityState: raw.activityState } : {}),
309
333
  ...(clampNumber(raw.lastActivityAt) !== undefined ? { lastActivityAt: clampNumber(raw.lastActivityAt) } : {}),
@@ -336,6 +360,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
336
360
  : undefined;
337
361
  const totalTokens = sanitizeTokenUsage(raw.totalTokens);
338
362
  const totalCost = sanitizeCost(raw.totalCost);
363
+ const sandbox = sandboxProfileValue(raw.sandbox);
339
364
  return {
340
365
  id: raw.id,
341
366
  parentRunId: raw.parentRunId,
@@ -344,6 +369,7 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
344
369
  depth: Math.min(Math.max(0, clampNumber(raw.depth) ?? 0), MAX_DEPTH),
345
370
  path: pathParts,
346
371
  state: sanitizeState(raw.state, "running"),
372
+ ...(stringValue(raw.sessionName, 256) ? { sessionName: stringValue(raw.sessionName, 256) } : {}),
347
373
  ...(stringValue(raw.model) ? { model: stringValue(raw.model) } : {}),
348
374
  ...(THINKING_LEVELS.find((level) => level === raw.thinking) ? { thinking: THINKING_LEVELS.find((level) => level === raw.thinking) } : {}),
349
375
  ...(stringValue(raw.asyncDir, 2048) ? { asyncDir: stringValue(raw.asyncDir, 2048) } : {}),
@@ -358,7 +384,9 @@ export function sanitizeSummary(input: unknown, depth = 0): NestedRunSummary | u
358
384
  ...(stringValue(raw.capabilityToken, 128) ? { capabilityToken: stringValue(raw.capabilityToken, 128) } : {}),
359
385
  ...(raw.mode === "single" || raw.mode === "parallel" || raw.mode === "chain" ? { mode: raw.mode } : {}),
360
386
  ...(stringValue(raw.agent, 128) ? { agent: stringValue(raw.agent, 128) } : {}),
387
+ ...(sandbox ? { sandbox } : {}),
361
388
  ...(Array.isArray(raw.agents) ? { agents: raw.agents.map((agent) => stringValue(agent, 128)).filter((agent): agent is string => Boolean(agent)).slice(0, MAX_STEPS) } : {}),
389
+
362
390
  ...(clampNumber(raw.currentStep) !== undefined ? { currentStep: clampNumber(raw.currentStep) } : {}),
363
391
  ...(clampNumber(raw.chainStepCount) !== undefined ? { chainStepCount: clampNumber(raw.chainStepCount) } : {}),
364
392
  ...(raw.activityState === "active_long_running" || raw.activityState === "needs_attention" ? { activityState: raw.activityState } : {}),
@@ -434,7 +462,7 @@ export function parseNestedEventRecords(content: string, route: NestedRoute): Ne
434
462
  }
435
463
 
436
464
  function terminal(state: NestedRunState): boolean {
437
- return state === "complete" || state === "failed" || state === "paused" || state === "stopped";
465
+ return state === "complete" || state === "failed" || state === "partial" || state === "paused" || state === "stopped";
438
466
  }
439
467
 
440
468
  function mergeBoundedChildren(existing: NestedRunSummary[] | undefined, incoming: NestedRunSummary[] | undefined): NestedRunSummary[] | undefined {
@@ -764,7 +792,7 @@ export function projectNestedEvents(route: NestedRoute): NestedRegistry {
764
792
  return registry;
765
793
  }
766
794
 
767
- function writeRouteRecord(dir: string, ts: number, payload: object): string {
795
+ function writeRouteRecord<T extends object>(dir: string, ts: number, payload: T): string {
768
796
  const content = `${JSON.stringify(payload)}\n`;
769
797
  if (Buffer.byteLength(content, "utf-8") > MAX_EVENT_BYTES) throw new Error("Nested route record exceeds the maximum size.");
770
798
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -943,15 +971,6 @@ export function readNestedControlResults(route: NestedRoute): NestedControlResul
943
971
  .flatMap((entry) => readControlResultsFromFile(route, path.join(route.eventSink, entry)));
944
972
  }
945
973
 
946
- export function nestedRouteEnv(route: NestedRoute): Record<string, string> {
947
- return {
948
- [SUBAGENT_PARENT_EVENT_SINK_ENV]: route.eventSink,
949
- [SUBAGENT_PARENT_CONTROL_INBOX_ENV]: route.controlInbox,
950
- [SUBAGENT_PARENT_ROOT_RUN_ID_ENV]: route.rootRunId,
951
- [SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]: route.capabilityToken,
952
- };
953
- }
954
-
955
974
  export function attachRootChildrenToSteps<T extends { children?: NestedRunSummary[]; index?: number }>(rootRunId: string, steps: T[] | undefined, children: NestedRunSummary[] | undefined): void {
956
975
  if (!steps?.length) return;
957
976
  for (const step of steps) {
@@ -991,6 +1010,7 @@ export function hasLiveNestedDescendants(children: NestedRunSummary[] | undefine
991
1010
  }
992
1011
 
993
1012
  export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: string, fallback: { id: string; parentRunId: string; parentStepIndex?: number; depth: number; path?: Array<{ runId: string; stepIndex?: number; agent?: string }>; mode?: SubagentRunMode; ts: number }): NestedRunSummary {
1013
+ const sandbox = sandboxProfileValue(status.sandbox);
994
1014
  return {
995
1015
  id: status.runId || fallback.id,
996
1016
  parentRunId: fallback.parentRunId,
@@ -1001,8 +1021,10 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
1001
1021
  ...(status.pid ? { pid: status.pid } : {}),
1002
1022
  ...(status.sessionId ? { sessionId: status.sessionId } : {}),
1003
1023
  mode: status.mode ?? fallback.mode,
1024
+ ...(sandbox ? { sandbox } : {}),
1004
1025
  ...(status.steps?.length === 1 && status.steps[0]?.model ? { model: status.steps[0].model } : {}),
1005
1026
  ...(status.steps?.length === 1 && status.steps[0]?.thinking ? { thinking: status.steps[0].thinking } : {}),
1027
+ ...(status.steps?.length === 1 && status.steps[0]?.sessionName ? { sessionName: status.steps[0].sessionName } : {}),
1006
1028
  ...(status.processTerminal ? { processTerminal: sanitizeProcessTerminal(status.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: status.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json`) } : {}),
1007
1029
  ...(status.launchResolvedExtensions ? { launchResolvedExtensions: status.launchResolvedExtensions } : {}),
1008
1030
  ...runtimeAcknowledgedEntry(status.runtimeAcknowledgedExtensions),
@@ -1031,40 +1053,40 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
1031
1053
  ...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
1032
1054
  lastUpdate: status.lastUpdate ?? fallback.ts,
1033
1055
  ...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
1034
- ...(status.steps?.length ? { steps: status.steps.map((step, index) => ({
1035
- agent: step.agent,
1036
- status: step.status,
1037
- ...(step.model ? { model: step.model } : {}),
1038
- ...(step.thinking ? { thinking: step.thinking } : {}),
1039
- ...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
1040
- ...(step.activityState ? { activityState: step.activityState } : {}),
1041
- ...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
1042
- ...(step.currentTool ? { currentTool: step.currentTool } : {}),
1043
- ...(step.currentToolStartedAt !== undefined ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
1044
- ...(step.currentPath ? { currentPath: step.currentPath } : {}),
1045
- ...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
1046
- ...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
1047
- ...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
1048
- ...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
1049
- ...(step.error ? { error: step.error } : {}),
1050
- ...(step.launchResolvedExtensions ? { launchResolvedExtensions: step.launchResolvedExtensions } : {}),
1051
- ...runtimeAcknowledgedEntry(step.runtimeAcknowledgedExtensions),
1052
- ...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
1053
- ...(step.stopped !== undefined ? { stopped: step.stopped } : {}),
1054
- ...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
1055
- ...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
1056
- ...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
1057
- ...(step.processTerminal ? { processTerminal: sanitizeProcessTerminal(step.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: step.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json step ${index}`) } : {}),
1058
- ...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
1059
- ...(step.capabilityAudit ? { capabilityAudit: step.capabilityAudit } : {}),
1060
- })).slice(0, MAX_STEPS) } : {}),
1061
- };
1062
- }
1063
-
1064
- export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Record<string, string> {
1065
- return {
1066
- PI_SUBAGENT_NESTED_ROOT_RUN_ID: rootRunId,
1067
- PI_SUBAGENT_NESTED_PARENT_RUN_ID: parentRunId,
1056
+ ...(status.steps?.length ? {
1057
+ steps: status.steps.map((step, index) => {
1058
+ const stepSandbox = sandboxProfileValue(step.sandbox);
1059
+ return {
1060
+ agent: step.agent,
1061
+ ...(step.sessionName ? { sessionName: step.sessionName } : {}),
1062
+ status: step.status,
1063
+ ...(step.model ? { model: step.model } : {}),
1064
+ ...(step.thinking ? { thinking: step.thinking } : {}),
1065
+ ...(stepSandbox ? { sandbox: stepSandbox } : {}),
1066
+ ...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
1067
+ ...(step.activityState ? { activityState: step.activityState } : {}),
1068
+ ...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
1069
+ ...(step.currentTool ? { currentTool: step.currentTool } : {}),
1070
+ ...(step.currentToolStartedAt !== undefined ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
1071
+ ...(step.currentPath ? { currentPath: step.currentPath } : {}),
1072
+ ...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
1073
+ ...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
1074
+ ...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
1075
+ ...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
1076
+ ...(step.error ? { error: step.error } : {}),
1077
+ ...(step.launchResolvedExtensions ? { launchResolvedExtensions: step.launchResolvedExtensions } : {}),
1078
+ ...runtimeAcknowledgedEntry(step.runtimeAcknowledgedExtensions),
1079
+ ...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
1080
+ ...(step.stopped !== undefined ? { stopped: step.stopped } : {}),
1081
+ ...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
1082
+ ...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
1083
+ ...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
1084
+ ...(step.processTerminal ? { processTerminal: sanitizeProcessTerminal(step.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: step.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json step ${index}`) } : {}),
1085
+ ...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
1086
+ ...(step.capabilityAudit ? { capabilityAudit: step.capabilityAudit } : {}),
1087
+ };
1088
+ }).slice(0, MAX_STEPS),
1089
+ } : {}),
1068
1090
  };
1069
1091
  }
1070
1092
 
@@ -36,17 +36,3 @@ export function sanitizeNestedPath(value: unknown): NestedPathEntry[] {
36
36
  };
37
37
  }).filter((part): part is NestedPathEntry => Boolean(part)).slice(0, MAX_NESTED_PATH_ENTRIES);
38
38
  }
39
-
40
- export function parseNestedPathEnv(value: string | undefined): NestedPathEntry[] {
41
- if (!value) return [];
42
- try {
43
- return sanitizeNestedPath(JSON.parse(value) as unknown);
44
- } catch {
45
- return [];
46
- }
47
- }
48
-
49
- export function encodeNestedPathEnv(value: NestedPathEntry[]): string {
50
- const sanitized = sanitizeNestedPath(value);
51
- return sanitized.length ? JSON.stringify(sanitized) : "";
52
- }
@@ -1,6 +1,6 @@
1
- import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
1
+ import { formatDuration, formatModelThinking, formatTokenUsage, shortenPath } from "../../shared/formatters.ts";
2
2
  import { formatActivityLabel } from "../../shared/status-format.ts";
3
- import type { ActivityState, NestedRunSummary, NestedStepSummary } from "../../shared/types.ts";
3
+ import type { ActivityState, NestedRunSummary } from "../../shared/types.ts";
4
4
 
5
5
  export interface NestedRunCounts {
6
6
  total: number;
@@ -8,13 +8,14 @@ export interface NestedRunCounts {
8
8
  paused: number;
9
9
  complete: number;
10
10
  failed: number;
11
+ partial: number;
11
12
  rejected: number;
12
13
  stopped: number;
13
14
  queued: number;
14
15
  }
15
16
 
16
17
  export function countNestedRuns(children: NestedRunSummary[] | undefined): NestedRunCounts {
17
- const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, rejected: 0, stopped: 0, queued: 0 };
18
+ const counts: NestedRunCounts = { total: 0, running: 0, paused: 0, complete: 0, failed: 0, partial: 0, rejected: 0, stopped: 0, queued: 0 };
18
19
  for (const child of children ?? []) {
19
20
  counts.total++;
20
21
  counts[child.state]++;
@@ -24,6 +25,7 @@ export function countNestedRuns(children: NestedRunSummary[] | undefined): Neste
24
25
  counts.paused += nested.paused;
25
26
  counts.complete += nested.complete;
26
27
  counts.failed += nested.failed;
28
+ counts.partial += nested.partial;
27
29
  counts.rejected += nested.rejected;
28
30
  counts.stopped += nested.stopped;
29
31
  counts.queued += nested.queued;
@@ -38,6 +40,7 @@ export function formatNestedAggregate(children: NestedRunSummary[] | undefined):
38
40
  counts.running > 0 ? `${counts.running} running` : "",
39
41
  counts.paused > 0 ? `${counts.paused} paused` : "",
40
42
  counts.failed > 0 ? `${counts.failed} failed` : "",
43
+ counts.partial > 0 ? `${counts.partial} partial` : "",
41
44
  counts.rejected > 0 ? `${counts.rejected} rejected` : "",
42
45
  counts.stopped > 0 ? `${counts.stopped} stopped` : "",
43
46
  counts.complete > 0 ? `${counts.complete} complete` : "",
@@ -47,6 +50,7 @@ export function formatNestedAggregate(children: NestedRunSummary[] | undefined):
47
50
  }
48
51
 
49
52
  function nestedRunLabel(run: NestedRunSummary): string {
53
+ if (run.sessionName?.trim()) return run.sessionName.trim();
50
54
  if (run.agent) return run.agent;
51
55
  if (run.agents?.length) return run.agents.length === 1 ? run.agents[0]! : `${run.agents.slice(0, 2).join(", ")}${run.agents.length > 2 ? ` +${run.agents.length - 2}` : ""}`;
52
56
  return run.id;
@@ -68,7 +72,7 @@ function formatNestedActivity(input: {
68
72
  if (input.currentPath) facts.push(shortenPath(input.currentPath));
69
73
  if (input.turnCount !== undefined) facts.push(`${input.turnCount} turns`);
70
74
  if (input.toolCount !== undefined) facts.push(`${input.toolCount} tools`);
71
- if (input.totalTokens) facts.push(`${formatTokens(input.totalTokens.total)} tok`);
75
+ if (input.totalTokens) facts.push(formatTokenUsage(input.totalTokens));
72
76
  const activity = formatActivityLabel(input.lastActivityAt, input.activityState as ActivityState | undefined);
73
77
  return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
74
78
  }
@@ -103,7 +107,7 @@ function formatNestedRunLines(children: NestedRunSummary[] | undefined, options:
103
107
  if (lines.length >= options.maxLines) return;
104
108
  const stepActivity = step.status === "running" ? formatNestedActivity(step) : undefined;
105
109
  const stepModelThinking = formatModelThinking(step.model, step.thinking);
106
- lines.push(`${indent} ${stepIndex + 1}. ${step.agent} ${step.status}${stepModelThinking ? ` | ${stepModelThinking}` : ""}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
110
+ lines.push(`${indent} ${stepIndex + 1}. ${step.sessionName?.trim() || step.agent} ${step.status}${stepModelThinking ? ` | ${stepModelThinking}` : ""}${stepActivity ? ` | ${stepActivity}` : ""}${step.error ? ` | error: ${step.error}` : ""}`);
107
111
  append(step.children, depth + 1, `${indent} `);
108
112
  }
109
113
  append(child.children, depth + 1, `${indent} `);
@@ -56,7 +56,8 @@ export interface OrcaProgressTab {
56
56
  append(text: string): void;
57
57
  section(input: { agent: string; index: number; count: number }): void;
58
58
  event(event: { type?: string; message?: Message; toolName?: string; args?: unknown }): void;
59
- finish(status: "completed" | "failed" | "stopped", sessionFile?: string): void;
59
+ /** Resolves once the mirrored log and its done marker are on disk, so a host may exit afterwards. */
60
+ finish(status: "completed" | "failed" | "stopped", sessionFile?: string): Promise<void>;
60
61
  }
61
62
 
62
63
  function executableFile(candidate: string): boolean {
@@ -475,7 +476,7 @@ export function createOrcaProgressTab(input: {
475
476
  }
476
477
  },
477
478
  finish(status, sessionFile) {
478
- if (!available || finished) return;
479
+ if (!available || finished) return Promise.resolve();
479
480
  finished = true;
480
481
  const sessionId = status === "completed" ? resolvePiSessionId(sessionFile) : undefined;
481
482
  let verifiedSessionFile: string | undefined;
@@ -488,11 +489,15 @@ export function createOrcaProgressTab(input: {
488
489
  const truncation = truncated ? `\n[progress mirror truncated at ${MAX_MIRROR_BYTES} bytes]\n` : "";
489
490
  let footer = `${truncation}\n${"─".repeat(48)}\n${terminalMessage}\n`;
490
491
  if (scheduledBytes + Buffer.byteLength(footer) > MAX_MIRROR_BYTES) footer = `\n${status}\n`;
491
- logStream.end(footer, () => {
492
- if (!available) return;
493
- try { fs.writeFileSync(donePath, `${status}\n`, { encoding: "utf-8", mode: 0o600 }); } catch { /* best effort */ }
494
- cleanupPaths = [logPath, donePath];
495
- scheduleDeferredCleanup();
492
+ return new Promise<void>((resolve) => {
493
+ logStream.end(footer, () => {
494
+ if (available) {
495
+ try { fs.writeFileSync(donePath, `${status}\n`, { encoding: "utf-8", mode: 0o600 }); } catch { /* best effort */ }
496
+ cleanupPaths = [logPath, donePath];
497
+ scheduleDeferredCleanup();
498
+ }
499
+ resolve();
500
+ });
496
501
  });
497
502
  },
498
503
  };