@xzzpig/pi-subagents 0.1.0 → 0.2.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 (81) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/README.md +2 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +342 -0
  5. package/docs/configuration.md +328 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +119 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +174 -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 +17 -8
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/project-panes.ts +30 -0
  22. package/src/extension/config.ts +28 -1
  23. package/src/extension/fanout-child.ts +5 -4
  24. package/src/extension/index.ts +75 -30
  25. package/src/extension/rpc.ts +7 -6
  26. package/src/extension/schemas.ts +29 -8
  27. package/src/extension/subagent-guide.ts +39 -0
  28. package/src/extension/tool-description.ts +30 -12
  29. package/src/inspectors/herdr/project-panes.ts +459 -63
  30. package/src/intercom/native-supervisor-channel.ts +102 -4
  31. package/src/missions/actions.ts +25 -2
  32. package/src/missions/lifecycle.ts +21 -2
  33. package/src/missions/store.ts +79 -2
  34. package/src/missions/types.ts +33 -0
  35. package/src/missions/workflow-state.ts +19 -13
  36. package/src/runs/background/active-run-index.ts +42 -0
  37. package/src/runs/background/async-execution.ts +17 -6
  38. package/src/runs/background/async-job-tracker.ts +293 -133
  39. package/src/runs/background/async-resume.ts +19 -3
  40. package/src/runs/background/async-status.ts +33 -5
  41. package/src/runs/background/completion-replay.ts +267 -0
  42. package/src/runs/background/control-channel.ts +95 -54
  43. package/src/runs/background/result-watcher.ts +113 -10
  44. package/src/runs/background/resume-guidance.ts +33 -0
  45. package/src/runs/background/run-status.ts +18 -0
  46. package/src/runs/background/scheduled-runs.ts +25 -1
  47. package/src/runs/background/stale-run-reconciler.ts +12 -24
  48. package/src/runs/background/subagent-runner.ts +69 -11
  49. package/src/runs/background/subagent-wait.ts +5 -2
  50. package/src/runs/background/wait-completions.ts +39 -5
  51. package/src/runs/background/wait-subscriptions.ts +21 -5
  52. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  53. package/src/runs/foreground/async-steering-action.ts +7 -8
  54. package/src/runs/foreground/chain-execution.ts +3 -0
  55. package/src/runs/foreground/execution.ts +7 -0
  56. package/src/runs/foreground/foreground-history.ts +137 -0
  57. package/src/runs/foreground/subagent-executor.ts +466 -61
  58. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  59. package/src/runs/shared/dynamic-fanout.ts +1 -1
  60. package/src/runs/shared/model-fallback.ts +8 -4
  61. package/src/runs/shared/model-scope.ts +12 -2
  62. package/src/runs/shared/parallel-utils.ts +1 -0
  63. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  64. package/src/runs/shared/worktree.ts +3 -2
  65. package/src/shared/artifacts.ts +15 -15
  66. package/src/shared/display-text.ts +100 -0
  67. package/src/shared/file-coalescer.ts +9 -0
  68. package/src/shared/fork-context.ts +13 -0
  69. package/src/shared/formatters.ts +4 -6
  70. package/src/shared/prompt-resources.ts +51 -0
  71. package/src/shared/settings.ts +15 -2
  72. package/src/shared/types.ts +45 -2
  73. package/src/shared/utf8.ts +11 -0
  74. package/src/shared/utils.ts +43 -33
  75. package/src/slash/prompt-workflows.ts +2 -15
  76. package/src/slash/slash-commands.ts +22 -2
  77. package/src/tui/fleet-status.ts +22 -12
  78. package/src/tui/fleet.ts +135 -25
  79. package/src/tui/render.ts +150 -33
  80. package/src/watchdog/change-signature.ts +4 -3
  81. package/src/workflows/scripted-workflow.ts +210 -13
