@xzzpig/pi-subagents 0.20.0 → 0.21.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 (140) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +1 -1
  3. package/agents/oracle.md +8 -19
  4. package/agents/researcher.md +0 -3
  5. package/agents/reviewer.md +17 -61
  6. package/agents/scout.md +1 -4
  7. package/agents/worker.md +8 -25
  8. package/docs/agents.md +72 -7
  9. package/docs/configuration.md +58 -7
  10. package/docs/extension-api.md +36 -11
  11. package/docs/fork-extensions.md +1 -0
  12. package/docs/missions.md +34 -17
  13. package/docs/models.md +1 -1
  14. package/docs/observability.md +10 -5
  15. package/docs/tool-reference.md +117 -84
  16. package/docs/watchdog.md +8 -6
  17. package/docs/workflows.md +16 -7
  18. package/index.ts +5 -0
  19. package/package.json +5 -3
  20. package/prompts/council.md +1 -1
  21. package/skills/pi-subagents/SKILL.md +1 -1
  22. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  23. package/skills/pi-subagents/references/execution-controls.md +16 -16
  24. package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
  25. package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
  26. package/src/agents/advertised-agent-prompt.ts +9 -1
  27. package/src/agents/agent-management.ts +4 -0
  28. package/src/agents/agent-memory.ts +3 -3
  29. package/src/agents/agent-scope.ts +4 -0
  30. package/src/agents/agent-serializer.ts +8 -1
  31. package/src/agents/agents.ts +191 -145
  32. package/src/api/preflight.ts +8 -4
  33. package/src/extension/config.ts +21 -2
  34. package/src/extension/context-injection.ts +6 -1
  35. package/src/extension/control-notices.ts +1 -9
  36. package/src/extension/declaration-pinning.ts +164 -0
  37. package/src/extension/doctor.ts +7 -10
  38. package/src/extension/fanout-child.ts +7 -8
  39. package/src/extension/index.ts +114 -132
  40. package/src/extension/reply-workflow-script.ts +20 -11
  41. package/src/extension/rpc.ts +11 -6
  42. package/src/extension/schemas.ts +34 -30
  43. package/src/extension/subagent-guide.ts +86 -6
  44. package/src/extension/subagent-options.ts +47 -0
  45. package/src/extension/tool-activation.ts +3 -2
  46. package/src/extension/tool-description.ts +51 -68
  47. package/src/inspectors/actions.ts +37 -11
  48. package/src/inspectors/plugins.ts +3 -2
  49. package/src/inspectors/tmux/actions.ts +204 -0
  50. package/src/inspectors/tmux/client.ts +85 -0
  51. package/src/inspectors/tmux/plugin.ts +21 -0
  52. package/src/integrations/herdr-status.ts +18 -49
  53. package/src/integrations/program-status.ts +215 -0
  54. package/src/intercom/native-supervisor-channel.ts +77 -4
  55. package/src/intercom/result-intercom.ts +3 -2
  56. package/src/intercom/supervisor-ui.ts +2 -174
  57. package/src/missions/store.ts +25 -5
  58. package/src/profiles/profiles.ts +24 -21
  59. package/src/runs/background/active-async-capacity.ts +58 -8
  60. package/src/runs/background/async-execution.ts +143 -38
  61. package/src/runs/background/async-job-tracker.ts +11 -4
  62. package/src/runs/background/async-resume.ts +5 -2
  63. package/src/runs/background/await-async-run.ts +14 -9
  64. package/src/runs/background/binary-bootstrap.ts +2 -1
  65. package/src/runs/background/calendar-schedule.ts +90 -0
  66. package/src/runs/background/chain-root-attachment.ts +9 -5
  67. package/src/runs/background/fleet-view.ts +5 -5
  68. package/src/runs/background/notify.ts +185 -12
  69. package/src/runs/background/result-files.ts +116 -5
  70. package/src/runs/background/result-watcher.ts +99 -66
  71. package/src/runs/background/resume-guidance.ts +2 -2
  72. package/src/runs/background/run-child-session.ts +16 -2
  73. package/src/runs/background/run-id-resolver.ts +8 -5
  74. package/src/runs/background/run-status.ts +21 -16
  75. package/src/runs/background/runner-child-launch.ts +1 -0
  76. package/src/runs/background/runner-http-dispatcher.ts +3 -0
  77. package/src/runs/background/scheduled-runs.ts +256 -61
  78. package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
  79. package/src/runs/background/subagent-runner.ts +32 -12
  80. package/src/runs/background/subagent-wait.ts +38 -19
  81. package/src/runs/background/terminal-run-index.ts +46 -1
  82. package/src/runs/background/wait-completions.ts +1 -0
  83. package/src/runs/background/wait-tool.ts +33 -23
  84. package/src/runs/background/workflow-terminal-proof.ts +39 -22
  85. package/src/runs/foreground/async-stop-action.ts +48 -22
  86. package/src/runs/foreground/execution.ts +94 -52
  87. package/src/runs/foreground/foreground-history.ts +1 -0
  88. package/src/runs/foreground/subagent-executor.ts +207 -77
  89. package/src/runs/shared/child-commands.ts +2 -1
  90. package/src/runs/shared/child-hooks.ts +4 -3
  91. package/src/runs/shared/child-launch.ts +3 -0
  92. package/src/runs/shared/child-session.ts +41 -24
  93. package/src/runs/shared/child-tool-plan.ts +13 -26
  94. package/src/runs/shared/dynamic-fanout.ts +1 -1
  95. package/src/runs/shared/fork-command-result.ts +10 -0
  96. package/src/runs/shared/herdr-placed-run.ts +5 -4
  97. package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
  98. package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
  99. package/src/runs/shared/model-resolution.ts +30 -1
  100. package/src/runs/shared/nested-events.ts +5 -0
  101. package/src/runs/shared/parallel-handoff.ts +56 -8
  102. package/src/runs/shared/parallel-utils.ts +2 -0
  103. package/src/runs/shared/partial-output.ts +48 -0
  104. package/src/runs/shared/runner-launcher.ts +25 -0
  105. package/src/runs/shared/single-output.ts +53 -0
  106. package/src/runs/shared/structured-output.ts +14 -7
  107. package/src/runs/shared/subagent-control.ts +3 -3
  108. package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
  109. package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
  110. package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
  111. package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
  112. package/src/runs/shared/worktree-lock.ts +29 -0
  113. package/src/runs/shared/worktree.ts +12 -1
  114. package/src/shared/atomic-json.ts +4 -2
  115. package/src/shared/edit-distance.ts +33 -0
  116. package/src/shared/file-lease.ts +74 -0
  117. package/src/shared/formatters.ts +1 -5
  118. package/src/shared/model-info.ts +22 -0
  119. package/src/shared/package-version.ts +17 -0
  120. package/src/shared/parent-wake.ts +79 -0
  121. package/src/shared/pruned-fork.ts +7 -1
  122. package/src/shared/runtime-module-path.ts +19 -0
  123. package/src/shared/settings-file-lease.ts +36 -0
  124. package/src/shared/types.ts +36 -2
  125. package/src/shared/utils.ts +8 -6
  126. package/src/slash/slash-commands.ts +3 -3
  127. package/src/slash/subagents-admin.ts +2 -1
  128. package/src/tui/fleet-native-transcript.ts +2 -0
  129. package/src/tui/fleet-transcript.ts +12 -3
  130. package/src/tui/fleet.ts +11 -8
  131. package/src/tui/render.ts +27 -19
  132. package/src/tui/subagent-messages.ts +305 -0
  133. package/src/watchdog/diff-tool.ts +2 -2
  134. package/src/watchdog/register-main.ts +2 -22
  135. package/src/watchdog/render.ts +2 -24
  136. package/src/watchdog/runtime.ts +6 -4
  137. package/src/watchdog/settings.ts +18 -13
  138. package/src/watchdog/tool-actions.ts +2 -2
  139. package/src/workflows/scripted-workflow.ts +20 -6
  140. package/src/workflows/workflow-resources.ts +11 -0
