@xzzpig/pi-subagents 0.4.2 → 0.6.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 (128) hide show
  1. package/CHANGELOG.md +172 -1
  2. package/README.md +8 -0
  3. package/agents/oracle.md +3 -1
  4. package/agents/reviewer.md +1 -0
  5. package/agents/scout.md +2 -2
  6. package/agents/worker.md +2 -1
  7. package/async-retention-discovery-worker.mjs +180 -0
  8. package/docs/agents.md +79 -2
  9. package/docs/configuration.md +42 -14
  10. package/docs/extension-api.md +45 -2
  11. package/docs/models.md +2 -0
  12. package/docs/observability.md +41 -5
  13. package/docs/tool-reference.md +38 -39
  14. package/docs/workflows.md +173 -3
  15. package/package.json +13 -10
  16. package/prompts/council.md +48 -0
  17. package/skills/council-mode/SKILL.md +230 -0
  18. package/skills/pi-subagents/SKILL.md +8 -4
  19. package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
  20. package/skills/pi-subagents/references/execution-controls.md +40 -15
  21. package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
  22. package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
  24. package/src/agents/agent-management.ts +158 -357
  25. package/src/agents/agent-serializer.ts +4 -0
  26. package/src/agents/agents.ts +227 -53
  27. package/src/agents/builtin-names.ts +9 -0
  28. package/src/agents/runtime-agent-registry.ts +422 -0
  29. package/src/agents/skills.ts +1 -1
  30. package/src/api/agents.ts +7 -0
  31. package/src/api/external-job-provider.ts +186 -0
  32. package/src/api/preflight.ts +37 -9
  33. package/src/api/shared-types.ts +2 -0
  34. package/src/extension/config.ts +6 -3
  35. package/src/extension/context-injection.ts +118 -0
  36. package/src/extension/doctor.ts +15 -6
  37. package/src/extension/fanout-child.ts +2 -2
  38. package/src/extension/index.ts +224 -90
  39. package/src/extension/public-execution.ts +31 -2
  40. package/src/extension/rpc.ts +41 -1
  41. package/src/extension/schemas.ts +17 -37
  42. package/src/extension/tool-description.ts +35 -24
  43. package/src/inspectors/herdr/actions.ts +2 -2
  44. package/src/inspectors/herdr/inspector-runner.ts +2 -1
  45. package/src/inspectors/herdr/project-panes.ts +2 -2
  46. package/src/intercom/native-supervisor-channel.ts +32 -10
  47. package/src/missions/lifecycle.ts +6 -1
  48. package/src/missions/store.ts +4 -9
  49. package/src/missions/workflow-state.ts +2 -2
  50. package/src/profiles/profiles.ts +3 -1
  51. package/src/runs/background/active-run-index.ts +31 -8
  52. package/src/runs/background/async-execution.ts +70 -41
  53. package/src/runs/background/async-job-tracker.ts +24 -7
  54. package/src/runs/background/async-resume.ts +49 -16
  55. package/src/runs/background/async-retention.ts +886 -0
  56. package/src/runs/background/async-status-snapshot.ts +14 -5
  57. package/src/runs/background/async-status.ts +39 -53
  58. package/src/runs/background/auto-drain.ts +1 -0
  59. package/src/runs/background/chain-append.ts +3 -33
  60. package/src/runs/background/completion-dedupe.ts +5 -1
  61. package/src/runs/background/completion-replay.ts +22 -12
  62. package/src/runs/background/control-channel.ts +14 -68
  63. package/src/runs/background/fleet-view.ts +68 -19
  64. package/src/runs/background/index-segment.ts +59 -0
  65. package/src/runs/background/inspect-rpc.ts +443 -0
  66. package/src/runs/background/notify.ts +31 -5
  67. package/src/runs/background/result-files.ts +158 -90
  68. package/src/runs/background/result-watcher.ts +124 -20
  69. package/src/runs/background/resume-guidance.ts +8 -5
  70. package/src/runs/background/retained-children.ts +13 -3
  71. package/src/runs/background/run-id-query.ts +7 -0
  72. package/src/runs/background/run-id-resolver.ts +11 -9
  73. package/src/runs/background/run-status.ts +27 -18
  74. package/src/runs/background/scheduled-runs.ts +24 -4
  75. package/src/runs/background/stale-run-reconciler.ts +6 -3
  76. package/src/runs/background/steering.ts +11 -1
  77. package/src/runs/background/subagent-runner.ts +260 -144
  78. package/src/runs/background/subagent-wait.ts +17 -13
  79. package/src/runs/background/terminal-run-index.ts +138 -0
  80. package/src/runs/background/wait-completions.ts +21 -4
  81. package/src/runs/background/wait-subscriptions.ts +81 -2
  82. package/src/runs/background/wait-tool.ts +1 -0
  83. package/src/runs/foreground/async-steering-action.ts +21 -14
  84. package/src/runs/foreground/execution.ts +8 -2
  85. package/src/runs/foreground/subagent-executor.ts +816 -1593
  86. package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
  87. package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
  88. package/src/runs/shared/acceptance.ts +48 -5
  89. package/src/runs/shared/chain-outputs.ts +1 -3
  90. package/src/runs/shared/external-job-bridge.ts +444 -0
  91. package/src/runs/shared/external-job-runner.ts +286 -0
  92. package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
  93. package/src/runs/shared/model-exclusions.ts +242 -0
  94. package/src/runs/shared/model-fallback.ts +153 -40
  95. package/src/runs/shared/orca-progress-tabs.ts +84 -22
  96. package/src/runs/shared/parallel-handoff.ts +46 -4
  97. package/src/runs/shared/parallel-utils.ts +4 -15
  98. package/src/runs/shared/permissions.ts +5 -1
  99. package/src/runs/shared/pi-args.ts +8 -1
  100. package/src/runs/shared/session-lease.ts +0 -6
  101. package/src/runs/shared/subagent-control.ts +51 -7
  102. package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
  103. package/src/runs/shared/workflow-graph.ts +1 -23
  104. package/src/runs/shared/worktree.ts +14 -2
  105. package/src/shared/atomic-json.ts +22 -2
  106. package/src/shared/capacity-resilient-json.ts +102 -0
  107. package/src/shared/completion-owner.ts +14 -0
  108. package/src/shared/file-system-retry.ts +49 -1
  109. package/src/shared/fork-context.ts +59 -1
  110. package/src/shared/model-info.ts +20 -0
  111. package/src/shared/prompt-resources.ts +0 -40
  112. package/src/shared/settings.ts +5 -29
  113. package/src/shared/types.ts +110 -26
  114. package/src/shared/utils.ts +8 -0
  115. package/src/shared/watch-strategy.ts +10 -0
  116. package/src/slash/slash-bridge.ts +2 -1
  117. package/src/slash/slash-commands.ts +47 -7
  118. package/src/slash/slash-live-state.ts +3 -3
  119. package/src/tui/fleet-status.ts +86 -1
  120. package/src/tui/fleet.ts +117 -16
  121. package/src/tui/render.ts +73 -3
  122. package/src/watchdog/change-signature.ts +1 -1
  123. package/src/watchdog/lsp-diagnostics.ts +1 -0
  124. package/src/workflows/chat-progress.ts +2 -2
  125. package/src/workflows/scripted-workflow.ts +320 -79
  126. package/src/workflows/workflow-receipt.ts +140 -0
  127. package/src/runs/foreground/chain-clarify.ts +0 -1354
  128. package/src/runs/foreground/chain-execution.ts +0 -1581
