@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
@@ -267,6 +267,7 @@ function activeRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps
267
267
  resultsDir,
268
268
  kill: deps.kill,
269
269
  now: deps.now,
270
+ includeNested: false,
270
271
  ...(params.id ? { runId: params.id } : {}),
271
272
  });
272
273
  return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
@@ -286,6 +287,7 @@ function allRunsForSession(params: SubagentWaitParams, deps: SubagentWaitDeps):
286
287
  resultsDir,
287
288
  kill: deps.kill,
288
289
  now: deps.now,
290
+ includeNested: false,
289
291
  ...(params.id ? { runId: params.id } : {}),
290
292
  });
291
293
  return params.id ? runs.filter((run) => matchesId(run, params.id!)) : runs;
@@ -1,8 +1,8 @@
1
1
  import * as fs from "node:fs";
2
- import * as path from "node:path";
3
2
  import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
4
3
  import type { AsyncRunSummary } from "./async-status.ts";
5
4
  import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
5
+ import { resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
6
6
 
7
7
  function asNonEmptyString(value: unknown): string | undefined {
8
8
  return typeof value === "string" && value ? value : undefined;
@@ -114,7 +114,10 @@ export function collectWaitCompletions(terminal: AsyncRunSummary[], state: Subag
114
114
  completions.push(recorded.completion);
115
115
  continue;
116
116
  }
117
- const resultPath = path.join(resultsDir, `${run.id}.json`);
117
+ const publicResultPath = resultFilePath(resultsDir, run.id);
118
+ const resultPath = run.sessionId
119
+ ? resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id) ?? publicResultPath
120
+ : publicResultPath;
118
121
  try {
119
122
  const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
120
123
  completions.push(toWaitCompletion(raw, run.id));
@@ -6,6 +6,7 @@ import { DIRS, type Details, type SubagentState } from "../../shared/types.ts";
6
6
  import { readStatus } from "../../shared/utils.ts";
7
7
  import { updateActiveRunIndex } from "../background/active-run-index.ts";
8
8
  import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
9
+ import { resultFilePath } from "../background/result-files.ts";
9
10
 
10
11
  export function dismissRecoveredWorkflow(
11
12
  state: SubagentState,
@@ -50,7 +51,7 @@ export function dismissRecoveredWorkflow(
50
51
  };
51
52
  }
52
53
  let latestStatus = status;
53
- const resultPath = path.join(DIRS.results, `${status.runId}.json`);
54
+ const resultPath = resultFilePath(DIRS.results, status.runId);
54
55
  if (fs.existsSync(resultPath)) {
55
56
  const reconciled = reconcileAsyncRun(asyncDir).status;
56
57
  if (reconciled && reconciled.state !== "running") {
@@ -34,6 +34,7 @@ import {
34
34
  import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
35
35
  import { INTERCOM_BRIDGE_MARKER } from "../../intercom/intercom-bridge.ts";
36
36
  import { runSync } from "./execution.ts";
37
+ import { createTaskMutationArbiter } from "../shared/llm-intent-arbiter.ts";
37
38
  import { workflowForegroundSteeringLaunchOptions } from "./workflow-foreground-steering.ts";
38
39
  import {
39
40
  beginForegroundChild,
@@ -42,6 +43,7 @@ import {
42
43
  settleForegroundSchedulingOwner,
43
44
  updateForegroundChild,
44
45
  } from "./foreground-control.ts";
46
+ import { updateLiveEffectivePrompt } from "./prompt-audit.ts";
45
47
  import { buildChainSummary } from "../../shared/formatters.ts";
46
48
  import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, resolveChildCwd, sumResultsCost, sumResultsUsage } from "../../shared/utils.ts";
47
49
  import { DEFAULT_GLOBAL_CONCURRENCY_LIMIT, Semaphore } from "../shared/parallel-utils.ts";
@@ -71,6 +73,7 @@ import {
71
73
  type ResolvedControlConfig,
72
74
  type ResolvedTurnBudget,
73
75
  type ResolvedToolBudget,
76
+ type RunFanoutBudgetDescriptor,
74
77
  type SingleResult,
75
78
  type ToolBudgetConfig,
76
79
  type ChainCheckpointState,
@@ -86,6 +89,7 @@ import { ChainOutputValidationError, outputEntryFromResult, resolveOutputReferen
86
89
  import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
87
90
  import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection, type DynamicCollectedResult } from "../shared/dynamic-fanout.ts";
88
91
  import { acceptanceFailureMessage, aggregateAcceptanceReport, evaluateAcceptance, resolveEffectiveAcceptance } from "../shared/acceptance.ts";
92
+ import { claimRunFanoutBatch, RunFanoutLimitError } from "../shared/run-fanout-budget.ts";
89
93
  import { isAgentContractV1 } from "../shared/agent-contract.ts";
90
94
  import type { ChainOutputMap } from "../../shared/types.ts";
91
95
  import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
@@ -158,6 +162,8 @@ interface ParallelChainRunInput {
158
162
  nestedRoute?: NestedRouteInfo;
159
163
  timeoutMs?: number;
160
164
  deadlineAt?: number;
165
+ callToolTimeoutMs?: number;
166
+ configToolTimeoutMs?: number;
161
167
  turnBudget?: ResolvedTurnBudget;
162
168
  usageBudget?: UsageBudgetConfig;
163
169
  onDetachedExit?: (index: number, result: SingleResult) => void;
@@ -167,6 +173,7 @@ interface ParallelChainRunInput {
167
173
  configToolBudget?: ToolBudgetConfig;
168
174
  globalSemaphore?: Semaphore;
169
175
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
176
+ runFanoutBudget?: RunFanoutBudgetDescriptor;
170
177
  permissions?: PermissionConfig;
171
178
  dynamic?: boolean;
172
179
  }
@@ -368,7 +375,11 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
368
375
  beginForegroundChild(input.foregroundControl, {
369
376
  index: childIndex,
370
377
  agent: task.agent,
371
- description: cleanTask.trim(),
378
+ authoredTask: cleanTask,
379
+ effectivePrompt: taskStr,
380
+ cwd: taskCwd,
381
+ ...(outputPath ? { outputPath } : {}),
382
+ description: `${task.agent} child`,
372
383
  ...(effectiveModel ? { model: effectiveModel } : {}),
373
384
  ...(thinking ? { thinking } : {}),
374
385
  interrupt: () => {
@@ -388,8 +399,10 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
388
399
  result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
389
400
  permissions: input.permissions,
390
401
  parentSessionId: input.ctx.sessionManager.getSessionId() ?? undefined,
402
+ llmIntentArbiter: createTaskMutationArbiter(input.ctx),
391
403
  ...workflowForegroundSteeringLaunchOptions(input.foregroundControl, childIndex),
392
404
  capabilityCeiling: input.capabilityCeiling,
405
+ runFanoutBudget: input.runFanoutBudget ? { ...input.runFanoutBudget, parentPath: `${input.runFanoutBudget.parentPath ? `${input.runFanoutBudget.parentPath}/` : ""}chain[${input.stepIndex}]${input.dynamic ? `.expand[${taskIndex}]` : `.parallel[${taskIndex}]`}` } : undefined,
393
406
  context: input.contextForAgent?.(task.agent),
394
407
  cwd: taskCwd,
395
408
  signal: input.signal,
@@ -422,8 +435,11 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
422
435
  agentContract,
423
436
  acceptance: task.acceptance,
424
437
  acceptanceContext: { mode: "chain", dynamic: input.dynamic && task.acceptance === undefined },
438
+ onEffectivePrompt: input.foregroundControl ? (prompt) => updateLiveEffectivePrompt(input.foregroundControl!, childIndex, prompt) : undefined,
425
439
  timeoutMs: input.timeoutMs,
426
440
  deadlineAt: input.deadlineAt,
441
+ toolTimeoutMs: input.callToolTimeoutMs,
442
+ configToolTimeoutMs: input.configToolTimeoutMs,
427
443
  turnBudget: input.turnBudget,
428
444
  onDetachedExit: (result) => {
429
445
  try {
@@ -536,10 +552,17 @@ interface ChainExecutionParams {
536
552
  toolBudget?: ResolvedToolBudget;
537
553
  usageBudget?: UsageBudgetConfig;
538
554
  configToolBudget?: ToolBudgetConfig;
555
+ /** Optional per-call hard toolTimeoutMs override (highest precedence). */
556
+ callToolTimeoutMs?: number;
557
+ /** Global config.toolTimeoutMs (third precedence, after agent frontmatter). */
558
+ configToolTimeoutMs?: number;
559
+ /** PI_SUBAGENT_TOOL_TIMEOUT_MS override (lowest precedence). */
560
+ toolTimeoutMsEnv?: string | undefined;
539
561
  permissions?: PermissionConfig;
540
562
  /** Global cap on simultaneously-running tasks within this chain. Defaults to DEFAULT_GLOBAL_CONCURRENCY_LIMIT. */
541
563
  globalConcurrencyLimit?: number;
542
564
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
565
+ runFanoutBudget?: RunFanoutBudgetDescriptor;
543
566
  }
544
567
 
545
568
  interface ChainExecutionResult {
@@ -868,6 +891,8 @@ ${step.message}` : ""}` }],
868
891
  maxSubagentDepth: params.maxSubagentDepth,
869
892
  timeoutMs: params.timeoutMs,
870
893
  deadlineAt,
894
+ callToolTimeoutMs: params.callToolTimeoutMs,
895
+ configToolTimeoutMs: params.configToolTimeoutMs,
871
896
  turnBudget: params.turnBudget,
872
897
  usageBudget: params.usageBudget,
873
898
  onDetachedExit,
@@ -876,6 +901,7 @@ ${step.message}` : ""}` }],
876
901
  configToolBudget: params.configToolBudget,
877
902
  globalSemaphore,
878
903
  permissions: params.permissions,
904
+ runFanoutBudget: params.runFanoutBudget,
879
905
  });
880
906
  globalTaskIndex += step.parallel.length;
881
907
 
@@ -1002,6 +1028,19 @@ ${step.message}` : ""}` }],
1002
1028
  return buildChainExecutionErrorResult(message, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex }));
1003
1029
  }
1004
1030
 
1031
+ try {
1032
+ if (params.runFanoutBudget) claimRunFanoutBatch(params.runFanoutBudget, materialized.parallel.map((_, itemIndex) => `chain[${stepIndex}].expand[${itemIndex}]`));
1033
+ } catch (error) {
1034
+ const message = error instanceof Error ? error.message : String(error);
1035
+ dynamicGroupStatuses[stepIndex] = { status: "failed", error: message };
1036
+ const result = buildChainExecutionErrorResult(message, makeDetailsInput({ currentStepIndex: stepIndex, currentFlatIndex: globalTaskIndex }));
1037
+ if (error instanceof RunFanoutLimitError) {
1038
+ result.details.runFanoutBudget = error.snapshot;
1039
+ result.details.runFanoutRejection = error.rejection;
1040
+ }
1041
+ return result;
1042
+ }
1043
+
1005
1044
  dynamicChildren[stepIndex] = materialized.items.map((item, itemIndex) => ({
1006
1045
  agent: step.parallel.agent,
1007
1046
  label: materialized.parallel[itemIndex]?.label,
@@ -1129,6 +1168,8 @@ ${step.message}` : ""}` }],
1129
1168
  maxSubagentDepth: params.maxSubagentDepth,
1130
1169
  timeoutMs: params.timeoutMs,
1131
1170
  deadlineAt,
1171
+ callToolTimeoutMs: params.callToolTimeoutMs,
1172
+ configToolTimeoutMs: params.configToolTimeoutMs,
1132
1173
  turnBudget: params.turnBudget,
1133
1174
  usageBudget: params.usageBudget,
1134
1175
  onDetachedExit,
@@ -1137,6 +1178,7 @@ ${step.message}` : ""}` }],
1137
1178
  configToolBudget: params.configToolBudget,
1138
1179
  globalSemaphore,
1139
1180
  permissions: params.permissions,
1181
+ runFanoutBudget: params.runFanoutBudget,
1140
1182
  dynamic: true,
1141
1183
  });