@@ -9,6 +9,7 @@ type SubagentExecutionContext = "fresh" | "fork";
9
9
  interface BranchSessionEntry {
10
10
  type: string;
11
11
  id?: string;
12
+ cwd?: string;
12
13
  parentId?: string | null;
13
14
  timestamp?: string;
14
15
  message?: {
@@ -128,6 +129,18 @@ function readSessionEntries(sessionFile: string): BranchSessionEntry[] {
128
129
  });
129
130
  }
130
131
 
132
+ /** Keep Pi from restoring a forked session into the parent's cwd instead of the child launch cwd. */
133
+ export function alignForkedSessionCwd(sessionFile: string, cwd: string): void {
134
+ const entries = readSessionEntries(sessionFile);
135
+ const header = entries[0];
136
+ if (header?.type !== "session") throw new Error(`Forked session ${sessionFile} does not start with a session header.`);
137
+ const resolvedCwd = path.resolve(cwd);
138
+ const effectiveCwd = fs.realpathSync.native(resolvedCwd);
139
+ if (header.cwd === effectiveCwd) return;
140
+ header.cwd = effectiveCwd;
141
+ fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
142
+ }
143
+
131
144
  export function createForkContextResolver(
132
145
  sessionManager: ForkableSessionManager,
133
146
  requestedContext: unknown,
@@ -7,6 +7,7 @@ import * as path from "node:path";
7
7
  import type { Usage, SingleResult } from "./types.ts";
8
8
  import type { ChainStep } from "./settings.ts";
9
9
  import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
10
+ import { previewDisplayText, sanitizeDisplayText } from "./display-text.ts";
10
11
  import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
11
12
 
12
13
  /**
@@ -100,8 +101,7 @@ export function formatToolCall(name: string, args: Record<string, unknown>, expa
100
101
  switch (name) {
101
102
  case "bash": {
102
103
  const command = typeof args.command === "string" ? args.command : "";
103
- const maxLength = expanded ? 240 : 60;
104
- return `$ ${command.slice(0, maxLength)}${command.length > maxLength ? "..." : ""}`;
104
+ return `$ ${previewDisplayText(command, expanded ? 240 : 60)}`;
105
105
  }
106
106
  case "read":
107
107
  case "write":
@@ -111,12 +111,10 @@ export function formatToolCall(name: string, args: Record<string, unknown>, expa
111
111
  : typeof args.file_path === "string"
112
112
  ? args.file_path
113
113
  : "";
114
- return `${name} ${shortenPath(target)}`;
114
+ return `${name} ${sanitizeDisplayText(shortenPath(target))}`;
115
115
  }
116
116
  default: {
117
- const s = JSON.stringify(args);
118
- const maxLength = expanded ? 160 : 40;
119
- return `${name} ${s.slice(0, maxLength)}${s.length > maxLength ? "..." : ""}`;
117
+ return `${name} ${previewDisplayText(JSON.stringify(args), expanded ? 160 : 40)}`;
120
118
  }
121
119
  }
122
120
  }
@@ -0,0 +1,51 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+ import { parseFrontmatter } from "../agents/frontmatter.ts";
5
+ import { getAgentDir, getProjectConfigDir } from "./utils.ts";
6
+
7
+ const PROMPT_REF_PATTERN = /^(package|user|project):([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
8
+ const PROMPT_VARIABLE_PATTERN = /\{\{(\w+)\}\}/g;
9
+
10
+ type PromptVariable = string | number | boolean;
11
+
12
+ export function getPromptDirectories(cwd: string) {
13
+ return {
14
+ package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
15
+ user: path.join(getAgentDir(), "prompts"),
16
+ project: path.join(getProjectConfigDir(cwd), "prompts"),
17
+ };
18
+ }
19
+
20
+ function promptVariables(vars: unknown): Record<string, PromptVariable> {
21
+ if (vars === undefined) return {};
22
+ if (!vars || typeof vars !== "object" || Array.isArray(vars)) throw new Error("prompts.render vars must be a plain object.");
23
+ const prototype = Object.getPrototypeOf(vars);
24
+ if (prototype !== null && prototype !== Object.prototype) throw new Error("prompts.render vars must be a plain object.");
25
+ for (const [name, value] of Object.entries(vars)) {
26
+ if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
27
+ throw new Error(`prompts.render variable '${name}' must be a string, number, or boolean.`);
28
+ }
29
+ }
30
+ return vars as Record<string, PromptVariable>;
31
+ }
32
+
33
+ export function renderWorkflowPrompt(ref: string, vars: unknown, cwd: string): string {
34
+ const match = ref.match(PROMPT_REF_PATTERN);
35
+ if (!match) throw new Error("prompts.render ref must use package:<name>, user:<name>, or project:<name>.");
36
+ const scope = match[1] as keyof ReturnType<typeof getPromptDirectories>;
37
+ const name = match[2]!;
38
+ const filePath = path.join(getPromptDirectories(cwd)[scope], `${name}.md`);
39
+ let content: string;
40
+ try {
41
+ if (!fs.lstatSync(filePath).isFile()) throw new Error("not a regular file");
42
+ content = fs.readFileSync(filePath, "utf-8");
43
+ } catch (error) {
44
+ const detail = error instanceof Error ? error.message : String(error);
45
+ throw new Error(`Could not read prompt fragment '${ref}': ${detail}`);
46
+ }
47
+ const variables = promptVariables(vars);
48
+ return parseFrontmatter(content).body.trim().replace(PROMPT_VARIABLE_PATTERN, (placeholder, variable: string) => {
49
+ return Object.hasOwn(variables, variable) ? String(variables[variable]) : placeholder;
50
+ });
51
+ }
@@ -353,6 +353,18 @@ export function resolveChainPath(filePath: string, chainDir: string): string {
353
353
  return path.isAbsolute(expanded) ? expanded : path.join(chainDir, expanded);
354
354
  }
355
355
 
356
+ export function resolveExistingReadInstructionPaths(reads: readonly string[], instructionCwd: string, existenceCwd = instructionCwd): string[] {
357
+ return reads.flatMap((filePath) => {
358
+ const instructionPath = resolveChainPath(filePath, instructionCwd);
359
+ const existencePath = resolveChainPath(filePath, existenceCwd);
360
+ return fs.existsSync(existencePath) ? [instructionPath] : [];
361
+ });
362
+ }
363
+
364
+ export function resolveExistingReadPaths(reads: readonly string[], cwd: string): string[] {
365
+ return resolveExistingReadInstructionPaths(reads, cwd);
366
+ }
367
+
356
368
  /**
357
369
  * Build chain instructions from resolved behavior.
358
370
  * These are appended to the task to tell the agent what to read/write.
@@ -367,14 +379,15 @@ export function buildChainInstructions(
367
379
  chainDir: string,
368
380
  isFirstProgressAgent: boolean,
369
381
  previousSummary?: string,
382
+ readExistenceDir = chainDir,
370
383
  ): { prefix: string; suffix: string } {
371
384
  const prefixParts: string[] = [];
372
385
  const suffixParts: string[] = [];
373
386
 
374
387
  // READS - prepend to override any hardcoded filenames in task text
375
388
  if (behavior.reads && behavior.reads.length > 0) {
376
- const files = behavior.reads.map((f) => resolveChainPath(f, chainDir));
377
- prefixParts.push(`[Read from: ${files.join(", ")}]`);
389
+ const files = resolveExistingReadInstructionPaths(behavior.reads, chainDir, readExistenceDir);
390
+ if (files.length > 0) prefixParts.push(`[Read from: ${files.join(", ")}]`);
378
391
  }
379
392
 
380
393
  // OUTPUT - prepend so agent knows where to write
@@ -969,6 +969,8 @@ export interface WaitCompletion {
969
969
  mode?: string;
970
970
  state?: string;
971
971
  success?: boolean;
972
+ /** Versioned bounded output archive retained with the durable completion replay. */
973
+ archivePath?: string;
972
974
  results?: WaitCompletionChild[];
973
975
  }
