@xzzpig/pi-subagents 0.4.1 → 0.5.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 (128) hide show
  1. package/CHANGELOG.md +175 -0
  2. package/README.md +4 -0
  3. package/agents/oracle.md +3 -1
  4. package/agents/reviewer.md +1 -0
  5. package/agents/scout.md +2 -2
  6. package/agents/worker.md +2 -1
  7. package/async-retention-discovery-worker.mjs +180 -0
  8. package/docs/agents.md +41 -3
  9. package/docs/configuration.md +41 -13
  10. package/docs/extension-api.md +65 -2
  11. package/docs/models.md +2 -0
  12. package/docs/observability.md +41 -5
  13. package/docs/tool-reference.md +38 -39
  14. package/docs/workflows.md +173 -3
  15. package/package.json +14 -10
  16. package/prompts/council.md +48 -0
  17. package/skills/council-mode/SKILL.md +230 -0
  18. package/skills/pi-subagents/SKILL.md +8 -4
  19. package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
  20. package/skills/pi-subagents/references/execution-controls.md +40 -15
  21. package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
  22. package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
  24. package/src/agents/agent-management.ts +471 -377
  25. package/src/agents/agent-serializer.ts +2 -0
  26. package/src/agents/agents.ts +186 -44
  27. package/src/agents/builtin-names.ts +9 -0
  28. package/src/agents/runtime-agent-registry.ts +418 -0
  29. package/src/agents/skills.ts +1 -1
  30. package/src/api/agent-management.ts +9 -0
  31. package/src/api/agents.ts +7 -0
  32. package/src/api/external-job-provider.ts +186 -0
  33. package/src/api/preflight.ts +45 -13
  34. package/src/api/shared-types.ts +2 -0
  35. package/src/extension/config.ts +6 -3
  36. package/src/extension/doctor.ts +4 -6
  37. package/src/extension/fanout-child.ts +2 -2
  38. package/src/extension/index.ts +183 -90
  39. package/src/extension/public-execution.ts +31 -2
  40. package/src/extension/rpc.ts +41 -1
  41. package/src/extension/schemas.ts +17 -37
  42. package/src/extension/tool-description.ts +35 -24
  43. package/src/inspectors/herdr/actions.ts +2 -2
  44. package/src/inspectors/herdr/inspector-runner.ts +2 -1
  45. package/src/inspectors/herdr/project-panes.ts +2 -2
  46. package/src/intercom/native-supervisor-channel.ts +32 -10
  47. package/src/missions/lifecycle.ts +6 -1
  48. package/src/missions/store.ts +4 -9
  49. package/src/missions/workflow-state.ts +2 -2
  50. package/src/profiles/profiles.ts +3 -1
  51. package/src/runs/background/active-run-index.ts +31 -8
  52. package/src/runs/background/async-execution.ts +70 -41
  53. package/src/runs/background/async-job-tracker.ts +24 -7
  54. package/src/runs/background/async-resume.ts +49 -16
  55. package/src/runs/background/async-retention.ts +886 -0
  56. package/src/runs/background/async-status-snapshot.ts +14 -5
  57. package/src/runs/background/async-status.ts +39 -53
  58. package/src/runs/background/auto-drain.ts +1 -0
  59. package/src/runs/background/chain-append.ts +3 -33
  60. package/src/runs/background/completion-dedupe.ts +5 -1
  61. package/src/runs/background/completion-replay.ts +22 -12
  62. package/src/runs/background/control-channel.ts +14 -68
  63. package/src/runs/background/fleet-view.ts +68 -19
  64. package/src/runs/background/index-segment.ts +59 -0
  65. package/src/runs/background/inspect-rpc.ts +443 -0
  66. package/src/runs/background/notify.ts +31 -5
  67. package/src/runs/background/result-files.ts +158 -90
  68. package/src/runs/background/result-watcher.ts +124 -20
  69. package/src/runs/background/resume-guidance.ts +8 -5
  70. package/src/runs/background/retained-children.ts +13 -3
  71. package/src/runs/background/run-id-query.ts +7 -0
  72. package/src/runs/background/run-id-resolver.ts +11 -9
  73. package/src/runs/background/run-status.ts +27 -18
  74. package/src/runs/background/scheduled-runs.ts +24 -4
  75. package/src/runs/background/stale-run-reconciler.ts +6 -3
  76. package/src/runs/background/steering.ts +11 -1
  77. package/src/runs/background/subagent-runner.ts +260 -144
  78. package/src/runs/background/subagent-wait.ts +17 -13
  79. package/src/runs/background/terminal-run-index.ts +138 -0
  80. package/src/runs/background/wait-completions.ts +21 -4
  81. package/src/runs/background/wait-subscriptions.ts +81 -2
  82. package/src/runs/background/wait-tool.ts +1 -0
  83. package/src/runs/foreground/async-steering-action.ts +21 -14
  84. package/src/runs/foreground/execution.ts +104 -71
  85. package/src/runs/foreground/subagent-executor.ts +816 -1593
  86. package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
  87. package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
  88. package/src/runs/shared/acceptance.ts +48 -5
  89. package/src/runs/shared/chain-outputs.ts +1 -3
  90. package/src/runs/shared/external-job-bridge.ts +444 -0
  91. package/src/runs/shared/external-job-runner.ts +286 -0
  92. package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
  93. package/src/runs/shared/model-exclusions.ts +242 -0
  94. package/src/runs/shared/model-fallback.ts +153 -40
  95. package/src/runs/shared/orca-progress-tabs.ts +84 -22
  96. package/src/runs/shared/parallel-handoff.ts +46 -4
  97. package/src/runs/shared/parallel-utils.ts +4 -15
  98. package/src/runs/shared/permissions.ts +5 -1
  99. package/src/runs/shared/pi-args.ts +8 -1
  100. package/src/runs/shared/session-lease.ts +0 -6
  101. package/src/runs/shared/subagent-control.ts +51 -7
  102. package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
  103. package/src/runs/shared/workflow-graph.ts +1 -23
  104. package/src/runs/shared/worktree.ts +14 -2
  105. package/src/shared/atomic-json.ts +22 -2
  106. package/src/shared/capacity-resilient-json.ts +102 -0
  107. package/src/shared/completion-owner.ts +14 -0
  108. package/src/shared/file-system-retry.ts +49 -1
  109. package/src/shared/fork-context.ts +59 -1
  110. package/src/shared/model-info.ts +20 -0
  111. package/src/shared/prompt-resources.ts +0 -40
  112. package/src/shared/settings.ts +5 -29
  113. package/src/shared/types.ts +106 -26
  114. package/src/shared/utils.ts +8 -0
  115. package/src/shared/watch-strategy.ts +10 -0
  116. package/src/slash/slash-bridge.ts +2 -1
  117. package/src/slash/slash-commands.ts +47 -7
  118. package/src/slash/slash-live-state.ts +3 -3
  119. package/src/tui/fleet-status.ts +86 -1
  120. package/src/tui/fleet.ts +117 -16
  121. package/src/tui/render.ts +73 -3
  122. package/src/watchdog/change-signature.ts +1 -1
  123. package/src/watchdog/lsp-diagnostics.ts +1 -0
  124. package/src/workflows/chat-progress.ts +2 -2
  125. package/src/workflows/scripted-workflow.ts +320 -79
  126. package/src/workflows/workflow-receipt.ts +140 -0
  127. package/src/runs/foreground/chain-clarify.ts +0 -1354
  128. package/src/runs/foreground/chain-execution.ts +0 -1581
