@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -5,43 +5,21 @@
5
5
  import * as fs from "node:fs";
6
6
  import * as os from "node:os";
7
7
  import * as path from "node:path";
8
- import type { AgentConfig } from "../agents/agents.ts";
8
+ import { discoverAgents, formatUnknownAgentError, unknownAgentDiagnosticContext, type AgentConfig, type AgentScope, type UnknownAgentDiagnosticContext } from "../agents/agents.ts";
9
9
  import { normalizeSkillInput } from "../agents/skills.ts";
10
+ import { normalizeOutputOverride, type OutputOverrideInput, type ResolvedStepBehavior } from "../runs/shared/child-launch-plan.ts";
10
11
  import { CHAIN_RUNS_DIR, type AcceptanceInput, type AgentContract, type ChainGateLayer, type JsonSchemaObject, type OutputMode, type ToolBudgetConfig } from "./types.ts";
11
12
  const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
12
13
  const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
13
14
 
14
- // =============================================================================
15
- // Behavior Resolution Types
16
- // =============================================================================
17
-
18
- export interface ResolvedStepBehavior {
19
- output: string | false;
20
- outputMode: OutputMode;
21
- reads: string[] | false;
22
- progress: boolean;
23
- skills: string[] | false;
24
- model?: string;
25
- fast?: boolean;
26
- }
27
-
28
- export type OutputOverrideInput = string | boolean;
29
-
30
- export interface StepOverrides {
31
- output?: OutputOverrideInput;
32
- outputMode?: OutputMode;
33
- reads?: string[] | false;
34
- progress?: boolean;
35
- skills?: string[] | false;
36
- model?: string;
37
- fast?: boolean;
38
- }
39
-
40
- function normalizeOutputOverride(output: unknown): string | false | undefined {
41
- if (output === false || output === "false") return false;
42
- if (output === true || output === "true") return undefined;
43
- return typeof output === "string" && output.length > 0 ? output : undefined;
44
- }
15
+ export {
16
+ planChildLaunch,
17
+ resolveStepBehavior,
18
+ resolveTaskTextForFileUpdatePolicy,
19
+ suppressProgressForReadOnlyTask,
20
+ taskDisallowsFileUpdates,
21
+ } from "../runs/shared/child-launch-plan.ts";
22
+ export type { ChildLaunchPlan, ChildLaunchPlanInput, OutputOverrideInput, ResolvedStepBehavior, StepOverrides } from "../runs/shared/child-launch-plan.ts";
45
23
 
46
24
  // =============================================================================
47
25
  // Chain Step Types
@@ -239,78 +217,6 @@ export function resolveChainTemplates(
239
217
  });
240
218
  }
241
219
 
