@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
@@ -328,6 +328,7 @@ export interface FileMutationEffect {
328
328
  expected: boolean;
329
329
  attempted: boolean;
330
330
  message?: string;
331
+ resolvedBy?: "llm-intent-arbiter";
331
332
  }
332
333
 
333
334
  export interface EffectsProjection {
@@ -343,6 +344,7 @@ export type ProcessTerminalReason =
343
344
  | "runner-candidate-missing"
344
345
  | "runner-instance-mismatch"
345
346
  | "writer-close-unverified"
347
+ | "process-tree-unverified"
346
348
  | "canonical-session-unavailable"
347
349
  | "canonical-session-lease-active"
348
350
  | "canonical-session-release-unverified"
@@ -357,6 +359,19 @@ export interface RunnerProcessInstanceExitV1 {
357
359
  signal: string | null;
358
360
  }
359
361
 
362
+ export type ProcessTreeTerminalV1 =
363
+ | {
364
+ state: "observed";
365
+ mechanism: "posix-process-group";
366
+ processGroupId: number;
367
+ verifiedAt: number;
368
+ }
369
+ | {
370
+ state: "unknown";
371
+ reason: "unsupported-platform" | "signal-failed" | "verification-failed";
372
+ diagnostic?: string;
373
+ };
374
+
360
375
  export interface PiWriterProcessInstanceExitV1 {
361
376
  processInstanceId: string;
362
377
  kind: "pi-writer";
@@ -364,6 +379,7 @@ export interface PiWriterProcessInstanceExitV1 {
364
379
  closeObservedAt: number;
365
380
  exitCode: number | null;
366
381
  signal: string | null;
382
+ processTree: ProcessTreeTerminalV1;
367
383
  }
368
384
 
369
385
  export type ProcessInstanceExitV1 = RunnerProcessInstanceExitV1 | PiWriterProcessInstanceExitV1;
@@ -462,9 +478,30 @@ export interface SteeringNotice {
462
478
  currentSessionId?: string;
463
479
  }
464
480
 
481
+ export interface RunFanoutBudgetDescriptor {
482
+ version: 1;
483
+ rootRunId: string;
484
+ directory: string;
485
+ limit: number;
486
+ parentPath?: string;
487
+ }
488
+
489
+ export interface RunFanoutBudgetSnapshot {
490
+ used: number;
491
+ limit: number;
492
+ remaining: number;
493
+ }
494
+
495
+ export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
496
+ code: "RUN_FANOUT_LIMIT";
497
+ path: string;
498
+ requested: number;
499
+ }
500
+
465
501
  export interface SteeringRecoveryDescriptor {
466
502
  version: 1;
467
503
  launchContractDigest?: string;
504
+ runFanoutBudget: RunFanoutBudgetDescriptor;
468
505
  sourceRunId: string;
469
506
  agentContract?: AgentContract;
470
507
  agent: string;
@@ -491,6 +528,8 @@ export interface SteeringRecoveryDescriptor {
491
528
  structuredOutputSchema?: JsonSchemaObject;
492
529
  acceptance?: AcceptanceInput;
493
530
  controlConfig?: ResolvedControlConfig;
531
+ /** Raw per-run bridge override. Omitted descriptors continue to use global config. */
532
+ intercomBridge?: IntercomBridgeConfig;
494
533
  absoluteDeadlineAt?: number;
495
534
  initialTurnBudget?: ResolvedTurnBudget;
496
535
  initialToolBudget?: ResolvedToolBudget;
@@ -969,6 +1008,8 @@ export interface WaitCompletion {
969
1008
  mode?: string;
970
1009
  state?: string;
971
1010
  success?: boolean;
1011
+ /** Versioned bounded output archive retained with the durable completion replay. */
1012
+ archivePath?: string;
972
1013
  results?: WaitCompletionChild[];
973
1014
  }
974
1015
 
@@ -1022,6 +1063,9 @@ export interface Details {
1022
1063
  // Aggregated cost across all agents in the run
1023
1064
  totalCost?: CostSummary;
1024
1065
  spawnBudget?: SpawnBudgetSnapshot;
1066
+ runFanoutBudget?: RunFanoutBudgetSnapshot;
1067
+ runFanoutRejection?: RunFanoutRejection;
1068
+ activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1025
1069
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1026
1070
  capabilityAudit?: SubagentCapabilityAudit;
1027
1071
  parallelHandoff?: ParallelHandoffReference;
@@ -1044,7 +1088,8 @@ export interface Details {
1044
1088
  trace: Array<{
1045
1089
  operation: "run" | "status";
1046
1090
  key: string;
1047
- state: "started" | "completed" | "failed" | "reused";
1091
+ state: "started" | "completed" | "failed" | "stopped" | "reused";
1092
+ agent?: string;
1048
1093
  runId?: string;
1049
1094
  phase?: string;
1050
1095
  label?: string;
@@ -1216,6 +1261,8 @@ export interface AsyncStartedEvent {
1216
1261
  asyncDir?: string;
1217
1262
  /** Parent-resolved launch directory, used as a trusted artifact root while this session is live. */
1218
1263
  cwd?: string;
1264
+ /** Parent-resolved child session root, used only while this session owns the live run. */
1265
+ sessionRoot?: string;
1219
1266
  pid?: number;
1220
1267
  sessionId?: string;
1221
1268
  mode?: SubagentRunMode;
@@ -1287,6 +1334,8 @@ export interface AsyncStatus {
1287
1334
  context?: "fresh" | "fork" | "mixed";
1288
1335
  isNested?: boolean;
1289
1336
  state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1337
+ /** Display-only dismissal marker for a reload-orphaned workflow. */
1338
+ displayDismissedAt?: number;
1290
1339
  error?: string;
1291
1340
  activityState?: ActivityState;
1292
1341
  lastActivityAt?: number;
@@ -1318,6 +1367,8 @@ export interface AsyncStatus {
1318
1367
  workflowGraph?: WorkflowGraphSnapshot;
1319
1368
  checkpoint?: ChainCheckpointState;
1320
1369
  processTerminal?: ProcessTerminalV1;
1370
+ runFanoutBudget?: RunFanoutBudgetSnapshot;
1371
+ runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
1321
1372
  launchContractDigest?: string;
1322
1373
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1323
1374
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1337,6 +1388,10 @@ export interface AsyncStatus {
1337
1388
  phase?: string;
1338
1389
  label?: string;
1339
1390
  workflowKey?: string;
1391
+ /** Child run identity for workflow capacity reconciliation. */
1392
+ runId?: string;
1393
+ /** True only when this workflow child owns a detached async runner. */
1394
+ async?: boolean;
1340
1395
  parentWorkflowRunId?: string;
1341
1396
  outputName?: string;
1342
1397
  structured?: boolean;
@@ -1411,6 +1466,8 @@ export interface AsyncJobState {
1411
1466
  asyncDir: string;
1412
1467
  /** Parent-resolved launch directory retained for trusted live artifact lookup. */
1413
1468
  cwd?: string;
1469
+ /** Parent-resolved child session root retained for trusted live transcript lookup. */
1470
+ sessionRoot?: string;
1414
1471
  status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1415
1472
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1416
1473
  description?: string;
@@ -1538,6 +1595,12 @@ export interface ForegroundChildControl {
1538
1595
 
1539
1596
  export interface ForegroundRunControl {
1540
1597
  runId: string;
1598
+ /** Workflow shell that owns this live foreground child, when applicable. */
1599
+ parentWorkflowRunId?: string;
1600
+ /** Stable workflow lane key for this live foreground child. */
1601
+ workflowKey?: string;
1602
+ /** Private control root used to steer a live workflow-owned child. */
1603
+ workflowSteeringDir?: string;
1541
1604
  /** Originating parent session; required for public fleet projection. */
1542
1605
  sessionId?: string;
1543
1606
  mode: SubagentRunMode;
@@ -1563,6 +1626,12 @@ export interface ForegroundRunControl {
1563
1626
  toolCount?: number;
1564
1627
  /** Independently tracked children for foreground parallel work and fleet inspection. */
1565
1628
  activeChildren?: Map<number, ForegroundChildControl>;
1629
+ /** Live Prompt Audit redo callback. It is current-session memory only. */
1630
+ promptAuditRedo?: (index: number, guidance: string) => Promise<{ text: string; isError?: boolean }>;
1631
+ /** Memory-only source run for Prompt Audit redo. */
1632
+ sourceRunId?: string;
1633
+ /** Memory-only replacement run started by Prompt Audit redo. */
1634
+ supersededByRunId?: string;
1566
1635
  /** Scheduling owners that may still launch another child. Removal is safe only at zero. */
1567
1636
  schedulingOwners?: number;
1568
1637
  nestedRoute?: NestedRouteInfo;
@@ -1582,6 +1651,12 @@ export interface WaitSubscriptionRecord {
1582
1651
  expiresAt: number;
1583
1652
  }
1584
1653
 
1654
+ export interface ActiveAsyncCapacitySnapshot {
1655
+ used: number;
1656
+ /** Zero means the opt-in cap is disabled. */
1657
+ limit: number;
1658
+ }
1659
+
1585
1660
  export interface SubagentState {
1586
1661
  baseCwd: string;
1587
1662
  currentSessionId: string | null;
@@ -1592,6 +1667,10 @@ export interface SubagentState {
1592
1667
  /** Runtime mission-store snapshot used by optional inspector context. */
1593
1668
  missionStoreConfig?: MissionStoreConfig;
1594
1669
  parentSessionFile?: string | null;
1670
+ /** Extension-owned roots trusted for child session transcript reads. */
1671
+ trustedSessionRoots?: string[];
1672
+ /** Live async session roots created by this parent executor, keyed by run id. */
1673
+ liveAsyncSessionRoots?: Map<string, string>;
1595
1674
  /** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
1596
1675
  lastParentModel?: { provider: string; id: string };
1597
1676
  subagentInProgress?: boolean;
@@ -1602,11 +1681,15 @@ export interface SubagentState {
1602
1681
  granted?: number;
1603
1682
  grantHistory?: SpawnBudgetGrant[];
1604
1683
  };
1684
+ /** Current-session top-level async capacity projection. */
1685
+ activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1605
1686
  asyncJobs: Map<string, AsyncJobState>;
1606
1687
  /** Current-session active and recent async runs for the native fleet inspector. */
1607
1688
  fleetJobs?: Map<string, AsyncJobState>;
1608
1689
  /** Suppress dynamic status widgets while the fleet overlay owns the viewport. */
1609
1690
  fleetInspectorOpen?: boolean;
1691
+ /** Temporarily suppress dynamic widgets while Pi compacts the session. */
1692
+ widgetsSuspended?: boolean;
1610
1693
  foregroundRuns?: Map<string, ForegroundResumeRun>;
1611
1694
  foregroundControls: Map<string, ForegroundRunControl>;
1612
1695
  lastForegroundControlId: string | null;
@@ -1673,6 +1756,10 @@ export interface RunSyncOptions {
1673
1756
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
1674
1757
  /** Session id of the direct parent session for permission-system ask forwarding. */
1675
1758
  parentSessionId?: string;
1759
+ /** Private prompt-runtime steering transport for workflow-owned foreground children. */
1760
+ steerInboxDir?: string;
1761
+ steerCapabilityPath?: string;
1762
+ steerAckDir?: string;
1676
1763
  /** Resolved launch context for this child. */
1677
1764
  context?: "fresh" | "fork";
1678
1765
  cwd?: string;
@@ -1713,9 +1800,12 @@ export interface RunSyncOptions {
1713
1800
  /** Effective parent wait-tool setting propagated to the child runtime. */
1714
1801
  waitToolEnabled?: boolean;
1715
1802
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1803
+ runFanoutBudget?: RunFanoutBudgetDescriptor;
1716
1804
  nestedRoute?: NestedRouteInfo;
1717
1805
  /** Override the agent's default model (format: "provider/id" or just "id") */
1718
1806
  modelOverride?: string;
1807
+ /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
1808
+ llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
1719
1809
  /** Override the agent's default thinking level for this run */
1720
1810
  thinkingOverride?: AgentConfig["thinking"];
1721
1811
  /** Registry models available for heuristic bare-model resolution */
@@ -1739,6 +1829,8 @@ export interface RunSyncOptions {
1739
1829
  dynamic?: boolean;
1740
1830
  dynamicGroup?: boolean;
1741
1831
  };
1832
+ /** Private live callback for the exact child prompt after runtime acceptance injection. */
1833
+ onEffectivePrompt?: (prompt: string) => void;
1742
1834
  }
1743
1835
 
1744
1836
  export type IntercomBridgeMode = "off" | "fork-only" | "always";
@@ -1780,18 +1872,51 @@ export interface ScheduledRunsConfig {
1780
1872
 
1781
1873
  export type FleetViewPlacement = "aboveEditor" | "belowEditor";
1782
1874
 
1875
+ export const FLEET_KEYBINDING_ACTIONS = [
1876
+ "close",
1877
+ "scrollUp",
1878
+ "scrollDown",
1879
+ "selectUp",
1880
+ "selectDown",
1881
+ "selectFirst",
1882
+ "selectLast",
1883
+ "pageUp",
1884
+ "pageDown",
1885
+ "refresh",
1886
+ "steer",
1887
+ "inspect",
1888
+ "stop",
1889
+ "toggleTools",
1890
+ ] as const;
1891
+
1892
+ export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
1893
+ export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
1894
+
1895
+ export interface MainWindowRendererConfig {
1896
+ /** Unit of horizontal space in main chat subagent call/result rows. Omit to preserve current spacing. Set 0 for no extra padding. */
1897
+ horizontalSpacing?: number;
1898
+ /** Maximum collapsed rich-result rows. Expanded output is not capped. */
1899
+ compactResultMaxLines?: number;
1900
+ }
1901
+
1783
1902
  export interface ExtensionConfig {
1784
1903
  asyncByDefault?: boolean;
1785
1904
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
1786
1905
  fleetView?: boolean;
1787
1906
  /** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
1788
1907
  fleetViewPlacement?: FleetViewPlacement;
1908
+ /** Local keybindings for the full Fleet inspector. */
1909
+ fleetKeybindings?: FleetKeybindingsConfig;
1789
1910
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
1790
1911
  asyncWidget?: boolean;
1791
1912
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
1792
1913
  toolDescriptionMode?: ToolDescriptionMode;
1914
+ /** Include legacy append-step and checkpoint controls in the registered tool schema. Defaults to false. */
1915
+ legacyChainControls?: boolean;
1793
1916
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
1794
1917
  inlineToolDisplay?: InlineToolDisplay;
1918
+ /** Density controls for the main chat subagent call/result renderer. */
1919
+ mainWindowRenderer?: MainWindowRendererConfig;
1795
1920
  forceTopLevelAsync?: boolean;
1796
1921
  waitTool?: WaitToolConfig;
1797
1922
  defaultSessionDir?: string;
@@ -1799,8 +1924,22 @@ export interface ExtensionConfig {
1799
1924
  maxSubagentDepth?: number;
1800
1925
  /** Optional cumulative session cap. Unset or 0 means unlimited. */
1801
1926
  maxSubagentSpawnsPerSession?: number;
1927
+ /** Cumulative logical-child cap for one top-level run tree. Defaults to 64. */
1928
+ maxSubagentSpawnsPerRun?: number;
1929
+ /** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
1930
+ maxActiveAsyncRunsPerSession?: number;
1802
1931
  /** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
1803
1932
  globalConcurrencyLimit?: number;
1933
+ /**
1934
+ * Global default runtime deadline in milliseconds. It replaces the built-in
1935
+ * 30-minute backstop for single, parallel, and chain launches (foreground, plus
1936
+ * plain single-agent async runs) when neither the call (`timeoutMs`/`maxRuntimeMs`)
1937
+ * nor the selected agent provides a timeout. Explicit call values and agent
1938
+ * frontmatter defaults still win. Composite async runs (chain/parallel/workflow)
1939
+ * stay unbounded at the top level by design — their children are bounded individually.
1940
+ * Must be a positive integer; invalid values are ignored.
1941
+ */
1942
+ timeoutMs?: number;
1804
1943
  control?: ControlConfig;
1805
1944
  completionBatch?: CompletionBatchConfig;
1806
1945
  turnBudget?: TurnBudgetConfig;
@@ -1813,8 +1952,10 @@ export interface ExtensionConfig {
1813
1952
  worktreeSetupHook?: string;
1814
1953
  worktreeSetupHookTimeoutMs?: number;
1815
1954
  worktreeBaseDir?: string;
1816
- /** Where to store subagent artifact files. Defaults to "project" (cwd/.pi-subagents). Set to "session" for pi session dir, or "temp" for OS temp. */
1955
+ /** Where to store subagent artifact files. Defaults to "session" (the pi session directory, or OS temp when unavailable). Set to "project" for cwd/.pi/subagents. */
1817
1956
  artifactDir?: ArtifactDirPreference;
1957
+ /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
1958
+ artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
1818
1959
  intercomBridge?: IntercomBridgeConfig;
1819
1960
  proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
1820
1961
  scheduledRuns?: ScheduledRunsConfig;
@@ -1835,7 +1976,7 @@ export const DEFAULT_MAX_OUTPUT: Required<MaxOutputConfig> = {
1835
1976
 
1836
1977
  export const DEFAULT_ARTIFACT_CONFIG: ArtifactConfig = {
1837
1978
  enabled: true,
1838
- dir: "project",
1979
+ dir: "session",
1839
1980
  includeInput: true,
1840
1981
  includeOutput: true,
1841
1982
  includeJsonl: false,
@@ -1922,7 +2063,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
1922
2063
  export const POLL_INTERVAL_MS = 250;
1923
2064
  export const MAX_WIDGET_JOBS = 4;
1924
2065
  export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
1925
- export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
2066
+ export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
1926
2067
 
1927
2068
  export const DEFAULT_FORK_PREAMBLE =
1928
2069
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -2014,6 +2155,19 @@ export function resolveMaxSubagentSpawnsPerSession(configMaxSpawns?: number): nu
2014
2155
  return configuredMaxSpawns === 0 ? undefined : configuredMaxSpawns;
2015
2156
  }
2016
2157
 
2158
+ export const DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN = 64;
2159
+
2160
+ export function normalizeMaxSubagentSpawnsPerRun(value: unknown): number | undefined {
2161
+ const normalized = normalizeNonNegativeInteger(value);
2162
+ return normalized !== undefined && normalized > 0 ? normalized : undefined;
2163
+ }
2164
+
2165
+ export function resolveMaxSubagentSpawnsPerRun(configMaxSpawns?: number): number {
2166
+ return normalizeMaxSubagentSpawnsPerRun(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_RUN)
2167
+ ?? normalizeMaxSubagentSpawnsPerRun(configMaxSpawns)
2168
+ ?? DEFAULT_MAX_SUBAGENT_SPAWNS_PER_RUN;
2169
+ }
2170
+
2017
2171
  // ============================================================================
2018
2172
  // Utility Functions
2019
2173
  // ============================================================================
@@ -0,0 +1,11 @@
1
+ export function decodeUtf8Tail(bytes: Buffer): string {
2
+ let start = 0;
3
+ while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
4
+ return bytes.subarray(start).toString("utf-8");
5
+ }
6
+
7
+ export function utf8Tail(value: string, maxBytes: number): { text: string; truncated: boolean } {
8
+ const bytes = Buffer.from(value, "utf-8");
9
+ if (bytes.length <= maxBytes) return { text: value, truncated: false };
10
+ return { text: decodeUtf8Tail(bytes.subarray(bytes.length - maxBytes)), truncated: true };
11
+ }
@@ -6,6 +6,7 @@ import * as fs from "node:fs";
6
6
  import * as os from "node:os";
7
7
  import * as path from "node:path";
8
8
  import type { Message } from "@earendil-works/pi-ai";
9
+ import { previewDisplayText, sanitizeDisplayText, truncateDisplayText } from "./display-text.ts";
9
10
  import { formatToolCall } from "./formatters.ts";
10
11
  import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, NestedRunSummary, SingleResult, ToolCallSummary, Usage } from "./types.ts";
11
12
 
@@ -16,6 +17,7 @@ import type { AgentProgress, AsyncStatus, Details, DisplayItem, ErrorInfo, Neste
16
17
  const DEFAULT_CONFIG_DIR_NAME = ".pi";
17
18
  const PI_CODING_AGENT_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
18
19
  export const PI_CODING_AGENT_PACKAGE_ROOT_ENV = "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT";
20
+ export const PROMPT_REDACTED = "[prompt redacted]";
19
21
 
20
22
  export function resolveWatchPath(
21
23
  watchPath: string,
@@ -101,6 +103,23 @@ export function getAgentDir(): string {
101
103
 
102
104
  const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
103
105
 
106
+ export function pruneStatusCacheForAsyncRoot(asyncDirRoot: string, runIds: Iterable<string>): number {
107
+ const root = path.resolve(asyncDirRoot);
108
+ const currentStatusPaths = new Set(
109
+ Array.from(runIds, (runId) => path.resolve(root, runId, "status.json")),
110
+ );
111
+ let removed = 0;
112
+ for (const statusPath of statusCache.keys()) {
113
+ const resolved = path.resolve(statusPath);
114
+ const relative = path.relative(root, resolved);
115
+ if (relative && !relative.startsWith("..") && !path.isAbsolute(relative) && !currentStatusPaths.has(resolved)) {
116
+ statusCache.delete(statusPath);
117
+ removed++;
118
+ }
119
+ }
120
+ return removed;
121
+ }
122
+
104
123
  function getErrorMessage(error: unknown): string {
105
124
  return error instanceof Error ? error.message : String(error);
106
125
  }
@@ -127,7 +146,10 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
127
146
  try {
128
147
  stat = fs.statSync(statusPath);
129
148
  } catch (error) {
130
- if (isNotFoundError(error)) return null;
149
+ if (isNotFoundError(error)) {
150
+ statusCache.delete(statusPath);
151
+ return null;
152
+ }
131
153
  throw new Error(`Failed to inspect async status file '${statusPath}': ${getErrorMessage(error)}`, {
132
154
  cause: error instanceof Error ? error : undefined,
133
155
  });
@@ -148,7 +170,10 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
148
170
  try {
149
171
  content = fs.readFileSync(statusPath, "utf-8");
150
172
  } catch (error) {
151
- if (isNotFoundError(error)) return null;
173
+ if (isNotFoundError(error)) {
174
+ statusCache.delete(statusPath);
175
+ return null;
176
+ }
152
177
  throw new Error(`Failed to read async status file '${statusPath}': ${getErrorMessage(error)}`, {
153
178
  cause: error instanceof Error ? error : undefined,
154
179
  });
@@ -170,10 +195,6 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
170
195
  ino: stat.ino,
171
196
  status,
172
197
  });
173
- if (statusCache.size > 50) {
174
- const firstKey = statusCache.keys().next().value;
175
- if (firstKey) statusCache.delete(firstKey);
176
- }
177
198
  return status;
178
199
  }
179
200
 
@@ -334,7 +355,7 @@ function compactCompletedProgress(progress: AgentProgress): AgentProgress {
334
355
  agent: progress.agent,
335
356
  status: progress.status,
336
357
  activityState: progress.activityState,
337
- task: progress.task,
358
+ task: "[prompt redacted]",
338
359
  skills: progress.skills,
339
360
  toolCount: progress.toolCount,
340
361
  tokens: progress.tokens,
@@ -408,6 +429,7 @@ export function compactForegroundResult(result: SingleResult): SingleResult {
408
429
  const toolCalls = result.toolCalls?.length ? result.toolCalls : extractToolCallSummaries(result.messages);
409
430
  return {
410
431
  ...result,
432
+ task: "[prompt redacted]",
411
433
  messages: undefined,
412
434
  progress: undefined,
413
435
  toolCalls: toolCalls.length ? toolCalls : undefined,
@@ -522,11 +544,8 @@ export function detectSubagentError(messages: Message[]): ErrorInfo {
522
544
  * Extract a preview of tool arguments for display
523
545
  */
524
546
  export function extractToolArgsPreview(args: Record<string, unknown>): string {
525
- const truncatePreview = (value: string, maxLength: number): string =>
526
- value.length > maxLength ? `${value.slice(0, maxLength - 3)}...` : value;
527
-
528
547
  const stringifyPreviewValue = (value: unknown): string | undefined => {
529
- if (typeof value === "string" && value.trim().length > 0) return value;
548
+ if (typeof value === "string" && value.trim().length > 0) return sanitizeDisplayText(value);
530
549
  if (typeof value === "number" || typeof value === "boolean") return String(value);
531
550
  return undefined;
532
551
  };
@@ -539,39 +558,32 @@ export function extractToolArgsPreview(args: Record<string, unknown>): string {
539
558
  return `${first}${suffix}`;
540
559
  };
541
560
 
542
- // Handle MCP tool calls - show server/tool info
543
- if (args.tool && typeof args.tool === "string") {
544
- const server = args.server && typeof args.server === "string" ? `${args.server}/` : "";
545
- const toolArgs = args.args && typeof args.args === "string" ? ` ${args.args.slice(0, 40)}` : "";
546
- return `${server}${args.tool}${toolArgs}`;
561
+ if (typeof args.tool === "string") {
562
+ const server = typeof args.server === "string" ? `${sanitizeDisplayText(args.server)}/` : "";
563
+ const toolArgs = typeof args.args === "string" ? ` ${truncateDisplayText(sanitizeDisplayText(args.args), 40)}` : "";
564
+ return sanitizeDisplayText(`${server}${args.tool}${toolArgs}`);
547
565
  }
548
566
 
549
567
  const queriesPreview = previewArray(args.queries);
550
- if (queriesPreview) return truncatePreview(queriesPreview, 60);
551
- if (typeof args.query === "string" && args.query.trim().length > 0) return truncatePreview(args.query, 60);
552
- if (typeof args.workflow === "string" && args.workflow.trim().length > 0) return `workflow=${truncatePreview(args.workflow, 48)}`;
568
+ if (queriesPreview) return previewDisplayText(queriesPreview, 60);
569
+ if (typeof args.query === "string" && args.query.trim().length > 0) return previewDisplayText(args.query, 60);
570
+ if (typeof args.workflow === "string" && args.workflow.trim().length > 0) return `workflow=${previewDisplayText(args.workflow, 48)}`;
553
571
 
554
- if (typeof args.url === "string" && args.url.trim().length > 0) return truncatePreview(args.url, 60);
572
+ if (typeof args.url === "string" && args.url.trim().length > 0) return previewDisplayText(args.url, 60);
555
573
  const urlsPreview = previewArray(args.urls);
556
- if (urlsPreview) return truncatePreview(urlsPreview, 60);
557
- if (typeof args.prompt === "string" && args.prompt.trim().length > 0) return truncatePreview(args.prompt, 60);
558
-
574
+ if (urlsPreview) return previewDisplayText(urlsPreview, 60);
575
+ if (typeof args.prompt === "string" && args.prompt.trim().length > 0) return previewDisplayText(args.prompt, 60);
576
+
559
577
  const previewKeys = ["command", "path", "file_path", "pattern", "query", "url", "task", "describe", "search"];
560
578
  for (const key of previewKeys) {
561
- if (args[key] && typeof args[key] === "string") {
562
- const value = args[key] as string;
563
- return truncatePreview(value, 60);
564
- }
579
+ if (typeof args[key] === "string") return previewDisplayText(args[key], 60);
565
580
  }
566
-
567
- // Fallback: show first string value found
581
+
568
582
  for (const [key, value] of Object.entries(args)) {
583
+ const displayKey = sanitizeDisplayText(key);
569
584
  const arrayPreview = previewArray(value);
570
- if (arrayPreview) return `${key}=${truncatePreview(arrayPreview, 50)}`;
571
- if (typeof value === "string" && value.length > 0) {
572
- const preview = truncatePreview(value, 50);
573
- return `${key}=${preview}`;
574
- }
585
+ if (arrayPreview) return `${displayKey}=${previewDisplayText(arrayPreview, 50)}`;
586
+ if (typeof value === "string" && value.length > 0) return `${displayKey}=${previewDisplayText(value, 50)}`;
575
587
  }
576
588
  return "";
577
589
  }
@@ -1,10 +1,9 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { fileURLToPath } from "node:url";
4
3
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
5
4
  import { parseFrontmatter } from "../agents/frontmatter.ts";
6
5
  import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
7
- import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
6
+ import { getPromptDirectories } from "../shared/prompt-resources.ts";
8
7
 
9
8
  interface PromptWorkflow {
10
9
  name: string;
@@ -32,21 +31,9 @@ const RESERVED_COMMAND_NAMES = new Set([
32
31
  "subagents-models",
33
32
  ]);
34
33
 
35
- function packagePromptsDir(): string {
36
- return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts");
37
- }
38
-
39
- function promptDirs(cwd: string): string[] {
40
- return [
41
- packagePromptsDir(),
42
- path.join(getAgentDir(), "prompts"),
43
- path.join(getProjectConfigDir(cwd), "prompts"),
44
- ];
45
- }
46
-
47
34
  function readPromptFiles(cwd: string): string[] {
48
35
  const files: string[] = [];
49
- for (const dir of promptDirs(cwd)) {
36
+ for (const dir of Object.values(getPromptDirectories(cwd))) {
50
37
  let entries: fs.Dirent[];
51
38
  try {
52
39
  entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -4,6 +4,7 @@ import * as path from "node:path";
4
4
  import { keyText, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
5
5
  import { Key, matchesKey, truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
6
6
  import { BUILTIN_AGENT_NAMES, discoverAgents } from "../agents/agents.ts";
7
+ import { resolveExistingReadPaths } from "../shared/settings.ts";
7
8
  import {
8
9
  DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS,
9
10
  applySubagentProfile,
@@ -22,6 +23,7 @@ import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
22
23
  import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
23
24
  import { registerPromptWorkflowCommands } from "./prompt-workflows.ts";
24
25
  import { openSubagentsAdmin } from "./subagents-admin.ts";
26
+ import { SUBAGENT_GUIDE_TOPICS } from "../extension/subagent-guide.ts";
25
27
  import { openSubagentFleet } from "../tui/fleet.ts";
26
28
  import {
27
29
  applySlashUpdate,
@@ -40,6 +42,7 @@ import {
40
42
  SLASH_SUBAGENT_UPDATE_EVENT,
41
43
  DIRS,
42
44
  type Details,
45
+ type FleetKeybindingsConfig,
43
46
  type JsonSchemaObject,
44
47
  type SingleResult,
45
48
  type SubagentState,
@@ -628,6 +631,7 @@ function slashRunWorkflowScript(key: string, child: Record<string, unknown>): st
628
631
  export function registerSlashCommands(
629
632
  pi: ExtensionAPI,
630
633
  state: SubagentState,
634
+ options: { fleetKeybindings?: FleetKeybindingsConfig } = {},
631
635
  ): void {
632
636
  let fleetOpen = false;
633
637
  const showFleet = async (ctx: ExtensionContext) => {
@@ -642,7 +646,7 @@ export function registerSlashCommands(
642
646
  }
643
647
  fleetOpen = true;
644
648
  try {
645
- await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results });
649
+ await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: options.fleetKeybindings });
646
650
  } finally {
647
651
  fleetOpen = false;
648
652
  }
@@ -672,7 +676,8 @@ export function registerSlashCommands(
672
676
 
673
677
  let finalTask = task;
674
678
  if (inline.reads && Array.isArray(inline.reads) && inline.reads.length > 0) {
675
- finalTask = `[Read from: ${inline.reads.join(", ")}]\n\n${finalTask}`;
679
+ const existingReads = inline.reads.filter((read) => resolveExistingReadPaths([read], state.baseCwd).length > 0);
680
+ if (existingReads.length > 0) finalTask = `[Read from: ${existingReads.join(", ")}]\n\n${finalTask}`;
676
681
  }
677
682
  const child: Record<string, unknown> = { agent: agentName, task: finalTask, agentScope: "both" };
678
683
  if (inline.output !== undefined) child.output = inline.output;
@@ -698,6 +703,21 @@ export function registerSlashCommands(
698
703
  },
699
704
  });
700
705
 
706
+ pi.registerCommand("subagents-guide", {
707
+ description: "Show a packaged subagents guide topic",
708
+ getArgumentCompletions: (prefix) => prefix.includes(" ") ? null : SUBAGENT_GUIDE_TOPICS
709
+ .filter((topic) => topic.startsWith(prefix))
710
+ .map((topic) => ({ value: topic, label: topic })),
711
+ handler: async (args, ctx) => {
712
+ const topic = args.trim();
713
+ if (topic.includes(" ")) {
714
+ ctx.ui.notify("Usage: /subagents-guide [topic]", "error");
715
+ return;
716
+ }
717
+ await runSlashSubagent(pi, ctx, { action: "guide", ...(topic ? { topic } : {}) });
718
+ },
719
+ });
720
+
701
721
  pi.registerCommand("subagents-refine", {
702
722
  description: "Generate a bounded project-local refinement overlay for one subagent",
703
723
  getArgumentCompletions: makeAgentCompletions(state),