@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.
- package/CHANGELOG.md +175 -0
- package/README.md +4 -0
- package/agents/oracle.md +3 -1
- package/agents/reviewer.md +1 -0
- package/agents/scout.md +2 -2
- package/agents/worker.md +2 -1
- package/async-retention-discovery-worker.mjs +180 -0
- package/docs/agents.md +41 -3
- package/docs/configuration.md +41 -13
- package/docs/extension-api.md +65 -2
- package/docs/models.md +2 -0
- package/docs/observability.md +41 -5
- package/docs/tool-reference.md +38 -39
- package/docs/workflows.md +173 -3
- package/package.json +14 -10
- package/prompts/council.md +48 -0
- package/skills/council-mode/SKILL.md +230 -0
- package/skills/pi-subagents/SKILL.md +8 -4
- package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
- package/skills/pi-subagents/references/execution-controls.md +40 -15
- package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
- package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
- package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
- package/src/agents/agent-management.ts +471 -377
- package/src/agents/agent-serializer.ts +2 -0
- package/src/agents/agents.ts +186 -44
- package/src/agents/builtin-names.ts +9 -0
- package/src/agents/runtime-agent-registry.ts +418 -0
- package/src/agents/skills.ts +1 -1
- package/src/api/agent-management.ts +9 -0
- package/src/api/agents.ts +7 -0
- package/src/api/external-job-provider.ts +186 -0
- package/src/api/preflight.ts +45 -13
- package/src/api/shared-types.ts +2 -0
- package/src/extension/config.ts +6 -3
- package/src/extension/doctor.ts +4 -6
- package/src/extension/fanout-child.ts +2 -2
- package/src/extension/index.ts +183 -90
- package/src/extension/public-execution.ts +31 -2
- package/src/extension/rpc.ts +41 -1
- package/src/extension/schemas.ts +17 -37
- package/src/extension/tool-description.ts +35 -24
- package/src/inspectors/herdr/actions.ts +2 -2
- package/src/inspectors/herdr/inspector-runner.ts +2 -1
- package/src/inspectors/herdr/project-panes.ts +2 -2
- package/src/intercom/native-supervisor-channel.ts +32 -10
- package/src/missions/lifecycle.ts +6 -1
- package/src/missions/store.ts +4 -9
- package/src/missions/workflow-state.ts +2 -2
- package/src/profiles/profiles.ts +3 -1
- package/src/runs/background/active-run-index.ts +31 -8
- package/src/runs/background/async-execution.ts +70 -41
- package/src/runs/background/async-job-tracker.ts +24 -7
- package/src/runs/background/async-resume.ts +49 -16
- package/src/runs/background/async-retention.ts +886 -0
- package/src/runs/background/async-status-snapshot.ts +14 -5
- package/src/runs/background/async-status.ts +39 -53
- package/src/runs/background/auto-drain.ts +1 -0
- package/src/runs/background/chain-append.ts +3 -33
- package/src/runs/background/completion-dedupe.ts +5 -1
- package/src/runs/background/completion-replay.ts +22 -12
- package/src/runs/background/control-channel.ts +14 -68
- package/src/runs/background/fleet-view.ts +68 -19
- package/src/runs/background/index-segment.ts +59 -0
- package/src/runs/background/inspect-rpc.ts +443 -0
- package/src/runs/background/notify.ts +31 -5
- package/src/runs/background/result-files.ts +158 -90
- package/src/runs/background/result-watcher.ts +124 -20
- package/src/runs/background/resume-guidance.ts +8 -5
- package/src/runs/background/retained-children.ts +13 -3
- package/src/runs/background/run-id-query.ts +7 -0
- package/src/runs/background/run-id-resolver.ts +11 -9
- package/src/runs/background/run-status.ts +27 -18
- package/src/runs/background/scheduled-runs.ts +24 -4
- package/src/runs/background/stale-run-reconciler.ts +6 -3
- package/src/runs/background/steering.ts +11 -1
- package/src/runs/background/subagent-runner.ts +260 -144
- package/src/runs/background/subagent-wait.ts +17 -13
- package/src/runs/background/terminal-run-index.ts +138 -0
- package/src/runs/background/wait-completions.ts +21 -4
- package/src/runs/background/wait-subscriptions.ts +81 -2
- package/src/runs/background/wait-tool.ts +1 -0
- package/src/runs/foreground/async-steering-action.ts +21 -14
- package/src/runs/foreground/execution.ts +104 -71
- package/src/runs/foreground/subagent-executor.ts +816 -1593
- package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
- package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
- package/src/runs/shared/acceptance.ts +48 -5
- package/src/runs/shared/chain-outputs.ts +1 -3
- package/src/runs/shared/external-job-bridge.ts +444 -0
- package/src/runs/shared/external-job-runner.ts +286 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
- package/src/runs/shared/model-exclusions.ts +242 -0
- package/src/runs/shared/model-fallback.ts +153 -40
- package/src/runs/shared/orca-progress-tabs.ts +84 -22
- package/src/runs/shared/parallel-handoff.ts +46 -4
- package/src/runs/shared/parallel-utils.ts +4 -15
- package/src/runs/shared/permissions.ts +5 -1
- package/src/runs/shared/pi-args.ts +8 -1
- package/src/runs/shared/session-lease.ts +0 -6
- package/src/runs/shared/subagent-control.ts +51 -7
- package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
- package/src/runs/shared/workflow-graph.ts +1 -23
- package/src/runs/shared/worktree.ts +14 -2
- package/src/shared/atomic-json.ts +22 -2
- package/src/shared/capacity-resilient-json.ts +102 -0
- package/src/shared/completion-owner.ts +14 -0
- package/src/shared/file-system-retry.ts +49 -1
- package/src/shared/fork-context.ts +59 -1
- package/src/shared/model-info.ts +20 -0
- package/src/shared/prompt-resources.ts +0 -40
- package/src/shared/settings.ts +5 -29
- package/src/shared/types.ts +106 -26
- package/src/shared/utils.ts +8 -0
- package/src/shared/watch-strategy.ts +10 -0
- package/src/slash/slash-bridge.ts +2 -1
- package/src/slash/slash-commands.ts +47 -7
- package/src/slash/slash-live-state.ts +3 -3
- package/src/tui/fleet-status.ts +86 -1
- package/src/tui/fleet.ts +117 -16
- package/src/tui/render.ts +73 -3
- package/src/watchdog/change-signature.ts +1 -1
- package/src/watchdog/lsp-diagnostics.ts +1 -0
- package/src/workflows/chat-progress.ts +2 -2
- package/src/workflows/scripted-workflow.ts +320 -79
- package/src/workflows/workflow-receipt.ts +140 -0
- package/src/runs/foreground/chain-clarify.ts +0 -1354
- 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}`);
|
package/src/agents/agents.ts
CHANGED
|
@@ -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-
|
|
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='
|
|
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
|
-
|
|
1514
|
-
|
|
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
|
|
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
|
-
|
|
1636
|
+
packageSpecified = parsedPackage.packageName !== undefined || parsedPackage.error !== undefined;
|
|
1637
|
+
if (parsedPackage.error) throw new Error(parsedPackage.error);
|
|
1537
1638
|
const packageName = parsedPackage.packageName;
|
|
1538
|
-
|
|
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(
|
|
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
|
|
1793
|
-
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
1871
|
-
|
|
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
|
-
|
|
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
|
}
|