@@ -5,6 +5,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
5
5
  import { BUILTIN_AGENT_NAMES, validateOptionalMachine } from "../agents/agents.ts";
6
6
  import { getPiSpawnCommand } from "../runs/shared/pi-spawn.ts";
7
7
  import { findModelInfo, getSupportedThinkingLevels, splitKnownThinkingSuffix, toModelInfo } from "../shared/model-info.ts";
8
+ import { withSettingsFileLease } from "../shared/settings-file-lease.ts";
8
9
  import { getAgentDir } from "../shared/utils.ts";
9
10
 
10
11
  export const DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS = 7;
@@ -483,27 +484,29 @@ export function readSubagentProfile(name: string): { filePath: string; profile:
483
484
  export function applySubagentProfile(name: string): { filePath: string; settingsPath: string } {
484
485
  const { filePath, profile } = readSubagentProfile(name);
485
486
  const settingsPath = getUserSettingsPath();
486
- const settings = readSettingsFile(settingsPath);
487
- const existing = settings.subagents && typeof settings.subagents === "object" && !Array.isArray(settings.subagents)
488
- ? settings.subagents as Record<string, unknown>
489
- : {};
490
- // A profile owns the complete agent mapping, but unrelated subagent settings
491
- // (notably disableBuiltins, modelScope, watchdog, etc.) survive profile switches.
492
- // Machine placement is not a model choice, so an existing pin survives a profile switch too.
493
- const agentOverrides: Record<string, ProfileAgentOverride> = { ...profile.subagents.agentOverrides };
494
- const existingOverrides = existing.agentOverrides && typeof existing.agentOverrides === "object" && !Array.isArray(existing.agentOverrides)
495
- ? existing.agentOverrides as Record<string, unknown>
496
- : {};
497
- for (const [name, value] of Object.entries(existingOverrides)) {
498
- const machine = value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>).machine : undefined;
499
- if (typeof machine === "string" && agentOverrides[name]?.machine === undefined) agentOverrides[name] = { ...agentOverrides[name], machine };
500
- }
501
- settings.subagents = {
502
- ...existing,
503
- ...profile.subagents,
504
- agentOverrides,
505
- };
506
- writeJsonFile(settingsPath, settings);
487
+ withSettingsFileLease(settingsPath, () => {
488
+ const settings = readSettingsFile(settingsPath);
489
+ const existing = settings.subagents && typeof settings.subagents === "object" && !Array.isArray(settings.subagents)
490
+ ? settings.subagents as Record<string, unknown>
491
+ : {};
492
+ // A profile owns the complete agent mapping, but unrelated subagent settings
493
+ // (notably disableBuiltins, modelScope, watchdog, etc.) survive profile switches.
494
+ // Machine placement is not a model choice, so an existing pin survives a profile switch too.
495
+ const agentOverrides: Record<string, ProfileAgentOverride> = { ...profile.subagents.agentOverrides };
496
+ const existingOverrides = existing.agentOverrides && typeof existing.agentOverrides === "object" && !Array.isArray(existing.agentOverrides)
497
+ ? existing.agentOverrides as Record<string, unknown>
498
+ : {};
499
+ for (const [name, value] of Object.entries(existingOverrides)) {
500
+ const machine = value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>).machine : undefined;
501
+ if (typeof machine === "string" && agentOverrides[name]?.machine === undefined) agentOverrides[name] = { ...agentOverrides[name], machine };
502
+ }
503
+ settings.subagents = {
504
+ ...existing,
505
+ ...profile.subagents,
506
+ agentOverrides,
507
+ };
508
+ writeJsonFile(settingsPath, settings);
509
+ });
507
510
  return { filePath, settingsPath };
