@xzzpig/pi-subagents 0.18.0 → 0.19.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 (95) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +1 -1
  3. package/docs/agents.md +18 -12
  4. package/docs/configuration.md +66 -9
  5. package/docs/extension-api.md +5 -4
  6. package/docs/missions.md +13 -13
  7. package/docs/models.md +2 -2
  8. package/docs/observability.md +2 -2
  9. package/docs/standalone-background.md +1 -1
  10. package/docs/tool-reference.md +63 -86
  11. package/docs/workflows.md +170 -172
  12. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  13. package/package.json +6 -6
  14. package/prompts/review-loop.md +1 -1
  15. package/skills/council-mode/SKILL.md +1 -1
  16. package/skills/pi-subagents/SKILL.md +12 -5
  17. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -3
  18. package/skills/pi-subagents/references/execution-controls.md +68 -67
  19. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  20. package/skills/pi-subagents/references/multi-lane-orchestration.md +1 -1
  21. package/skills/pi-subagents/references/prompting-and-roles.md +45 -48
  22. package/src/agents/advertised-agent-prompt.ts +21 -41
  23. package/src/agents/agent-management.ts +2 -2
  24. package/src/agents/agents.ts +7 -0
  25. package/src/api/preflight.ts +67 -62
  26. package/src/extension/config.ts +12 -4
  27. package/src/extension/control-notices.ts +3 -0
  28. package/src/extension/doctor.ts +1 -0
  29. package/src/extension/fanout-child.ts +12 -3
  30. package/src/extension/herdr-pi-bridge.ts +2 -0
  31. package/src/extension/index.ts +68 -159
  32. package/src/extension/public-execution.ts +69 -35
  33. package/src/extension/reply-workflow-script.ts +58 -0
  34. package/src/extension/rpc.ts +29 -10
  35. package/src/extension/schemas.ts +36 -133
  36. package/src/extension/tool-activation.ts +57 -108
  37. package/src/extension/tool-description.ts +62 -27
  38. package/src/extension/upgrade-notice.ts +40 -0
  39. package/src/integrations/herdr-status.ts +19 -3
  40. package/src/intercom/native-supervisor-channel.ts +4 -1
  41. package/src/runs/background/async-execution.ts +58 -53
  42. package/src/runs/background/async-job-tracker.ts +63 -22
  43. package/src/runs/background/async-retention.ts +46 -16
  44. package/src/runs/background/await-async-run.ts +76 -0
  45. package/src/runs/background/chain-root-attachment.ts +4 -4
  46. package/src/runs/background/control-channel.ts +18 -2
  47. package/src/runs/background/notify.ts +5 -0
  48. package/src/runs/background/run-child-session.ts +4 -1
  49. package/src/runs/background/run-status.ts +6 -0
  50. package/src/runs/background/runner-aliases.ts +30 -2
  51. package/src/runs/background/runner-child-launch.ts +3 -0
  52. package/src/runs/background/scheduled-runs.ts +5 -5
  53. package/src/runs/background/subagent-runner.ts +15 -1
  54. package/src/runs/foreground/async-stop-action.ts +17 -3
  55. package/src/runs/foreground/execution.ts +130 -125
  56. package/src/runs/foreground/subagent-executor.ts +487 -288
  57. package/src/runs/shared/async-status-projection.ts +5 -0
  58. package/src/runs/shared/child-launch.ts +15 -2
  59. package/src/runs/shared/child-session.ts +92 -6
  60. package/src/runs/shared/child-tool-plan.ts +15 -3
  61. package/src/runs/shared/dynamic-fanout.ts +1 -1
  62. package/src/runs/shared/mcp-config-sources.ts +2 -1
  63. package/src/runs/shared/mcp-direct-tool-allowlist.ts +103 -11
  64. package/src/runs/shared/model-resolution.ts +29 -9
  65. package/src/runs/shared/model-scope.ts +28 -9
  66. package/src/runs/shared/nested-events.ts +55 -55
  67. package/src/runs/shared/parallel-utils.ts +2 -0
  68. package/src/runs/shared/pi-spawn.ts +7 -95
  69. package/src/runs/shared/subagent-prompt-runtime.ts +2 -0
  70. package/src/runs/shared/worktree.ts +1 -1
  71. package/src/shared/disabled-features.ts +123 -0
  72. package/src/shared/extension-context.ts +13 -0
  73. package/src/shared/model-info.ts +9 -0
  74. package/src/shared/settings.ts +1 -1
  75. package/src/shared/types.ts +21 -0
  76. package/src/slash/prompt-template-bridge.ts +2 -2
  77. package/src/slash/slash-commands.ts +10 -5
  78. package/src/slash/subagents-admin.ts +24 -24
  79. package/src/tui/fleet-status.ts +14 -6
  80. package/src/tui/fleet.ts +14 -2
  81. package/src/tui/render.ts +113 -52
  82. package/src/tui/running-tone.ts +28 -0
  83. package/src/watchdog/diff-tool.ts +23 -9
  84. package/src/watchdog/register-child.ts +3 -3
  85. package/src/watchdog/register-main.ts +3 -3
  86. package/src/watchdog/review.ts +2 -2
  87. package/src/watchdog/turn-delta.ts +1 -1
  88. package/src/workflows/chat-progress.ts +2 -2
  89. package/src/workflows/scripted-workflow.ts +117 -37
  90. package/src/workflows/structured-workflow-scripts.ts +177 -0
  91. package/src/workflows/workflow-checklist.ts +6 -0
  92. package/src/workflows/workflow-receipt.ts +8 -2
  93. package/src/workflows/workflow-resources.ts +37 -12
  94. package/src/workflows/workflow-reuse.ts +120 -0
  95. package/src/workflows/workflow-revival.ts +123 -0
