@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
@@ -54,11 +54,19 @@ type Theme = TranscriptTheme;
54
54
  type ThemeColor = string;
55
55
  type ThemeBackground = string;
56
56
  export type TranscriptNoticeTone = "info" | "warning" | "error";
57
+ /**
58
+ * How a turn ended. A host that distinguishes a completed exchange from one the
59
+ * user aborted or that failed records it on the turn's end boundary; rendering
60
+ * treats every finished turn the same, so this stays metadata for hosts/tests.
61
+ */
62
+ export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
57
63
  export type TranscriptEntry = {
58
64
  id: number;
59
65
  turnId: number;
60
66
  type: "turn-boundary";
61
67
  phase: "start" | "end";
68
+ /** Present on `end` boundaries when the host reported how the turn ended. */
69
+ outcome?: TranscriptTurnOutcome;
62
70
  } | {
63
71
  id: number;
64
72
  turnId: number;
@@ -206,10 +214,12 @@ export declare function findLatestEntry<TType extends TranscriptEntry["type"]>(s
206
214
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
207
215
  * unless one already exists, clears streaming flags on the turn's entries,
208
216
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
209
- * a no-op for boundary creation. Public building block for hosts that know
210
- * when a replayed exchange is complete.
217
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
218
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
219
+ * Public building block for hosts that know when a replayed exchange is
220
+ * complete.
211
221
  */
212
- export declare function finishTurn(state: TranscriptState, turnId?: number | null): void;
222
+ export declare function finishTurn(state: TranscriptState, turnId?: number | null, outcome?: TranscriptTurnOutcome): void;
213
223
  export declare function removeTranscriptTurn(state: TranscriptState, turnId: number | null): void;
214
224
  /**
215
225
  * Degraded stand-in stored on a tool-call entry when the original arguments
@@ -314,17 +314,29 @@ export function findLatestEntry(state, turnId, type) {
314
314
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
315
315
  * unless one already exists, clears streaming flags on the turn's entries,
316
316
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
317
- * a no-op for boundary creation. Public building block for hosts that know
318
- * when a replayed exchange is complete.
317
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
318
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
319
+ * Public building block for hosts that know when a replayed exchange is
320
+ * complete.
319
321
  */
320
- export function finishTurn(state, turnId = state.currentTurnId) {
322
+ export function finishTurn(state, turnId = state.currentTurnId, outcome) {
321
323
  if (turnId === null)
322
324
  return;
323
- const alreadyFinished = state.entries.some((entry) => entry.turnId === turnId &&
325
+ const endBoundary = state.entries.find((entry) => entry.turnId === turnId &&
324
326
  entry.type === "turn-boundary" &&
325
327
  entry.phase === "end");
326
- if (!alreadyFinished)
327
- appendEntry(state, { type: "turn-boundary", turnId, phase: "end" });
328
+ if (endBoundary) {
329
+ if (outcome !== undefined)
330
+ endBoundary.outcome = outcome;
331
+ }
332
+ else {
333
+ appendEntry(state, {
334
+ type: "turn-boundary",
335
+ turnId,
336
+ phase: "end",
337
+ ...(outcome === undefined ? {} : { outcome }),
338
+ });
339
+ }
328
340
  for (const entry of state.entries) {
329
341
  if (entry.turnId !== turnId)
330
342
  continue;
@@ -79,12 +79,21 @@ type ThemeBackground = string;
79
79
 
80
80
  export type TranscriptNoticeTone = "info" | "warning" | "error";
81
81
 
82
+ /**
83
+ * How a turn ended. A host that distinguishes a completed exchange from one the
84
+ * user aborted or that failed records it on the turn's end boundary; rendering
85
+ * treats every finished turn the same, so this stays metadata for hosts/tests.
86
+ */
87
+ export type TranscriptTurnOutcome = "completed" | "aborted" | "failed";
88
+
82
89
  export type TranscriptEntry =
83
90
  | {
84
91
  id: number;
85
92
  turnId: number;
86
93
  type: "turn-boundary";
87
94
  phase: "start" | "end";
95
+ /** Present on `end` boundaries when the host reported how the turn ended. */
96
+ outcome?: TranscriptTurnOutcome;
88
97
  }
89
98
  | { id: number; turnId: number; type: "user-message"; text: string }
90
99
  | {
@@ -555,22 +564,33 @@ export function findLatestEntry<TType extends TranscriptEntry["type"]>(
555
564
  * Closes `turnId` (defaulting to the current turn): appends the end boundary
556
565
  * unless one already exists, clears streaming flags on the turn's entries,
557
566
  * and updates bookkeeping. Idempotent — finishing an already-finished turn is
558
- * a no-op for boundary creation. Public building block for hosts that know
559
- * when a replayed exchange is complete.
567
+ * a no-op for boundary creation. An optional `outcome` is recorded on the end
568
+ * boundary, letting hosts distinguish completed, aborted, and failed turns.
569
+ * Public building block for hosts that know when a replayed exchange is
570
+ * complete.
560
571
  */
561
572
  export function finishTurn(
562
573
  state: TranscriptState,
563
574
  turnId: number | null = state.currentTurnId,
575
+ outcome?: TranscriptTurnOutcome,
564
576
  ): void {
565
577
  if (turnId === null) return;
566
- const alreadyFinished = state.entries.some(
567
- (entry) =>
578
+ const endBoundary = state.entries.find(
579
+ (entry): entry is Extract<TranscriptEntry, { type: "turn-boundary" }> =>
568
580
  entry.turnId === turnId &&
569
581
  entry.type === "turn-boundary" &&
570
582
  entry.phase === "end",
571
583
  );
572
- if (!alreadyFinished)
573
- appendEntry(state, { type: "turn-boundary", turnId, phase: "end" });
584
+ if (endBoundary) {
585
+ if (outcome !== undefined) endBoundary.outcome = outcome;
586
+ } else {
587
+ appendEntry(state, {
588
+ type: "turn-boundary",
589
+ turnId,
590
+ phase: "end",
591
+ ...(outcome === undefined ? {} : { outcome }),
592
+ });
593
+ }
574
594
  for (const entry of state.entries) {
575
595
  if (entry.turnId !== turnId) continue;
576
596
  if (
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xzzpig/pi-subagents",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
5
5
  "author": "Nico Bailon",
6
6
  "license": "MIT",
@@ -13,6 +13,8 @@
13
13
  "./agents": "./src/api/agents.ts",
14
14
  "./delegation": "./src/api/delegation.ts",
15
15
  "./capability-ceiling": "./src/api/capability-ceiling.ts",
16
+ "./workflow-resources": "./src/api/workflow-resources.ts",
17
+ "./required-child-extensions": "./src/api/required-child-extensions.ts",
16
18
  "./preflight": "./src/api/preflight.ts",
17
19
  "./agent-management": "./src/api/agent-management.ts",
18
20
  "./control-channel": "./src/api/control-channel.ts",
@@ -88,12 +90,13 @@
88
90
  "acorn": "8.18.0",
89
91
  "jiti": "2.7.0",
90
92
  "typebox": "1.1.38",
93
+ "undici": "8.10.0",
91
94
  "yaml": "2.8.3"
92
95
  },
93
96
  "devDependencies": {
94
- "@earendil-works/pi-agent-core": "^0.85.1",
95
- "@earendil-works/pi-ai": "^0.85.1",
96
- "@earendil-works/pi-tui": "^0.85.1",
97
+ "@earendil-works/pi-agent-core": "0.85.1",
98
+ "@earendil-works/pi-ai": "0.85.1",
99
+ "@earendil-works/pi-tui": "0.85.1",
97
100
  "@oxlint/plugins": "1.80.0",
98
101
  "@types/node": "24.13.3",
99
102
  "oxlint": "1.80.0",
@@ -107,6 +110,8 @@
107
110
  "@xzzpig/pi-components"
108
111
  ],
109
112
  "scripts": {
113
+ "build:pkg": "node scripts/build-package.mjs",
114
+ "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
110
115
  "typecheck": "tsc --noEmit",
111
116
  "test": "npm run test:unit",
112
117
  "test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
@@ -28,7 +28,7 @@ Choose or adapt angles when the work calls for it:
28
28
 
29
29
  Prefer three strong reviewers over many vague reviewers.
30
30
 
31
- Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete, current, caused or made reachable by the target diff, and supported by source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
31
+ Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. Filter on evidence, not severity: a finding must be concrete and current within the named review target, and supported by source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2. P0 blocks merge. P1 should be fixed before release. P2 is report-only. End each review with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. If nothing qualifies, ask the reviewer to say exactly `No issues found.` The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
32
32
 
33
33
  Do not default first-pass reviews to `blockers only`. That phrase is valid only for final pre-merge re-checks after P1/P2 findings are already inventoried, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred.
34
34
 
@@ -0,0 +1,24 @@
1
+ import { pathToFileURL } from "node:url";
2
+
3
+ let aliases = {};
4
+ let nativeRunner = false;
5
+ let compiledRunner = false;
6
+ let packageRootUrl;
7
+ const redirected = new Set([
8
+ "@earendil-works/pi-tui",
9
+ ]);
10
+
11
+ export function initialize(data) {
12
+ aliases = data?.aliases ?? {};
13
+ nativeRunner = data?.nativeRunner === true;
14
+ compiledRunner = data?.compiledRunner === true;
15
+ packageRootUrl = data?.packageRootUrl;
16
+ }
17
+
18
+ export function resolve(specifier, context, nextResolve) {
19
+ const packageImport = typeof packageRootUrl === "string" && context.parentURL?.startsWith(packageRootUrl) === true;
20
+ if (nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier]) {
21
+ return nextResolve(pathToFileURL(aliases[specifier]).href, context);
22
+ }
23
+ return nextResolve(specifier, context);
24
+ }
@@ -0,0 +1,36 @@
1
+ import * as nodeModule from "node:module";
2
+ import { pathToFileURL } from "node:url";
3
+
4
+ // Upstream-original preload: JITI_ALIAS is written by the runner launcher, so a malformed value must fail loudly.
5
+ // pi-lens-ignore: unchecked-throwing-call-js
6
+ const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
7
+ const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
8
+ const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
9
+ // Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
10
+ const packageRootUrl = new URL("./", import.meta.url).href;
11
+ const redirected = new Set([
12
+ "@earendil-works/pi-tui",
13
+ ]);
14
+
15
+ // Upstream-original: Node version feature detection for registerHooks (Node 22.12+ vs register()).
16
+ // pi-lens-ignore: no-runtime-typeof
17
+ if (typeof nodeModule.registerHooks === "function") {
18
+ nodeModule.registerHooks({
19
+ resolve(specifier, context, nextResolve) {
20
+ const packageImport = context.parentURL?.startsWith(packageRootUrl) === true;
21
+ if ((nativeRunner && (!compiledRunner || packageImport) ? aliases[specifier] : redirected.has(specifier) && aliases[specifier])) {
22
+ return nextResolve(pathToFileURL(aliases[specifier]).href, context);
23
+ }
24
+ try {
25
+ return nextResolve(specifier, context);
26
+ } catch (error) {
27
+ if (nativeRunner && specifier.endsWith(".js")) return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
28
+ throw error;
29
+ }
30
+ },
31
+ });
32
+ } else {
33
+ nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
34
+ data: { aliases, nativeRunner, compiledRunner, packageRootUrl },
35
+ });
36
+ }
@@ -1,28 +1,25 @@
1
1
  ---
2
2
  name: pi-subagents
3
3
  description: |
4
- Delegate to builtin or custom subagents for single-agent handoffs, parallel
5
- review, scripted chaining, async work, forked context, and coordinated
6
- workflows. Use when one parent agent should stay in control while children
7
- supply focused context, planning, review, or execution.
4
+ Technical guidance for operator-requested delegation to builtin or custom
5
+ subagents: bounded handoffs, parallel review, scripted workflows, async work,
6
+ forked context, isolation, and coordinated execution.
8
7
  ---
9
8
 
10
9
  # Pi Subagents
11
10
 
12
- Choose a mode:
13
-
14
- - **Direct mode:** For tiny or focused work, the parent handles the task
15
- directly; a single bounded child handoff is fine. Skip workflow ceremony.
16
- - **Orchestrator mode:** For substantial or delegated work, the parent is the
17
- supervisor, arbiter, and authority holder—not the routine primary doer.
18
- Subagents may own planning/design, scouting, implementation,
19
- simplification/challenge, validation, and review as useful. The parent keeps
20
- user intent, constraints, authority, routing, arbitration, final acceptance,
21
- and publication.
22
- - A useful loop for substantial work is **writer → challenge/simplify → review**;
23
- the parent arbitrates between steps, and tiny tasks can skip it.
24
- - Direct parent edits during orchestrator mode should be intentional, small
25
- interventions with a brief reason.
11
+ The parent works directly by default. Invoke subagents only when the operator
12
+ requested delegation in the current request or through applicable user/project
13
+ instructions. Task size, complexity, risk, tool-call count, recipe fit, or an
14
+ available specialist does not independently authorize delegation.
15
+
16
+ Once authorized, choose the smallest bounded shape that earns its token and
17
+ elapsed-time overhead through concrete evidence, independent review,
18
+ specialization, useful parallelism, or needed isolation. A single child is
19
+ valid; writer, challenge, and review stages must each earn their overhead rather
20
+ than becoming default ceremony. The parent keeps user intent, constraints,
21
+ routing, arbitration, decisions, final acceptance, and publication authority,
22
+ and may perform the work directly where it is the most efficient owner.
26
23
 
27
24
  Children do not spawn subagents unless the parent explicitly delegated fanout
28
25
  and their resolved `tools` allow `subagent`.
@@ -50,6 +47,18 @@ use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
50
47
  example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
51
48
  bounded, but do not add stages or ceremony just to satisfy this skill.
52
49
 
50
+ When composing `runs.run(...)`, `runs.all(...)`, or `runs.lanes(...)`, always
51
+ supply a short verb + behavior display `label` derived from the task, unless
52
+ the user supplied an explicit label; preserve that label. Keep the stable
53
+ machine `key` independent (for example, `issue2011-writer` with
54
+ `label: "Fix workflow steering"`). For `runs.lanes`, put labels on stage
55
+ items, not lane objects. Use stage-appropriate labels for reviews and retained-child
56
+ follow-ups too (for example, `Review workflow steering`). Generate labels in
57
+ the orchestrator while composing the launch—no extra model call, runtime
58
+ generator, or schema change. Native direct `{ agent, task }` calls have no
59
+ top-level `label` parameter; do not invent one or wrap a tiny single task in
60
+ a workflow just to label it.
61
+
53
62
  Use async/background by default. Set `async:false` only when the parent must
54
63
  block. Final reviews, validation gates, oracle checks, and publication checks
55
64
  stay async.
@@ -71,6 +80,8 @@ that runner explicitly supports the option.
71
80
 
72
81
  ## Read the reference for the branch
73
82
 
83
+ For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
84
+
74
85
  | Branch | Read |
75
86
  | --- | --- |
76
87
  | Delegate or choose roles, prompts, models, or slash commands | `references/prompting-and-roles.md` |
@@ -80,9 +91,9 @@ that runner explicitly supports the option.
80
91
  | List, create, edit, disable, eject, or expose agents/RPC | `references/management-authoring-rpc.md` |
81
92
  | Check safety constraints, recipes, or error handling | `references/constraints-and-recipes.md` |
82
93
 
83
- For complex work, read `prompting-and-roles.md` and `execution-controls.md`, then
84
- load `review-and-validation.md` and `constraints-and-recipes.md` before launch or
85
- review.
94
+ For an authorized complex delegated workflow, read `prompting-and-roles.md` and
95
+ `execution-controls.md`, then load `review-and-validation.md` and
96
+ `constraints-and-recipes.md` before launch or review.
86
97
 
87
98
  ## Operating rules
88
99
 
@@ -91,7 +102,8 @@ review.
91
102
  - Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
92
103
  - Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
93
104
  - For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
94
- - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. See `references/execution-controls.md`.
105
+ - Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
106
+ - Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
95
107
  - For cross-codebase work, record the repo, explicit `cwd`, authority boundary, and expected output before launch.
96
108
  - Make parallel prompts distinct by source seam, evidence, and decision. Do not clone prompts with only item numbers swapped.
97
109
  - Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
@@ -52,10 +52,11 @@ This reference keeps cross-cutting policy and failure handling. Load the matchin
52
52
  | Independent lanes, repositories, worktrees, and handoffs | [`references/multi-lane-orchestration.md`](multi-lane-orchestration.md) |
53
53
  | Agent management, file authoring, prompt integration, or RPC | [`references/management-authoring-rpc.md`](management-authoring-rpc.md) |
54
54
 
55
- Choose the smallest recipe that fits:
55
+ After delegation is operator-authorized, choose the smallest recipe that earns
56
+ its overhead. Recipes select a shape; they do not authorize delegation:
56
57
 
57
58
  - **Recon → plan → implement:** run one focused `scout`, then one `worker` that consumes its findings.
58
- - **Non-trivial implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, scout load-bearing code, plan when useful, use one writer, run fresh review/validation, apply only accepted fixes with one writer, then inspect direct evidence and the final diff before parent acceptance. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
59
+ - **Implementation:** clarify scope and acceptance, record user-owned decisions and seam/validation contracts, and use a bounded scout, writer, or fresh reviewer only where the requested delegation benefits from that stage. Keep one writer, inspect direct evidence, and require every added stage to earn its overhead. Split large work into serial milestones instead of a writer swarm; do not stop at review without disposition.
59
60
  - **Parallel analysis:** fan out only independent read/review/validation work, or isolate each writer in its own worktree. Never run concurrent writers in one checkout.
60
61
 
61
62
  ## Error Handling
@@ -24,7 +24,7 @@ Project settings resolve from the nearest parent directory containing `.pi` or `
24
24
 
25
25
  An agent may set `runner.type: external-cli` with a non-empty `command`, optional string `args`, and `promptDelivery: stdin` (the default). The command runs with `shell: false`, inherits the resolved cwd and environment, and receives the combined agent instructions and task through stdin. It must already be installed; pi-subagents adds no CLI dependency.
26
26
 
27
- External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, fallbacks, and sessions are also unsupported.
27
+ External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, and sessions are also unsupported.
28
28
 
29
29
  ### External job profiles
30
30
 
@@ -32,7 +32,7 @@ An agent may set `runner.type: external-job` with a non-empty `provider` and opt
32
32
 
33
33
  External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
34
34
 
35
- External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, fallbacks, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
35
+ External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
36
36
 
37
37
  ### Single agent
38
38
 
@@ -83,10 +83,10 @@ lanes, or a fanout that the parent will consume together.
83
83
  ```js
84
84
  subagent({
85
85
  workflowScript: `
86
- const scan = await runs.run("scan", { agent: "scout", task: "Map the target" });
86
+ const scan = await runs.run("scan", { label: "Map target behavior", agent: "scout", task: "Map the target" });
87
87
  const reviews = await runs.all([
88
- { key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
89
- { key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
88
+ { key: "correctness", label: "Review target correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
89
+ { key: "tests", label: "Review target test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
90
90
  ]);
91
91
  return reviews.map(result => result.output);
92
92
  `
@@ -109,6 +109,7 @@ Terminal async workflows also persist `workflow-receipt.json` beside `status.jso
109
109
 
110
110
  ```js
111
111
  return runs.run("cross-oracle", {
112
+ label: "Challenge proposed direction",
112
113
  resume: { workflowRunId: "<pass-1-workflow-id>", key: "advisor-oracle", latest: true },
113
114
  task: "Review the focused challenge packet."
114
115
  });
@@ -120,7 +121,8 @@ Keyed resume reads that one exact receipt and revalidates the retained run at la
120
121
 
121
122
  For a broad plan with a known set of narrow, visible stages per lane, use
122
123
  `runs.lanes(...)` inside a `workflowScript`; it is a nested helper, not a
123
- top-level `subagent` mode. Give each lane and stage a stable key. The first
124
+ top-level `subagent` mode. Give each lane and stage a stable key; give stage
125
+ items a short verb + behavior `label`, preserving explicit user labels. The first
124
126
  stage from every lane is launched together, then later stages sequence per lane.
125
127
  `resume: "previous"` requires the retained predecessor, and a failed or blocked
126
128
  stage blocks only that lane. The returned board exposes lane/stage results for
@@ -246,15 +248,19 @@ Use diagnostics when setup or child startup looks wrong:
246
248
  subagent({ action: "doctor" })
247
249
  ```
248
250
 
251
+ ### Failed lane recovery and execution-mode changes
252
+
253
+ A failure in the subagent workflow, child launch, prompt runtime, extension loading, or child tooling setup is a lane infrastructure blocker, not permission to silently change execution mode. Stop and report the exact failure, run/status, and repo/cwd/worktree/branch/ref state. Retry or fix the `subagent` path only through a clear same-protocol retry; before retrying or asking the owner, verify the worktree is clean or capture the partial diff. For backlog lanes and other subagent-governed workflows, switching to `interactive_shell`, `pi -ne`, Codex/Claude/Cursor CLI, a foreground agent, or another external mode requires explicit owner approval. Pi core may print a generic `pi -ne` extension-load hint; that hint is outside this package and is not protocol-approved. A verified compaction abort may continue the retained child session once on the same resolved model; provider failures never select another model automatically.
254
+
249
255
  ### External terminal work
250
256
 
251
- Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts, and recovery.
257
+ Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts, or recovery only when the user explicitly requests that mode or the task is outside the governed subagent protocol; it is not an implicit replacement for a failed `subagent` lane.
252
258
 
253
259
  A cooperating terminal runtime can register read-only external records through `@xzzpig/pi-subagents/external-runs`. Records include the source, session, state, optional report path, and completion reason. They are observations only: pi-subagents does not start, stop, steer, or otherwise own the foreign process. Run unattended raw terminal agents in an explicit isolated cwd or worktree; do not use a live project checkout as disposable review space.
254
260
 
255
261
  ### Scheduled subagent runs
256
262
 
257
- Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
263
+ Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for. To keep schedules outside the project repository, set `{ "scheduledRuns": { "storeRoot": "~/.pi/subagent-schedules" } }` in the same config: `storeRoot` accepts an absolute path or a `~/`-prefixed path, and records land under `<storeRoot>/<sha256(path.resolve(cwd)) first 20 hex>/<scheduleId>/`.
258
264
 
259
265
  ```typescript
260
266
  // One-shot reviewer
@@ -323,6 +329,19 @@ subagent({ action: "steer", id: "abc123", message: "Focus on the failing test."
323
329
 
324
330
  The action waits up to three seconds for the child Pi session to accept the correlated user input and returns a request id with `delivered`, `scheduled`, `pending`, `partial`, `recovered`, or `failed` plus per-child states. Indexed pending children return `scheduled` immediately. Only a top-level single-child run may automatically interrupt after a missed acknowledgment and recover after confirmed pause within a further 15 seconds. Recovery preserves the original child contract and only its remaining deadline, turn, and tool budgets. If the session is missing, a budget is exhausted, the pause cannot be confirmed, or replacement launch fails, the source remains paused when pausing succeeded and the action returns the exact failure. Chain, parallel, and nested runs never auto-interrupt; inspect their per-child outcomes and handle failures explicitly. A late acknowledgment is recorded and cannot cancel committed recovery.
325
331
 
332
+ Steering supports three delivery modes via the `mode` parameter (`steer` is the default):
333
+
334
+ - `mode: "steer"` — interrupt the child at the next safe point of its current turn and deliver the message.
335
+ - `mode: "follow_up"` — do not interrupt; queue input through Pi's native follow-up path for the next turn boundary. Eligible completed retained workflow children (single-step runs in state `complete` with a stored session file) receive the message as a revival brief (`queueRevivalBrief`) when they are revived; paused children reject follow-up steering outright. The 20-message queue limit applies to retained revival briefs, not live follow-up input.
336
+ - `mode: "auto"` — same next-safe-point delivery path as `steer`, but without the automatic pause-and-revive recovery after a missed acknowledgment.
337
+
338
+ ```typescript
339
+ subagent({ action: "steer", id: "abc123", mode: "follow_up", message: "After this step, also validate the config file." })
340
+ subagent({ action: "steer", id: "abc123", mode: "auto", message: "Switch to the failing test now." })
341
+ ```
342
+
343
+ For async runs, `delivered` records that the child consumed the correlated user input; foreground `delivered` records in-process transport acceptance. Neither is proof of model compliance. A live foreground follow-up acknowledgment reports `queued`, meaning Pi accepted it into its follow-up queue, not that it was delivered. The foreground transport does not provide a later correlated queued-to-delivered receipt.
344
+
326
345
  ## Watchdog
327
346
 
328
347
  The subagent watchdog is an **opt-in** adversarial change reviewer. It is not the
@@ -96,6 +96,7 @@ A minimal agent file looks like this:
96
96
  name: my-agent
97
97
  package: code-analysis
98
98
  description: What this agent does
99
+ advertise: true
99
100
  aliases: developer, coder
100
101
  model: provider/model-id
101
102
  thinking: high
@@ -111,12 +112,11 @@ skillPath: ./skills, ../shared-skills
111
112
  Your system prompt here.
112
113
  ```
113
114
 
114
- That is only a starting point. Omit `package` for the traditional unqualified runtime name. Common optional fields include:
115
+ That is only a starting point. Omit `package` for the traditional unqualified runtime name. Set `advertise: true` only when the parent should receive this agent's name and description before deciding whether to delegate; advertisement is off by default. Common optional fields include:
115
116
  - `defaultProgress`
116
117
  - `defaultReads`
117
118
  - `output`
118
119
  - `aliases`
119
- - `fallbackModels`
120
120
  - `subagentOnlyExtensions`
121
121
  - `skills`
122
122
  - `skillPath`
@@ -2,7 +2,7 @@
2
2
 
3
3
  Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
4
4
 
5
- Create lanes only when delegation materially improves evidence, independent review, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
5
+ Create lanes only after delegation is operator-authorized and each lane materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
6
6
 
7
7
  ## Lane board and authority
8
8
 
@@ -46,6 +46,8 @@ After a writer produces a candidate, run the required fresh-context, read-only r
46
46
 
47
47
  Use stable lane-qualified artifact paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths. Copy only the final evidence to memory, a mission record, or a PR/comment, then remove scratch files from the active worktree before closing the lane.
48
48
 
49
+ For backlog lanes and other subagent-governed workflows, a setup/runtime/tooling failure remains an infrastructure blocker. Preserve the exact failure, run/status, and repository/cwd/worktree/branch/ref state; verify a clean worktree or capture any partial diff before a same-protocol retry or asking the owner. Do not start another writer or switch to an external, foreground, or CLI execution mode without explicit owner approval.
50
+
49
51
  Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
50
52
 
51
53
  Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.