508
511
  }
509
512
 
@@ -5,8 +5,9 @@ import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
5
5
  import { TEMP_ROOT_DIR, type ActiveAsyncCapacitySnapshot, type AsyncStatus } from "../../shared/types.ts";
6
6
  import { readStatus } from "../../shared/utils.ts";
7
7
  import { checkPidLiveness, type PidLiveness } from "./stale-run-reconciler.ts";
8
+ import { currentPidNamespaceScope } from "./pid-namespace.ts";
8
9
  import { readProcessTerminal } from "./process-terminal.ts";
9
- import { isTerminalAsyncState as terminalState, readWorkflowChildProcessEvidence } from "./workflow-terminal-proof.ts";
10
+ import { isTerminalAsyncState as terminalState, readWorkflowChildEvidence, readWorkflowChildProcessEvidence } from "./workflow-terminal-proof.ts";
10
11
 
11
12
  export const ACTIVE_ASYNC_CAPACITY_DIR = path.join(TEMP_ROOT_DIR, "session-active-async-capacity");
12
13
  export const DEFAULT_ABANDONED_SLOT_RELEASE_AFTER_MS = 20 * 60 * 1000;
@@ -44,11 +45,12 @@ interface CapacityOptions {
44
45
  token?: () => string;
45
46
  abandonedSlotReleaseAfterMs?: number | false;
46
47
  pidLiveness?: (pid: number) => PidLiveness;
48
+ pidNamespaceScope?: () => string | undefined;
47
49
  afterSlotRename?: (releasedDir: string) => void;
48
50
  writeOwner?: (filePath: string, owner: ActiveAsyncCapacityOwner) => void;
49
51
  }
50
52
 
