@xzzpig/pi-subagents 0.1.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 (196) hide show
  1. package/CHANGELOG.md +1621 -0
  2. package/LICENSE +21 -0
  3. package/README.md +118 -0
  4. package/agents/delegate.md +14 -0
  5. package/agents/oracle.md +74 -0
  6. package/agents/researcher.md +52 -0
  7. package/agents/reviewer.md +79 -0
  8. package/agents/scout.md +50 -0
  9. package/agents/worker.md +58 -0
  10. package/index.ts +1 -0
  11. package/inspector-runner.mjs +11 -0
  12. package/install.mjs +93 -0
  13. package/package.json +105 -0
  14. package/prompts/gather-context-and-clarify.md +13 -0
  15. package/prompts/parallel-cleanup.md +59 -0
  16. package/prompts/parallel-research.md +50 -0
  17. package/prompts/parallel-review.md +54 -0
  18. package/prompts/review-loop.md +43 -0
  19. package/skills/pi-subagents/SKILL.md +41 -0
  20. package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
  21. package/skills/pi-subagents/references/execution-controls.md +428 -0
  22. package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
  24. package/src/agents/agent-management.ts +1256 -0
  25. package/src/agents/agent-memory.ts +254 -0
  26. package/src/agents/agent-refinements.ts +624 -0
  27. package/src/agents/agent-scope.ts +6 -0
  28. package/src/agents/agent-selection.ts +25 -0
  29. package/src/agents/agent-serializer.ts +163 -0
  30. package/src/agents/agents.ts +1889 -0
  31. package/src/agents/chain-serializer.ts +280 -0
  32. package/src/agents/frontmatter.ts +149 -0
  33. package/src/agents/identity.ts +30 -0
  34. package/src/agents/proactive-skills.ts +194 -0
  35. package/src/agents/skills.ts +761 -0
  36. package/src/api/background-work.ts +197 -0
  37. package/src/api/capability-ceiling.ts +17 -0
  38. package/src/api/control-channel.ts +4 -0
  39. package/src/api/delegation.ts +119 -0
  40. package/src/api/external-runs.ts +129 -0
  41. package/src/api/intercom-bridge.ts +3 -0
  42. package/src/api/pi-args.ts +5 -0
  43. package/src/api/preflight.ts +403 -0
  44. package/src/api/shared-types.ts +19 -0
  45. package/src/extension/config.ts +76 -0
  46. package/src/extension/control-notices.ts +58 -0
  47. package/src/extension/doctor.ts +230 -0
  48. package/src/extension/fanout-child.ts +201 -0
  49. package/src/extension/index.ts +805 -0
  50. package/src/extension/public-execution.ts +71 -0
  51. package/src/extension/rpc.ts +653 -0
  52. package/src/extension/schemas.ts +375 -0
  53. package/src/extension/steering-notices.ts +35 -0
  54. package/src/extension/tool-description.ts +164 -0
  55. package/src/inspectors/herdr/actions.ts +229 -0
  56. package/src/inspectors/herdr/client.ts +130 -0
  57. package/src/inspectors/herdr/inspector-runner.ts +141 -0
  58. package/src/inspectors/herdr/project-panes.ts +154 -0
  59. package/src/integrations/herdr-status.ts +330 -0
  60. package/src/intercom/intercom-bridge.ts +187 -0
  61. package/src/intercom/native-supervisor-channel.ts +715 -0
  62. package/src/intercom/result-intercom.ts +421 -0
  63. package/src/missions/actions.ts +410 -0
  64. package/src/missions/goal-driver.ts +162 -0
  65. package/src/missions/lifecycle.ts +346 -0
  66. package/src/missions/store.ts +507 -0
  67. package/src/missions/types.ts +157 -0
  68. package/src/missions/workflow-state.ts +250 -0
  69. package/src/policy/authority.ts +46 -0
  70. package/src/profiles/profiles.ts +661 -0
  71. package/src/runs/background/async-execution.ts +1574 -0
  72. package/src/runs/background/async-job-tracker.ts +511 -0
  73. package/src/runs/background/async-resume.ts +539 -0
  74. package/src/runs/background/async-status.ts +542 -0
  75. package/src/runs/background/auto-drain.ts +67 -0
  76. package/src/runs/background/chain-append.ts +328 -0
  77. package/src/runs/background/chain-root-attachment.ts +199 -0
  78. package/src/runs/background/completion-batcher.ts +168 -0
  79. package/src/runs/background/completion-dedupe.ts +54 -0
  80. package/src/runs/background/control-channel.ts +692 -0
  81. package/src/runs/background/fleet-view.ts +540 -0
  82. package/src/runs/background/notify.ts +332 -0
  83. package/src/runs/background/parallel-groups.ts +45 -0
  84. package/src/runs/background/process-terminal.ts +280 -0
  85. package/src/runs/background/result-watcher.ts +414 -0
  86. package/src/runs/background/retained-children.ts +68 -0
  87. package/src/runs/background/run-id-resolver.ts +167 -0
  88. package/src/runs/background/run-status.ts +504 -0
  89. package/src/runs/background/scheduled-runs.ts +753 -0
  90. package/src/runs/background/stale-run-reconciler.ts +396 -0
  91. package/src/runs/background/steering.ts +239 -0
  92. package/src/runs/background/subagent-runner.ts +4718 -0
  93. package/src/runs/background/subagent-wait.ts +661 -0
  94. package/src/runs/background/top-level-async.ts +14 -0
  95. package/src/runs/background/wait-completions.ts +112 -0
  96. package/src/runs/background/wait-config.ts +36 -0
  97. package/src/runs/background/wait-subscriptions.ts +253 -0
  98. package/src/runs/background/wait-tool.ts +34 -0
  99. package/src/runs/foreground/async-steering-action.ts +256 -0
  100. package/src/runs/foreground/async-stop-action.ts +65 -0
  101. package/src/runs/foreground/chain-clarify.ts +1354 -0
  102. package/src/runs/foreground/chain-execution.ts +1527 -0
  103. package/src/runs/foreground/execution.ts +1868 -0
  104. package/src/runs/foreground/foreground-control.ts +132 -0
  105. package/src/runs/foreground/subagent-executor.ts +5532 -0
  106. package/src/runs/shared/acceptance.ts +1365 -0
  107. package/src/runs/shared/agent-contract.ts +38 -0
  108. package/src/runs/shared/capability-ceiling.ts +209 -0
  109. package/src/runs/shared/chain-outputs.ts +118 -0
  110. package/src/runs/shared/child-protocol.ts +401 -0
  111. package/src/runs/shared/completion-guard.ts +95 -0
  112. package/src/runs/shared/context-mode.ts +44 -0
  113. package/src/runs/shared/dynamic-fanout.ts +297 -0
  114. package/src/runs/shared/external-cli-runner.ts +130 -0
  115. package/src/runs/shared/long-running-guard.ts +220 -0
  116. package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
  117. package/src/runs/shared/model-fallback.ts +336 -0
  118. package/src/runs/shared/model-scope.ts +128 -0
  119. package/src/runs/shared/nested-events.ts +1076 -0
  120. package/src/runs/shared/nested-path.ts +52 -0
  121. package/src/runs/shared/nested-render.ts +123 -0
  122. package/src/runs/shared/parallel-handoff.ts +238 -0
  123. package/src/runs/shared/parallel-utils.ts +256 -0
  124. package/src/runs/shared/permissions.ts +95 -0
  125. package/src/runs/shared/pi-args.ts +808 -0
  126. package/src/runs/shared/pi-spawn.ts +163 -0
  127. package/src/runs/shared/process-signal.ts +19 -0
  128. package/src/runs/shared/run-history.ts +181 -0
  129. package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
  130. package/src/runs/shared/session-lease.ts +299 -0
  131. package/src/runs/shared/single-output.ts +235 -0
  132. package/src/runs/shared/spawn-budget.ts +128 -0
  133. package/src/runs/shared/structured-output.ts +182 -0
  134. package/src/runs/shared/subagent-control.ts +231 -0
  135. package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
  136. package/src/runs/shared/subagent-startup-retry.ts +104 -0
  137. package/src/runs/shared/task-intent.ts +181 -0
  138. package/src/runs/shared/tool-availability.ts +83 -0
  139. package/src/runs/shared/tool-budget.ts +80 -0
  140. package/src/runs/shared/turn-budget.ts +98 -0
  141. package/src/runs/shared/usage-budget.ts +65 -0
  142. package/src/runs/shared/workflow-graph.ts +231 -0
  143. package/src/runs/shared/worktree.ts +759 -0
  144. package/src/shared/accessible-dir.ts +47 -0
  145. package/src/shared/artifacts.ts +285 -0
  146. package/src/shared/atomic-json.ts +61 -0
  147. package/src/shared/child-transcript.ts +264 -0
  148. package/src/shared/file-coalescer.ts +40 -0
  149. package/src/shared/file-system-retry.ts +47 -0
  150. package/src/shared/fork-context.ts +213 -0
  151. package/src/shared/formatters.ts +133 -0
  152. package/src/shared/jsonl-writer.ts +81 -0
  153. package/src/shared/launch-contract.ts +124 -0
  154. package/src/shared/model-info.ts +81 -0
  155. package/src/shared/post-exit-stdio-guard.ts +85 -0
  156. package/src/shared/session-identity.ts +10 -0
  157. package/src/shared/session-tokens.ts +44 -0
  158. package/src/shared/settings.ts +501 -0
  159. package/src/shared/status-format.ts +55 -0
  160. package/src/shared/types.ts +2069 -0
  161. package/src/shared/utils.ts +613 -0
  162. package/src/slash/delegation-adapters.ts +434 -0
  163. package/src/slash/delegation-json.ts +108 -0
  164. package/src/slash/delegation-request.ts +166 -0
  165. package/src/slash/prompt-template-bridge.ts +383 -0
  166. package/src/slash/prompt-workflows.ts +300 -0
  167. package/src/slash/selector.ts +147 -0
  168. package/src/slash/slash-bridge.ts +192 -0
  169. package/src/slash/slash-commands.ts +994 -0
  170. package/src/slash/slash-live-state.ts +296 -0
  171. package/src/slash/subagents-admin.ts +432 -0
  172. package/src/tui/fleet-status.ts +564 -0
  173. package/src/tui/fleet-transcript.ts +577 -0
  174. package/src/tui/fleet.ts +879 -0
  175. package/src/tui/render-helpers.ts +80 -0
  176. package/src/tui/render.ts +2029 -0
  177. package/src/types/pi-runtime-compat.d.ts +8 -0
  178. package/src/watchdog/change-signature.ts +220 -0
  179. package/src/watchdog/child-status.ts +205 -0
  180. package/src/watchdog/emission-guard.ts +123 -0
  181. package/src/watchdog/lsp-diagnostics.ts +537 -0
  182. package/src/watchdog/model-selection.ts +167 -0
  183. package/src/watchdog/permission-arbiter.ts +145 -0
  184. package/src/watchdog/register-child.ts +117 -0
  185. package/src/watchdog/register-main.ts +440 -0
  186. package/src/watchdog/render.ts +54 -0
  187. package/src/watchdog/review.ts +302 -0
  188. package/src/watchdog/runtime.ts +868 -0
  189. package/src/watchdog/scope.ts +62 -0
  190. package/src/watchdog/settings.ts +568 -0
  191. package/src/watchdog/tool-actions.ts +155 -0
  192. package/src/watchdog/turn-delta.ts +161 -0
  193. package/src/watchdog/types.ts +198 -0
  194. package/src/watchdog/warning-format.ts +73 -0
  195. package/src/workflows/chat-progress.ts +140 -0
  196. package/src/workflows/scripted-workflow.ts +506 -0