@@ -7,6 +7,8 @@ import {
7
7
  type ResolvedControlConfig,
8
8
  } from "../../shared/types.ts";
9
9
  import { isToolTimeoutExempt } from "./tool-timeout.ts";
10
+ import { createHash } from "node:crypto";
11
+ import { previewDisplayText } from "../../shared/display-text.ts";
10
12
 
11
13
  const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
12
14
  const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
@@ -15,6 +17,7 @@ const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_att
15
17
  export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
16
18
  enabled: true,
17
19
  needsAttentionAfterMs: 60_000,
20
+ needsAttentionAfterMsIsExplicit: false,
18
21
  activeNoticeAfterMs: 240_000,
19
22
  failedToolAttemptsBeforeAttention: 3,
20
23
  notifyOn: DEFAULT_NOTIFY_ON,
@@ -40,9 +43,13 @@ export function resolveControlConfig(
40
43
  override?: ControlConfig,
41
44
  ): ResolvedControlConfig {
42
45
  const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
43
- const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
44
- ?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
46
+ const overrideNeedsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs);
47
+ const globalNeedsAttentionAfterMs = parsePositiveInt(globalConfig?.needsAttentionAfterMs);
48
+ const needsAttentionAfterMs = overrideNeedsAttentionAfterMs
49
+ ?? globalNeedsAttentionAfterMs
45
50
  ?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
51
+ const needsAttentionAfterMsIsExplicit = overrideNeedsAttentionAfterMs !== undefined
52
+ || globalNeedsAttentionAfterMs !== undefined;
46
53
  const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
47
54
  ?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
48
55
  ?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