51
- export interface ActiveAsyncCapacityReleaseEvidence {
53
+ interface AbandonedRunnerEvidence {
52
54
  releasedBy: "abandoned-timeout";
53
55
  processProof: "unknown";
54
56
  runnerPid: "gone";
@@ -56,6 +58,18 @@ export interface ActiveAsyncCapacityReleaseEvidence {
56
58
  abandonedSlotReleaseAfterMs: number;
57
59
  }
58
60
 
61
+ /** A workflow's own status PID is the parent Pi host, so workflow evidence names its dead child runners instead. */
62
+ interface AbandonedWorkflowEvidence {
63
+ releasedBy: "abandoned-timeout";
64
+ processProof: "unknown";
65
+ controller: "unregistered";
66
+ workflowEndedAgeMs: number;
67
+ abandonedChildren: Array<{ runId: string; lastActivityAgeMs: number }>;
68
+ abandonedSlotReleaseAfterMs: number;
69
+ }
70
+
71
+ export type ActiveAsyncCapacityReleaseEvidence = AbandonedRunnerEvidence | AbandonedWorkflowEvidence;
72
+
59
73
  export type ActiveAsyncCapacityReleaseVerdict =
60
74
  | { state: "releasable"; reason: string; evidence?: ActiveAsyncCapacityReleaseEvidence }
61
75
  | { state: "retained"; reason: string }
@@ -232,12 +246,14 @@ function runnerReleaseVerdict(owner: ActiveAsyncCapacityOwner, status: AsyncStat
232
246
  : abandonedRunnerReleaseVerdict(status, proof?.state ?? "missing", options);
233
247
  }
234
248
 
235
- function abandonedRunnerReleaseVerdict(status: AsyncStatus, proofState: string, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
249
+ function abandonedRunnerReleaseVerdict(status: AsyncStatus, proofState: string, options: CapacityOptions): { state: "retained"; reason: string } | { state: "releasable"; reason: string; evidence: AbandonedRunnerEvidence } {
236
250
  const proofReason = `process-terminal proof is ${proofState}`;
237
251
  const thresholdMs = resolveAbandonedSlotReleaseAfterMs(options.abandonedSlotReleaseAfterMs);
238
252
  if (thresholdMs === false) return { state: "retained", reason: `${proofReason}; abandoned-timeout policy is disabled` };
239
253
  if (status.state !== "failed") return { state: "retained", reason: `${proofReason}; abandoned-timeout policy requires a failed run, not ${status.state}` };
240
254
  if (typeof status.pid !== "number" || !Number.isInteger(status.pid) || status.pid < 1) return { state: "retained", reason: `${proofReason}; runner PID is missing or invalid` };
255
+ // A PID from another namespace can look dead here while the runner is alive.
256
+ if (status.pidNamespaceScope !== undefined && status.pidNamespaceScope !== (options.pidNamespaceScope ?? currentPidNamespaceScope)()) return { state: "retained", reason: `${proofReason}; runner PID namespace differs from this process, so liveness is unknown` };
241
257
  const liveness = (options.pidLiveness ?? checkPidLiveness)(status.pid);
242
258
  if (liveness !== "dead") return { state: "retained", reason: `${proofReason}; runner PID liveness is ${liveness}` };
243
259
  const lastActivityAt = status.lastActivityAt ?? status.lastUpdate ?? status.endedAt;
@@ -245,7 +261,7 @@ function abandonedRunnerReleaseVerdict(status: AsyncStatus, proofState: string,
245
261
  const now = options.now?.() ?? Date.now();
246
262
  const lastActivityAgeMs = Math.max(0, now - lastActivityAt);
247
263
  if (lastActivityAgeMs <= thresholdMs) return { state: "retained", reason: `${proofReason}; last activity age ${lastActivityAgeMs}ms has not exceeded abandoned-timeout ${thresholdMs}ms` };
248
- const evidence: ActiveAsyncCapacityReleaseEvidence = {
264
+ const evidence: AbandonedRunnerEvidence = {
249
265
  releasedBy: "abandoned-timeout",
250
266
  processProof: "unknown",
251
267
  runnerPid: "gone",
@@ -259,7 +275,7 @@ function abandonedRunnerReleaseVerdict(status: AsyncStatus, proofState: string,
259
275
  };
260
276
  }
261
277
 
262
- function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwner, status: AsyncStatus | null, liveWorkflowRunIds: ReadonlySet<string>): ActiveAsyncCapacityReleaseVerdict {
278
+ function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwner, status: AsyncStatus | null, liveWorkflowRunIds: ReadonlySet<string>, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
263
279
  if (!status) return { state: "retained", reason: "status file is missing or unreadable" };
264
280
  if (status.sessionId !== owner.ownerSessionId) return { state: "retained", reason: `status session ${status.sessionId ?? "unknown"} does not match owner session ${owner.ownerSessionId}` };
265
281
  if (status.runId !== owner.runId) return { state: "retained", reason: `status run ${status.runId} does not match owner run ${owner.runId}` };
@@ -267,15 +283,49 @@ function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwner, status: AsyncSt
267
283
  if (!terminalState(status.state)) return { state: "retained", reason: `workflow is still ${status.state}` };
268
284
  if (liveWorkflowRunIds.has(owner.runId)) return { state: "retained", reason: "workflow controller is still live" };
269
285
  const evidence = readWorkflowChildProcessEvidence(owner.asyncDir, status.steps);
270
- if (evidence.state !== "observed") return { state: "retained", reason: evidence.reason };
271
- return { state: "releasable", reason: "workflow is terminal, controller is gone, and async children have observed proof" };
286
+ if (evidence.state === "observed") return { state: "releasable", reason: "workflow is terminal, controller is gone, and async children have observed proof" };
287
+ return abandonedWorkflowReleaseVerdict(owner, status, evidence.reason, options);
288
+ }
289
+
290
+ /** Every unresolved async child must itself pass the abandoned runner policy; any other unresolved child keeps the slot. */
291
+ function abandonedWorkflowReleaseVerdict(owner: ActiveAsyncCapacityOwner, status: AsyncStatus, proofReason: string, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
292
+ const thresholdMs = resolveAbandonedSlotReleaseAfterMs(options.abandonedSlotReleaseAfterMs);
293
+ if (thresholdMs === false) return { state: "retained", reason: `${proofReason}; abandoned-timeout policy is disabled` };
294
+ if (!status.steps) return { state: "retained", reason: proofReason };
295
+ if (typeof status.endedAt !== "number" || !Number.isFinite(status.endedAt)) return { state: "retained", reason: `${proofReason}; workflow end timestamp is missing or invalid` };
296
+ const workflowEndedAgeMs = (options.now?.() ?? Date.now()) - status.endedAt;
297
+ if (workflowEndedAgeMs <= thresholdMs) return { state: "retained", reason: `${proofReason}; workflow ended ${workflowEndedAgeMs}ms ago, within abandoned-timeout ${thresholdMs}ms` };
298
+ const abandonedChildren: AbandonedWorkflowEvidence["abandonedChildren"] = [];
299
+ for (const step of status.steps) {
300
+ const child = readWorkflowChildEvidence(owner.asyncDir, step);
301
+ if (!child || child.state === "resolved") continue;
302
+ const unresolved = child.unresolvedProof;
303
+ if (!unresolved) return { state: "retained", reason: child.reason };
304
+ if (unresolved.status.sessionId !== owner.ownerSessionId) return { state: "retained", reason: `${child.reason}; child session ${unresolved.status.sessionId ?? "unknown"} does not match owner session ${owner.ownerSessionId}` };
305
+ const verdict = abandonedRunnerReleaseVerdict(unresolved.status, unresolved.proofState, options);
306
+ if (verdict.state !== "releasable") return { state: "retained", reason: `async workflow child ${unresolved.status.runId}: ${verdict.reason}` };
307
+ abandonedChildren.push({ runId: unresolved.status.runId, lastActivityAgeMs: verdict.evidence.lastActivityAgeMs });
308
+ }
309
+ const evidence: AbandonedWorkflowEvidence = {
310
+ releasedBy: "abandoned-timeout",
311
+ processProof: "unknown",
312
+ controller: "unregistered",
313
+ workflowEndedAgeMs,
314
+ abandonedChildren,
315
+ abandonedSlotReleaseAfterMs: thresholdMs,
316
+ };
317
+ return {
318
+ state: "releasable",
319
+ reason: `${evidence.releasedBy}: ${proofReason}; workflow controller is unregistered; failed async children ${abandonedChildren.map((child) => child.runId).join(", ")} have dead runner PIDs; process proof unknown; workflow ended ${workflowEndedAgeMs}ms ago, over ${thresholdMs}ms`,
320
+ evidence,
321
+ };
272
322
  }
273
323
 
274
324
  function ownerReleaseVerdict(owner: ActiveAsyncCapacityOwner, liveWorkflowRunIds: ReadonlySet<string>, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
275
325
  const status = readStatus(owner.asyncDir);
276
326
  return owner.kind === "runner"
277
327
  ? runnerReleaseVerdict(owner, status, options)
278
- : workflowReleaseVerdict(owner, status, liveWorkflowRunIds);
328
+ : workflowReleaseVerdict(owner, status, liveWorkflowRunIds, options);
279
329
  }
280
330
 
281
331
  function capacitySessionDirs(rootDir: string, sessionId?: string): string[] {