974
976
 
@@ -1045,6 +1047,7 @@ export interface Details {
1045
1047
  operation: "run" | "status";
1046
1048
  key: string;
1047
1049
  state: "started" | "completed" | "failed" | "reused";
1050
+ agent?: string;
1048
1051
  runId?: string;
1049
1052
  phase?: string;
1050
1053
  label?: string;
@@ -1287,6 +1290,8 @@ export interface AsyncStatus {
1287
1290
  context?: "fresh" | "fork" | "mixed";
1288
1291
  isNested?: boolean;
1289
1292
  state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1293
+ /** Display-only dismissal marker for a reload-orphaned workflow. */
1294
+ displayDismissedAt?: number;
1290
1295
  error?: string;
1291
1296
  activityState?: ActivityState;
1292
1297
  lastActivityAt?: number;
@@ -1538,6 +1543,12 @@ export interface ForegroundChildControl {
1538
1543
 
1539
1544
  export interface ForegroundRunControl {
1540
1545
  runId: string;
1546
+ /** Workflow shell that owns this live foreground child, when applicable. */
1547
+ parentWorkflowRunId?: string;
1548
+ /** Stable workflow lane key for this live foreground child. */
1549
+ workflowKey?: string;
1550
+ /** Private control root used to steer a live workflow-owned child. */
1551
+ workflowSteeringDir?: string;
1541
1552
  /** Originating parent session; required for public fleet projection. */
1542
1553
  sessionId?: string;
1543
1554
  mode: SubagentRunMode;
@@ -1607,6 +1618,8 @@ export interface SubagentState {
1607
1618
  fleetJobs?: Map<string, AsyncJobState>;
1608
1619
  /** Suppress dynamic status widgets while the fleet overlay owns the viewport. */
1609
1620
  fleetInspectorOpen?: boolean;
1621
+ /** Temporarily suppress dynamic widgets while Pi compacts the session. */
1622
+ widgetsSuspended?: boolean;
1610
1623
  foregroundRuns?: Map<string, ForegroundResumeRun>;
1611
1624
  foregroundControls: Map<string, ForegroundRunControl>;
1612
1625
  lastForegroundControlId: string | null;
@@ -1673,6 +1686,10 @@ export interface RunSyncOptions {
1673
1686
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
1674
1687
  /** Session id of the direct parent session for permission-system ask forwarding. */
1675
1688
  parentSessionId?: string;
1689
+ /** Private prompt-runtime steering transport for workflow-owned foreground children. */
1690
+ steerInboxDir?: string;
1691
+ steerCapabilityPath?: string;
1692
+ steerAckDir?: string;
1676
1693
  /** Resolved launch context for this child. */
1677
1694
  context?: "fresh" | "fork";
1678
1695
  cwd?: string;
@@ -1780,16 +1797,40 @@ export interface ScheduledRunsConfig {
1780
1797
 
1781
1798
  export type FleetViewPlacement = "aboveEditor" | "belowEditor";
1782
1799
 
1800
+ export const FLEET_KEYBINDING_ACTIONS = [
1801
+ "close",
1802
+ "scrollUp",
1803
+ "scrollDown",
1804
+ "selectUp",
1805
+ "selectDown",
1806
+ "selectFirst",
1807
+ "selectLast",
1808
+ "pageUp",
1809
+ "pageDown",
1810
+ "refresh",
1811
+ "steer",
1812
+ "inspect",
1813
+ "stop",
1814
+ "toggleTools",
1815
+ ] as const;
1816
+
1817
+ export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
1818
+ export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
1819
+
1783
1820
  export interface ExtensionConfig {
1784
1821
  asyncByDefault?: boolean;
1785
1822
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
1786
1823
  fleetView?: boolean;
1787
1824
  /** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
1788
1825
  fleetViewPlacement?: FleetViewPlacement;
1826
+ /** Local keybindings for the full Fleet inspector. */
1827
+ fleetKeybindings?: FleetKeybindingsConfig;
1789
1828
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
1790
1829
  asyncWidget?: boolean;
1791
1830
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
1792
1831
  toolDescriptionMode?: ToolDescriptionMode;
1832
+ /** Include legacy append-step and checkpoint controls in the registered tool schema. Defaults to false. */
1833
+ legacyChainControls?: boolean;
1793
1834
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
1794
1835
  inlineToolDisplay?: InlineToolDisplay;
1795
1836
  forceTopLevelAsync?: boolean;
@@ -1813,8 +1854,10 @@ export interface ExtensionConfig {
1813
1854
  worktreeSetupHook?: string;
1814
1855
  worktreeSetupHookTimeoutMs?: number;
1815
1856
  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. */
1857
+ /** Where to store subagent artifact files. Defaults to "project" (cwd/.pi/subagents). Set to "session" for pi session dir, or "temp" for OS temp. */
1817
1858
  artifactDir?: ArtifactDirPreference;
1859
+ /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
1860
+ artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
1818
1861
  intercomBridge?: IntercomBridgeConfig;
1819
1862
  proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
1820
1863
  scheduledRuns?: ScheduledRunsConfig;
@@ -1922,7 +1965,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
1922
1965
  export const POLL_INTERVAL_MS = 250;
1923
1966
  export const MAX_WIDGET_JOBS = 4;
1924
1967
  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;
1968
+ 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", "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
1969
 
1927
1970
  export const DEFAULT_FORK_PREAMBLE =
1928
1971
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -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
 
@@ -101,6 +102,23 @@ export function getAgentDir(): string {
101
102
 
102
103
  const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
103
104
 
105
+ export function pruneStatusCacheForAsyncRoot(asyncDirRoot: string, runIds: Iterable<string>): number {
106
+ const root = path.resolve(asyncDirRoot);
107
+ const currentStatusPaths = new Set(
108
+ Array.from(runIds, (runId) => path.resolve(root, runId, "status.json")),
109
+ );
110
+ let removed = 0;
111
+ for (const statusPath of statusCache.keys()) {
112
+ const resolved = path.resolve(statusPath);
113
+ const relative = path.relative(root, resolved);
114
+ if (relative && !relative.startsWith("..") && !path.isAbsolute(relative) && !currentStatusPaths.has(resolved)) {
115
+ statusCache.delete(statusPath);
116
+ removed++;
117
+ }
118
+ }
119
+ return removed;
120
+ }
121
+
104
122
  function getErrorMessage(error: unknown): string {
105
123
  return error instanceof Error ? error.message : String(error);
106
124
  }
@@ -127,7 +145,10 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
127
145
  try {
128
146
  stat = fs.statSync(statusPath);
129
147
  } catch (error) {
130
- if (isNotFoundError(error)) return null;
148
+ if (isNotFoundError(error)) {
149
+ statusCache.delete(statusPath);
150
+ return null;
151
+ }
131
152
  throw new Error(`Failed to inspect async status file '${statusPath}': ${getErrorMessage(error)}`, {
132
153
  cause: error instanceof Error ? error : undefined,
133
154
  });
@@ -148,7 +169,10 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
148
169
  try {
149
170
  content = fs.readFileSync(statusPath, "utf-8");
150
171
  } catch (error) {
151
- if (isNotFoundError(error)) return null;
172
+ if (isNotFoundError(error)) {
173
+ statusCache.delete(statusPath);
174
+ return null;
175
+ }
152
176
  throw new Error(`Failed to read async status file '${statusPath}': ${getErrorMessage(error)}`, {
153
177
  cause: error instanceof Error ? error : undefined,
154
178
  });
@@ -170,10 +194,6 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
170
194
  ino: stat.ino,
171
195
  status,
172
196
  });
173
- if (statusCache.size > 50) {
174
- const firstKey = statusCache.keys().next().value;
175
- if (firstKey) statusCache.delete(firstKey);
176
- }
177
197
  return status;
178
198
  }
179
199
 
@@ -522,11 +542,8 @@ export function detectSubagentError(messages: Message[]): ErrorInfo {
522
542
  * Extract a preview of tool arguments for display
523
543
  */
524
544
  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
545
  const stringifyPreviewValue = (value: unknown): string | undefined => {
529
- if (typeof value === "string" && value.trim().length > 0) return value;
546
+ if (typeof value === "string" && value.trim().length > 0) return sanitizeDisplayText(value);
530
547
  if (typeof value === "number" || typeof value === "boolean") return String(value);
531
548
  return undefined;
532
549
  };
@@ -539,39 +556,32 @@ export function extractToolArgsPreview(args: Record<string, unknown>): string {
539
556
  return `${first}${suffix}`;
540
557
  };
541
558
 
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}`;
559
+ if (typeof args.tool === "string") {
560
+ const server = typeof args.server === "string" ? `${sanitizeDisplayText(args.server)}/` : "";
561
+ const toolArgs = typeof args.args === "string" ? ` ${truncateDisplayText(sanitizeDisplayText(args.args), 40)}` : "";
562
+ return sanitizeDisplayText(`${server}${args.tool}${toolArgs}`);
547
563
  }
548
564
 
549
565
  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)}`;
566
+ if (queriesPreview) return previewDisplayText(queriesPreview, 60);
567
+ if (typeof args.query === "string" && args.query.trim().length > 0) return previewDisplayText(args.query, 60);
568
+ if (typeof args.workflow === "string" && args.workflow.trim().length > 0) return `workflow=${previewDisplayText(args.workflow, 48)}`;
553
569
 
554
- if (typeof args.url === "string" && args.url.trim().length > 0) return truncatePreview(args.url, 60);
570
+ if (typeof args.url === "string" && args.url.trim().length > 0) return previewDisplayText(args.url, 60);
555
571
  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
-
572
+ if (urlsPreview) return previewDisplayText(urlsPreview, 60);
573
+ if (typeof args.prompt === "string" && args.prompt.trim().length > 0) return previewDisplayText(args.prompt, 60);
574
+
559
575
  const previewKeys = ["command", "path", "file_path", "pattern", "query", "url", "task", "describe", "search"];
560
576
  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
- }
577
+ if (typeof args[key] === "string") return previewDisplayText(args[key], 60);
565
578
  }
566
-
567
- // Fallback: show first string value found
579
+
568
580
  for (const [key, value] of Object.entries(args)) {
581
+ const displayKey = sanitizeDisplayText(key);
569
582
  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
- }
583
+ if (arrayPreview) return `${displayKey}=${previewDisplayText(arrayPreview, 50)}`;
584
+ if (typeof value === "string" && value.length > 0) return `${displayKey}=${previewDisplayText(value, 50)}`;
575
585
  }
576
586
  return "";
577
587
  }
@@ -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),
@@ -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
321
  if (this.entries.length === 0) {
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;
@@ -530,6 +533,13 @@ export class SubagentFleetStatus {
530
533
  }
531
534
  }
532
535
 
536
+ private clearWidget(): void {
537
+ if (!this.widgetRegistered) return;
538
+ this.ui?.setWidget(FLEET_STATUS_WIDGET_KEY, undefined);
539
+ this.widgetRegistered = false;
540
+ this.tui = undefined;
541
+ }
542
+
533
543
  private clearUiRegistration(): void {
534
544
  if (this.timer) clearInterval(this.timer);
535
545
  this.timer = undefined;