@@ -28,6 +28,7 @@ export const KNOWN_FIELDS = new Set([
28
28
  "extensions",
29
29
  "subagentOnlyExtensions",
30
30
  "output",
31
+ "outputMode",
31
32
  "defaultReads",
32
33
  "defaultProgress",
33
34
  "interactive",
@@ -113,6 +114,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
113
114
  }
114
115
 
115
116
  if (config.output) lines.push(`output: ${config.output}`);
117
+ if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
116
118
 
117
119
  const readsValue = joinComma(config.defaultReads);
118
120
  if (readsValue) lines.push(`defaultReads: ${readsValue}`);
@@ -16,6 +16,7 @@ import { mergeAgentsForScope } from "./agent-selection.ts";
16
16
  import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.ts";
17
17
  import { buildRuntimeName, parsePackageName } from "./identity.ts";
18
18
  import { parseModelScopeConfig, type ModelScopeConfig } from "../runs/shared/model-scope.ts";
19
+ export { BUILTIN_AGENT_NAMES } from "./builtin-names.ts";
19
20
  export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
20
21
  import { parseMemoryFrontmatter } from "./agent-memory.ts";
21
22
  import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
@@ -24,7 +25,7 @@ import { validatePermissionRules, type PermissionRules } from "../runs/shared/pe
24
25
 
25
26
  export type AgentScope = "user" | "project" | "both";
26
27
 
27
- export type AgentSource = "builtin" | "package" | "user" | "project";
28
+ export type AgentSource = "builtin" | "package" | "user" | "project" | "runtime";
28
29
  type SystemPromptMode = "append" | "replace";
29
30
  export type AgentDefaultContext = "fresh" | "fork";
30
31
 
@@ -35,16 +36,6 @@ export interface AgentMemoryConfig {
35
36
  path: string;
36
37
  }
37
38
 
38
- export const BUILTIN_AGENT_NAMES = [
39
- "advisor",
40
- "delegate",
41
- "oracle",
42
- "researcher",
43
- "reviewer",
44
- "scout",
45
- "worker",
46
- ] as const;
47
-
48
39
  export function defaultSystemPromptMode(name: string): SystemPromptMode {
49
40
  return name === "delegate" ? "append" : "replace";
50
41
  }
@@ -59,6 +50,7 @@ export function defaultInheritSkills(): boolean {
59
50
 
60
51
  export interface BuiltinAgentOverrideBase {
61
52
  description?: string;
53
+ outputMode?: OutputMode;
62
54
  model?: string;
63
55
  fallbackModels?: string[];
64
56
  thinking?: string | false;
@@ -81,6 +73,7 @@ export interface BuiltinAgentOverrideBase {
81
73
 
82
74
  interface BuiltinAgentOverrideConfig {
83
75
  description?: string;
76
+ outputMode?: OutputMode;
84
77
  model?: string | false;
85
78
  fallbackModels?: string[] | false;
86
79
  thinking?: string | false;
@@ -137,12 +130,14 @@ export interface AgentConfig {
137
130
  systemPrompt: string;
138
131
  source: AgentSource;
139
132
  filePath: string;
133
+ discoveryPriority?: number;
140
134
  skills?: string[];
141
135
  skillPath?: string[];
142
136
  extensions?: string[];
143
137
  extensionsFromDefault?: boolean;
144
138
  subagentOnlyExtensions?: string[];
145
139
  output?: string;
140
+ outputMode?: OutputMode;
146
141
  defaultReads?: string[];
147
142
  defaultProgress?: boolean;
148
143
  interactive?: boolean;
@@ -212,8 +207,46 @@ export interface ChainDiscoveryDiagnostic {
212
207
  error: string;
213
208
  }
214
209
 
210
+ export interface AgentDiscoveryDiagnostic extends ChainDiscoveryDiagnostic {
211
+ name?: string;
212
+ runtimeName?: string;
213
+ packageSpecified?: boolean;
214
+ discoveryPriority?: number;
215
+ }
216
+
217
+ const AGENT_SOURCE_PRIORITY: Record<AgentSource, number> = {
218
+ builtin: 0,
219
+ package: 1,
220
+ user: 2,
221
+ project: 3,
222
+ runtime: 4,
223
+ };
224
+
225
+ function agentDefinitionPriority(definition: Pick<AgentConfig | AgentDiscoveryDiagnostic, "source" | "discoveryPriority">): number {
226
+ return AGENT_SOURCE_PRIORITY[definition.source] * 1_000_000
227
+ + (definition.discoveryPriority ?? 0);
228
+ }
229
+
230
+ export function findBlockingAgentDiagnostic(name: string, agent: AgentConfig | readonly AgentConfig[] | undefined, diagnostics: AgentDiscoveryDiagnostic[] | undefined): AgentDiscoveryDiagnostic | undefined {
231
+ const normalizedName = name.trim();
232
+ const agents = Array.isArray(agent) ? agent : agent ? [agent] : [];
233
+ let match: AgentDiscoveryDiagnostic | undefined;
234
+ for (const diagnostic of diagnostics ?? []) {
235
+ if ((diagnostic.runtimeName === normalizedName
236
+ || (diagnostic.name === normalizedName && (!diagnostic.packageSpecified
237
+ || diagnostic.runtimeName === undefined
238
+ || agents.some((agent) => agent.name === diagnostic.runtimeName && agent.localName === diagnostic.name))))
239
+ && (!match || agentDefinitionPriority(diagnostic) > agentDefinitionPriority(match))) {
240
+ match = diagnostic;
241
+ }
242
+ }
243
+ const highestPriority = Math.max(...agents.map(agentDefinitionPriority), -Infinity);
244
+ return !agents.length || (match && agentDefinitionPriority(match) > highestPriority) ? match : undefined;
245
+ }
246
+
215
247
  interface AgentDiscoveryResult {
216
248
  agents: AgentConfig[];
249
+ agentDiagnostics?: AgentDiscoveryDiagnostic[];
217
250
  projectAgentsDir: string | null;
218
251
  modelScope?: ModelScopeConfig;
219
252
  }
@@ -345,7 +378,7 @@ function getGlobalNpmRoot(): string | null {
345
378
  }
346
379
 
347
380
  try {
348
- cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
381
+ cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
349
382
  return cachedGlobalNpmRoot;
350
383
  } catch {
351
384
  cachedGlobalNpmRoot = "";
@@ -502,7 +535,7 @@ function normalizeAgentAliases(rawAliases: string[] | undefined, agentName: stri
502
535
  function effectiveAgentMatch(matches: AgentConfig[]): { agent?: AgentConfig; error?: string } {
503
536
  const distinctNames = [...new Set(matches.map((agent) => agent.name))];
504
537
  if (distinctNames.length === 1) {
505
- const sourceRank = new Map<AgentConfig["source"], number>([["builtin", 0], ["package", 1], ["user", 2], ["project", 3]]);
538
+ const sourceRank = new Map<AgentConfig["source"], number>([["builtin", 0], ["package", 1], ["user", 2], ["project", 3], ["runtime", 4]]);
506
539
  const agent = [...matches].sort((a, b) => (sourceRank.get(b.source) ?? 0) - (sourceRank.get(a.source) ?? 0))[0];
507
540
  return agent ? { agent } : {};
508
541
  }
@@ -566,6 +599,7 @@ function arraysEqual(a: string[] | undefined, b: string[] | undefined): boolean
566
599
  function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
567
600
  return {
568
601
  description: agent.description,
602
+ ...(agent.outputMode !== undefined ? { outputMode: agent.outputMode } : {}),
569
603
  ...(agent.model !== undefined ? { model: agent.model } : {}),
570
604
  ...(agent.fallbackModels ? { fallbackModels: [...agent.fallbackModels] } : {}),
571
605
  ...(agent.thinking !== undefined ? { thinking: agent.thinking } : {}),
@@ -590,6 +624,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
590
624
  function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentOverrideConfig {
591
625
  return {
592
626
  ...(override.description !== undefined ? { description: override.description } : {}),
627
+ ...(override.outputMode !== undefined ? { outputMode: override.outputMode } : {}),
593
628
  ...(override.model !== undefined ? { model: override.model } : {}),
594
629
  ...(override.fallbackModels !== undefined
595
630
  ? { fallbackModels: override.fallbackModels === false ? false : [...override.fallbackModels] }
@@ -770,6 +805,14 @@ function parseBuiltinOverrideEntry(
770
805
  }
771
806
  }
772
807
 
808
+ if ("outputMode" in input) {
809
+ if (input.outputMode === "inline" || input.outputMode === "file-only") {
810
+ override.outputMode = input.outputMode;
811
+ } else {
812
+ throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'outputMode'; expected 'inline' or 'file-only'.`);
813
+ }
814
+ }
815
+
773
816
  if ("model" in input) {
774
817
  if (typeof input.model === "string" || input.model === false) override.model = input.model;
775
818
  else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`);
@@ -1038,6 +1081,7 @@ function applyBuiltinOverride(
1038
1081
  };
1039
1082
 
1040
1083
  if (override.description !== undefined) next.description = override.description;
1084
+ if (override.outputMode !== undefined) next.outputMode = override.outputMode;
1041
1085
  if (override.model !== undefined) {
1042
1086
  if (override.model === false) delete next.model; else next.model = override.model;
1043
1087
  delete next.modelSource;
@@ -1155,6 +1199,9 @@ function applyCustomAgentOverride(
1155
1199
  mutable().description = override.description;
1156
1200
  anyFilled = true;
1157
1201
  }
1202
+ if (override.outputMode !== undefined) {
1203
+ fill("outputMode", ["outputMode"], override.outputMode);
1204
+ }
1158
1205
  if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
1159
1206
  const target = mutable();
1160
1207
  if (override.model === false) delete target.model; else target.model = override.model;
@@ -1245,7 +1292,7 @@ function applyCustomAgentOverrides(
1245
1292
 
1246
1293
  export function buildBuiltinOverrideConfig(
1247
1294
  base: BuiltinAgentOverrideBase,
1248
- draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description">>,
1295
+ draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description" | "outputMode">>,
1249
1296
  ): BuiltinAgentOverrideConfig | undefined {
1250
1297
  const override: BuiltinAgentOverrideConfig = {};
1251
1298
 
@@ -1253,6 +1300,7 @@ export function buildBuiltinOverrideConfig(
1253
1300
  const description = draft.description.trim();
1254
1301
  if (description && description !== base.description) override.description = description;
1255
1302
  }
1303
+ if (draft.outputMode !== undefined && draft.outputMode !== base.outputMode) override.outputMode = draft.outputMode;
1256
1304
  if (draft.model !== base.model) override.model = draft.model ?? false;
1257
1305
  if (!arraysEqual(draft.fallbackModels, base.fallbackModels)) override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
1258
1306
  if (draft.thinking !== base.thinking) override.thinking = draft.thinking ?? false;
@@ -1448,6 +1496,14 @@ function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
1448
1496
  return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
1449
1497
  }
1450
1498
 
1499
+ function isJsonSerializable(value: unknown): boolean {
1500
+ if (value === null || typeof value === "string" || typeof value === "boolean") return true;
1501
+ if (typeof value === "number") return Number.isFinite(value);
1502
+ if (Array.isArray(value)) return value.every(isJsonSerializable);
1503
+ if (value && typeof value === "object") return Object.values(value).every(isJsonSerializable);
1504
+ return false;
1505
+ }
1506
+
1451
1507
  function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string): AgentRunnerConfig | undefined {
1452
1508
  if (raw === undefined || !raw.trim()) return undefined;
1453
1509
  let parsed: unknown;
@@ -1464,8 +1520,24 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
1464
1520
  if (Object.keys(runner).some((key) => key !== "type")) throw new Error(`Agent '${agentName}' has invalid Pi runner frontmatter; only 'type' is supported.`);
1465
1521
  return { type: "pi" };
1466
1522
  }
1523
+ if (runner.type === "external-job") {
1524
+ if (typeof runner.provider !== "string" || !runner.provider.trim() || runner.provider.trim() !== runner.provider) {
1525
+ throw new Error(`Agent '${agentName}' external-job runner requires a non-empty trimmed provider string.`);
1526
+ }
1527
+ if (runner.options !== undefined && (!runner.options || typeof runner.options !== "object" || Array.isArray(runner.options) || !isJsonSerializable(runner.options))) {
1528
+ throw new Error(`Agent '${agentName}' external-job runner options must be a JSON-serializable object.`);
1529
+ }
1530
+ const supported = new Set(["type", "provider", "options"]);
1531
+ const unknown = Object.keys(runner).filter((key) => !supported.has(key));
1532
+ if (unknown.length > 0) throw new Error(`Agent '${agentName}' external-job runner has unsupported fields: ${unknown.join(", ")}.`);
1533
+ return {
1534
+ type: "external-job",
1535
+ provider: runner.provider,
1536
+ ...(runner.options ? { options: runner.options as Record<string, unknown> } : {}),
1537
+ };
1538
+ }
1467
1539
  if (runner.type !== "external-cli") {
1468
- throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'pi' or 'external-cli'.`);
1540
+ throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'pi', 'external-cli', or 'external-job'.`);
1469
1541
  }
1470
1542
  if (typeof runner.command !== "string" || !runner.command.trim()) {
1471
1543
  throw new Error(`Agent '${agentName}' external-cli runner requires a non-empty command string.`);
@@ -1489,11 +1561,11 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
1489
1561
  }
1490
1562
 
1491
1563
  function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
1492
- if (runner?.type !== "external-cli") return;
1564
+ if (runner?.type !== "external-cli" && runner?.type !== "external-job") return;
1493
1565
  const unsupported = ["tools", "model", "fallbackModels", "thinking", "extensions", "subagentOnlyExtensions", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "permission", "permissions"]
1494
1566
  .filter((field) => frontmatter[field] !== undefined);
1495
1567
  if (unsupported.length > 0) {
1496
- throw new Error(`Agent '${agentName}' uses runner.type='external-cli' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
1568
+ throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
1497
1569
  }
1498
1570
  }
1499
1571
 
@@ -1510,21 +1582,48 @@ function parseAgentAcceptanceFrontmatter(raw: string | undefined, agentName: str
1510
1582
  return parsed as AcceptanceInput;
1511
1583
  }
1512
1584
 
1513
- function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
1514
- const agents: AgentConfig[] = [];
1585
+ interface AgentDefinitionFile {
1586
+ filePath: string;
1587
+ content: string;
1588
+ }
1515
1589
 
1590
+ function readAgentDefinitionFiles(dir: string): AgentDefinitionFile[] {
1591
+ const files: AgentDefinitionFile[] = [];
1516
1592
  for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
1517
1593
  if (isLegacyAgentSkillPath(dir, filePath)) {
1518
1594
  continue;
1519
1595
  }
1520
1596
 
1521
- let content: string;
1522
1597
  try {
1523
- content = fs.readFileSync(filePath, "utf-8");
1598
+ files.push({ filePath, content: fs.readFileSync(filePath, "utf-8") });
1524
1599
  } catch {
1525
1600
  continue;
1526
1601
  }
1602
+ }
1603
+ return files;
1604
+ }
1605
+
1606
+ function resolveAgentRelativeExtensionPaths(paths: string[] | undefined, agentFilePath: string): string[] | undefined {
1607
+ if (paths === undefined) return undefined;
1608
+ const baseDir = path.dirname(agentFilePath);
1609
+ return paths.map((entry) => {
1610
+ const trimmed = entry.trim();
1611
+ if (trimmed === "." || trimmed === ".." || trimmed.startsWith("./") || trimmed.startsWith("../")) {
1612
+ return path.resolve(baseDir, trimmed);
1613
+ }
1614
+ return entry;
1615
+ });
1616
+ }
1617
+
1618
+ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
1619
+ const agents: AgentConfig[] = [];
1620
+ const diagnostics: AgentDiscoveryDiagnostic[] = [];
1527
1621
 
1622
+ for (const { filePath, content } of files) {
1623
+ let name: string | undefined;
1624
+ let runtimeName: string | undefined;
1625
+ let packageSpecified = false;
1626
+ try {
1528
1627
  const { frontmatter, body } = parseFrontmatter(content);
1529
1628
 
1530
1629
  if (!frontmatter.name || !frontmatter.description) {
@@ -1532,10 +1631,12 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
1532
1631
  }
1533
1632
 
1534
1633
  const localName = frontmatter.name;
1634
+ name = localName;
1535
1635
  const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
1536
- if (parsedPackage.error) continue;
1636
+ packageSpecified = parsedPackage.packageName !== undefined || parsedPackage.error !== undefined;
1637
+ if (parsedPackage.error) throw new Error(parsedPackage.error);
1537
1638
  const packageName = parsedPackage.packageName;
1538
- const runtimeName = buildRuntimeName(localName, packageName);
1639
+ runtimeName = buildRuntimeName(localName, packageName);
1539
1640
 
1540
1641
  const runner = parseAgentRunnerFrontmatter(frontmatter.runner, localName);
1541
1642
  validateExternalRunnerProfile(frontmatter, localName, runner);
@@ -1599,14 +1700,19 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
1599
1700
  defaultTurnBudget = resolved.turnBudget;
1600
1701
  }
1601
1702
  const defaultAcceptance = parseAgentAcceptanceFrontmatter(frontmatter.acceptance, localName);
1703
+ let outputMode: OutputMode | undefined;
1704
+ if (frontmatter.outputMode !== undefined) {
1705
+ if (frontmatter.outputMode === "inline" || frontmatter.outputMode === "file-only") outputMode = frontmatter.outputMode;
1706
+ else throw new Error(`Agent '${localName}' has invalid outputMode frontmatter; expected 'inline' or 'file-only'.`);
1707
+ }
1602
1708
  let acceptanceRole: AcceptanceRole | undefined;
1603
1709
  if (frontmatter.acceptanceRole !== undefined && frontmatter.acceptanceRole.trim()) {
1604
1710
  if (frontmatter.acceptanceRole === "read-only" || frontmatter.acceptanceRole === "writer") acceptanceRole = frontmatter.acceptanceRole;
1605
1711
  else throw new Error(`Agent '${localName}' has invalid acceptanceRole frontmatter; expected 'read-only' or 'writer'.`);
1606
1712
  }
1607
1713
 
1608
- const extensions = parseFrontmatterList(frontmatter.extensions);
1609
- const subagentOnlyExtensions = parseFrontmatterList(frontmatter.subagentOnlyExtensions);
1714
+ const extensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.extensions), filePath);
1715
+ const subagentOnlyExtensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.subagentOnlyExtensions), filePath);
1610
1716
 
1611
1717
  const extraFields: Record<string, string> = {};
1612
1718
  for (const [key, value] of Object.entries(frontmatter)) {
@@ -1664,11 +1770,13 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
1664
1770
  systemPrompt: body,
1665
1771
  source,
1666
1772
  filePath,
1773
+ ...(discoveryPriority !== undefined ? { discoveryPriority } : {}),
1667
1774
  ...(skills?.length ? { skills } : {}),
1668
1775
  ...(skillPath?.length ? { skillPath } : {}),
1669
1776
  ...(extensions !== undefined ? { extensions } : {}),
1670
1777
  ...(subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions } : {}),
1671
1778
  ...(frontmatter.output !== undefined ? { output: frontmatter.output } : {}),
1779
+ ...(outputMode !== undefined ? { outputMode } : {}),
1672
1780
  ...(defaultReads?.length ? { defaultReads } : {}),
1673
1781
  defaultProgress: frontmatter.defaultProgress === "true",
1674
1782
  interactive: frontmatter.interactive === "true",
@@ -1681,9 +1789,16 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
1681
1789
  };
1682
1790
  agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
1683
1791
  agents.push(agent);
1792
+ } catch (error) {
1793
+ diagnostics.push({ source, filePath, ...(name ? { name } : {}), ...(runtimeName && runtimeName !== name ? { runtimeName } : {}), ...(packageSpecified ? { packageSpecified: true } : {}), ...(discoveryPriority !== undefined ? { discoveryPriority } : {}), error: error instanceof Error ? error.message : String(error) });
1794
+ }
1684
1795
  }
1685
1796
 
1686
- return agents;
1797
+ return { agents, diagnostics };
1798
+ }
1799
+
1800
+ function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
1801
+ return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir), source, discoveryPriority);
1687
1802
  }
1688
1803
 
1689
1804
  function loadChainsFromDir(dir: string, source: AgentSource): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
@@ -1747,6 +1862,7 @@ function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; pref
1747
1862
  };
1748
1863
  }
1749
1864
  const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
1865
+ const BUILTIN_AGENT_DEFINITION_FILES = readAgentDefinitionFiles(BUILTIN_AGENTS_DIR);
1750
1866
 
1751
1867
  export const EXTRA_AGENT_DIRS_ENV = "PI_SUBAGENT_EXTRA_AGENT_DIRS";
1752
1868
 
@@ -1781,34 +1897,42 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
1781
1897
  includeProject: scope !== "user",
1782
1898
  });
1783
1899
 
1900
+ const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
1784
1901
  const builtinAgents = applyBuiltinOverrides(
1785
- applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
1902
+ applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
1786
1903
  userSettings,
1787
1904
  projectSettings,
1788
1905
  userSettingsPath,
1789
1906
  projectSettingsPath,
1790
1907
  );
1791
1908
 
1792
- const userAgentsExtra = scope === "project" ? [] : extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user"));
1793
- const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
1794
- const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
1909
+ const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew]
1910
+ .map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
1795
1911
  const userAgents = applyCustomAgentOverrides(
1796
- applySubagentDefaults([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel, defaultThinking, defaultExtensions),
1912
+ applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
1797
1913
  userSettings,
1798
1914
  projectSettings,
1799
1915
  userSettingsPath,
1800
1916
  projectSettingsPath,
1801
1917
  );
1802
1918
 
1919
+ const projectLoaded = scope === "user" ? [] : projectAgentDirs.map((dir) => loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0));
1803
1920
  const projectAgents = applyCustomAgentOverrides(
1804
- applySubagentDefaults(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel, defaultThinking, defaultExtensions),
1921
+ applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
1805
1922
  userSettings,
1806
1923
  projectSettings,
1807
1924
  userSettingsPath,
1808
1925
  projectSettingsPath,
1809
1926
  );
1927
+ const packageLoaded = packageSubagentPaths.agents.map((dir, index) => loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index));
1928
+ const packageMap = new Map<string, AgentConfig>();
1929
+ for (const loaded of packageLoaded) {
1930
+ for (const agent of loaded.agents) {
1931
+ if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
1932
+ }
1933
+ }
1810
1934
  const packageAgents = applyCustomAgentOverrides(
1811
- applySubagentDefaults(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel, defaultThinking, defaultExtensions),
1935
+ applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultThinking, defaultExtensions),
1812
1936
  userSettings,
1813
1937
  projectSettings,
1814
1938
  userSettingsPath,
@@ -1817,7 +1941,13 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
1817
1941
  const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
1818
1942
  .filter((agent) => agent.disabled !== true);
1819
1943
 
1820
- return { agents, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
1944
+ const agentDiagnostics = [
1945
+ ...builtinLoaded.diagnostics,
1946
+ ...userLoaded.flatMap((loaded) => loaded.diagnostics),
1947
+ ...projectLoaded.flatMap((loaded) => loaded.diagnostics),
1948
+ ...packageLoaded.flatMap((loaded) => loaded.diagnostics),
1949
+ ];
1950
+ return { agents, agentDiagnostics, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}) };
1821
1951
  }
1822
1952
 
1823
1953
  export function discoverAgentsAll(cwd: string): {
@@ -1825,6 +1955,7 @@ export function discoverAgentsAll(cwd: string): {
1825
1955
  package: AgentConfig[];
1826
1956
  user: AgentConfig[];
1827
1957
  project: AgentConfig[];
1958
+ agentDiagnostics?: AgentDiscoveryDiagnostic[];
1828
1959
  chains: ChainConfig[];
1829
1960
  chainDiagnostics: ChainDiscoveryDiagnostic[];
1830
1961
  userDir: string;
@@ -1848,27 +1979,29 @@ export function discoverAgentsAll(cwd: string): {
1848
1979
  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
1849
1980
  const packageSubagentPaths = collectPackageSubagentPaths(cwd);
1850
1981
 
1982
+ const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
1851
1983
  const builtin = applyBuiltinOverrides(
1852
- applySubagentDefaults(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel, defaultThinking, defaultExtensions),
1984
+ applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultThinking, defaultExtensions),
1853
1985
  userSettings,
1854
1986
  projectSettings,
1855
1987
  userSettingsPath,
1856
1988
  projectSettingsPath,
1857
1989
  );
1990
+ const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew]
1991
+ .map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
1858
1992
  const user = applyCustomAgentOverrides(
1859
- applySubagentDefaults([
1860
- ...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
1861
- ...loadAgentsFromDir(userDirOld, "user"),
1862
- ...loadAgentsFromDir(userDirNew, "user"),
1863
- ], defaultModel, defaultThinking, defaultExtensions),
1993
+ applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultThinking, defaultExtensions),
1864
1994
  userSettings,
1865
1995
  projectSettings,
1866
1996
  userSettingsPath,
1867
1997
  projectSettingsPath,
1868
1998
  );
1869
1999
  const packageMap = new Map<string, AgentConfig>();
1870
- for (const dir of packageSubagentPaths.agents) {
1871
- for (const agent of loadAgentsFromDir(dir, "package")) {
2000
+ const packageAgentDiagnostics: AgentDiscoveryDiagnostic[] = [];
2001
+ for (const [index, dir] of packageSubagentPaths.agents.entries()) {
2002
+ const loaded = loadAgentsFromDir(dir, "package", packageSubagentPaths.agents.length - index);
2003
+ packageAgentDiagnostics.push(...loaded.diagnostics);
2004
+ for (const agent of loaded.agents) {
1872
2005
  if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
1873
2006
  }
1874
2007
  }
@@ -1880,8 +2013,11 @@ export function discoverAgentsAll(cwd: string): {
1880
2013
  projectSettingsPath,
1881
2014
  );
1882
2015
  const projectMap = new Map<string, AgentConfig>();
2016
+ const projectAgentDiagnostics: AgentDiscoveryDiagnostic[] = [];
1883
2017
  for (const dir of projectDirs) {
1884
- for (const agent of loadAgentsFromDir(dir, "project")) {
2018
+ const loaded = loadAgentsFromDir(dir, "project", dir === projectDir ? 1 : 0);
2019
+ projectAgentDiagnostics.push(...loaded.diagnostics);
2020
+ for (const agent of loaded.agents) {
1885
2021
  projectMap.set(agent.name, agent);
1886
2022
  }
1887
2023
  }
@@ -1922,8 +2058,14 @@ export function discoverAgentsAll(cwd: string): {
1922
2058
  ...userChains.diagnostics,
1923
2059
  ...projectChainDiagnostics,
1924
2060
  ];
2061
+ const agentDiagnostics = [
2062
+ ...builtinLoaded.diagnostics,
2063
+ ...userLoaded.flatMap((loaded) => loaded.diagnostics),
2064
+ ...packageAgentDiagnostics,
2065
+ ...projectAgentDiagnostics,
2066
+ ];
1925
2067
 
1926
2068
  const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
1927
2069
 
1928
- return { builtin, package: packageAgents, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
2070
+ return { builtin, package: packageAgents, user, project, agentDiagnostics, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
1929
2071
  }
@@ -0,0 +1,9 @@
1
+ export const BUILTIN_AGENT_NAMES = [
2
+ "advisor",
3
+ "delegate",
4
+ "oracle",
5
+ "researcher",
6
+ "reviewer",
7
+ "scout",
8
+ "worker",
9
+ ] as const;