@xzzpig/pi-subagents 0.16.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 (166) hide show
  1. package/CHANGELOG.md +233 -1
  2. package/README.md +5 -3
  3. package/agents/claude-code-writer.md +1 -0
  4. package/agents/codex-exec-writer.md +1 -0
  5. package/agents/cursor-agent-writer.md +1 -0
  6. package/agents/reviewer.md +3 -2
  7. package/agents/worker.md +3 -2
  8. package/docs/agents.md +34 -21
  9. package/docs/configuration.md +82 -7
  10. package/docs/extension-api.md +75 -8
  11. package/docs/missions.md +13 -13
  12. package/docs/models.md +7 -5
  13. package/docs/observability.md +23 -13
  14. package/docs/standalone-background.md +5 -5
  15. package/docs/tool-reference.md +98 -100
  16. package/docs/watchdog.md +2 -0
  17. package/docs/workflows.md +214 -162
  18. package/inspector-runner.mjs +1 -1
  19. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  20. package/package.json +15 -9
  21. package/prompts/council.md +6 -3
  22. package/prompts/review-loop.md +1 -1
  23. package/runner-peer-loader.mjs +4 -7
  24. package/runner-peer-preload.mjs +5 -7
  25. package/skills/council-mode/SKILL.md +1 -1
  26. package/skills/pi-subagents/SKILL.md +13 -5
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
  28. package/skills/pi-subagents/references/execution-controls.md +72 -69
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
  32. package/src/agents/advertised-agent-prompt.ts +21 -41
  33. package/src/agents/agent-eject.ts +3 -3
  34. package/src/agents/agent-management.ts +63 -54
  35. package/src/agents/agent-memory.ts +90 -3
  36. package/src/agents/agent-serializer.ts +4 -4
  37. package/src/agents/agents.ts +132 -51
  38. package/src/agents/global-npm-root.ts +58 -0
  39. package/src/agents/proactive-skills.ts +4 -1
  40. package/src/agents/runtime-agent-registry.ts +14 -11
  41. package/src/agents/skills.ts +42 -9
  42. package/src/api/delegation.ts +15 -0
  43. package/src/api/inspectors.ts +27 -0
  44. package/src/api/preflight.ts +7 -2
  45. package/src/extension/config.ts +12 -4
  46. package/src/extension/control-notices.ts +3 -0
  47. package/src/extension/doctor.ts +10 -4
  48. package/src/extension/fanout-child.ts +20 -3
  49. package/src/extension/herdr-pi-bridge.ts +2 -0
  50. package/src/extension/index.ts +168 -206
  51. package/src/extension/public-execution.ts +69 -35
  52. package/src/extension/reply-workflow-script.ts +58 -0
  53. package/src/extension/rpc.ts +39 -11
  54. package/src/extension/schemas.ts +47 -138
  55. package/src/extension/subagent-guide.ts +12 -4
  56. package/src/extension/tool-activation.ts +146 -0
  57. package/src/extension/tool-description.ts +62 -27
  58. package/src/extension/upgrade-notice.ts +40 -0
  59. package/src/inspectors/ghostty/plugin.ts +13 -1
  60. package/src/inspectors/plugins.ts +70 -3
  61. package/src/integrations/herdr-status.ts +19 -3
  62. package/src/intercom/intercom-bridge.ts +2 -0
  63. package/src/intercom/native-supervisor-channel.ts +26 -16
  64. package/src/intercom/result-intercom.ts +4 -0
  65. package/src/runs/background/active-async-capacity.ts +3 -25
  66. package/src/runs/background/async-execution.ts +60 -95
  67. package/src/runs/background/async-job-tracker.ts +91 -56
  68. package/src/runs/background/async-resume.ts +16 -8
  69. package/src/runs/background/async-retention.ts +46 -16
  70. package/src/runs/background/async-status.ts +2 -0
  71. package/src/runs/background/await-async-run.ts +76 -0
  72. package/src/runs/background/binary-bootstrap.ts +34 -6
  73. package/src/runs/background/chain-root-attachment.ts +4 -4
  74. package/src/runs/background/control-channel.ts +18 -2
  75. package/src/runs/background/fleet-view.ts +51 -7
  76. package/src/runs/background/notify.ts +98 -7
  77. package/src/runs/background/pid-namespace.ts +18 -0
  78. package/src/runs/background/process-terminal-candidate.ts +98 -0
  79. package/src/runs/background/process-terminal.ts +17 -96
  80. package/src/runs/background/result-watcher.ts +1 -1
  81. package/src/runs/background/retained-children.ts +3 -2
  82. package/src/runs/background/run-child-session.ts +20 -6
  83. package/src/runs/background/run-id-resolver.ts +10 -5
  84. package/src/runs/background/run-status.ts +16 -4
  85. package/src/runs/background/runner-aliases.ts +54 -16
  86. package/src/runs/background/runner-child-launch.ts +4 -2
  87. package/src/runs/background/runner-startup-failure.ts +56 -0
  88. package/src/runs/background/scheduled-runs.ts +5 -5
  89. package/src/runs/background/stale-run-reconciler.ts +19 -3
  90. package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
  91. package/src/runs/background/subagent-runner.ts +111 -288
  92. package/src/runs/background/wait-tool.ts +2 -0
  93. package/src/runs/background/workflow-terminal-proof.ts +68 -0
  94. package/src/runs/foreground/async-stop-action.ts +17 -3
  95. package/src/runs/foreground/execution.ts +111 -139
  96. package/src/runs/foreground/prompt-audit.ts +3 -9
  97. package/src/runs/foreground/subagent-executor.ts +715 -258
  98. package/src/runs/shared/acceptance.ts +167 -68
  99. package/src/runs/shared/async-status-projection.ts +5 -0
  100. package/src/runs/shared/capability-ceiling.ts +4 -1
  101. package/src/runs/shared/child-hooks.ts +1 -16
  102. package/src/runs/shared/child-launch.ts +37 -16
  103. package/src/runs/shared/child-runtime-config.ts +3 -0
  104. package/src/runs/shared/child-session.ts +144 -8
  105. package/src/runs/shared/child-tool-plan.ts +38 -116
  106. package/src/runs/shared/dynamic-fanout.ts +1 -1
  107. package/src/runs/shared/external-cli-runner.ts +3 -1
  108. package/src/runs/shared/external-job-bridge.ts +54 -0
  109. package/src/runs/shared/git-environment.ts +29 -0
  110. package/src/runs/shared/mcp-config-sources.ts +5 -1
  111. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
  112. package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
  113. package/src/runs/shared/model-resolution.ts +35 -10
  114. package/src/runs/shared/model-scope.ts +28 -9
  115. package/src/runs/shared/nested-events.ts +12 -0
  116. package/src/runs/shared/orca-progress-tabs.ts +3 -2
  117. package/src/runs/shared/parallel-utils.ts +4 -1
  118. package/src/runs/shared/pi-spawn.ts +1 -3
  119. package/src/runs/shared/single-output.ts +11 -2
  120. package/src/runs/shared/structured-output.ts +227 -7
  121. package/src/runs/shared/subagent-control.ts +2 -16
  122. package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
  123. package/src/runs/shared/tool-availability.ts +2 -2
  124. package/src/runs/shared/tool-budget.ts +21 -0
  125. package/src/runs/shared/usage-reconciliation.ts +73 -0
  126. package/src/runs/shared/worktree.ts +36 -9
  127. package/src/shared/child-session-name.ts +4 -2
  128. package/src/shared/disabled-features.ts +123 -0
  129. package/src/shared/extension-context.ts +13 -0
  130. package/src/shared/fork-context.ts +11 -4
  131. package/src/shared/launch-contract.ts +1 -1
  132. package/src/shared/model-info.ts +9 -0
  133. package/src/shared/pruned-fork.ts +69 -56
  134. package/src/shared/settings.ts +1 -1
  135. package/src/shared/types.ts +73 -16
  136. package/src/slash/delegation-adapters.ts +25 -1
  137. package/src/slash/prompt-template-bridge.ts +18 -3
  138. package/src/slash/prompt-workflows.ts +12 -1
  139. package/src/slash/slash-commands.ts +17 -246
  140. package/src/slash/subagent-cost.ts +313 -0
  141. package/src/slash/subagents-admin.ts +4 -5
  142. package/src/tui/fleet-status.ts +38 -8
  143. package/src/tui/fleet.ts +21 -6
  144. package/src/tui/render.ts +166 -71
  145. package/src/tui/running-tone.ts +28 -0
  146. package/src/watchdog/diff-tool.ts +47 -12
  147. package/src/watchdog/permission-arbiter.ts +13 -15
  148. package/src/watchdog/register-child.ts +13 -5
  149. package/src/watchdog/register-main.ts +3 -3
  150. package/src/watchdog/review.ts +16 -16
  151. package/src/watchdog/runtime.ts +2 -1
  152. package/src/watchdog/turn-delta.ts +12 -6
  153. package/src/workflows/chat-progress.ts +2 -2
  154. package/src/workflows/scripted-workflow.ts +225 -59
  155. package/src/workflows/structured-workflow-scripts.ts +177 -0
  156. package/src/workflows/workflow-checklist.ts +6 -0
  157. package/src/workflows/workflow-child-summary.ts +4 -2
  158. package/src/workflows/workflow-receipt.ts +8 -2
  159. package/src/workflows/workflow-resources.ts +37 -12
  160. package/src/workflows/workflow-reuse.ts +120 -0
  161. package/src/workflows/workflow-revival.ts +123 -0
  162. package/src/workflows/workflow-settlement.ts +4 -1
  163. package/src/runs/shared/completion-evidence.ts +0 -89
  164. package/src/runs/shared/completion-guard.ts +0 -255
  165. package/src/runs/shared/llm-intent-arbiter.ts +0 -321
  166. package/src/runs/shared/task-intent.ts +0 -244
