@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,163 @@
1
+ import { stringify as stringifyYaml } from "yaml";
2
+ import type { AgentConfig } from "./agents.ts";
3
+ import { frontmatterNameForConfig } from "./identity.ts";
4
+
5
+ export const KNOWN_FIELDS = new Set([
6
+ "name",
7
+ "package",
8
+ "description",
9
+ "alias",
10
+ "aliases",
11
+ "tools",
12
+ "model",
13
+ "fallbackModels",
14
+ "thinking",
15
+ "systemPromptMode",
16
+ "inheritProjectContext",
17
+ "inheritSkills",
18
+ "defaultContext",
19
+ "async",
20
+ "timeoutMs",
21
+ "turnBudget",
22
+ "acceptance",
23
+ "acceptanceRole",
24
+ "skill",
25
+ "skills",
26
+ "skillPath",
27
+ "extensions",
28
+ "subagentOnlyExtensions",
29
+ "output",
30
+ "defaultReads",
31
+ "defaultProgress",
32
+ "interactive",
33
+ "maxSubagentDepth",
34
+ "completionGuard",
35
+ "toolBudget",
36
+ "permission",
37
+ "permissions",
38
+ "memory",
39
+ "runner",
40
+ ]);
41
+
42
+ function joinComma(values: string[] | undefined): string | undefined {
43
+ if (!values || values.length === 0) return undefined;
44
+ return values.join(", ");
45
+ }
46
+
47
+ interface SerializeAgentOptions {
48
+ preserveFrontmatterFields?: ReadonlySet<string>;
49
+ }
50
+
51
+ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptions = {}): string {
52
+ const lines: string[] = [];
53
+ const preserve = (...fields: string[]) => fields.some((field) => options.preserveFrontmatterFields?.has(field));
54
+ const preservingExistingFrontmatter = options.preserveFrontmatterFields !== undefined;
55
+ lines.push("---");
56
+ lines.push(`name: ${frontmatterNameForConfig(config)}`);
57
+ if (config.packageName) lines.push(`package: ${config.packageName}`);
58
+ lines.push(`description: ${config.description}`);
59
+ const aliasesValue = joinComma(config.aliases);
60
+ if (aliasesValue || preserve("alias", "aliases")) lines.push(`aliases: ${aliasesValue ?? ""}`);
61
+
62
+ const tools = [
63
+ ...(config.tools ?? []),
64
+ ...(config.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
65
+ ];
66
+ const toolsValue = joinComma(tools);
67
+ if (toolsValue || preserve("tools")) lines.push(`tools: ${toolsValue ?? ""}`);
68
+
69
+ if (config.model || preserve("model")) lines.push(`model: ${config.model ?? ""}`);
70
+ const fallbackModelsValue = joinComma(config.fallbackModels);
71
+ if (fallbackModelsValue || preserve("fallbackModels")) lines.push(`fallbackModels: ${fallbackModelsValue ?? ""}`);
72
+ if ((config.thinking && (config.thinking !== "off" || preserve("thinking"))) || (!config.thinking && preserve("thinking"))) {
73
+ lines.push(`thinking: ${config.thinking ?? ""}`);
74
+ }
75
+ if (!preservingExistingFrontmatter || preserve("systemPromptMode")) lines.push(`systemPromptMode: ${config.systemPromptMode}`);
76
+ if (!preservingExistingFrontmatter || preserve("inheritProjectContext")) lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
77
+ if (!preservingExistingFrontmatter || preserve("inheritSkills")) lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
78
+ if (config.defaultContext || preserve("defaultContext")) lines.push(`defaultContext: ${config.defaultContext ?? ""}`);
79
+ if (config.runner || preserve("runner")) {
80
+ if (config.runner) {
81
+ lines.push("runner:");
82
+ for (const line of stringifyYaml(config.runner).trimEnd().split("\n")) lines.push(` ${line}`);
83
+ } else {
84
+ lines.push("runner:");
85
+ }
86
+ }
87
+ if (config.defaultAsync !== undefined || preserve("async")) lines.push(`async: ${config.defaultAsync === undefined ? "" : config.defaultAsync ? "true" : "false"}`);
88
+ if (config.defaultTimeoutMs !== undefined || preserve("timeoutMs")) lines.push(`timeoutMs: ${config.defaultTimeoutMs ?? ""}`);
89
+ if (config.defaultTurnBudget || preserve("turnBudget")) lines.push(`turnBudget: ${config.defaultTurnBudget ? JSON.stringify(config.defaultTurnBudget) : ""}`);
90
+ if (config.defaultAcceptance !== undefined || preserve("acceptance")) {
91
+ lines.push(`acceptance: ${config.defaultAcceptance === undefined
92
+ ? ""
93
+ : typeof config.defaultAcceptance === "object"
94
+ ? JSON.stringify(config.defaultAcceptance)
95
+ : String(config.defaultAcceptance)}`);
96
+ }
97
+ if (config.acceptanceRole || preserve("acceptanceRole")) lines.push(`acceptanceRole: ${config.acceptanceRole ?? ""}`);
98
+
99
+ const skillsValue = joinComma(config.skills);
100
+ if (skillsValue || preserve("skill", "skills")) lines.push(`skills: ${skillsValue ?? ""}`);
101
+ const skillPathValue = joinComma(config.skillPath);
102
+ if (skillPathValue || preserve("skillPath")) lines.push(`skillPath: ${skillPathValue ?? ""}`);
103
+
104
+ if (config.extensions !== undefined) {
105
+ const extensionsValue = joinComma(config.extensions);
106
+ lines.push(`extensions: ${extensionsValue ?? ""}`);
107
+ }
108
+ if (config.subagentOnlyExtensions !== undefined || preserve("subagentOnlyExtensions")) {
109
+ const subagentOnlyExtensionsValue = joinComma(config.subagentOnlyExtensions);
110
+ lines.push(`subagentOnlyExtensions: ${subagentOnlyExtensionsValue ?? ""}`);
111
+ }
112
+
113
+ if (config.output) lines.push(`output: ${config.output}`);
114
+
115
+ const readsValue = joinComma(config.defaultReads);
116
+ if (readsValue) lines.push(`defaultReads: ${readsValue}`);
117
+
118
+ if (config.defaultProgress) lines.push("defaultProgress: true");
119
+ if (config.interactive) lines.push("interactive: true");
120
+ const maxSubagentDepth = config.maxSubagentDepth;
121
+ if (typeof maxSubagentDepth === "number" && Number.isInteger(maxSubagentDepth) && maxSubagentDepth >= 0) {
122
+ lines.push(`maxSubagentDepth: ${maxSubagentDepth}`);
123
+ }
124
+ if (config.completionGuard === false || preserve("completionGuard")) {
125
+ lines.push(`completionGuard: ${config.completionGuard === undefined ? "" : config.completionGuard ? "true" : "false"}`);
126
+ }
127
+ if (config.toolBudget || preserve("toolBudget")) {
128
+ lines.push(`toolBudget: ${config.toolBudget ? JSON.stringify(config.toolBudget) : ""}`);
129
+ }
130
+ if (config.permissions || preserve("permission", "permissions")) {
131
+ const key = preserve("permission") && !preserve("permissions") ? "permission" : "permissions";
132
+ lines.push(`${key}:`);
133
+ if (config.permissions) {
134
+ for (const line of stringifyYaml(config.permissions).trimEnd().split("\n")) lines.push(` ${line}`);
135
+ }
136
+ }
137
+
138
+ if (config.memory) {
139
+ lines.push("memory:");
140
+ lines.push(` scope: ${config.memory.scope}`);
141
+ lines.push(` path: ${config.memory.path}`);
142
+ }
143
+
144
+ if (config.extraFields) {
145
+ for (const [key, value] of Object.entries(config.extraFields)) {
146
+ if (KNOWN_FIELDS.has(key)) continue;
147
+ if (typeof value === "string" && value.includes("\n")) {
148
+ // Multi-line block value (e.g. permission: nested YAML)
149
+ lines.push(`${key}:`);
150
+ for (const blockLine of value.split("\n")) {
151
+ lines.push(` ${blockLine}`);
152
+ }
153
+ } else {
154
+ lines.push(`${key}: ${value}`);
155
+ }
156
+ }
157
+ }
158
+
159
+ lines.push("---");
160
+
161
+ const body = config.systemPrompt ?? "";
162
+ return `${lines.join("\n")}\n\n${body}\n`;
163
+ }