@@ -0,0 +1,296 @@
1
+ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
2
+ import type { Message } from "@earendil-works/pi-ai";
3
+ import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
4
+ import { previewSimpleWorkflowRun } from "../workflows/scripted-workflow.ts";
5
+ import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
6
+ import { type Details, type SingleResult, type Usage, SLASH_RESULT_TYPE } from "../shared/types.ts";
7
+
8
+ export interface SlashMessageDetails {
9
+ requestId: string;
10
+ result: AgentToolResult<Details>;
11
+ }
12
+
13
+ interface SlashSnapshot {
14
+ result: AgentToolResult<Details>;
15
+ version: number;
16
+ }
17
+
18
+ interface SequentialChainStepLike {
19
+ agent: string;
20
+ task?: string;
21
+ }
22
+
23
+ interface ParallelChainStepLike {
24
+ parallel: Array<{ agent: string; task?: string }>;
25
+ }
26
+
27
+ type ChainStepLike = SequentialChainStepLike | ParallelChainStepLike;
28
+
29
+ const liveSnapshots = new Map<string, SlashSnapshot>();
30
+ const finalSnapshots = new Map<string, SlashSnapshot>();
31
+ let versionCounter = 1;
32
+
33
+ const EMPTY_MESSAGES: Message[] = [];
34
+ const EMPTY_USAGE: Usage = {
35
+ input: 0,
36
+ output: 0,
37
+ cacheRead: 0,
38
+ cacheWrite: 0,
39
+ cost: 0,
40
+ turns: 0,
41
+ };
42
+
43
+ function nextVersion(): number {
44
+ return versionCounter++;
45
+ }
46
+
47
+ function cloneUsage(): Usage {
48
+ return { ...EMPTY_USAGE };
49
+ }
50
+
51
+ function createPlaceholderResult(
52
+ agent: string,
53
+ task: string,
54
+ status: "pending" | "running",
55
+ index: number,
56
+ ): SingleResult {
57
+ return {
58
+ agent,
59
+ task,
60
+ index,
61
+ exitCode: 0,
62
+ messages: EMPTY_MESSAGES,
63
+ usage: cloneUsage(),
64
+ progress: {
65
+ index,
66
+ agent,
67
+ status,
68
+ task,
69
+ recentTools: [],
70
+ recentOutput: [],
71
+ toolCount: 0,
72
+ tokens: 0,
73
+ durationMs: 0,
74
+ },
75
+ };
76
+ }
77
+
78
+ function buildParallelInitialResult(params: SubagentParamsLike): AgentToolResult<Details> {
79
+ const tasks = params.tasks ?? [];
80
+ return {
81
+ content: [{ type: "text", text: tasks.map((task) => `${task.agent}: ${task.task}`).join("\n\n") }],
82
+ details: {
83
+ mode: "parallel",
84
+ ...(params.context ? { context: params.context } : {}),
85
+ results: tasks.map((task, index) => createPlaceholderResult(task.agent, task.task, "running", index)),
86
+ progress: tasks.map((task, index) => ({
87
+ index,
88
+ agent: task.agent,
89
+ status: "running" as const,
90
+ task: task.task,
91
+ recentTools: [],
92
+ recentOutput: [],
93
+ toolCount: 0,
94
+ tokens: 0,
95
+ durationMs: 0,
96
+ })),
97
+ },
98
+ };
99
+ }
100
+
101
+ function isParallelChainStep(step: ChainStepLike): step is ParallelChainStepLike {
102
+ return "parallel" in step && Array.isArray(step.parallel);
103
+ }
104
+
105
+ function chainStepLabel(step: ChainStepLike): string {
106
+ if (isParallelChainStep(step)) {
107
+ return `[${step.parallel.map((entry) => entry.agent).join("+")}]`;
108
+ }
109
+ return step.agent;
110
+ }
111
+
112
+ function flattenChainResults(chain: ChainStepLike[], fallbackTask: string | undefined): SingleResult[] {
113
+ const results: SingleResult[] = [];
114
+ let flatIndex = 0;
115
+ for (const step of chain) {
116
+ if (isParallelChainStep(step)) {
117
+ for (const task of step.parallel) {
118
+ results.push(createPlaceholderResult(task.agent, task.task ?? fallbackTask ?? "", results.length === 0 ? "running" : "pending", flatIndex));
119
+ flatIndex++;
120
+ }
121
+ continue;
122
+ }
123
+ results.push(createPlaceholderResult(step.agent, step.task ?? fallbackTask ?? "", results.length === 0 ? "running" : "pending", flatIndex));
124
+ flatIndex++;
125
+ }
126
+ return results;
127
+ }
128
+
129
+ function buildChainInitialResult(params: SubagentParamsLike): AgentToolResult<Details> {
130
+ const chain = (params.chain ?? []) as ChainStepLike[];
131
+ const results = flattenChainResults(chain, params.task);
132
+ return {
133
+ content: [{
134
+ type: "text",
135
+ text: results.map((result, index) => `Step ${index + 1}: ${result.agent}\n${result.task}`).join("\n\n"),
136
+ }],
137
+ details: {
138
+ mode: "chain",
139
+ ...(params.context ? { context: params.context } : {}),
140
+ results,
141
+ progress: results.map((result, index) => ({
142
+ index,
143
+ agent: result.agent,
144
+ status: index === 0 ? "running" as const : "pending" as const,
145
+ task: result.task,
146
+ recentTools: [],
147
+ recentOutput: [],
148
+ toolCount: 0,
149
+ tokens: 0,
150
+ durationMs: 0,
151
+ })),
152
+ chainAgents: chain.map((step) => chainStepLabel(step)),
153
+ totalSteps: chain.length,
154
+ currentStepIndex: 0,
155
+ },
156
+ };
157
+ }
158
+
159
+ function buildSingleInitialResult(params: SubagentParamsLike): AgentToolResult<Details> {
160
+ const preview = previewSimpleWorkflowRun(params.workflowScript) ?? {};
161
+ const agent = params.agent ?? preview.agent ?? "subagent";
162
+ const task = params.task ?? preview.task ?? "";
163
+ return {
164
+ content: [{ type: "text", text: task }],
165
+ details: {
166
+ mode: "single",
167
+ ...(params.context ? { context: params.context } : {}),
168
+ results: [createPlaceholderResult(agent, task, "running", 0)],
169
+ progress: [{
170
+ index: 0,
171
+ agent,
172
+ status: "running",
173
+ task,
174
+ recentTools: [],
175
+ recentOutput: [],
176
+ toolCount: 0,
177
+ tokens: 0,
178
+ durationMs: 0,
179
+ }],
180
+ },
181
+ };
182
+ }
183
+
184
+ export function buildSlashInitialResult(requestId: string, params: SubagentParamsLike): SlashMessageDetails {
185
+ const result = (params.tasks?.length ?? 0) > 0
186
+ ? buildParallelInitialResult(params)
187
+ : (params.chain?.length ?? 0) > 0
188
+ ? buildChainInitialResult(params)
189
+ : buildSingleInitialResult(params);
190
+ liveSnapshots.set(requestId, { result, version: nextVersion() });
191
+ finalSnapshots.delete(requestId);
192
+ return { requestId, result };
193
+ }
194
+
195
+ function cloneResultsWithProgress(
196
+ results: SingleResult[],
197
+ progress: NonNullable<Details["progress"]> | undefined,
198
+ ): SingleResult[] {
199
+ return results.map((result, index) => {
200
+ const nextProgress = progress?.find((entry) => entry.index === index
201
+ || (entry.index === undefined && entry.agent === result.agent))
202
+ ?? result.progress;
203
+ return nextProgress ? { ...result, progress: nextProgress } : result;
204
+ });
205
+ }
206
+
207
+ export function applySlashUpdate(requestId: string, update: SlashSubagentUpdate): void {
208
+ const snapshot = liveSnapshots.get(requestId);
209
+ if (!snapshot) return;
210
+ const progress = update.progress;
211
+ if (!progress || !snapshot.result.details) return;
212
+ const currentStepIndex = progress.findIndex((entry) => entry.status === "running");
213
+ const nextDetails: Details = {
214
+ ...snapshot.result.details,
215
+ progress,
216
+ results: cloneResultsWithProgress(snapshot.result.details.results, progress),
217
+ ...(snapshot.result.details.mode === "chain" && currentStepIndex >= 0 ? { currentStepIndex } : {}),
218
+ };
219
+ liveSnapshots.set(requestId, {
220
+ result: {
221
+ ...snapshot.result,
222
+ details: nextDetails,
223
+ },
224
+ version: nextVersion(),
225
+ });
226
+ }
227
+
228
+ export function finalizeSlashResult(response: SlashSubagentResponse): SlashMessageDetails {
229
+ const snapshot = {
230
+ result: response.result,
231
+ version: nextVersion(),
232
+ };
233
+ finalSnapshots.set(response.requestId, snapshot);
234
+ liveSnapshots.delete(response.requestId);
235
+ return {
236
+ requestId: response.requestId,
237
+ result: response.result,
238
+ };
239
+ }
240
+
241
+ export function failSlashResult(requestId: string, params: SubagentParamsLike, message: string): SlashMessageDetails {
242
+ const initial = buildSlashInitialResult(requestId, params).result;
243
+ const failedResults = initial.details.results.map((result) => ({
244
+ ...result,
245
+ exitCode: 1,
246
+ error: message,
247
+ progress: result.progress ? { ...result.progress, status: "failed" as const } : result.progress,
248
+ }));
249
+ const result: AgentToolResult<Details> = {
250
+ content: [{ type: "text", text: message }],
251
+ details: {
252
+ ...initial.details,
253
+ results: failedResults,
254
+ progress: failedResults.map((entry) => entry.progress!).filter(Boolean),
255
+ },
256
+ };
257
+ const snapshot = { result, version: nextVersion() };
258
+ finalSnapshots.set(requestId, snapshot);
259
+ liveSnapshots.delete(requestId);
260
+ return { requestId, result };
261
+ }
262
+
263
+ function isSlashMessageDetails(value: unknown): value is SlashMessageDetails {
264
+ if (!value || typeof value !== "object") return false;
265
+ const v = value as { requestId?: string; result?: { content?: unknown; details?: { results?: unknown } } };
266
+ if (typeof v.requestId !== "string" || !v.requestId) return false;
267
+ if (!v.result || !Array.isArray(v.result.content)) return false;
268
+ return !!v.result.details && Array.isArray(v.result.details.results);
269
+ }
270
+
271
+ export function resolveSlashMessageDetails(value: unknown): SlashMessageDetails | undefined {
272
+ return isSlashMessageDetails(value) ? value : undefined;
273
+ }
274
+
275
+ export function getSlashRenderableSnapshot(details: SlashMessageDetails): SlashSnapshot {
276
+ return finalSnapshots.get(details.requestId)
277
+ ?? liveSnapshots.get(details.requestId)
278
+ ?? { result: details.result, version: 0 };
279
+ }
280
+
281
+ export function restoreSlashFinalSnapshots(entries: unknown[]): void {
282
+ liveSnapshots.clear();
283
+ finalSnapshots.clear();
284
+ for (const entry of entries) {
285
+ const e = entry as { type?: string; customType?: string; details?: unknown };
286
+ if (e?.type !== "custom_message" || e.customType !== SLASH_RESULT_TYPE) continue;
287
+ const details = resolveSlashMessageDetails(e.details);
288
+ if (!details) continue;
289
+ finalSnapshots.set(details.requestId, { result: details.result, version: nextVersion() });
290
+ }
291
+ }
292
+
293
+ export function clearSlashSnapshots(): void {
294
+ liveSnapshots.clear();
295
+ finalSnapshots.clear();
296
+ }