@@ -5,7 +5,7 @@
5
5
  * - Sync (default): Streams output, renders markdown, tracks usage
6
6
  * - Async: Background execution, emits events when done
7
7
  *
8
- * Public execution mode: workflow (workflowScript)
8
+ * Public execution mode: workflow (workflow: true reply block, script path, or named resource)
9
9
  * Toggle: async parameter (default: true; set asyncByDefault:false in config.json to opt out)
10
10
  *
11
11
  * Config file: ~/.pi/agent/extensions/subagent/config.json
@@ -21,7 +21,7 @@ import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition
21
21
  import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
22
22
  import { clearAgentDiscoveryCache, discoverAgentSnapshot, discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
23
23
  import { resolveGlobalNpmRoot } from "../agents/global-npm-root.ts";
24
- import { appendAdvertisedAgentPrompt, buildAdvertisedAgentPrompt } from "../agents/advertised-agent-prompt.ts";
24
+ import { buildAdvertisedAgentCatalog, buildAdvertisedAgentPrompt } from "../agents/advertised-agent-prompt.ts";
25
25
  import { mergeAgentsForScope } from "../agents/agent-selection.ts";
26
26
  import { clearRuntimeAgentsForPi, listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
27
27
  import { discoverAgentsWithRuntime } from "../agents/runtime-discovery.ts";
@@ -30,13 +30,15 @@ import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
30
30
  import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
31
31
  import { resolveCurrentSessionId } from "../shared/session-identity.ts";
32
32
  import { getAgentDir } from "../shared/utils.ts";
33
- import { isStaleExtensionContextError, withCachedUiContext } from "../shared/extension-context.ts";
33
+ import { isStaleExtensionContextError, MODEL_ONLY_TOOL, withCachedUiContext } from "../shared/extension-context.ts";
34
34
  import { currentCompletionOwnerId } from "../shared/completion-owner.ts";
35
35
  import { cleanupOldChainDirs } from "../shared/settings.ts";
36
36
  import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary, setInlineWorkflowCoverage } from "../tui/render.ts";
37
37
  import { getInspectorPlugins, registerInspectorEventListener } from "../inspectors/plugins.ts";
38
38
  import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
39
+ import { readMainThinkingLevel, setMainThinkingLevelSource } from "../tui/running-tone.ts";
39
40
  import { createSubagentParamsSchema } from "./schemas.ts";
41
+ import { resolveDisabledFeatureSurface } from "../shared/disabled-features.ts";
40
42
  import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
41
43
  import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
42
44
  import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
@@ -78,7 +80,9 @@ import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./
78
80
  import { applyInjectionBlock, renderInjectionBlock, resolveInjectableAgents } from "./context-injection.ts";
79
81
  import { buildSubagentToolDescription, buildSubagentToolPromptMetadata } from "./tool-description.ts";
80
82
  import { formatWorkflowPreflightSummary, normalizeWorkflowPreflight } from "../workflows/workflow-preflight.ts";
83
+ import { runtimeReplacedAbortReason } from "../workflows/workflow-reuse.ts";
81
84
  import { finalizeToolResult } from "./tool-result.ts";
85
+ import { removedModelWorkflowFieldError } from "./public-execution.ts";
82
86
  import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
83
87
  import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
84
88
  import { resolveMissionStoreLocation } from "../missions/store.ts";
@@ -105,10 +109,13 @@ import {
105
109
  SUBAGENT_CONTROL_MESSAGE_TYPE,
106
110
  type SubagentControlMessageDetails,
107
111
  } from "./control-notices.ts";
112
+ import { showUpgradeNotice } from "./upgrade-notice.ts";
108
113
 
109
114
  export { loadConfig, resolveAsyncByDefault } from "./config.ts";
110
115
 
111
116
  const SLOW_RELOAD_PHASE_MS = 250;
117
+ // Long enough for Pi to finish starting; loading the executor blocks the event loop for tens of ms.
118
+ const MODULE_PRELOAD_DELAY_MS = 1_000;
112
119
  const RUNTIME_REGISTRY_STORE_KEY = "__piSubagentRuntimeRegistry";
113
120
 
114
121
  type SubagentExecutorModule = typeof import("../runs/foreground/subagent-executor.ts");
@@ -150,128 +157,6 @@ function logSlowPhase(label: string, startedAt: number): void {
150
157
  if (elapsed >= SLOW_RELOAD_PHASE_MS) console.error(`Subagent reload phase '${label}' took ${elapsed}ms.`);
151
158
  }
152
159
 
153
- function workflowLaneKeys(script: string): string[] {
154
- const keys: string[] = [];
155
- const seen = new Set<string>();
156
- const add = (key: string): void => {
157
- if (!seen.has(key)) {
158
- seen.add(key);
159
- keys.push(key);
160
- }
161
- };
162
- const isIdentifier = (char: string | undefined): boolean => char !== undefined && /[\w$]/.test(char);
163
- const skipTrivia = (start: number): number => {
164
- let index = start;
165
- while (index < script.length) {
166
- if (/\s/.test(script[index]!)) index += 1;
167
- else if (script.startsWith("//", index)) {
168
- const end = script.indexOf("\n", index + 2);
169
- index = end === -1 ? script.length : end + 1;
170
- } else if (script.startsWith("/*", index)) {
171
- const end = script.indexOf("*/", index + 2);
172
- index = end === -1 ? script.length : end + 2;
173
- } else break;
174
- }
175
- return index;
176
- };
177
- const readLiteral = (start: number): { key?: string; end: number } | undefined => {
178
- const quote = script[start];
179
- if (quote !== "'" && quote !== '"' && quote !== "`") return undefined;
180
- let index = start + 1;
181
- let dynamicTemplate = false;
182
- while (index < script.length) {
183
- if (script[index] === "\\") {
184
- index += 2;
185
- continue;
186
- }
187
- if (quote === "`" && script.startsWith("${", index)) dynamicTemplate = true;
188
- if (script[index] === quote) return { key: dynamicTemplate ? undefined : script.slice(start + 1, index), end: index + 1 };
189
- if (quote !== "`" && /[\r\n]/.test(script[index]!)) return { end: index + 1 };
190
- index += 1;
191
- }
192
- return { end: script.length };
193
- };
194
-
195
- const collectRunsAllKeys = (start: number): number => {
196
- let index = skipTrivia(start);
197
- if (script[index] !== "(") return start;
198
- index = skipTrivia(index + 1);
199
- if (script[index] !== "[") return start;
200
- let arrayDepth = 1;
201
- let objectDepth = 0;
202
- let directChildObject = false;
203
- let expectingElement = true;
204
- for (index += 1; index < script.length; index += 1) {
205
- index = skipTrivia(index);
206
- const literal = readLiteral(index);
207
- if (literal) {
208
- index = literal.end - 1;
209
- continue;
210
- }
211
- if (script[index] === "[") {
212
- arrayDepth += 1;
213
- expectingElement = false;
214
- continue;
215
- }
216
- if (script[index] === "]") {
217
- arrayDepth -= 1;
218
- if (arrayDepth === 0) return index + 1;
219
- continue;
220
- }
221
- if (script[index] === "{") {
222
- objectDepth += 1;
223
- if (objectDepth === 1) directChildObject = arrayDepth === 1 && expectingElement;
224
- expectingElement = false;
225
- continue;
226
- }
227
- if (script[index] === "}") {
228
- objectDepth -= 1;
229
- if (objectDepth === 0) directChildObject = false;
230
- continue;
231
- }
232
- if (script[index] === "," && arrayDepth === 1 && objectDepth === 0) {
233
- expectingElement = true;
234
- continue;
235
- }
236
- if (directChildObject && objectDepth === 1 && !isIdentifier(script[index - 1]) && script.startsWith("key", index) && !isIdentifier(script[index + 3])) {
237
- const colon = skipTrivia(index + 3);
238
- const key = script[colon] === ":" ? readLiteral(skipTrivia(colon + 1)) : undefined;
239
- if (key) {
240
- const next = skipTrivia(key.end);
241
- if (key.key !== undefined && (script[next] === "," || script[next] === "}")) add(key.key);
242
- index = key.end - 1;
243
- }
244
- }
245
- }
246
- return index;
247
- };
248
-
249
- for (let index = 0; index < script.length;) {
250
- index = skipTrivia(index);
251
- const literal = readLiteral(index);
252
- if (literal) {
253
- index = literal.end;
254
- continue;
255
- }
256
- if (!isIdentifier(script[index - 1]) && script.startsWith("runs.run", index) && !isIdentifier(script[index + 8])) {
257
- const open = skipTrivia(index + 8);
258
- const key = script[open] === "(" ? readLiteral(skipTrivia(open + 1)) : undefined;
259
- if (key) {
260
- const next = skipTrivia(key.end);
261
- if (key.key !== undefined && (script[next] === "," || script[next] === ")")) add(key.key);
262
- index = key.end;
263
- continue;
264
- }
265
- }
266
- if (!isIdentifier(script[index - 1]) && script.startsWith("runs.all", index) && !isIdentifier(script[index + 8])) {
267
- index = collectRunsAllKeys(index + 8);
268
- continue;
269
- }
270
- index += 1;
271
- }
272
- return keys;
273
- }
274
-
275
160
  function formatWorkflowPreflightCall(input: unknown): string {
276
161
  if (input === undefined) return "";
277
162
  try {
@@ -281,18 +166,6 @@ function formatWorkflowPreflightCall(input: unknown): string {
281
166
  }
282
167
  }
283
168
 
284
- function formatWorkflowManifest(script: string, async: unknown, clarify: unknown, preflightInput?: unknown): string {
285
- if (clarify === true) return "workflow script · rejected: clarify UI unsupported";
286
- const keys = workflowLaneKeys(script);
287
- // The workflow executor starts background work unless callers pass async:false.
288
- const mode = async === false ? "foreground" : "background";
289
- const preflight = formatWorkflowPreflightCall(preflightInput);
290
- if (keys.length === 0) return `workflow script · ${mode}${preflight ? ` · ${preflight}` : ""}`;
291
- const visibleKeys = keys.slice(0, 4).join(", ");
292
- const remainder = keys.length > 4 ? `, +${keys.length - 4}` : "";
293
- return `workflow · ${mode} · ${keys.length} lane${keys.length === 1 ? "" : "s"}: ${visibleKeys}${remainder}${preflight ? ` · ${preflight}` : ""}`;
294
- }
295
-
296
169
  /**
297
170
  * Derive subagent session base directory from parent session file.
298
171
  * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
@@ -412,18 +285,31 @@ export function projectActiveHerdrRuns(state: SubagentState): HerdrStatusRun[] {
412
285
  existing.push(...children);
413
286
  foregroundChildrenByWorkflow.set(control.parentWorkflowRunId, existing);
414
287
  }
288
+
289
+ // Keep each async child under its own ID: completion and attention events
290
+ // address that ID directly. The workflow row accounts only for foreground
291
+ // children; its own coordinator and step summaries are not leaf agents.
415
292
  return [...state.asyncJobs.values()]
416
293
  .filter((job) => active(job.status))
417
294
  .map((job) => {
418
- const children = job.mode === "workflow" ? foregroundChildrenByWorkflow.get(job.asyncId) : undefined;
419
295
  const currentStep = job.steps?.find((step) => step.status === "running")
420
296
  ?? (job.currentStep !== undefined ? job.steps?.[job.currentStep] : undefined)
421
297
  ?? job.steps?.find((step) => step.status === "pending");
298
+ if (job.mode === "workflow") {
299
+ const children = foregroundChildrenByWorkflow.get(job.asyncId) ?? [];
300
+ return {
301
+ id: job.asyncId,
302
+ coordinator: true as const,
303
+ agents: children.map((child) => child.agent),
304
+ ...(currentStep?.label ? { taskLabel: currentStep.label } : {}),
305
+ needsAttention: job.activityState === "needs_attention" || children.some((child) => child.needsAttention),
306
+ };
307
+ }
422
308
  return {
423
309
  id: job.asyncId,
424
- agents: children?.length ? children.map((child) => child.agent) : job.agents,
310
+ agents: job.agents,
425
311
  ...(currentStep?.label ? { taskLabel: currentStep.label } : {}),
426
- needsAttention: job.activityState === "needs_attention" || children?.some((child) => child.needsAttention),
312
+ needsAttention: job.activityState === "needs_attention",
427
313
  };
428
314
  });
429
315
  }
@@ -433,6 +319,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
433
319
  return;
434
320
  }
435
321
  const runtimeRegistry = getRuntimeRegistry();
322
+ setMainThinkingLevelSource(() => readMainThinkingLevel(() => pi.getThinkingLevel()));
436
323
 
437
324
  DIRS.results = ensureAccessibleDir(DIRS.results);
438
325
  DIRS.async = ensureAccessibleDir(DIRS.async);
@@ -682,13 +569,29 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
682
569
  };
683
570
  let executor: SubagentExecutor | undefined;
684
571
  let executorPromise: Promise<SubagentExecutor> | undefined;
572
+ let executorModulePromise: Promise<SubagentExecutorModule> | undefined;
573
+ const loadExecutorModule = () => executorModulePromise ??= import("../runs/foreground/subagent-executor.ts");
685
574
  const getExecutor = (): Promise<SubagentExecutor> => {
686
- executorPromise ??= import("../runs/foreground/subagent-executor.ts").then(({ createSubagentExecutor }) => {
575
+ executorPromise ??= loadExecutorModule().then(({ createSubagentExecutor }) => {
687
576
  executor = createSubagentExecutor(executorDeps);
688
577
  return executor;
689
578
  });
690
579
  return executorPromise;
691
580
  };
581
+ // Loading these on first use could happen days after startup, when pi-subagents may have
582
+ // changed on disk and the new files would import stale cached copies of modules loaded at
583
+ // startup. Load them shortly after a session starts instead, off Pi's startup path; child
584
+ // runtimes return before registration and never schedule this.
585
+ let modulePreloadTimer: ReturnType<typeof setTimeout> | undefined;
586
+ const scheduleModulePreload = () => {
587
+ if (executorModulePromise || modulePreloadTimer) return;
588
+ modulePreloadTimer = setTimeout(() => {
589
+ // Errors surface from the first call that needs the module.
590
+ loadExecutorModule().catch(() => {});
591
+ if (fleetViewEnabled) import("../tui/fleet.ts").catch(() => {});
592
+ }, MODULE_PRELOAD_DELAY_MS);
593
+ modulePreloadTimer.unref?.();
594
+ };
692
595
 
693
596
  pi.registerMessageRenderer<SupervisorRequestMessageDetails>(SUPERVISOR_REQUEST_MESSAGE_TYPE, renderSupervisorRequest);
694
597
  // SAFETY: `registerEntryRenderer` is not part of the typed ExtensionAPI in the
@@ -805,23 +708,28 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
805
708
  },
806
709
  });
807
710
 
711
+ const disabledFeatures = resolveDisabledFeatureSurface(config);
808
712
  const rpcBridge = registerSubagentRpcBridge({
809
713
  events: pi.events,
810
714
  getContext: () => state.lastUiContext,
811
715
  execute: executeSubagentReady,
812
716
  state,
717
+ disabledFeatures,
813
718
  });
814
719
 
815
720
 
816
- const parameters = createSubagentParamsSchema();
721
+ const parameters = createSubagentParamsSchema(disabledFeatures);
817
722
  const tool: ToolDefinition<typeof parameters, Details> = {
818
723
  name: "subagent",
724
+ ...MODEL_ONLY_TOOL,
819
725
  label: "Subagent",
820
- description: buildSubagentToolDescription(config),
821
- ...buildSubagentToolPromptMetadata(config),
726
+ description: buildSubagentToolDescription(config, { disabledFeatures }),
727
+ ...buildSubagentToolPromptMetadata(config, disabledFeatures),
822
728
  parameters,
823
729
 
824
730
  async execute(id, params, signal, onUpdate, ctx) {
731
+ const removedField = removedModelWorkflowFieldError(params);
732
+ if (removedField) throw new Error(removedField);
825
733
  return finalizeToolResult(await executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
826
734
  },
827
735
 
@@ -835,15 +743,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
835
743
  0, 0,
836
744
  );
837
745
  }
838
- if (args.workflowScript)
839
- return new Text(
840
- `${title}${gap}${formatWorkflowManifest(args.workflowScript, args.async, false, args.preflight)}`,
841
- 0,
842
- 0,
843
- );
844
- if (args.workflowScriptPath)
746
+ if (args.workflow !== undefined)
845
747
  return new Text(
846
- `${title}${gap}${theme.fg("accent", args.workflowScriptPath)}${args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : ""}${args.preflight !== undefined ? `${gap}${theme.fg("dim", formatWorkflowPreflightCall(args.preflight))}` : ""}`,
748
+ `${title}${gap}${theme.fg("accent", args.workflow === true ? "workflow (reply block)" : `workflow ${String(args.workflow)}`)}${args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : ""}${args.preflight !== undefined ? `${gap}${theme.fg("dim", formatWorkflowPreflightCall(args.preflight))}` : ""}`,
847
749
  0,
848
750
  0,
849
751
  );
@@ -878,13 +780,13 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
878
780
 
879
781
  pi.on("before_agent_start", async (event, ctx) => {
880
782
  await waitForAdvertisement();
881
- const selectedTools = event.systemPromptOptions?.selectedTools ?? (typeof pi.getActiveTools === "function" ? pi.getActiveTools() : []);
783
+ if (!event.systemPromptOptions.selectedTools.includes("subagent")) return;
882
784
  const sessionId = state.currentSessionId ?? resolveCurrentSessionId(ctx.sessionManager);
883
- const advertisedPrompt = Array.isArray(selectedTools) && selectedTools.includes("subagent")
884
- ? buildAdvertisedAgentPrompt(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(sessionId))
885
- : undefined;
886
- const systemPrompt = appendAdvertisedAgentPrompt(event.systemPrompt, advertisedPrompt);
887
- if (systemPrompt !== event.systemPrompt) return { systemPrompt };
785
+ // Structured sections let Pi append a transcript delta instead of replacing the
786
+ // cached system prompt. Set the section on every turn it applies: Pi rebuilds the
787
+ // options each turn, and an unset turn records a removal.
788
+ const catalog = buildAdvertisedAgentCatalog(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(sessionId));
789
+ if (catalog) event.systemPromptOptions.sections.advertised_subagents = catalog;
888
790
  });
889
791
 
890
792
  registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager, waitToolConfig.defaultTimeoutMs, undefined, supervisorChannel.hasPendingRequests);
@@ -913,6 +815,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
913
815
  const disposeSlashCommands = registerSlashCommands(pi, state, {
914
816
  fleetKeybindings: config.fleetKeybindings,
915
817
  foregroundDetachShortcut: config.foregroundDetachShortcut,
818
+ workflowScriptsDisabled: disabledFeatures.features.has("workflow-scripts"),
916
819
  });
917
820
 
918
821
  let visibleControlNotices = new Set<string>();
@@ -1124,7 +1027,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1124
1027
  // Workflow continuations retain their launch context; abort them before
1125
1028
  // teardown so a reload cannot launch through a stale context.
1126
1029
  for (const controller of state.workflowControllers?.values() ?? []) {
1127
- if (!controller.signal.aborted) controller.abort(new Error("Workflow stopped because the extension session was replaced or reloaded."));
1030
+ if (!controller.signal.aborted) controller.abort(runtimeReplacedAbortReason());
1128
1031
  }
1129
1032
  state.workflowControllers?.clear();
1130
1033
  state.workflowChildStops?.clear();
@@ -1133,6 +1036,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1133
1036
  resultIndexCleanupTimer = undefined;
1134
1037
  if (asyncRetentionTimer) clearTimeout(asyncRetentionTimer);
1135
1038
  asyncRetentionTimer = undefined;
1039
+ if (modulePreloadTimer) clearTimeout(modulePreloadTimer);
1040
+ modulePreloadTimer = undefined;
1136
1041
  asyncRetentionAbort.abort();
1137
1042
  stopResultWatcher();
1138
1043
  resultDeliveryOwnership.clear();
@@ -1239,6 +1144,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1239
1144
  pi.on("session_start", (event, ctx) => {
1240
1145
  installRuntime(ctx);
1241
1146
  startSessionMaintenance();
1147
+ scheduleModulePreload();
1242
1148
  const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
1243
1149
  resetSessionState(ctx, recovering, event.previousSessionFile);
1244
1150
  refreshContextInjectionSnapshot(ctx);
@@ -1276,9 +1182,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1276
1182
  await herdrStatusBridge.flush();
1277
1183
  });
1278
1184
 
1185
+ // Child processes and Herdr panes never load this module; in-process children have no UI.
1186
+ pi.on("session_start", (_event, ctx) => void showUpgradeNotice(ctx).catch((error) => console.error("Failed to show the pi-subagents upgrade notice:", error)));
1279
1187
  pi.on("session_start", (_event, ctx) => beginAdvertisement(ctx));
1280
1188
 
1281
1189
  registerSubagentToolActivation(pi, {
1190
+ mode: config.toolActivation,
1282
1191
  advertisedPrompt: async () => {
1283
1192
  await waitForAdvertisement();
1284
1193
  return buildAdvertisedAgentPrompt(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(state.currentSessionId ?? undefined));
@@ -53,6 +53,25 @@ export type PublicSubagentExecutionNormalization<T> =
53
53
  | { ok: true; params: T }
54
54
  | { ok: false; error: string; mode: PublicSubagentExecutionMode };
55
55
 
56
+ const RAW_SCRIPT_FORMS = "workflow: true or a workflow script path";
57
+ const REMOVED_WORKFLOW_SCRIPT = "workflowScript was removed; write the script in one ```js workflow block in this reply and call subagent({ workflow: true }), or pass a script file as workflow: \"./path/to/script.js\".";
58
+ const REMOVED_WORKFLOW_SCRIPT_PATH = "workflowScriptPath was removed; pass the script file as workflow: \"./path/to/script.js\" (a workflow value containing '/' is a path).";
59
+
60
+ /** A workflow value containing "/" or "\" is a script path; named workflow resource names contain neither. */
61
+ export function isWorkflowScriptPath(workflow: string): boolean {
62
+ return workflow.includes("/") || workflow.includes("\\");
63
+ }
64
+
65
+ /**
66
+ * Model tool calls supply script text only through workflow: true (the reply block) or a script path.
67
+ * workflowScript remains the internal carrier for slash, prompt-workflow, scheduled, RPC, and named-resource launches.
68
+ */
69
+ export function removedModelWorkflowFieldError(params: object): string | undefined {
70
+ if (Object.hasOwn(params, "workflowScript")) return REMOVED_WORKFLOW_SCRIPT;
71
+ if (Object.hasOwn(params, "workflowScriptPath")) return REMOVED_WORKFLOW_SCRIPT_PATH;
72
+ return undefined;
73
+ }
74
+
56
75
  export function validateWorkflowCapacityOverrides(params: PublicSubagentExecutionParams): string | undefined {
57
76
  for (const [name, value] of [
58
77
  ["globalConcurrencyLimit", params.globalConcurrencyLimit],
@@ -66,7 +85,7 @@ export function validateWorkflowCapacityOverrides(params: PublicSubagentExecutio
66
85
  * Enforce the public execution cutover before requests reach the executor.
67
86
  * Internal runs.run children and structured owned delegation bypass this boundary.
68
87
  */
69
- export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T): PublicSubagentExecutionNormalization<T> {
88
+ export function normalizePublicSubagentExecution<T extends PublicSubagentExecutionParams>(params: T, options: { structuredWorkflows?: boolean } = {}): PublicSubagentExecutionNormalization<T> {
70
89
  for (const field of ["resource", "resourceProvenance", "workflowResource", "workflowResourceProvenance", "workflowResourcePermit", "resourcePermit", "permit"] as const) {
71
90
  if (Object.hasOwn(params, field) && (params as Record<string, unknown>)[field] !== undefined) {
72
91
  return { ok: false, error: "Public execution does not accept workflow resource provenance or permit fields.", mode: params.action === undefined ? "workflow" : "management" };
@@ -79,19 +98,22 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
79
98
  return { ok: false, error: error instanceof Error ? error.message : String(error), mode: params.action === undefined ? "workflow" : "management" };
80
99
  }
81
100
  }
82
- if (params.workflowScript !== undefined && params.workflowScriptPath !== undefined) {
83
- return { ok: false, error: "workflowScript and workflowScriptPath are mutually exclusive.", mode: "workflow" };
101
+ if (params.workflowScriptPath !== undefined) {
102
+ return { ok: false, error: REMOVED_WORKFLOW_SCRIPT_PATH, mode: params.action === undefined ? "workflow" : "management" };
84
103
  }
85
- const hasNamedWorkflow = params.workflow !== undefined;
86
- if (hasNamedWorkflow && (typeof params.workflow !== "string" || !params.workflow.trim())) {
87
- return { ok: false, error: "workflow must be a non-empty named workflow resource.", mode: "workflow" };
104
+ const workflow = params.workflow;
105
+ if (workflow !== undefined && workflow !== true && (typeof workflow !== "string" || !workflow.trim())) {
106
+ return { ok: false, error: "workflow must be true (the ```js workflow block in this reply), a script path containing '/', or a named workflow resource.", mode: "workflow" };
88
107
  }
89
- if (hasNamedWorkflow && (params.workflowScript !== undefined || params.workflowScriptPath !== undefined)) {
90
- return { ok: false, error: "workflow is mutually exclusive with workflowScript and workflowScriptPath.", mode: "workflow" };
108
+ const hasNamedWorkflow = typeof workflow === "string" && !isWorkflowScriptPath(workflow);
109
+ // workflowScript is the internal script carrier; model tool calls cannot set it.
110
+ if (workflow !== undefined && params.workflowScript !== undefined) {
111
+ return { ok: false, error: "workflow cannot be combined with an internal workflowScript.", mode: "workflow" };
91
112
  }
92
- const hasWorkflowInput = params.workflowScript !== undefined || params.workflowScriptPath !== undefined || hasNamedWorkflow;
113
+ const hasRawScript = params.workflowScript !== undefined || (workflow !== undefined && !hasNamedWorkflow);
114
+ const hasWorkflowInput = hasRawScript || hasNamedWorkflow;
93
115
  if (!hasWorkflowInput && params.args !== undefined) {
94
- return { ok: false, error: "args requires workflow, workflowScript, or workflowScriptPath.", mode: "workflow" };
116
+ return { ok: false, error: "args requires workflow.", mode: "workflow" };
95
117
  }
96
118
  const hasCapacityOverride = params.globalConcurrencyLimit !== undefined || params.maxSubagentSpawnsPerRun !== undefined;
97
119
  if (hasCapacityOverride) {
@@ -99,19 +121,17 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
99
121
  if (capacityOverrideError) return { ok: false, error: capacityOverrideError, mode: params.action === undefined ? "workflow" : "management" };
100
122
  const validatesSpawnBudget = typeof params.action === "string" && params.action.trim() === "validate"
101
123
  && params.globalConcurrencyLimit === undefined && params.maxSubagentSpawnsPerRun !== undefined;
102
- if ((params.action !== undefined && !validatesSpawnBudget) || hasNamedWorkflow || (params.workflowScript === undefined && params.workflowScriptPath === undefined)) {
103
- return { ok: false, error: "Workflow capacity overrides are only supported on top-level workflowScript or workflowScriptPath calls; validate accepts maxSubagentSpawnsPerRun for static budget checks.", mode: params.action === undefined ? "workflow" : "management" };
124
+ if ((params.action !== undefined && !validatesSpawnBudget) || !hasRawScript) {
125
+ return { ok: false, error: `Workflow capacity overrides are only supported on top-level ${RAW_SCRIPT_FORMS} calls; validate accepts maxSubagentSpawnsPerRun for static budget checks.`, mode: params.action === undefined ? "workflow" : "management" };
104
126
  }
105
127
  }
106
128
  if (params.preflight !== undefined && !hasWorkflowInput) {
107
- return { ok: false, error: "preflight requires workflowScript or workflowScriptPath.", mode: params.action === undefined ? "workflow" : "management" };
129
+ return { ok: false, error: `preflight requires ${RAW_SCRIPT_FORMS}.`, mode: params.action === undefined ? "workflow" : "management" };
108
130
  }
109
- if (params.preflight !== undefined && hasNamedWorkflow && params.workflowScript === undefined && params.workflowScriptPath === undefined) {
131
+ if (params.preflight !== undefined && hasNamedWorkflow) {
110
132
  return { ok: false, error: "preflight is not supported with named workflow resources.", mode: "workflow" };
111
133
  }
112
- const hasValidWorkflowInput = (typeof params.workflowScript === "string" && Boolean(params.workflowScript.trim()))
113
- || (typeof params.workflowScriptPath === "string" && Boolean(params.workflowScriptPath.trim()))
114
- || (typeof params.workflow === "string" && Boolean(params.workflow.trim()));
134
+ const hasValidWorkflowInput = workflow !== undefined || (typeof params.workflowScript === "string" && Boolean(params.workflowScript.trim()));
115
135
  if (params.isolation !== undefined) {
116
136
  if (params.isolation !== "none" && params.isolation !== "worktree") {
117
137
  return { ok: false, error: "isolation must be 'none' or 'worktree'.", mode: hasWorkflowInput ? "workflow" : "management" };
@@ -131,7 +151,7 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
131
151
  }
132
152
  const action = params.action;
133
153
  if (action !== undefined && (typeof action !== "string" || !action.trim())) {
134
- return { ok: false, error: "action must be a non-empty management/control action, or omit action and use workflowScript.", mode: "management" };
154
+ return { ok: false, error: "action must be a non-empty management/control action, or omit action and use workflow.", mode: "management" };
135
155
  }
136
156
  const normalizedAction = typeof action === "string" ? action.trim() : undefined;
137
157
  if (params.baseRef !== undefined && normalizedAction !== undefined && normalizedAction !== "resume" && normalizedAction !== "schedule.create") {
@@ -141,55 +161,69 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
141
161
  return { ok: false, error: "Named workflow resource execution must omit action.", mode: "management" };
142
162
  }
143
163
  if (params.clarify !== undefined) {
144
- return { ok: false, error: "Public workflowScript execution does not support clarify UI.", mode: "workflow" };
164
+ return { ok: false, error: "Public workflow execution does not support clarify UI.", mode: "workflow" };
145
165
  }
146
166
  if (params.chainName !== undefined) {
147
- return { ok: false, error: "Durable chain management was removed; use workflowScript or /prompt-workflow for repeatable workflows.", mode: "management" };
167
+ return { ok: false, error: "Durable chain management was removed; use a workflow script or /prompt-workflow for repeatable workflows.", mode: "management" };
148
168
  }
149
169
  if (params.config && typeof params.config === "object" && !Array.isArray(params.config) && Object.prototype.hasOwnProperty.call(params.config, "steps")) {
150
- return { ok: false, error: "Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", mode: "management" };
170
+ return { ok: false, error: "Durable chain definitions were removed; use a workflow script or /prompt-workflow for repeatable workflows.", mode: "management" };
151
171
  }
152
172
  if (params.resume !== undefined) {
153
- return { ok: false, error: "Top-level resume execution is not available. Put resume on a workflowScript runs.run/runs.all item.", mode: "workflow" };
173
+ return { ok: false, error: "Top-level resume execution is not available. Put resume on a workflow script runs.run/runs.all item.", mode: "workflow" };
154
174
  }
155
- const hasLegacyOrchestration = params.tasks !== undefined || params.chain !== undefined || params.parallel !== undefined || params.concurrency !== undefined || params.chainDir !== undefined;
175
+ // action: "chain"/"tasks"/"parallel" stays a legacy error even where top-level chain/tasks are accepted.
176
+ const legacyOrchestrationAction = ["parallel", "tasks", "chain"].includes(normalizedAction?.toLowerCase() ?? "");
177
+ const hasStructuredWorkflow = options.structuredWorkflows === true && !legacyOrchestrationAction && (params.tasks !== undefined || params.chain !== undefined);
178
+ const hasLegacyOrchestration = (!hasStructuredWorkflow && (params.tasks !== undefined || params.chain !== undefined)) || params.parallel !== undefined || params.concurrency !== undefined || params.chainDir !== undefined;
156
179
  if (hasLegacyOrchestration) {
157
- return { ok: false, error: "Legacy top-level chain and parallel inputs were removed; use workflowScript.", mode: normalizedAction ? "management" : "workflow" };
180
+ return { ok: false, error: `Legacy top-level chain and parallel inputs were removed; use a workflow script (${RAW_SCRIPT_FORMS}).`, mode: normalizedAction ? "management" : "workflow" };
181
+ }
182
+ if (hasStructuredWorkflow) {
183
+ if (params.tasks !== undefined && params.chain !== undefined) {
184
+ return { ok: false, error: "Pass either tasks or chain, not both.", mode: "workflow" };
185
+ }
186
+ const field = params.tasks !== undefined ? "tasks" : "chain";
187
+ // workflow and workflowScript were already rejected by the workflow-scripts feature check.
188
+ for (const [name, value] of [["action", params.action], ["agent", params.agent], ["step", params.step]] as const) {
189
+ if (value !== undefined) return { ok: false, error: `${field} cannot be combined with ${name}.`, mode: normalizedAction ? "management" : "workflow" };
190
+ }
191
+ return { ok: true, params };
158
192
  }
159
193
  if (normalizedAction !== undefined) {
160
194
  const legacyAction = normalizedAction.toLowerCase();
161
195
  if (legacyAction === "append-step") {
162
- return { ok: false, error: "Legacy append-step control was removed from the public subagent tool; use current workflowScript orchestration.", mode: "management" };
196
+ return { ok: false, error: "Legacy append-step control was removed from the public subagent tool; use workflow script orchestration.", mode: "management" };
163
197
  }
164
198
  if (legacyAction === "approve-checkpoint" || legacyAction === "reject-checkpoint") {
165
- return { ok: false, error: "Legacy checkpoint approval controls were removed from the public subagent tool; use current workflowScript orchestration.", mode: "management" };
199
+ return { ok: false, error: "Legacy checkpoint approval controls were removed from the public subagent tool; use workflow script orchestration.", mode: "management" };
166
200
  }
167
201
  if (legacyAction === "single") {
168
202
  return { ok: false, error: "action='single' is not supported. Omit action and pass { agent, task } for one child.", mode: "workflow" };
169
203
  }
170
204
  if (legacyAction === "parallel" || legacyAction === "tasks" || legacyAction === "chain") {
171
- return { ok: false, error: "Legacy top-level chain and parallel inputs were removed; use workflowScript.", mode: "workflow" };
205
+ return { ok: false, error: `Legacy top-level chain and parallel inputs were removed; use a workflow script (${RAW_SCRIPT_FORMS}).`, mode: "workflow" };
172
206
  }
173
207
  if (normalizedAction === "validate") {
174
208
  if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
175
- return { ok: false, error: "validate requires workflowScript or workflowScriptPath and does not accept direct agent, task, or step execution fields.", mode: "management" };
209
+ return { ok: false, error: `validate requires ${RAW_SCRIPT_FORMS} and does not accept direct agent, task, or step execution fields.`, mode: "management" };
176
210
  }
177
211
  if (!hasValidWorkflowInput) {
178
- return { ok: false, error: "validate requires a non-empty workflowScript or workflowScriptPath.", mode: "management" };
212
+ return { ok: false, error: `validate requires ${RAW_SCRIPT_FORMS}.`, mode: "management" };
179
213
  }
180
214
  return { ok: true, params: { ...params, action: normalizedAction } };
181
215
  }
182
216
  if (normalizedAction === "schedule.create") {
183
217
  if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
184
- return { ok: false, error: "schedule.create requires workflowScript or workflowScriptPath and does not accept direct agent, task, or step execution fields.", mode: "management" };
218
+ return { ok: false, error: `schedule.create requires ${RAW_SCRIPT_FORMS} and does not accept direct agent, task, or step execution fields.`, mode: "management" };
185
219
  }
186
220
  if (!hasValidWorkflowInput) {
187
- return { ok: false, error: "schedule.create requires a non-empty workflowScript or workflowScriptPath.", mode: "management" };
221
+ return { ok: false, error: `schedule.create requires ${RAW_SCRIPT_FORMS}.`, mode: "management" };
188
222
  }
189
223
  return { ok: true, params: { ...params, action: normalizedAction } };
190
224
  }
191
225
  if (hasWorkflowInput) {
192
- return { ok: false, error: "Workflow execution must omit action; only validate and schedule.create accept action with workflowScript or workflowScriptPath.", mode: "management" };
226
+ return { ok: false, error: `Workflow execution must omit action; only validate and schedule.create accept action with ${RAW_SCRIPT_FORMS}.`, mode: "management" };
193
227
  }
194
228
  if (params.task !== undefined) {
195
229
  return { ok: false, error: "Structured single-child task cannot be combined with a management/control action.", mode: "management" };
@@ -197,10 +231,10 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
197
231
  return { ok: true, params: { ...params, action: normalizedAction } };
198
232
  }
199
233
  if (params.step !== undefined) {
200
- return { ok: false, error: "step is not a public execution field; use workflowScript for orchestration.", mode: "workflow" };
234
+ return { ok: false, error: `step is not a public execution field; use a workflow script (${RAW_SCRIPT_FORMS}) for orchestration.`, mode: "workflow" };
201
235
  }
202
236
  if (hasWorkflowInput && (params.agent !== undefined || params.task !== undefined)) {
203
- return { ok: false, error: "Structured single-child execution cannot be combined with workflow, workflowScript, or workflowScriptPath.", mode: "workflow" };
237
+ return { ok: false, error: "Structured single-child execution cannot be combined with workflow.", mode: "workflow" };
204
238
  }
205
239
  if (params.agent !== undefined || params.task !== undefined) {
206
240
  if (typeof params.agent !== "string" || !params.agent.trim()) {
@@ -219,7 +253,7 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
219
253
  };
220
254
  }
221
255
  if (!hasValidWorkflowInput) {
222
- return { ok: false, error: "Execution requires either { agent, task? } for one child, a named workflow resource, or a non-empty workflowScript or workflowScriptPath for orchestration.", mode: "workflow" };
256
+ return { ok: false, error: "Execution requires either { agent, task? } for one child or workflow (true, a script path, or a named workflow resource) for orchestration.", mode: "workflow" };
223
257
  }
224
258
  return { ok: true, params };
225
259
  }