@xzzpig/pi-subagents 0.6.0 → 0.8.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 (98) hide show
  1. package/CHANGELOG.md +45 -4
  2. package/README.md +1 -1
  3. package/agents/reviewer.md +12 -2
  4. package/docs/agents.md +4 -4
  5. package/docs/configuration.md +6 -6
  6. package/docs/extension-api.md +14 -4
  7. package/docs/models.md +47 -6
  8. package/docs/observability.md +14 -3
  9. package/docs/tool-reference.md +21 -6
  10. package/docs/workflows.md +7 -1
  11. package/index.ts +10 -1
  12. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +102 -0
  13. package/node_modules/@xzzpig/pi-components/LICENSE +21 -0
  14. package/node_modules/@xzzpig/pi-components/README.md +59 -0
  15. package/node_modules/@xzzpig/pi-components/dist/index.d.ts +1 -0
  16. package/node_modules/@xzzpig/pi-components/dist/index.js +1 -0
  17. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +345 -0
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +1169 -0
  19. package/node_modules/@xzzpig/pi-components/package.json +49 -0
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +1785 -0
  21. package/package.json +7 -3
  22. package/prompts/council.md +19 -7
  23. package/prompts/parallel-review.md +5 -1
  24. package/prompts/review-loop.md +9 -5
  25. package/skills/council-mode/SKILL.md +50 -26
  26. package/skills/pi-subagents/SKILL.md +5 -1
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +16 -1
  28. package/skills/pi-subagents/references/execution-controls.md +13 -4
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -3
  30. package/skills/pi-subagents/references/prompting-and-roles.md +14 -7
  31. package/src/agents/agent-management.ts +115 -14
  32. package/src/agents/agent-serializer.ts +4 -2
  33. package/src/agents/agents.ts +226 -48
  34. package/src/api/external-job-provider.ts +10 -1
  35. package/src/api/preflight.ts +52 -19
  36. package/src/api/project-panes.ts +2 -0
  37. package/src/extension/doctor.ts +10 -0
  38. package/src/extension/fanout-child.ts +3 -2
  39. package/src/extension/index.ts +24 -4
  40. package/src/extension/public-execution.ts +12 -9
  41. package/src/extension/rpc.ts +77 -3
  42. package/src/extension/schemas.ts +7 -1
  43. package/src/extension/tool-description.ts +9 -6
  44. package/src/extension/tool-result.ts +19 -0
  45. package/src/inspectors/herdr/client.ts +3 -3
  46. package/src/inspectors/herdr/focus.ts +55 -0
  47. package/src/inspectors/herdr/project-panes.ts +228 -44
  48. package/src/integrations/herdr-status.ts +26 -4
  49. package/src/runs/background/async-execution.ts +146 -17
  50. package/src/runs/background/async-job-tracker.ts +33 -14
  51. package/src/runs/background/async-resume.ts +23 -2
  52. package/src/runs/background/async-retention.ts +1 -1
  53. package/src/runs/background/async-status.ts +10 -0
  54. package/src/runs/background/chain-root-attachment.ts +5 -0
  55. package/src/runs/background/control-channel.ts +98 -10
  56. package/src/runs/background/notify.ts +62 -1
  57. package/src/runs/background/result-watcher.ts +4 -3
  58. package/src/runs/background/run-status.ts +15 -1
  59. package/src/runs/background/stale-run-reconciler.ts +3 -0
  60. package/src/runs/background/subagent-runner.ts +333 -48
  61. package/src/runs/background/wait-completions.ts +2 -0
  62. package/src/runs/background/wait-tool.ts +4 -3
  63. package/src/runs/foreground/async-stop-action.ts +23 -2
  64. package/src/runs/foreground/execution.ts +148 -13
  65. package/src/runs/foreground/foreground-history.ts +3 -2
  66. package/src/runs/foreground/subagent-executor.ts +417 -50
  67. package/src/runs/foreground/workflow-detach-reconcile.ts +18 -6
  68. package/src/runs/shared/acceptance.ts +11 -5
  69. package/src/runs/shared/agent-contract.ts +1 -1
  70. package/src/runs/shared/child-identity.ts +36 -0
  71. package/src/runs/shared/completion-guard.ts +52 -2
  72. package/src/runs/shared/dynamic-fanout.ts +1 -1
  73. package/src/runs/shared/extension-bindings.ts +78 -0
  74. package/src/runs/shared/external-cli-runner.ts +2 -0
  75. package/src/runs/shared/external-job-bridge.ts +53 -37
  76. package/src/runs/shared/external-job-runner.ts +126 -23
  77. package/src/runs/shared/fast-mode-extension.ts +10 -0
  78. package/src/runs/shared/model-exclusions.ts +2 -1
  79. package/src/runs/shared/model-fallback.ts +48 -22
  80. package/src/runs/shared/model-scope.ts +106 -39
  81. package/src/runs/shared/mutation-evidence.ts +145 -0
  82. package/src/runs/shared/orca-progress-tabs.ts +71 -9
  83. package/src/runs/shared/parallel-utils.ts +15 -0
  84. package/src/runs/shared/pi-args.ts +78 -1
  85. package/src/runs/shared/structured-output.ts +18 -4
  86. package/src/runs/shared/subagent-prompt-runtime.ts +48 -15
  87. package/src/runs/shared/tool-availability.ts +1 -3
  88. package/src/shared/launch-contract.ts +12 -5
  89. package/src/shared/settings.ts +6 -1
  90. package/src/shared/thinking-ceiling.ts +52 -0
  91. package/src/shared/types.ts +121 -5
  92. package/src/tui/fleet-native-transcript.ts +374 -0
  93. package/src/tui/fleet-status.ts +66 -13
  94. package/src/tui/fleet-transcript.ts +47 -1
  95. package/src/tui/fleet.ts +96 -24
  96. package/src/tui/render.ts +5 -4
  97. package/src/watchdog/permission-arbiter.ts +59 -52
  98. package/src/workflows/scripted-workflow.ts +156 -12