@@ -62,6 +69,7 @@ export function resolveControlConfig(
62
69
  return {
63
70
  enabled,
64
71
  needsAttentionAfterMs,
72
+ needsAttentionAfterMsIsExplicit,
65
73
  activeNoticeAfterMs,
66
74
  activeNoticeAfterTurns,
67
75
  activeNoticeAfterTokens,
@@ -71,18 +79,34 @@ export function resolveControlConfig(
71
79
  };
72
80
  }
73
81
 
82
+ function scaledNeedsAttentionAfterMs(config: ResolvedControlConfig, thinking?: string | false): number {
83
+ if (config.needsAttentionAfterMsIsExplicit !== false) return config.needsAttentionAfterMs;
84
+ switch (thinking) {
85
+ case "medium":
86
+ return config.needsAttentionAfterMs * 2;
87
+ case "high":
88
+ return config.needsAttentionAfterMs * 5;
89
+ case "xhigh":
90
+ case "max":
91
+ return config.needsAttentionAfterMs * 10;
92
+ default:
93
+ return config.needsAttentionAfterMs;
94
+ }
95
+ }
96
+
74
97
  export function deriveActivityState(input: {
75
98
  config: ResolvedControlConfig;
76
99
  startedAt: number;
77
100
  lastActivityAt?: number;
78
101
  currentTool?: string;
102
+ thinking?: string | false;
79
103
  now?: number;
80
104
  }): ActivityState | undefined {
81
105
  if (!input.config.enabled || input.currentTool) return undefined;
82
106
  const now = input.now ?? Date.now();
83
107
  const lastActivity = input.lastActivityAt ?? input.startedAt;
84
108
  const ageMs = Math.max(0, now - lastActivity);
85
- return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
109
+ return ageMs > scaledNeedsAttentionAfterMs(input.config, input.thinking) ? "needs_attention" : undefined;
86
110
  }
87
111
 
88
112
  export function shouldEmitOpenToolAttention(input: {
@@ -116,6 +140,10 @@ export function buildControlEvent(input: {
116
140
  currentPath?: string;
117
141
  elapsedMs?: number;
118
142
  recentFailureSummary?: string;
143
+ workflowKey?: string;
144
+ phase?: string;
145
+ label?: string;
146
+ taskPreview?: string;
119
147
  }): ControlEvent {
120
148
  const ts = input.ts ?? Date.now();
121
149
  const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
@@ -144,6 +172,10 @@ export function buildControlEvent(input: {
144
172
  ...(input.currentPath ? { currentPath: input.currentPath } : {}),
145
173
  ...(elapsedMs !== undefined ? { elapsedMs } : {}),
146
174
  ...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
175
+ ...(input.workflowKey ? { workflowKey: input.workflowKey } : {}),
176
+ ...(input.phase ? { phase: input.phase } : {}),
177
+ ...(input.label ? { label: input.label } : {}),
178
+ ...(input.taskPreview ? { taskPreview: previewDisplayText(input.taskPreview, 160) } : {}),
147
179
  };
148
180
  }
149
181
 
@@ -153,7 +185,8 @@ export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: C
153
185
 
154
186
  export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
155
187
  const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
156
- return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
188
+ const contextHash = createHash("sha256").update(formatControlNudge(event)).digest("hex").slice(0, 8);
189
+ return `${childKey}:${event.type}:${event.reason ?? "idle"}:${contextHash}`;
157
190
  }
158
191
 
159
192
  export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
@@ -175,6 +208,17 @@ function formatLongRunningFacts(event: ControlEvent): string | undefined {
175
208
  return facts.length > 0 ? facts.join(" | ") : undefined;
176
209
  }
177
210
 
211
+ export function formatControlNudge(event: ControlEvent): string {
212
+ const scope = event.label ?? event.phase ?? event.workflowKey ?? event.taskPreview;
213
+ if (event.recentFailureSummary) return previewDisplayText(`Resolve the recent failure${scope ? ` for ${scope}` : ""}: ${event.recentFailureSummary}. Report the smallest next step or ask for a decision.`, 160);
214
+ if (event.currentTool || event.currentPath) {
215
+ const current = [event.currentTool ? `tool ${event.currentTool}` : undefined, event.currentPath ? `path ${event.currentPath}` : undefined].filter(Boolean).join(" at ");
216
+ return previewDisplayText(`Check ${current}${scope ? ` for ${scope}` : ""}. Report the smallest next step or ask for a decision.`, 160);
217
+ }
218
+ if (scope) return previewDisplayText(`Continue ${scope}. Report the smallest next step or ask for a decision.`, 160);
219
+ return "What are you blocked on? Reply with the smallest next step or ask for a decision.";
220
+ }
221
+
178
222
  export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
179
223
  const runTarget = event.runId;
180
224
  if (event.reason === "completion_guard") {
@@ -187,9 +231,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
187
231
  ].filter((line): line is string => Boolean(line)).join("\n");
188
232
  }
189
233
 
190
- const nudgeMessage = "What are you blocked on? Reply with the smallest next step or ask for a decision.";
191
- const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: "${nudgeMessage}" })`;
192
- const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: "${nudgeMessage}" })`;
234
+ const nudgeMessage = formatControlNudge(event);
235
+ const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: ${JSON.stringify(nudgeMessage)} })`;
236
+ const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: ${JSON.stringify(nudgeMessage)} })`;
193
237
  if (event.type === "active_long_running") {
194
238
  const facts = formatLongRunningFacts(event);
195
239
  return [
@@ -3,6 +3,7 @@ import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
5
5
  import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
6
+ import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
6
7
  import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.ts";
7
8
  import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
8
9
  import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
@@ -337,6 +338,7 @@ export function registerSteeringInbox(
337
338
  nativeRealpath?: (filePath: string) => string;
338
339
  legacySettleFallbackMs?: number;
339
340
  safetyPollIntervalMs?: number;
341
+ platform?: NodeJS.Platform;
340
342
  timers?: Pick<typeof globalThis, "setInterval" | "clearInterval">;
341
343
  } = {},
342
344
  ): void {
@@ -449,13 +451,17 @@ export function registerSteeringInbox(
449
451
  safetyInterval = (deps.timers?.setInterval ?? setInterval)(flush, deps.safetyPollIntervalMs ?? STEERING_SAFETY_POLL_INTERVAL_MS) as NodeJS.Timeout;
450
452
  safetyInterval.unref?.();
451
453
  };
452
- try {
453
- watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
454
- watcher.on("error", startPolling);
455
- startSafetyPolling();
456
- } catch {
457
- watcher = undefined;
454
+ if (!shouldUseNativeFsWatch("child-steering-inbox", deps.platform)) {
458
455
  startPolling();
456
+ } else {
457
+ try {
458
+ watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
459
+ watcher.on("error", startPolling);
460
+ startSafetyPolling();
461
+ } catch {
462
+ watcher = undefined;
463
+ startPolling();
464
+ }
459
465
  }
460
466
  };
461
467
  const activate = (): undefined => {
@@ -1,4 +1,4 @@
1
- import { isCheckpointStep, isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
1
+ import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
2
2
  import type { SingleResult, SubagentRunMode, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowNodeStatus } from "../../shared/types.ts";
3
3
 
4
4
  export interface WorkflowGraphBuildInput {
@@ -81,28 +81,6 @@ export function buildWorkflowGraphSnapshot(input: WorkflowGraphBuildInput): Work
81
81
 
82
82
  for (let stepIndex = 0; stepIndex < input.steps.length; stepIndex++) {
83
83
  const step = input.steps[stepIndex]!;
84
- if (isCheckpointStep(step)) {
85
- const status = normalizeStatus(input.stepStatuses?.[flatIndex]?.status)
86
- ?? (input.currentStepIndex === stepIndex ? "paused" : "pending");
87
- const checkpoint = { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: status === "rejected" ? "rejected" as const : status === "completed" ? "approved" as const : "pending" as const, stepIndex };
88
- const id = `step-${stepIndex}`;
89
- nodes.push({
90
- id,
91
- kind: "checkpoint",
92
- phase: step.phase,
93
- label: step.label?.trim() || step.checkpoint,
94
- status,
95
- flatIndex,
96
- stepIndex,
97
- checkpoint,
98
- error: input.stepStatuses?.[flatIndex]?.error,
99
- });
100
- pushPhase(phases, step.phase, id);
101
- if (status === "paused" || input.currentStepIndex === stepIndex) currentNodeId = id;
102
- flatIndex++;
103
- continue;
104
- }
105
-
106
84
  if (isParallelStep(step)) {
107
85
  const groupId = `step-${stepIndex}`;
108
86
  const children: WorkflowGraphNode[] = [];
@@ -46,7 +46,7 @@ export interface WorktreeCleanupTask {
46
46
  }
47
47
 
48
48
  export type WorktreeCleanupIntent =
49
- | { kind: "preserve"; capturedDiffs?: WorktreeDiff[]; handoffManifestPath?: string }
49
+ | { kind: "preserve"; capturedDiffs?: WorktreeDiff[]; handoffManifestPath?: string; cleanupBlocker?: string }
50
50
  | {
51
51
  kind: "discard";
52
52
  authorization:
@@ -115,7 +115,7 @@ interface RepoState {
115
115
  const DEFAULT_WORKTREE_SETUP_HOOK_TIMEOUT_MS = 30000;
116
116
 
117
117
  function runGit(cwd: string, args: string[]): GitResult {
118
- const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8" });
118
+ const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true });
119
119
  return {
120
120
  stdout: result.stdout ?? "",
121
121
  stderr: result.stderr ?? "",
@@ -338,6 +338,7 @@ function runWorktreeSetupHook(
338
338
  input: WorktreeSetupHookInput,
339
339
  ): string[] {
340
340
  const result = spawnSync(hook.hookPath, [], {
341
+ windowsHide: true,
341
342
  cwd: input.worktreePath,
342
343
  encoding: "utf-8",
343
344
  input: JSON.stringify(input),
@@ -571,6 +572,17 @@ function cleanupSingleWorktree(
571
572
  const errors: string[] = [];
572
573
  let worktreeRemoved = false;
573
574
  let branchRemoved = false;
575
+ if (intent.kind === "preserve" && intent.cleanupBlocker) {
576
+ return {
577
+ index: worktree.index,
578
+ path: worktree.path,
579
+ branch: worktree.branch,
580
+ worktreeRemoved: false,
581
+ branchRemoved: false,
582
+ preserved: true,
583
+ reason: intent.cleanupBlocker,
584
+ };
585
+ }
574
586
  if (intent.kind !== "setup-rollback") {
575
587
  try {
576
588
  removeSyntheticPathsBeforeDiff(worktree);
@@ -1,9 +1,12 @@
1
+ import { createHash } from "node:crypto";
1
2
  import * as fs from "node:fs";
2
3
  import * as path from "node:path";
3
4
  import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
4
5
 
5
6
  type AtomicJsonFs = Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "rmSync">;
6
7
 
8
+ const MAX_PATH_COMPONENT_BYTES = 255;
9
+
7
10
  type AtomicJsonWriterOptions = {
8
11
  fs?: AtomicJsonFs;
9
12
  now?: () => number;
@@ -28,6 +31,13 @@ function renameWithRetry(
28
31
  }, { retryDelaysMs, wait });
29
32
  }
30
33
 
34
+ function tempBaseName(filePath: string, pid: number, nowMs: number, randomId: string): string {
35
+ const suffix = `.${pid}.${nowMs}.${randomId}.tmp`;
36
+ const preferred = `.${path.basename(filePath)}${suffix}`;
37
+ if (Buffer.byteLength(preferred, "utf-8") <= MAX_PATH_COMPONENT_BYTES) return preferred;
38
+ return `.${createHash("sha256").update(path.basename(filePath)).digest("hex")}${suffix}`;
39
+ }
40
+
31
41
  export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (filePath: string, payload: object) => void {
32
42
  const fsImpl = options.fs ?? fs;
33
43
  const now = options.now ?? Date.now;
@@ -46,13 +56,23 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
46
56
  }, { retryDelaysMs: directoryRetryDelaysMs, wait });
47
57
  const tempPath = path.join(
48
58
  path.dirname(filePath),
49
- `.${path.basename(filePath)}.${pid}.${now()}.${random().toString(36).slice(2)}.tmp`,
59
+ tempBaseName(filePath, pid, now(), random().toString(36).slice(2)),
50
60
  );
61
+ let writeError: unknown;
51
62
  try {
52
63
  fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
53
64
  renameWithRetry(fsImpl, tempPath, filePath, renameRetryDelaysMs, wait);
65
+ } catch (error) {
66
+ writeError = error;
67
+ throw error;
54
68
  } finally {
55
- fsImpl.rmSync(tempPath, { force: true });
69
+ try {
70
+ fsImpl.rmSync(tempPath, { force: true });
71
+ } catch (cleanupError) {
72
+ // Preserve the write/rename failure: cleanup is best effort and must
73
+ // not hide the error callers need to classify or report.
74
+ if (writeError === undefined) throw cleanupError;
75
+ }
56
76
  }
57
77
  };
58
78
  }
@@ -0,0 +1,102 @@
1
+ import { isStorageCapacityError } from "./file-system-retry.ts";
2
+ import { writeAtomicJson } from "./atomic-json.ts";
3
+
4
+ type TimerApi = {
5
+ setTimeout(handler: () => void, delayMs: number): unknown;
6
+ clearTimeout(handle: unknown): void;
7
+ };
8
+
9
+ const defaultTimerApi: TimerApi = {
10
+ setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
11
+ clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
12
+ };
13
+
14
+ export type CapacityResilientJsonWriterOptions = {
15
+ /** The underlying write operation. It must be atomic for each target path. */
16
+ write?: (filePath: string, payload: object) => void;
17
+ /** Keep retry timers referenced by the event loop (needed by child runners). */
18
+ keepAlive?: boolean;
19
+ retryDelayMs?: number;
20
+ timerApi?: TimerApi;
21
+ onError?: (error: unknown, filePath: string) => void;
22
+ onSuccess?: (filePath: string, payload: object) => void;
23
+ };
24
+
25
+ export type CapacityResilientJsonWriter = {
26
+ write(filePath: string, payload: object, writeOperation?: (filePath: string, payload: object) => void): void;
27
+ pendingCount(): number;
28
+ dispose(): void;
29
+ };
30
+
31
+ /**
32
+ * Defers only storage-capacity failures, retaining the newest payload per path.
33
+ * Initial/ordinary writes remain synchronous and preserve their throwing contract;
34
+ * only ENOSPC-like failures enter the guarded retry loop.
35
+ */
36
+ export function createCapacityResilientJsonWriter(options: CapacityResilientJsonWriterOptions = {}): CapacityResilientJsonWriter {
37
+ const defaultWrite = options.write ?? writeAtomicJson;
38
+ const keepAlive = options.keepAlive ?? false;
39
+ const retryDelayMs = options.retryDelayMs ?? 1_000;
40
+ const timerApi = options.timerApi ?? defaultTimerApi;
41
+ const onError = options.onError ?? ((error, filePath) => console.error(`Failed to persist JSON '${filePath}':`, error));
42
+ const onSuccess = options.onSuccess;
43
+ const reportError = (error: unknown, filePath: string): void => {
44
+ try {
45
+ onError(error, filePath);
46
+ } catch (callbackError) {
47
+ console.error(`Failed to report JSON persistence error for '${filePath}':`, callbackError);
48
+ }
49
+ };
50
+ const notifySuccess = (filePath: string, payload: object): void => {
51
+ if (!onSuccess) return;
52
+ try {
53
+ onSuccess(filePath, payload);
54
+ } catch (error) {
55
+ reportError(error, filePath);
56
+ }
57
+ };
58
+ const pending = new Map<string, { payload: object; write: (filePath: string, payload: object) => void }>();
59
+ let retryTimer: unknown;
60
+
61
+ const scheduleRetry = (): void => {
62
+ if (retryTimer !== undefined) return;
63
+ retryTimer = timerApi.setTimeout(() => {
64
+ retryTimer = undefined;
65
+ for (const [filePath, entry] of pending) {
66
+ try {
67
+ entry.write(filePath, entry.payload);
68
+ pending.delete(filePath);
69
+ notifySuccess(filePath, entry.payload);
70
+ } catch (error) {
71
+ if (isStorageCapacityError(error)) continue;
72
+ pending.delete(filePath);
73
+ reportError(error, filePath);
74
+ }
75
+ }
76
+ if (pending.size > 0) scheduleRetry();
77
+ }, retryDelayMs);
78
+ if (!keepAlive && typeof retryTimer === "object" && retryTimer !== null && "unref" in retryTimer && typeof retryTimer.unref === "function") {
79
+ retryTimer.unref();
80
+ }
81
+ };
82
+
83
+ return {
84
+ write(filePath, payload, writeOperation = defaultWrite): void {
85
+ try {
86
+ writeOperation(filePath, payload);
87
+ pending.delete(filePath);
88
+ notifySuccess(filePath, payload);
89
+ } catch (error) {
90
+ if (!isStorageCapacityError(error)) throw error;
91
+ pending.set(filePath, { payload, write: writeOperation });
92
+ scheduleRetry();
93
+ }
94
+ },
95
+ pendingCount: () => pending.size,
96
+ dispose: (): void => {
97
+ if (retryTimer !== undefined) timerApi.clearTimeout(retryTimer);
98
+ retryTimer = undefined;
99
+ pending.clear();
100
+ },
101
+ };
102
+ }
@@ -0,0 +1,14 @@
1
+ import { randomUUID } from "node:crypto";
2
+
3
+ const COMPLETION_OWNER_KEY = Symbol.for("pi-subagents.completion-owner-id");
4
+
5
+ type CompletionOwnerGlobal = typeof globalThis & {
6
+ [COMPLETION_OWNER_KEY]?: string;
7
+ };
8
+
9
+ /** Stable for one parent Pi process across extension reloads. */
10
+ export function currentCompletionOwnerId(): string {
11
+ const runtime = globalThis as CompletionOwnerGlobal;
12
+ runtime[COMPLETION_OWNER_KEY] ??= randomUUID();
13
+ return runtime[COMPLETION_OWNER_KEY];
14
+ }
@@ -1,8 +1,51 @@
1
1
  const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
2
2
  const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
3
3
  const RETRYABLE_FILE_SYSTEM_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
4
+ const STORAGE_CAPACITY_ERROR_CODES = new Set(["EDQUOT", "EMFILE", "ENFILE", "ENOSPC"]);
4
5
 
5
- export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
6
+ export const FS_RETRY_MAX_TOTAL_MS_ENV = "PI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS";
7
+
8
+ const BASE_FILE_SYSTEM_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
9
+
10
+ /**
11
+ * Clamp the retry ladder to a total sleep budget, preserving its length.
12
+ *
13
+ * waitForFileSystemRetry blocks the calling thread, so the ladder above is also
14
+ * a ceiling on how long a single contended rename can stall that thread: about
15
+ * 7.9s. That is fine for a short-lived CLI. A long-lived host that loads this
16
+ * extension in-process runs the same writers on its event loop, where an 8s
17
+ * stall stops it serving anything at all -- and because Atomics.wait parks
18
+ * rather than spins, it presents as an unresponsive process at 0% CPU.
19
+ *
20
+ * The length is preserved deliberately: run-fanout-budget.ts and
21
+ * workflow-state.ts index this array by attempt number and treat running off
22
+ * the end as "timed out acquiring lock". Shortening it would quietly shrink
23
+ * those attempt budgets too, so only the sleeps shrink here.
24
+ *
25
+ * Unset by default, so behaviour is unchanged unless a host opts in. Opting in
26
+ * trades lock-wait tolerance for responsiveness: entries clamped to 0 return
27
+ * immediately, so contention that would previously have been waited out is
28
+ * surfaced as an error sooner.
29
+ */
30
+ export function resolveFileSystemRetryDelays(
31
+ env: NodeJS.ProcessEnv = process.env,
32
+ base: readonly number[] = BASE_FILE_SYSTEM_RETRY_DELAYS_MS,
33
+ ): readonly number[] {
34
+ const raw = env[FS_RETRY_MAX_TOTAL_MS_ENV];
35
+ if (raw === undefined || raw.trim() === "") return base;
36
+ const budget = Number(raw);
37
+ if (!Number.isInteger(budget) || budget < 0) {
38
+ throw new Error(`${FS_RETRY_MAX_TOTAL_MS_ENV} must be a non-negative integer number of milliseconds.`);
39
+ }
40
+ let spent = 0;
41
+ return base.map((delayMs) => {
42
+ const allowed = Math.max(0, Math.min(delayMs, budget - spent));
43
+ spent += allowed;
44
+ return allowed;
45
+ });
46
+ }
47
+
48
+ export const DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS = resolveFileSystemRetryDelays();
6
49
 
7
50
  export type FileSystemRetryOptions = {
8
51
  retryDelaysMs?: readonly number[];
@@ -32,6 +75,11 @@ export function isRetryableFileSystemError(error: unknown): boolean {
32
75
  return typeof code === "string" && RETRYABLE_FILE_SYSTEM_ERROR_CODES.has(code);
33
76
  }
34
77
 
78
+ export function isStorageCapacityError(error: unknown): boolean {
79
+ const code = (error as NodeJS.ErrnoException | undefined)?.code;
80
+ return typeof code === "string" && STORAGE_CAPACITY_ERROR_CODES.has(code);
81
+ }
82
+
35
83
  export function runFileSystemOperationWithRetry<T>(operation: () => T, options: FileSystemRetryOptions = {}): T {
36
84
  const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
37
85
  const wait = options.wait ?? waitForFileSystemRetry;
@@ -56,6 +56,48 @@ export function resolveSubagentContext(value: unknown): SubagentExecutionContext
56
56
  return value === "fork" ? "fork" : "fresh";
57
57
  }
58
58
 
59
+ export interface PreferredForkAvailability {
60
+ getSessionFile(): string | undefined;
61
+ getLeafId?: () => string | null;
62
+ }
63
+
64
+ export interface PreferredForkSnapshot {
65
+ parentSessionFile?: string | null;
66
+ leafId?: string | null;
67
+ }
68
+
69
+ export interface SubagentLaunchContextInput {
70
+ explicitContext?: SubagentExecutionContext;
71
+ agentDefaultContext?: SubagentExecutionContext;
72
+ defaultSubagentContext?: SubagentExecutionContext;
73
+ canUseImplicitFork: boolean;
74
+ }
75
+
76
+ /** Resolve the actual launch context from explicit, global, and agent preferences. */
77
+ export function resolveSubagentLaunchContext(input: SubagentLaunchContextInput): SubagentExecutionContext {
78
+ if (input.explicitContext !== undefined) return input.explicitContext;
79
+ const preferredContext = input.defaultSubagentContext ?? input.agentDefaultContext ?? "fresh";
80
+ return preferredContext === "fork" && input.canUseImplicitFork ? "fork" : "fresh";
81
+ }
82
+
83
+ /** True when an implicit `defaultContext: fork` can create a real branch now.
84
+ * Explicit `context: "fork"` stays strict and does not use this preference. */
85
+ export function canPreferFork(sessionManager: PreferredForkAvailability): boolean {
86
+ return canPreferForkFromSnapshot({
87
+ parentSessionFile: sessionManager.getSessionFile(),
88
+ leafId: sessionManager.getLeafId?.() ?? null,
89
+ });
90
+ }
91
+
92
+ export function canPreferForkFromSnapshot(input: PreferredForkSnapshot): boolean {
93
+ if (!input.parentSessionFile || !input.leafId) return false;
94
+ try {
95
+ return fs.existsSync(input.parentSessionFile);
96
+ } catch {
97
+ return false;
98
+ }
99
+ }
100
+
59
101
  /** Decide whether a resolved child model uses Anthropic's provider or message API, which
60
102
  * requires the sanitized fork to disable thinking. Unknown models stay conservative. */
61
103
  export function forkedChildRequiresThinkingOff(
@@ -166,7 +208,23 @@ export function createForkContextResolver(
166
208
  const openSession = options.openSession
167
209
  ?? sessionManager.openSession
168
210
  ?? ((file: string, dir?: string) => SessionManager.open(file, dir));
169
- const sessionDir = sessionManager.getSessionDir?.();
211
+ // Fork files must not land in the parent's top-level session directory.
212
+ // Pi's recent-session discovery (`pi -c` → findMostRecentSession) is
213
+ // non-recursive and picks the largest-mtime *.jsonl in that directory, so
214
+ // a still-running forked subagent — which keeps appending after the parent
215
+ // went idle — would hijack the next `pi -c` away from the conversation the
216
+ // user actually left. Nesting fork sessions in a per-parent directory keeps
217
+ // them invisible to that discovery; the `parentSession` header still
218
+ // records the tree relationship. The directory mirrors
219
+ // getSubagentSessionRoot() plus a "forks" level so fork files never sit
220
+ // loose next to run-N/ result directories. Derived from the file path
221
+ // rather than getSessionDir() so it also works when the manager cannot
222
+ // report its directory.
223
+ const sessionDir = path.join(
224
+ path.dirname(parentSessionFile),
225
+ path.basename(parentSessionFile, ".jsonl"),
226
+ "forks",
227
+ );
170
228
  const cachedResolutions = new Map<number, ForkContextResolution>();
171
229
 
172
230
  const resolveFork = (index = 0): ForkContextResolution => {
@@ -1,3 +1,5 @@
1
+ import type { ModelCost } from "@earendil-works/pi-ai";
2
+
1
3
  export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
2
4
  export type ThinkingLevel = typeof THINKING_LEVELS[number];
3
5
  export type ThinkingLevelMap = Partial<Record<ThinkingLevel, string | null>>;
@@ -9,6 +11,14 @@ export interface ModelInfo {
9
11
  api?: string;
10
12
  reasoning?: boolean;
11
13
  thinkingLevelMap?: ThinkingLevelMap;
14
+ /** Context window in tokens, when the host model registry reports one. */
15
+ contextWindow?: number;
16
+ /** Maximum output tokens, when the host model registry reports one. */
17
+ maxTokens?: number;
18
+ /** Input modalities reported by the registry, e.g. ["text", "image"]. */
19
+ input?: string[];
20
+ /** Per-token pricing from the registry (USD per 1M tokens). */
21
+ cost?: ModelCost;
12
22
  }
13
23
 
14
24
  interface RegistryModelLike {
@@ -17,6 +27,10 @@ interface RegistryModelLike {
17
27
  api?: string;
18
28
  reasoning?: boolean;
19
29
  thinkingLevelMap?: ThinkingLevelMap;
30
+ contextWindow?: number;
31
+ maxTokens?: number;
32
+ input?: string[];
33
+ cost?: ModelCost;
20
34
  }
21
35
 
22
36
  export function toModelInfo(model: RegistryModelLike): ModelInfo {
@@ -27,6 +41,12 @@ export function toModelInfo(model: RegistryModelLike): ModelInfo {
27
41
  api: model.api,
28
42
  reasoning: model.reasoning,
29
43
  thinkingLevelMap: model.thinkingLevelMap,
44
+ ...(typeof model.contextWindow === "number" && Number.isFinite(model.contextWindow) && model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
45
+ ...(typeof model.maxTokens === "number" && Number.isFinite(model.maxTokens) && model.maxTokens > 0 ? { maxTokens: model.maxTokens } : {}),
46
+ ...(Array.isArray(model.input) && model.input.length > 0 ? { input: [...model.input] } : {}),
47
+ ...(model.cost && Number.isFinite(model.cost.input) && Number.isFinite(model.cost.output)
48
+ ? { cost: { ...model.cost, ...(model.cost.tiers ? { tiers: model.cost.tiers.map((tier) => ({ ...tier })) } : {}) } }
49
+ : {}),
30
50
  };
31
51
  }
32
52
 
@@ -1,14 +1,7 @@
1
- import * as fs from "node:fs";
2
1
  import * as path from "node:path";
3
2
  import { fileURLToPath } from "node:url";
4
- import { parseFrontmatter } from "../agents/frontmatter.ts";
5
3
  import { getAgentDir, getProjectConfigDir } from "./utils.ts";
6
4
 
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
5
  export function getPromptDirectories(cwd: string) {
13
6
  return {
14
7
  package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
@@ -16,36 +9,3 @@ export function getPromptDirectories(cwd: string) {
16
9
  project: path.join(getProjectConfigDir(cwd), "prompts"),
17
10
  };
18
11
  }
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
- }