@@ -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
  }
@@ -0,0 +1,58 @@
1
+ import type { AssistantMessage } from "@earendil-works/pi-ai";
2
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
3
+
4
+ const WORKFLOW_FENCE = /^```(?:js|javascript) workflow[ \t]*$/;
5
+ const OPEN_FENCE = /^(`{3,}|~{3,})/;
6
+ const CLOSE_FENCE = /^(`{3,}|~{3,})[ \t]*$/;
7
+
8
+ export type ReplyWorkflowScript = { script: string } | { error: string };
9
+
10
+ /**
11
+ * Pi persists the whole assistant message before running its tool calls, so the
12
+ * message that issued this subagent call is on the branch and carries the script.
13
+ */
14
+ export function readReplyWorkflowScript(sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch">, toolCallId: string): ReplyWorkflowScript {
15
+ const branch = sessionManager.getBranch();
16
+ for (let index = branch.length - 1; index >= 0; index--) {
17
+ const entry = branch[index]!;
18
+ if (entry.type !== "message") continue;
19
+ const message = entry.message;
20
+ if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
21
+ if (!message.content.some((block) => block.type === "toolCall" && block.id === toolCallId)) continue;
22
+ return scriptFromReply(message.content);
23
+ }
24
+ return { error: "workflow: true only works from a model subagent tool call whose assistant message contains the ```js workflow block; other callers must pass a script path such as workflow: \"./script.js\"." };
25
+ }
26
+
27
+ function scriptFromReply(content: AssistantMessage["content"]): ReplyWorkflowScript {
28
+ const replyCalls = content.filter((block) => block.type === "toolCall" && block.name === "subagent"
29
+ && block.arguments?.workflow === true).length;
30
+ if (replyCalls > 1) return { error: `This reply has ${replyCalls} subagent calls with workflow: true; a reply can carry only one. Pass other scripts as workflow file paths.` };
31
+ const text = content.flatMap((block) => block.type === "text" && typeof block.text === "string" ? [block.text] : []).join("\n");
32
+ const { blocks, unclosed } = workflowBlocks(text);
33
+ if (unclosed) return { error: "The ```js workflow block in this reply is not closed." };
34
+ if (blocks.length !== 1) return { error: `workflow: true requires exactly one \`\`\`js workflow fenced block in the same reply as the tool call; found ${blocks.length}.` };
35
+ const script = blocks[0]!;
36
+ if (!script.trim()) return { error: "The ```js workflow block in this reply is empty." };
37
+ return { script };
38
+ }
39
+
40
+ /** Collects ```js workflow / ```javascript workflow fenced blocks, skipping the bodies of other fences. */
41
+ function workflowBlocks(text: string): { blocks: string[]; unclosed: boolean } {
42
+ const lines = text.split("\n");
43
+ const blocks: string[] = [];
44
+ let fence: { marker: string; tagged: boolean; start: number } | undefined;
45
+ for (let index = 0; index < lines.length; index++) {
46
+ const line = lines[index]!.replace(/\r$/, "");
47
+ if (!fence) {
48
+ const open = OPEN_FENCE.exec(line);
49
+ if (open) fence = { marker: open[1]!, tagged: WORKFLOW_FENCE.test(line), start: index + 1 };
50
+ continue;
51
+ }
52
+ const close = CLOSE_FENCE.exec(line);
53
+ if (!close || close[1]![0] !== fence.marker[0] || close[1]!.length < fence.marker.length) continue;
54
+ if (fence.tagged) blocks.push(lines.slice(fence.start, index).join("\n"));
55
+ fence = undefined;
56
+ }
57
+ return { blocks, unclosed: fence?.tagged === true };
58
+ }
@@ -22,7 +22,9 @@ import {
22
22
  import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.ts";
23
23
  import { readStatus } from "../shared/utils.ts";
24
24
  import { SubagentParams } from "./schemas.ts";
25
+ import { disabledFeatureUseError, type DisabledFeatureSurface } from "../shared/disabled-features.ts";
25
26
  import { normalizePublicSubagentExecution } from "./public-execution.ts";
27
+ import { collectSubagentCost, SUBAGENT_COST_REPORT_VERSION } from "../slash/subagent-cost.ts";
26
28
  import { ASYNC_STATUS_SNAPSHOT_KIND, ASYNC_STATUS_SNAPSHOT_VERSION, buildAsyncStatusSnapshotForState } from "../runs/background/async-status-snapshot.ts";
27
29
  import { isStoppableAsyncStatusStep, resolveAsyncStatusChild, stopStoppableAsyncStatusChildren, type ResolvedAsyncStatusChild } from "../runs/shared/child-identity.ts";
28
30
 
@@ -31,7 +33,7 @@ export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
31
33
  export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
32
34
  export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
33
35
 
34
- export const SUBAGENT_RPC_METHODS = ["ping", "status", "manage", "spawn", "steer", "interrupt", "stop", "resume"] as const;
36
+ export const SUBAGENT_RPC_METHODS = ["ping", "status", "manage", "spawn", "steer", "interrupt", "stop", "resume", "cost"] as const;
35
37
  export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
36
38
 
37
39
  export interface SubagentRpcRequestEnvelope {
@@ -317,6 +319,11 @@ interface RegisterSubagentRpcBridgeOptions {
317
319
  now?: () => number;
318
320
  /** Native live state, projected into the optional public fleet-status capability. */
319
321
  state?: SubagentState;
322
+ disabledFeatures?: DisabledFeatureSurface;
323
+ }
324
+
325
+ function enabledManagementActions(options: RegisterSubagentRpcBridgeOptions): string[] {
326
+ return SUBAGENT_RPC_MANAGEMENT_ACTIONS.filter((action) => !options.disabledFeatures?.actions.has(action));
320
327
  }
321
328
 
322
329
  class SubagentRpcError extends Error {
@@ -437,14 +444,14 @@ function sessionData(ctx: ExtensionContext | null): { cwd?: string; sessionId?:
437
444
  };
438
445
  }
439
446
 
440
- function pingData(ctx: ExtensionContext | null) {
447
+ function pingData(ctx: ExtensionContext | null, options: RegisterSubagentRpcBridgeOptions) {
441
448
  return {
442
449
  version: SUBAGENT_RPC_PROTOCOL_VERSION,
443
450
  methods: [...SUBAGENT_RPC_METHODS],
444
451
  capabilities: {
445
452
  status: true,
446
453
  statusProjection: { version: 1, untargeted: "in-memory-when-ready", targeted: "executor" },
447
- managementActions: [...SUBAGENT_RPC_MANAGEMENT_ACTIONS],
454
+ managementActions: enabledManagementActions(options),
448
455
  fleetStatus: { version: 1 },
449
456
  asyncStatusSnapshot: { kind: ASYNC_STATUS_SNAPSHOT_KIND, version: ASYNC_STATUS_SNAPSHOT_VERSION },
450
457
  asyncSpawn: true,
@@ -456,6 +463,7 @@ function pingData(ctx: ExtensionContext | null) {
456
463
  launchResolvedExtensions: { version: 1, source: "launch-resolved" },
457
464
  runtimeAcknowledgedExtensions: { version: 1, source: "child-runtime", event: "subagent:acknowledge-extension" },
458
465
  processTerminalProof: { version: 1, lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION },
466
+ cost: { version: SUBAGENT_COST_REPORT_VERSION },
459
467
  },
460
468
  events: {
461
469
  ready: SUBAGENT_RPC_READY_EVENT,
@@ -483,12 +491,13 @@ async function executeChecked(
483
491
  return dataFromToolResult(result);
484
492
  }
485
493
 
486
- function manageParams(params: unknown): SubagentParamsLike {
494
+ function manageParams(params: unknown, options: RegisterSubagentRpcBridgeOptions): SubagentParamsLike {
487
495
  const input = assertRecordParams(params, "manage");
488
496
  if (typeof input.action !== "string" || !(SUBAGENT_RPC_MANAGEMENT_ACTIONS as readonly string[]).includes(input.action)) {
497
+ const enabled = enabledManagementActions(options);
489
498
  throw new SubagentRpcError(
490
499
  "invalid_params",
491
- `RPC manage action must be one of: ${SUBAGENT_RPC_MANAGEMENT_ACTIONS.join(", ")}.`,
500
+ enabled.length > 0 ? `RPC manage action must be one of: ${enabled.join(", ")}.` : "RPC manage actions are all disabled by config.",
492
501
  );
493
502
  }
494
503
  if (input.id !== undefined && (typeof input.id !== "string" || !input.id.trim())) {
@@ -511,8 +520,20 @@ function manageParams(params: unknown): SubagentParamsLike {
511
520
  return output;
512
521
  }
513
522
 
514
- function spawnParams(params: unknown): SubagentParamsLike {
515
- const input = assertRecordParams(params, "spawn");
523
+ function spawnParams(params: unknown, options: RegisterSubagentRpcBridgeOptions): SubagentParamsLike {
524
+ const { script, ...input } = assertRecordParams(params, "spawn");
525
+ if (Object.hasOwn(input, "workflowScript")) throw new SubagentRpcError("invalid_params", "RPC spawn workflowScript was removed; pass inline script text as script.");
526
+ if (Object.hasOwn(input, "workflowScriptPath")) throw new SubagentRpcError("invalid_params", "RPC spawn workflowScriptPath was removed; pass the file as workflow: \"./path/to/script.js\".");
527
+ if (input.workflow === true) throw new SubagentRpcError("invalid_params", "RPC spawn has no reply block for workflow: true; pass inline script text as script or a file as workflow: \"./path/to/script.js\".");
528
+ if (script !== undefined) {
529
+ if (typeof script !== "string" || !script.trim()) throw new SubagentRpcError("invalid_params", "RPC spawn script must be a non-empty string.");
530
+ if (input.workflow !== undefined) throw new SubagentRpcError("invalid_params", "RPC spawn script cannot be combined with workflow.");
531
+ // The executor's internal carrier; the model-facing tool cannot set it.
532
+ input.workflowScript = script;
533
+ }
534
+ // With workflow scripts disabled, name the setting before normalization can report a script-shape error instead.
535
+ const disabledFeatureError = options.disabledFeatures?.features.has("workflow-scripts") ? disabledFeatureUseError(input, options.disabledFeatures, "RPC spawn") : undefined;
536
+ if (disabledFeatureError) throw new SubagentRpcError("invalid_params", disabledFeatureError);
516
537
  const normalized = normalizePublicSubagentExecution(input);
517
538
  if (!normalized.ok) throw new SubagentRpcError("invalid_params", normalized.error);
518
539
  if (normalized.params.action !== undefined) {
@@ -706,14 +727,14 @@ async function handleRequest(
706
727
  fleetKeys: FleetKeyState,
707
728
  ): Promise<unknown> {
708
729
  const ctx = options.getContext();
709
- if (request.method === "ping") return pingData(ctx);
730
+ if (request.method === "ping") return pingData(ctx, options);
710
731
  if (!ctx) throw new SubagentRpcError("no_active_session", "No active extension context for subagent RPC.");
711
732
 
712
733
  if (request.method === "manage") {
713
- return executeChecked(options, ctx, request.requestId, request.method, manageParams(request.params));
734
+ return executeChecked(options, ctx, request.requestId, request.method, manageParams(request.params, options));
714
735
  }
715
736
  if (request.method === "spawn") {
716
- return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params));
737
+ return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params, options));
717
738
  }
718
739
  if (request.method === "status") {
719
740
  const statusParams = normalizeStatusParams(request.params);
@@ -765,6 +786,13 @@ async function handleRequest(
765
786
  if (request.method === "resume") {
766
787
  return executeChecked(options, ctx, request.requestId, request.method, resumeParams(request.params));
767
788
  }
789
+ if (request.method === "cost") {
790
+ // The same parent-plus-child accounting `/subagent-cost` renders, as data.
791
+ // Read-only: it walks the current session branch and existing artifacts,
792
+ // so callers should request it on their own turn boundaries, not on a timer.
793
+ if (request.params !== undefined && !isRecord(request.params)) throw new SubagentRpcError("invalid_params", "RPC cost params must be an object when provided.");
794
+ return collectSubagentCost(ctx, options.state ?? { baseCwd: ctx.cwd });
795
+ }
768
796
  throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
769
797
  }
770
798
 
@@ -839,7 +867,7 @@ export function registerSubagentRpcBridge(options: RegisterSubagentRpcBridgeOpti
839
867
 
840
868
  return {
841
869
  emitReady: (ctx) => {
842
- options.events.emit(SUBAGENT_RPC_READY_EVENT, pingData(ctx ?? options.getContext()));
870
+ options.events.emit(SUBAGENT_RPC_READY_EVENT, pingData(ctx ?? options.getContext(), options));
843
871
  },
844
872
  dispose: () => {
845
873
  if (typeof unsubscribe === "function") unsubscribe();