@@ -39,6 +39,7 @@ import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from
39
39
  import { getProjectConfigDir } from "../shared/utils.ts";
40
40
  import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
41
41
  import { listRuntimeAgentConfigs, mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
42
+ import { listExternalJobProviders } from "../api/external-job-provider.ts";
42
43
 
43
44
  export const AGENT_MANAGEMENT_API_VERSION = 1 as const;
44
45
 
@@ -113,18 +114,23 @@ function parseCsv(value: string): string[] {
113
114
  return [...new Set(value.split(",").map((v) => v.trim()).filter(Boolean))];
114
115
  }
115
116
 
116
- function configObject(config: unknown): { value?: Record<string, unknown>; error?: string } {
117
+ type ConfigObjectResult =
118
+ | { status: "ok"; value: Record<string, unknown> }
119
+ | { status: "missing" }
120
+ | { status: "error"; message: string };
121
+
122
+ function configObject(config: unknown): ConfigObjectResult {
117
123
  let val = config;
118
124
  if (typeof val === "string") {
119
125
  try {
120
126
  val = JSON.parse(val);
121
127
  } catch (error) {
122
128
  const message = error instanceof Error ? error.message : String(error);
123
- return { error: `config must be valid JSON: ${message}` };
129
+ return { status: "error", message: `config must be valid JSON: ${message}` };
124
130
  }
125
131
  }
126
- if (!val || typeof val !== "object" || Array.isArray(val)) return {};
127
- return { value: val as Record<string, unknown> };
132
+ if (!val || typeof val !== "object" || Array.isArray(val)) return { status: "missing" };
133
+ return { status: "ok", value: val as Record<string, unknown> };
128
134
  }
129
135
 
130
136
  function hasKey(obj: Record<string, unknown>, key: string): boolean {
@@ -232,7 +238,8 @@ function isMutableSource(source: AgentSource): source is ManagementScope {
232
238
  function modelWarning(ctx: ManagementContext, model: string | undefined): string | undefined {
233
239
  if (!model) return undefined;
234
240
  const found = ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === model || m.id === model);
235
- return found ? undefined : `Warning: model '${model}' is not in the current model registry.`;
241
+ if (found) return undefined;
242
+ return `Warning: model '${model}' is not in the current model registry. Run subagent({ action: "models" }) to list valid provider/id selectors, then use the exact provider/id form (bare ids resolve only when unique).`;
236
243
  }
237
244
 
238
245
  function fallbackModelsWarning(ctx: ManagementContext, fallbackModels: string[] | undefined): string | undefined {
@@ -270,7 +277,9 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
270
277
  const base = agent.override?.base;
271
278
  const {
272
279
  override: _override,
280
+ output: _output,
273
281
  outputMode: _outputMode,
282
+ defaultReads: _defaultReads,
274
283
  model: _model,
275
284
  fallbackModels: _fallbackModels,
276
285
  thinking: _thinking,
@@ -298,7 +307,9 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
298
307
 
299
308
  return withDeclaredExtensionPaths({
300
309
  ...editable,
310
+ ...(base.output !== undefined ? { output: base.output } : {}),
301
311
  ...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
312
+ ...(base.defaultReads !== undefined ? { defaultReads: [...base.defaultReads] } : {}),
302
313
  ...(base.model !== undefined ? { model: base.model } : {}),
303
314
  ...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
304
315
  ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
@@ -646,9 +657,83 @@ function renamePath(currentPath: string, newName: string, scope: ManagementScope
646
657
  return { filePath };
647
658
  }
648
659
 
660
+ function packageSourceLabel(agent: AgentConfig): string {
661
+ if (!agent.packageSourceName) return agent.source;
662
+ return agent.packageSourceVersion ? `${agent.packageSourceName}@${agent.packageSourceVersion}` : agent.packageSourceName;
663
+ }
664
+
665
+ type ExternalJobProviderStatus =
666
+ | { ok: true; names: Set<string> }
667
+ | { ok: false; error: string };
668
+
669
+ function errorMessage(error: unknown): string {
670
+ return error instanceof Error ? error.message : String(error);
671
+ }
672
+
673
+ function registeredExternalJobProviderStatus(): ExternalJobProviderStatus {
674
+ try {
675
+ return { ok: true, names: new Set(listExternalJobProviders().map((provider) => provider.name)) };
676
+ } catch (error) {
677
+ return { ok: false, error: errorMessage(error) };
678
+ }
679
+ }
680
+
681
+ function externalJobProviderSuffix(provider: string, names: Set<string> | undefined): string {
682
+ if (!names) return "?";
683
+ return names.has(provider) ? "✓" : "missing";
684
+ }
685
+
686
+ function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined): string | undefined {
687
+ if (agent.runner?.type === "external-job") return `external-job:${agent.runner.provider} ${externalJobProviderSuffix(agent.runner.provider, providerNames)}`;
688
+ if (agent.runner?.type === "external-cli") return "external-cli";
689
+ return undefined;
690
+ }
691
+
692
+ function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
693
+ const source = agent.source === "package" ? packageSourceLabel(agent) : agent.source;
694
+ const parts = [
695
+ source,
696
+ runnerListBadge(agent, providerNames),
697
+ agent.defaultContext ? `context: ${agent.defaultContext}` : undefined,
698
+ agent.aliases?.length ? `aliases: ${agent.aliases.join(", ")}` : undefined,
699
+ ].filter((part): part is string => Boolean(part));
700
+ return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
701
+ }
702
+
703
+ function formatAgentListSections(agents: AgentConfig[], providerNames: Set<string> | undefined): string[] {
704
+ if (agents.length === 0) return ["- (none)"];
705
+ const sections: Array<[AgentSource, string]> = [
706
+ ["package", "Package agents"],
707
+ ["user", "User agents"],
708
+ ["project", "Project agents"],
709
+ ["runtime", "Runtime agents"],
710
+ ["builtin", "Builtin agents"],
711
+ ];
712
+ const lines: string[] = [];
713
+ for (const [source, label] of sections) {
714
+ const matches = agents.filter((agent) => agent.source === source);
715
+ if (matches.length === 0) continue;
716
+ if (lines.length > 0) lines.push("");
717
+ lines.push(label, ...matches.map((agent) => formatAgentListLine(agent, providerNames)));
718
+ }
719
+ return lines;
720
+ }
721
+
722
+ function formatRunnerDetail(agent: AgentConfig, providerNames: Set<string> | undefined): string | undefined {
723
+ if (!agent.runner) return undefined;
724
+ if (agent.runner.type === "external-job") return `Runner: external-job via ${agent.runner.provider} ${externalJobProviderSuffix(agent.runner.provider, providerNames)}`;
725
+ if (agent.runner.type === "external-cli") return `Runner: external-cli ${agent.runner.command}`;
726
+ return `Runner: ${JSON.stringify(agent.runner)}`;
727
+ }
728
+
649
729
  function formatAgentDetail(agent: AgentConfig): string {
650
730
  const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
731
+ const providerStatus = registeredExternalJobProviderStatus();
651
732
  const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
733
+ if (agent.source === "package" && agent.packageSourceName) {
734
+ lines.push(`Source package: ${packageSourceLabel(agent)}`);
735
+ if (agent.packageSourceRoot) lines.push(`Package root: ${agent.packageSourceRoot}`);
736
+ }
652
737
  if (agent.packageName) {
653
738
  lines.push(`Local name: ${frontmatterNameForConfig(agent)}`);
654
739
  lines.push(`Package: ${agent.packageName}`);
@@ -660,7 +745,12 @@ function formatAgentDetail(agent: AgentConfig): string {
660
745
  if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
661
746
  if (agent.skillPath?.length) lines.push(`Skill paths: ${agent.skillPath.join(", ")}`);
662
747
  lines.push(`System prompt mode: ${agent.systemPromptMode}`);
663
- if (agent.runner) lines.push(`Runner: ${JSON.stringify(agent.runner)}`);
748
+ const runnerDetail = formatRunnerDetail(agent, providerStatus.ok ? providerStatus.names : undefined);
749
+ if (runnerDetail) {
750
+ lines.push(runnerDetail);
751
+ if (agent.runner?.type === "external-job" && !providerStatus.ok) lines.push(`External-job provider registry unavailable: ${providerStatus.error}`);
752
+ if (agent.runner?.type === "external-job" && agent.runner.options) lines.push(`Runner options: ${JSON.stringify(agent.runner.options)}`);
753
+ }
664
754
  lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
665
755
  lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
666
756
  if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
@@ -710,16 +800,16 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
710
800
  ...(ctx.config?.proactiveSkillSubagents !== undefined ? { config: ctx.config.proactiveSkillSubagents } : {}),
711
801
  discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
712
802
  });
803
+ const providerStatus = registeredExternalJobProviderStatus();
713
804
  const lines = [
714
805
  "Executable agents:",
715
- ...(agents.length
716
- ? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`)
717
- : ["- (none)"]),
806
+ ...formatAgentListSections(agents, providerStatus.ok ? providerStatus.names : undefined),
718
807
  ...(restrictedAgents.length ? [
719
808
  "",
720
809
  `Restricted agents (not executable in this session${restrictedSources?.length ? `; capability ceiling: ${restrictedSources.join(", ")}` : ""}):`,
721
- ...restrictedAgents.map((a) => `- ${a.name} (${a.source}${a.aliases?.length ? `, aliases: ${a.aliases.join(", ")}` : ""}): ${a.description}`),
810
+ ...restrictedAgents.map((a) => formatAgentListLine(a, providerStatus.ok ? providerStatus.names : undefined)),
722
811
  ] : []),
812
+ ...(!providerStatus.ok && [...agents, ...restrictedAgents].some((agent) => agent.runner?.type === "external-job") ? ["", `External-job provider registry unavailable: ${providerStatus.error}`] : []),
723
813
  ...(d.agentDiagnostics?.length ? [
724
814
  "",
725
815
  "Invalid agent definitions:",
@@ -808,6 +898,17 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
808
898
  lines.push("");
809
899
  }
810
900
 
901
+ const availableFullIds = availableModels.map((m) => m.fullId).sort();
902
+ if (availableFullIds.length > 0) {
903
+ lines.push("Available models in this session's registry (copy an exact provider/id when passing model):");
904
+ lines.push("");
905
+ const shown = availableFullIds.slice(0, 80);
906
+ for (const fullId of shown) lines.push(` ${fullId}`);
907
+ if (availableFullIds.length > shown.length) lines.push(` ... and ${availableFullIds.length - shown.length} more`);
908
+ lines.push("");
909
+ lines.push("Use an exact provider/id from this list when you pass model; bare ids resolve only when unique in the registry.");
910
+ }
911
+
811
912
  return result(lines.join("\n"));
812
913
  }
813
914
 
@@ -833,9 +934,9 @@ function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolR
833
934
 
834
935
  export function handleCreate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
835
936
  const parsedConfig = configObject(params.config);
836
- if (parsedConfig.error) return result(parsedConfig.error, true);
937
+ if (parsedConfig.status === "error") return result(parsedConfig.message, true);
938
+ if (parsedConfig.status === "missing") return result("config required for create.", true);
837
939
  const cfg = parsedConfig.value;
838
- if (!cfg) return result("config required for create.", true);
839
940
  if (typeof cfg.name !== "string" || !cfg.name.trim()) return result("config.name is required and must be a non-empty string.", true);
840
941
  if (typeof cfg.description !== "string" || !cfg.description.trim()) return result("config.description is required and must be a non-empty string.", true);
841
942
  const name = sanitizeName(cfg.name);
@@ -883,9 +984,9 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
883
984
  export function handleUpdate(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
884
985
  if (!params.agent) return result("Specify 'agent' for update.", true);
885
986
  const parsedConfig = configObject(params.config);
886
- if (parsedConfig.error) return result(parsedConfig.error, true);
987
+ if (parsedConfig.status === "error") return result(parsedConfig.message, true);
988
+ if (parsedConfig.status === "missing") return result("config required for update.", true);
887
989
  const cfg = parsedConfig.value;
888
- if (!cfg) return result("config required for update.", true);
889
990
  if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
890
991
  const warnings: string[] = [];
891
992
  const scopeHint = asDisambiguationScope(params.agentScope);
@@ -11,6 +11,7 @@ export const KNOWN_FIELDS = new Set([
11
11
  "tools",
12
12
  "model",
13
13
  "fallbackModels",
14
+ "fast",
14
15
  "thinking",
15
16
  "systemPromptMode",
16
17
  "inheritProjectContext",
@@ -72,6 +73,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
72
73
  if (config.model || preserve("model")) lines.push(`model: ${config.model ?? ""}`);
73
74
  const fallbackModelsValue = joinComma(config.fallbackModels);
74
75
  if (fallbackModelsValue || preserve("fallbackModels")) lines.push(`fallbackModels: ${fallbackModelsValue ?? ""}`);
76
+ if (config.fast === true || preserve("fast")) lines.push(`fast: ${config.fast === undefined ? "" : config.fast ? "true" : "false"}`);
75
77
  if ((config.thinking && (config.thinking !== "off" || preserve("thinking"))) || (!config.thinking && preserve("thinking"))) {
76
78
  lines.push(`thinking: ${config.thinking ?? ""}`);
77
79
  }
@@ -114,11 +116,11 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
114
116
  lines.push(`subagentOnlyExtensions: ${subagentOnlyExtensionsValue ?? ""}`);
115
117
  }
116
118
 
117
- if (config.output) lines.push(`output: ${config.output}`);
119
+ if (config.output || preserve("output")) lines.push(`output: ${config.output ?? ""}`);
118
120
  if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
119
121
 
120
122
  const readsValue = joinComma(config.defaultReads);
121
- if (readsValue) lines.push(`defaultReads: ${readsValue}`);
123
+ if (readsValue || preserve("defaultReads")) lines.push(`defaultReads: ${readsValue ?? ""}`);
122
124
 
123
125
  if (config.defaultProgress) lines.push("defaultProgress: true");
124
126
  if (config.injectToContext) lines.push("injectToContext: true");