242
- // =============================================================================
243
- // Behavior Resolution
244
- // =============================================================================
245
-
246
- /**
247
- * Resolve effective chain behavior per step.
248
- * Priority: step override > agent frontmatter > false (disabled)
249
- */
250
- export function resolveStepBehavior(
251
- agentConfig: AgentConfig,
252
- stepOverrides: StepOverrides,
253
- chainSkills?: string[],
254
- ): ResolvedStepBehavior {
255
- // Output: step override > frontmatter > false (no output)
256
- const stepOutput = normalizeOutputOverride(stepOverrides.output);
257
- const output =
258
- stepOutput !== undefined
259
- ? stepOutput
260
- : normalizeOutputOverride(agentConfig.output) ?? false;
261
-
262
- // Reads: step override > frontmatter defaultReads > false (no reads)
263
- const reads =
264
- stepOverrides.reads !== undefined
265
- ? stepOverrides.reads
266
- : agentConfig.defaultReads ?? false;
267
-
268
- // Progress: step override > frontmatter defaultProgress > false
269
- const progress =
270
- stepOverrides.progress !== undefined
271
- ? stepOverrides.progress
272
- : agentConfig.defaultProgress ?? false;
273
-
274
- let skills: string[] | false;
275
- if (stepOverrides.skills === false) {
276
- skills = false;
277
- } else if (stepOverrides.skills !== undefined) {
278
- skills = [...stepOverrides.skills];
279
- if (chainSkills && chainSkills.length > 0) {
280
- skills = [...new Set([...skills, ...chainSkills])];
281
- }
282
- } else {
283
- skills = agentConfig.skills ? [...agentConfig.skills] : [];
284
- if (chainSkills && chainSkills.length > 0) {
285
- skills = [...new Set([...skills, ...chainSkills])];
286
- }
287
- }
288
-
289
- const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
290
- const model = stepOverrides.model ?? agentConfig.model;
291
- const fast = stepOverrides.fast ?? agentConfig.fast;
292
- return { output, outputMode, reads, progress, skills, model, fast };
293
- }
294
-
295
- export function resolveTaskTextForFileUpdatePolicy(task: string | undefined, originalTask?: string): string | undefined {
296
- if (!task) return originalTask;
297
- return originalTask ? task.replaceAll("{task}", originalTask) : task;
298
- }
299
-
300
- export function taskDisallowsFileUpdates(task: string | undefined): boolean {
301
- if (!task) return false;
302
- return /\breview[- ]only\b/i.test(task)
303
- || /\bread[- ]only\s+(?:review|audit|inspection|pass)\b/i.test(task)
304
- || /\b(?:no|without)\s+(?:file\s+)?edits?\b/i.test(task)
305
- || /\b(?:do not|don't|must not)\s+(?:edit|modify|write|touch)\b/i.test(task)
306
- || /\bleave\s+files?\s+unchanged\b/i.test(task);
307
- }
308
-
309
- export function suppressProgressForReadOnlyTask(behavior: ResolvedStepBehavior, task: string | undefined, originalTask?: string): ResolvedStepBehavior {
310
- const policyTask = resolveTaskTextForFileUpdatePolicy(task, originalTask);
311
- return behavior.progress && taskDisallowsFileUpdates(policyTask) ? { ...behavior, progress: false } : behavior;
312
- }
313
-
314
220
  // =============================================================================
315
221
  // Chain Instruction Injection
316
222
  // =============================================================================
@@ -411,16 +317,24 @@ export function buildChainInstructions(
411
317
  * Resolve behaviors for all tasks in a parallel step.
412
318
  * Creates namespaced output paths to avoid collisions.
413
319
  */
320
+ /** Exact discovery context, or explicit input for defensive fallback discovery. */
321
+ export type ParallelBehaviorDiagnostics = UnknownAgentDiagnosticContext | { cwd: string; scope?: AgentScope };
322
+
414
323
  export function resolveParallelBehaviors(
415
324
  tasks: ParallelTaskItem[],
416
325
  agentConfigs: AgentConfig[],
417
326
  stepIndex: number,
418
327
  chainSkills?: string[],
328
+ diagnostics?: ParallelBehaviorDiagnostics,
419
329
  ): ResolvedStepBehavior[] {
420
330
  return tasks.map((task, taskIndex) => {
421
331
  const config = agentConfigs.find((a) => a.name === task.agent);
422
332
  if (!config) {
423
- throw new Error(`Unknown agent: ${task.agent}`);
333
+ if (!diagnostics) throw new Error("resolveParallelBehaviors requires unknown-agent diagnostic context or fallback discovery input.");
334
+ const context = "directories" in diagnostics
335
+ ? diagnostics
336
+ : unknownAgentDiagnosticContext(discoverAgents(path.resolve(diagnostics.cwd), diagnostics.scope ?? "both"));
337
+ throw new Error(formatUnknownAgentError(task.agent, context));
424
338
  }
425
339
 
426
340
  // Build subdirectory path for this parallel task
@@ -0,0 +1,17 @@
1
+ import { Key, type KeyId } from "@earendil-works/pi-tui";
2
+
3
+ export const FLEET_OPEN_SHORTCUT: KeyId = Key.ctrlAlt("f");
4
+
5
+ export function formatShortcutLabel(shortcut: string): string {
6
+ return shortcut
7
+ .split("+")
8
+ .map((part) => {
9
+ const normalized = part.trim().toLowerCase();
10
+ if (normalized === "ctrl") return "Ctrl";
11
+ if (normalized === "alt") return "Alt";
12
+ if (normalized === "shift") return "Shift";
13
+ if (normalized === "super") return "Super";
14
+ return normalized.length === 1 ? normalized.toUpperCase() : part.trim();
15
+ })
16
+ .join("+");
17
+ }
@@ -1,8 +1,6 @@
1
1
  import { resolveEffectiveThinking, THINKING_LEVELS, type ThinkingLevel } from "./model-info.ts";
2
2
  export type { ThinkingLevel } from "./model-info.ts";
3
3
 
4
- export const SUBAGENT_THINKING_CEILING_ENV = "PI_SUBAGENT_THINKING_CEILING";
5
-
6
4
  const thinkingLevelRanks = new Map<ThinkingLevel, number>(THINKING_LEVELS.map((level, index) => [level, index]));
7
5
 
8
6
  export function parseThinkingLevel(value: unknown, field = "thinking level"): ThinkingLevel {
@@ -26,10 +24,6 @@ export function intersectThinkingCeilings(...ceilings: Array<ThinkingLevel | und
26
24
  return active.reduce((lowest, ceiling) => compareThinkingLevels(ceiling, lowest) < 0 ? ceiling : lowest);
27
25
  }
28
26
 
29
- export function decodeThinkingCeiling(value: string | undefined): ThinkingLevel | undefined {
30
- if (value === undefined || value === "") return undefined;
31
- return parseThinkingLevel(value, "inherited thinking ceiling");
32
- }
33
27
 
34
28
  export interface ThinkingCeilingCheck {
35
29
  model?: string;