@xzzpig/pi-subagents 0.1.0 → 0.3.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 (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -144,6 +144,12 @@ function isStaleExtensionContextError(error: unknown): boolean {
144
144
  || error.message.includes("Extension context no longer active"));
145
145
  }
146
146
 
147
+ function foregroundDescription(control: { parentWorkflowRunId?: string; workflowKey?: string }, description: string | undefined): string | undefined {
148
+ if (!control.parentWorkflowRunId) return description;
149
+ const workflow = `workflow child: ${control.parentWorkflowRunId}${control.workflowKey ? ` (${control.workflowKey})` : ""}`;
150
+ return description ? `${workflow} · ${description}` : workflow;
151
+ }
152
+
147
153
  export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntry[] {
148
154
  const entries: FleetStatusEntry[] = [];
149
155
  for (const control of state.foregroundControls.values()) {
@@ -154,7 +160,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
154
160
  key: `foreground-active:${control.runId}:${child.index}`,
155
161
  agent: child.agent,
156
162
  ...(modelThinking ? { modelThinking } : {}),
157
- description: child.description,
163
+ description: foregroundDescription(control, child.description),
158
164
  startedAt: child.startedAt,
159
165
  tokens: child.tokens ?? 0,
160
166
  state: "running",
@@ -170,7 +176,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
170
176
  key: `foreground-active:${control.runId}:${control.currentIndex ?? 0}`,
171
177
  agent: control.currentAgent ?? control.mode,
172
178
  ...(modelThinking ? { modelThinking } : {}),
173
- description: control.description,
179
+ description: foregroundDescription(control, control.description),
174
180
  startedAt: control.startedAt,
175
181
  tokens: control.tokens ?? 0,
176
182
  state: "running",
@@ -301,26 +307,22 @@ export class SubagentFleetStatus {
301
307
  refresh(): void {
302
308
  const ctx = this.getActiveUiContext();
303
309
  if (!ctx) return;
310
+ if (this.state.widgetsSuspended) {
311
+ this.clearWidget();
312
+ return;
313
+ }
304
314
  this.entries = collectFleetStatusEntries(this.state);
305
315
  this.clampSelection();
306
316
  if (this.inspectorOpen || this.state.fleetInspectorOpen) {
307
317
  this.lastRenderKey = "";
308
- if (this.widgetRegistered) {
309
- ctx.ui.setWidget(FLEET_STATUS_WIDGET_KEY, undefined);
310
- this.widgetRegistered = false;
311
- this.tui = undefined;
312
- }
318
+ this.clearWidget();
313
319
  return;
314
320
  }
315
- if (this.entries.length === 0) {
321
+ if (this.entries.length === 0 && !(this.state.activeAsyncCapacity?.used)) {
316
322
  this.active = false;
317
323
  this.selectedKey = "main";
318
324
  this.lastRenderKey = "";
319
- if (this.widgetRegistered) {
320
- ctx.ui.setWidget(FLEET_STATUS_WIDGET_KEY, undefined);
321
- this.widgetRegistered = false;
322
- this.tui = undefined;
323
- }
325
+ this.clearWidget();
324
326
  return;
325
327
  }
326
328
 
@@ -350,6 +352,7 @@ export class SubagentFleetStatus {
350
352
  }
351
353
 
352
354
  handleKey(data: string): { consume?: boolean; data?: string } | undefined {
355
+ if (this.state.widgetsSuspended) return undefined;
353
356
  const ctx = this.getActiveUiContext();
354
357
  if (!ctx || this.entries.length === 0 || isKeyRelease(data)) return undefined;
355
358
  if (this.inspectorOpen) return undefined;
@@ -410,10 +413,13 @@ export class SubagentFleetStatus {
410
413
  }
411
414
 
412
415
  render(width: number, theme: Theme): string[] {
413
- if (this.entries.length === 0) return [];
416
+ if (this.entries.length === 0 && !(this.state.activeAsyncCapacity?.used)) return [];
414
417
  if (!this.active) {
415
418
  const tokens = this.entries.reduce((total, entry) => total + entry.tokens, 0);
416
- const label = `${this.entries.length} active ${this.entries.length === 1 ? "agent" : "agents"}`;
419
+ const capacity = this.state.activeAsyncCapacity;
420
+ const asyncRuns = capacity ? `Async runs ${capacity.used}/${capacity.limit || "∞"}` : "";
421
+ const agents = this.entries.length > 0 ? `${this.entries.length} active ${this.entries.length === 1 ? "agent" : "agents"}` : "";
422
+ const label = [agents, asyncRuns].filter(Boolean).join(" · ");
417
423
  return [truncateToWidth(` ${theme.fg("muted", label)} · ${theme.fg("dim", `${formatFleetTokens(tokens)} · ↓/← to inspect`)}`, width)];
418
424
  }
419
425
  const roster = this.rosterKeys();
@@ -441,9 +447,8 @@ export class SubagentFleetStatus {
441
447
  }
442
448
 
443
449
  private renderEntry(rosterIndex: number, selectedIndex: number, entry: FleetStatusEntry, width: number, theme: Theme): string {
444
- const description = entry.description?.replace(/\s+/g, " ").trim();
445
450
  const agent = entry.modelThinking ? `${entry.agent} (${entry.modelThinking})` : entry.agent;
446
- const left = ` ${this.bullet(rosterIndex, selectedIndex, theme)} ${theme.fg("muted", agent)} · ${entry.state}${description ? ` ${description}` : ""}`;
451
+ const left = ` ${this.bullet(rosterIndex, selectedIndex, theme)} ${theme.fg("muted", agent)} · ${entry.state}`;
447
452
  const elapsed = Date.now() - entry.startedAt;
448
453
  const right = theme.fg("dim", `${formatFleetElapsed(elapsed)} · ${formatFleetTokens(entry.tokens)}`);
449
454
  return rightAlign(left, right, width);
@@ -530,6 +535,13 @@ export class SubagentFleetStatus {
530
535
  }
531
536
  }
532
537
 
538
+ private clearWidget(): void {
539
+ if (!this.widgetRegistered) return;
540
+ this.ui?.setWidget(FLEET_STATUS_WIDGET_KEY, undefined);
541
+ this.widgetRegistered = false;
542
+ this.tui = undefined;
543
+ }
544
+
533
545
  private clearUiRegistration(): void {
534
546
  if (this.timer) clearInterval(this.timer);
535
547
  this.timer = undefined;
@@ -2,59 +2,12 @@ import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import { getLanguageFromPath, highlightCode, type ExtensionContext } from "@earendil-works/pi-coding-agent";
4
4
  import { Markdown, truncateToWidth, visibleWidth, wrapTextWithAnsi, type MarkdownTheme } from "@earendil-works/pi-tui";
5
+ import { safeTerminalText as safeDisplayText } from "../shared/display-text.ts";
5
6
 
6
7
  const DEFAULT_MAX_RECORDS = 240;
7
8
  const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
8
9
  const MAX_MESSAGE_CHARS = 64 * 1024;
9
10
  const TOOL_PREVIEW_LINES = 7;
10
- const BINARY_CONTENT_PLACEHOLDER = "[binary content omitted for safe display]";
11
-
12
- function isUnsafeDisplayCodePoint(codePoint: number): boolean {
13
- const terminalControl = (codePoint <= 0x1f && codePoint !== 0x09 && codePoint !== 0x0a)
14
- || (codePoint >= 0x7f && codePoint <= 0x9f);
15
- const bidiControl = codePoint === 0x061c
16
- || codePoint === 0x200e
17
- || codePoint === 0x200f
18
- || (codePoint >= 0x202a && codePoint <= 0x202e)
19
- || (codePoint >= 0x2066 && codePoint <= 0x2069);
20
- const privateUse = (codePoint >= 0xe000 && codePoint <= 0xf8ff)
21
- || (codePoint >= 0xf0000 && codePoint <= 0xffffd)
22
- || (codePoint >= 0x100000 && codePoint <= 0x10fffd);
23
- const invalidScalar = codePoint >= 0xd800 && codePoint <= 0xdfff;
24
- const nonCharacter = (codePoint >= 0xfdd0 && codePoint <= 0xfdef)
25
- || (codePoint & 0xffff) === 0xfffe
26
- || (codePoint & 0xffff) === 0xffff;
27
- return terminalControl || bidiControl || privateUse || invalidScalar || nonCharacter;
28
- }
29
-
30
- function looksLikeBinaryContent(text: string): boolean {
31
- if (text.includes("\0")) return true;
32
- let suspiciousControls = 0;
33
- let replacementCharacters = 0;
34
- let codePoints = 0;
35
- for (const character of text) {
36
- codePoints++;
37
- const codePoint = character.codePointAt(0) ?? 0;
38
- if ((codePoint <= 0x08) || (codePoint >= 0x0e && codePoint <= 0x1f)) suspiciousControls++;
39
- if (codePoint === 0xfffd) replacementCharacters++;
40
- }
41
- if (codePoints === 0) return false;
42
- return (suspiciousControls >= 4 && suspiciousControls / codePoints >= 0.1)
43
- || (replacementCharacters >= 3 && replacementCharacters / codePoints >= 0.1);
44
- }
45
-
46
- function safeDisplayText(text: string): string {
47
- const normalized = text.replace(/\r\n/g, "\n");
48
- if (looksLikeBinaryContent(normalized)) return BINARY_CONTENT_PLACEHOLDER;
49
- let safe = "";
50
- for (const character of normalized) {
51
- const codePoint = character.codePointAt(0) ?? 0;
52
- safe += isUnsafeDisplayCodePoint(codePoint)
53
- ? `[U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}]`
54
- : character;
55
- }
56
- return safe;
57
- }
58
11
 
59
12
  function sanitizeJsonDisplayValue(value: unknown): { value: unknown; changed: boolean } {
60
13
  if (typeof value === "string") {