1142
1184
  globalTaskIndex = dynamicStartIndex + reservedDynamicItems;
@@ -1332,7 +1374,11 @@ ${step.message}` : ""}` }],
1332
1374
  beginForegroundChild(foregroundControl, {
1333
1375
  index: childIndex,
1334
1376
  agent: seqStep.agent,
1335
- description: cleanTask.trim(),
1377
+ authoredTask: cleanTask,
1378
+ effectivePrompt: stepTask,
1379
+ cwd,
1380
+ ...(outputPath ? { outputPath } : {}),
1381
+ description: `${seqStep.agent} child`,
1336
1382
  ...(effectiveModel ? { model: effectiveModel } : {}),
1337
1383
  ...(thinking ? { thinking } : {}),
1338
1384
  interrupt: () => {
@@ -1369,8 +1415,10 @@ ${step.message}` : ""}` }],
1369
1415
  r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
1370
1416
  permissions: params.permissions,
1371
1417
  parentSessionId: ctx.sessionManager.getSessionId() ?? undefined,
1418
+ llmIntentArbiter: createTaskMutationArbiter(ctx),
1372
1419
  ...workflowForegroundSteeringLaunchOptions(params.foregroundControl, childIndex),
1373
1420
  capabilityCeiling: params.capabilityCeiling,
1421
+ runFanoutBudget: params.runFanoutBudget ? { ...params.runFanoutBudget, parentPath: `${params.runFanoutBudget.parentPath ? `${params.runFanoutBudget.parentPath}/` : ""}chain[${stepIndex}]` } : undefined,
1374
1422
  context: params.contextForAgent?.(seqStep.agent),
1375
1423
  cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
1376
1424
  signal,
@@ -1403,8 +1451,11 @@ ${step.message}` : ""}` }],
1403
1451
  agentContract,
1404
1452
  acceptance: seqStep.acceptance,
1405
1453
  acceptanceContext: { mode: "chain" },
1454
+ onEffectivePrompt: foregroundControl ? (prompt) => updateLiveEffectivePrompt(foregroundControl, childIndex, prompt) : undefined,
1406
1455
  timeoutMs: params.timeoutMs,
1407
1456
  deadlineAt,
1457
+ toolTimeoutMs: params.callToolTimeoutMs,
1458
+ configToolTimeoutMs: params.configToolTimeoutMs,
1408
1459
  turnBudget: params.turnBudget,
1409
1460
  onDetachedExit: (result) => {
1410
1461
  try {