@xzzpig/pi-subagents 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +135 -0
  2. package/README.md +4 -0
  3. package/agents/reviewer.md +3 -4
  4. package/docs/agents.md +343 -0
  5. package/docs/configuration.md +395 -0
  6. package/docs/extension-api.md +308 -0
  7. package/docs/missions.md +121 -0
  8. package/docs/models.md +192 -0
  9. package/docs/observability.md +198 -0
  10. package/docs/tool-reference.md +343 -0
  11. package/docs/watchdog.md +176 -0
  12. package/docs/workflows.md +163 -0
  13. package/package.json +13 -11
  14. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  15. package/skills/pi-subagents/references/execution-controls.md +7 -7
  16. package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
  17. package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
  18. package/src/agents/agents.ts +53 -23
  19. package/src/agents/frontmatter.ts +7 -3
  20. package/src/agents/skills.ts +2 -9
  21. package/src/api/preflight.ts +1 -1
  22. package/src/api/project-panes.ts +30 -0
  23. package/src/extension/config.ts +54 -1
  24. package/src/extension/doctor.ts +40 -0
  25. package/src/extension/fanout-child.ts +5 -4
  26. package/src/extension/index.ts +114 -38
  27. package/src/extension/public-execution.ts +35 -4
  28. package/src/extension/rpc.ts +10 -15
  29. package/src/extension/schemas.ts +33 -11
  30. package/src/extension/subagent-guide.ts +39 -0
  31. package/src/extension/tool-description.ts +38 -18
  32. package/src/inspectors/herdr/actions.ts +11 -2
  33. package/src/inspectors/herdr/inspector-runner.ts +16 -3
  34. package/src/inspectors/herdr/project-panes.ts +459 -63
  35. package/src/intercom/intercom-bridge.ts +7 -2
  36. package/src/intercom/native-supervisor-channel.ts +102 -4
  37. package/src/missions/actions.ts +25 -2
  38. package/src/missions/lifecycle.ts +25 -9
  39. package/src/missions/store.ts +89 -7
  40. package/src/missions/types.ts +33 -0
  41. package/src/missions/workflow-state.ts +25 -15
  42. package/src/runs/background/active-async-capacity.ts +431 -0
  43. package/src/runs/background/active-run-index.ts +46 -0
  44. package/src/runs/background/async-execution.ts +158 -71
  45. package/src/runs/background/async-job-tracker.ts +297 -133
  46. package/src/runs/background/async-resume.ts +37 -5
  47. package/src/runs/background/async-status.ts +39 -5
  48. package/src/runs/background/chain-append.ts +33 -15
  49. package/src/runs/background/completion-replay.ts +267 -0
  50. package/src/runs/background/control-channel.ts +95 -54
  51. package/src/runs/background/fleet-view.ts +18 -5
  52. package/src/runs/background/owned-process-tree.ts +104 -0
  53. package/src/runs/background/process-terminal.ts +17 -3
  54. package/src/runs/background/result-watcher.ts +113 -10
  55. package/src/runs/background/resume-guidance.ts +53 -0
  56. package/src/runs/background/retained-children.ts +14 -6
  57. package/src/runs/background/run-status.ts +119 -5
  58. package/src/runs/background/scheduled-runs.ts +25 -1
  59. package/src/runs/background/stale-run-reconciler.ts +12 -24
  60. package/src/runs/background/subagent-runner.ts +127 -41
  61. package/src/runs/background/subagent-wait.ts +5 -2
  62. package/src/runs/background/wait-completions.ts +39 -5
  63. package/src/runs/background/wait-subscriptions.ts +21 -5
  64. package/src/runs/foreground/async-dismiss-action.ts +85 -0
  65. package/src/runs/foreground/async-steering-action.ts +7 -8
  66. package/src/runs/foreground/chain-execution.ts +40 -2
  67. package/src/runs/foreground/execution.ts +97 -19
  68. package/src/runs/foreground/foreground-control.ts +12 -0
  69. package/src/runs/foreground/foreground-history.ts +137 -0
  70. package/src/runs/foreground/prompt-audit.ts +172 -0
  71. package/src/runs/foreground/subagent-executor.ts +1274 -243
  72. package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
  73. package/src/runs/shared/acceptance.ts +13 -4
  74. package/src/runs/shared/completion-guard.ts +17 -1
  75. package/src/runs/shared/dynamic-fanout.ts +1 -1
  76. package/src/runs/shared/llm-intent-arbiter.ts +302 -0
  77. package/src/runs/shared/model-fallback.ts +8 -4
  78. package/src/runs/shared/model-scope.ts +12 -2
  79. package/src/runs/shared/parallel-utils.ts +3 -0
  80. package/src/runs/shared/pi-args.ts +44 -1
  81. package/src/runs/shared/run-fanout-budget.ts +280 -0
  82. package/src/runs/shared/single-output.ts +4 -2
  83. package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
  84. package/src/runs/shared/task-intent.ts +19 -3
  85. package/src/runs/shared/worktree.ts +20 -7
  86. package/src/shared/agent-stream-options.ts +5 -0
  87. package/src/shared/artifacts.ts +17 -21
  88. package/src/shared/display-text.ts +150 -0
  89. package/src/shared/file-coalescer.ts +9 -0
  90. package/src/shared/fork-context.ts +13 -0
  91. package/src/shared/formatters.ts +4 -6
  92. package/src/shared/node-executable.ts +21 -0
  93. package/src/shared/prompt-resources.ts +51 -0
  94. package/src/shared/settings.ts +15 -2
  95. package/src/shared/types.ts +158 -4
  96. package/src/shared/utf8.ts +11 -0
  97. package/src/shared/utils.ts +46 -34
  98. package/src/slash/prompt-workflows.ts +2 -15
  99. package/src/slash/slash-commands.ts +22 -2
  100. package/src/tui/fleet-status.ts +29 -17
  101. package/src/tui/fleet-transcript.ts +1 -48
  102. package/src/tui/fleet.ts +362 -37
  103. package/src/tui/render.ts +235 -71
  104. package/src/watchdog/change-signature.ts +4 -3
  105. package/src/watchdog/permission-arbiter.ts +2 -1
  106. package/src/watchdog/review.ts +4 -3
  107. package/src/workflows/chat-progress.ts +8 -2
  108. package/src/workflows/scripted-workflow.ts +273 -20
@@ -4,13 +4,15 @@ import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "
4
4
  import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
5
5
  import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type Details, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState, type UsageBudgetState, type ChainCheckpointState } from "../../shared/types.ts";
6
6
  import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../shared/capability-ceiling.ts";
7
- import { readStatus } from "../../shared/utils.ts";
8
- import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
7
+ import { pruneStatusCacheForAsyncRoot, readStatus } from "../../shared/utils.ts";
8
+ import { attachRootChildrenToSteps, buildNestedRouteIndex, findNestedRouteForRootId, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
9
9
  import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
10
+ import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
10
11
  import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
11
12
  import { contextModeLabel, summarizeContextModes, type ContextMode, type ContextSummary } from "../shared/context-mode.ts";
12
13
  import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
13
14
  import { readProcessTerminal, sanitizeProcessTerminal } from "./process-terminal.ts";
15
+ import { ACTIVE_RUN_INDEX_DIR, isActiveAsyncState, readActiveRunIndex, releaseActiveRunIndex, updateActiveRunIndex } from "./active-run-index.ts";
14
16
 
15
17
  interface AsyncRunStepSummary {
16
18
  index: number;
@@ -105,6 +107,7 @@ export interface AsyncRunSummary {
105
107
  nestedChildren?: NestedRunSummary[];
106
108
  nestedWarnings?: string[];
107
109
  processTerminal?: AsyncStatus["processTerminal"];
110
+ runFanoutBudget?: AsyncStatus["runFanoutBudget"];
108
111
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
109
112
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
110
113
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -160,7 +163,7 @@ type TargetedAsyncRunResolution =
160
163
  * accepting a path whose canonical location escaped the async root.
161
164
  */
162
165
  export function resolveTargetedAsyncRun(asyncDirRoot: string, id: string, sessionId?: string): TargetedAsyncRunResolution {
163
- if (!id || id === "." || id === ".." || path.basename(id) !== id) return { kind: "reject" };
166
+ if (!id || id === "." || id === ".." || id === ACTIVE_RUN_INDEX_DIR || path.basename(id) !== id) return { kind: "reject" };
164
167
  const asyncDir = path.join(asyncDirRoot, id);
165
168
  let entryStat: fs.Stats;
166
169
  try {
@@ -221,6 +224,8 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
221
224
  const { activityState, lastActivityAt } = deriveAsyncActivityState(asyncDir, status);
222
225
  const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId })
223
226
  ?? sanitizeProcessTerminal(status.processTerminal, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId }, path.join(asyncDir, "status.json"));
227
+ const runFanoutBudgetDescriptor = readRunFanoutBudgetDescriptor(asyncDir);
228
+ const runFanoutBudget = runFanoutBudgetDescriptor ? getRunFanoutBudgetSnapshot(runFanoutBudgetDescriptor) : status.runFanoutBudget;
224
229
  const steps = status.steps ?? [];
225
230
  const chainStepCount = status.chainStepCount ?? steps.length;
226
231
  const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
@@ -326,6 +331,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
326
331
  ...(nestedChildren.length ? { nestedChildren } : {}),
327
332
  ...(nestedWarnings.length ? { nestedWarnings } : {}),
328
333
  ...(processTerminal ? { processTerminal } : {}),
334
+ ...(runFanoutBudget ? { runFanoutBudget } : {}),
329
335
  ...(status.launchContractDigest ? { launchContractDigest: status.launchContractDigest } : {}),
330
336
  ...(status.launchResolvedExtensions ? { launchResolvedExtensions: status.launchResolvedExtensions } : {}),
331
337
  ...(status.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: status.runtimeAcknowledgedExtensions } : {}),
@@ -370,6 +376,13 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
370
376
 
371
377
  export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
372
378
  let entries: string[];
379
+ let scannedCompleteRoot = false;
380
+ let usedActiveIndex = false;
381
+ const activeOnly = options.runId === undefined
382
+ && options.entryLimit === undefined
383
+ && options.states !== undefined
384
+ && options.states.length > 0
385
+ && options.states.every(isActiveAsyncState);
373
386
  try {
374
387
  if (options.runId !== undefined) {
375
388
  const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
@@ -381,8 +394,16 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
381
394
  && resolveTargetedAsyncRun(asyncDirRoot, entry, options.sessionId).kind === "exact"
382
395
  )
383
396
  : [];
397
+ } else if (activeOnly) {
398
+ entries = (readActiveRunIndex(asyncDirRoot) ?? []).filter((entry) => {
399
+ if (resolveTargetedAsyncRun(asyncDirRoot, entry).kind === "exact") return true;
400
+ updateActiveRunIndex(path.join(asyncDirRoot, entry), "failed");
401
+ return false;
402
+ });
403
+ usedActiveIndex = true;
384
404
  } else {
385
- entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
405
+ entries = fs.readdirSync(asyncDirRoot).filter((entry) => entry !== ACTIVE_RUN_INDEX_DIR && isAsyncRunDir(asyncDirRoot, entry));
406
+ scannedCompleteRoot = true;
386
407
  }
387
408
  } catch (error) {
388
409
  if (isNotFoundError(error)) return [];
@@ -392,6 +413,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
392
413
  }
393
414
 
394
415
  if (options.entryLimit !== undefined) {
416
+ scannedCompleteRoot = false;
395
417
  const limit = Math.max(0, Math.floor(options.entryLimit));
396
418
  entries = entries
397
419
  .map((entry) => {
@@ -410,6 +432,8 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
410
432
  .map((candidate) => candidate.entry);
411
433
  }
412
434
 
435
+ if (scannedCompleteRoot) pruneStatusCacheForAsyncRoot(asyncDirRoot, entries);
436
+
413
437
  const allowedStates = options.states ? new Set(options.states) : undefined;
414
438
  const runs: AsyncRunSummary[] = [];
415
439
  // Route resolution for every run shares a single index built from the
@@ -419,6 +443,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
419
443
  // entirely when no active runs match.
420
444
  let nestedRouteIndex: Map<string, NestedRoute> | undefined;
421
445
  const resolveNestedRoute = (rootRunId: string): NestedRoute | undefined => {
446
+ if (usedActiveIndex) return findNestedRouteForRootId(rootRunId);
422
447
  if (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
423
448
  return nestedRouteIndex.get(rootRunId);
424
449
  };
@@ -428,7 +453,15 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
428
453
  ? undefined
429
454
  : reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
430
455
  const status = (reconciliation?.status ?? readStatus(asyncDir)) as (AsyncStatus & { cwd?: string }) | null;
431
- if (!status) continue;
456
+ if (!status) {
457
+ if (usedActiveIndex) updateActiveRunIndex(asyncDir, "failed");
458
+ continue;
459
+ }
460
+ if (usedActiveIndex && !isActiveAsyncState(status.state)) {
461
+ const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId });
462
+ if (processTerminal?.state === "observed") releaseActiveRunIndex(asyncDir);
463
+ }
464
+ if (status.displayDismissedAt !== undefined) continue;
432
465
  // Filter before the nested-route lookup: the lookup builds an index over
433
466
  // the nested-events directory, so deferring it for filtered-out runs keeps
434
467
  // restoration at load from scanning that directory when no active runs
@@ -531,6 +564,7 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
531
564
  const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
532
565
  const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
533
566
  lines.push(...formatNestedRunStatusLines(unattached, { indent: " ", maxLines: 12 }));
567
+ if (run.runFanoutBudget) lines.push(` ${formatRunFanoutBudget(run.runFanoutBudget)}`);
534
568
  if (run.error) lines.push(` Error: ${run.error}`);
535
569
  for (const warning of run.nestedWarnings ?? []) lines.push(` Warning: ${warning}`);
536
570
  const outputPath = formatAsyncRunOutputPath(run);
@@ -4,7 +4,7 @@ import * as path from "node:path";
4
4
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
5
5
  import { appendJsonl } from "../../shared/artifacts.ts";
6
6
  import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
7
- import { readStatus } from "../../shared/utils.ts";
7
+ import { PROMPT_REDACTED, readStatus } from "../../shared/utils.ts";
8
8
  import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep, RunnerCheckpointStep } from "../shared/parallel-utils.ts";
9
9
  import { isCheckpointRunnerStep, isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
10
10
 
@@ -19,6 +19,7 @@ export interface ChainAppendRequest {
19
19
  export interface ChainAppendResult {
20
20
  request: ChainAppendRequest;
21
21
  pendingCount: number;
22
+ bookkeepingError?: string;
22
23
  }
23
24
 
24
25
  type StatusStep = NonNullable<AsyncStatus["steps"]>[number];
@@ -69,6 +70,7 @@ export function enqueueChainAppendRequest(input: {
69
70
  runId: string;
70
71
  steps: RunnerStep[];
71
72
  now?: number;
73
+ admit?: (persist: () => void) => void;
72
74
  }): ChainAppendResult {
73
75
  const status = readStatus(input.asyncDir);
74
76
  if (!status) throw new Error(`No async run status found for '${input.runId}'.`);
@@ -85,20 +87,36 @@ export function enqueueChainAppendRequest(input: {
85
87
  steps: input.steps,
86
88
  };
87
89
  fs.mkdirSync(appendDir(input.asyncDir), { recursive: true });
88
- writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
89
- const pendingCount = countPendingChainAppendRequests(input.asyncDir);
90
+ const persist = () => writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
91
+ if (input.admit) input.admit(persist);
92
+ else persist();
93
+ let pendingCount = 1;
94
+ const bookkeepingErrors: string[] = [];
95
+ try {
96
+ pendingCount = countPendingChainAppendRequests(input.asyncDir);
97
+ } catch (error) {
98
+ bookkeepingErrors.push(`pending append count failed: ${error instanceof Error ? error.message : String(error)}`);
99
+ }
90
100
  const statusPath = path.join(input.asyncDir, "status.json");
91
101
  const updatedStatus = { ...status, pendingAppends: pendingCount, lastUpdate: request.createdAt };
92
- writeAtomicJson(statusPath, updatedStatus);
93
- appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
94
- type: "subagent.chain.append.requested",
95
- ts: request.createdAt,
96
- runId: input.runId,
97
- requestId: request.id,
98
- stepCount: input.steps.length,
99
- pendingAppends: pendingCount,
100
- }));
101
- return { request, pendingCount };
102
+ try {
103
+ writeAtomicJson(statusPath, updatedStatus);
104
+ } catch (error) {
105
+ bookkeepingErrors.push(`status update failed: ${error instanceof Error ? error.message : String(error)}`);
106
+ }
107
+ try {
108
+ appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
109
+ type: "subagent.chain.append.requested",
110
+ ts: request.createdAt,
111
+ runId: input.runId,
112
+ requestId: request.id,
113
+ stepCount: input.steps.length,
114
+ pendingAppends: pendingCount,
115
+ }));
116
+ } catch (error) {
117
+ bookkeepingErrors.push(`event append failed: ${error instanceof Error ? error.message : String(error)}`);
118
+ }
119
+ return { request, pendingCount, ...(bookkeepingErrors.length > 0 ? { bookkeepingError: bookkeepingErrors.join("; ") } : {}) };
102
120
  }
103
121
 
104
122
  function readAppendRequest(filePath: string): ChainAppendRequest | undefined {
@@ -135,8 +153,8 @@ const MAX_STATUS_STEP_DESCRIPTION_CHARS = 160;
135
153
 
136
154
  /** Bounded one-line per-step task description persisted into status.json for fleet display. */
137
155
  export function statusStepDescription(task: string | undefined): string | undefined {
138
- const description = task?.replace(/\s+/g, " ").trim();
139
- if (!description) return undefined;
156
+ if (!task?.trim()) return undefined;
157
+ const description = PROMPT_REDACTED;
140
158
  return description.length > MAX_STATUS_STEP_DESCRIPTION_CHARS
141
159
  ? `${description.slice(0, MAX_STATUS_STEP_DESCRIPTION_CHARS - 1)}…`
142
160
  : description;
@@ -0,0 +1,267 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
4
+ import type { WaitCompletion } from "../../shared/types.ts";
5
+ import { utf8Tail } from "../../shared/utf8.ts";
6
+
7
+ const REPLAY_VERSION = 1;
8
+ const ARCHIVE_VERSION = 1;
9
+ const ARCHIVE_TEXT_LIMIT_BYTES = 64 * 1024;
10
+ const REPLAY_DIR_NAME = "completion-replay";
11
+ const ARCHIVE_DIR_NAME = "output-archives";
12
+
13
+ export interface CompletionArchiveEntry {
14
+ agent?: string;
15
+ source: "output-artifact" | "session" | "result-tail";
16
+ path?: string;
17
+ text?: string;
18
+ truncated?: boolean;
19
+ }
20
+
21
+ export interface CompletionArchive {
22
+ version: 1;
23
+ runId: string;
24
+ createdAt: number;
25
+ entries: CompletionArchiveEntry[];
26
+ }
27
+
28
+ export interface CompletionReplayRecord {
29
+ version: 1;
30
+ runId: string;
31
+ sessionId: string;
32
+ completedAt: number;
33
+ expiresAt: number;
34
+ completion: WaitCompletion;
35
+ archivePath: string;
36
+ }
37
+
38
+ function safeRunFile(runId: string): string {
39
+ return `${encodeURIComponent(runId)}.json`;
40
+ }
41
+
42
+ export function completionReplayPath(resultsDir: string, runId: string): string {
43
+ return path.join(resultsDir, REPLAY_DIR_NAME, safeRunFile(runId));
44
+ }
45
+
46
+ export function completionArchivePath(resultsDir: string, runId: string): string {
47
+ return path.join(resultsDir, ARCHIVE_DIR_NAME, safeRunFile(runId));
48
+ }
49
+
50
+ function nonEmptyString(value: unknown): string | undefined {
51
+ return typeof value === "string" && value.length > 0 ? value : undefined;
52
+ }
53
+
54
+ function existingFile(value: unknown): string | undefined {
55
+ const filePath = nonEmptyString(value);
56
+ if (!filePath) return undefined;
57
+ try {
58
+ return fs.statSync(filePath).isFile() ? filePath : undefined;
59
+ } catch {
60
+ return undefined;
61
+ }
62
+ }
63
+
64
+ function outputArtifactPath(child: Record<string, unknown>): string | undefined {
65
+ if (!child.artifactPaths || typeof child.artifactPaths !== "object" || Array.isArray(child.artifactPaths)) return undefined;
66
+ return existingFile((child.artifactPaths as Record<string, unknown>).outputPath);
67
+ }
68
+
69
+ /** Create a small archive that references saved child artifacts and retains only bounded fallback output text. */
70
+ export function writeCompletionArchive(resultsDir: string, runId: string, data: Record<string, unknown>, createdAt: number): string {
71
+ const entries: CompletionArchiveEntry[] = [];
72
+ const fallback: string[] = [];
73
+ const results = Array.isArray(data.results) ? data.results : [];
74
+ for (const value of results) {
75
+ if (!value || typeof value !== "object" || Array.isArray(value)) continue;
76
+ const child = value as Record<string, unknown>;
77
+ const agent = nonEmptyString(child.agent);
78
+ const artifactPath = outputArtifactPath(child);
79
+ if (artifactPath) {
80
+ entries.push({ ...(agent ? { agent } : {}), source: "output-artifact", path: artifactPath });
81
+ continue;
82
+ }
83
+ const sessionPath = existingFile(child.sessionFile);
84
+ if (sessionPath) {
85
+ entries.push({ ...(agent ? { agent } : {}), source: "session", path: sessionPath });
86
+ continue;
87
+ }
88
+ const output = nonEmptyString(child.output);
89
+ const error = nonEmptyString(child.error);
90
+ if (output || error) {
91
+ fallback.push([agent ? `[${agent}]` : undefined, error ? `Error: ${error}` : undefined, output].filter(Boolean).join("\n"));
92
+ }
93
+ }
94
+ if (results.length === 0) {
95
+ const sessionPath = existingFile(data.sessionFile);
96
+ if (sessionPath) entries.push({ source: "session", path: sessionPath });
97
+ }
98
+ if (entries.length === 0 && fallback.length === 0) {
99
+ const summary = nonEmptyString(data.summary);
100
+ if (summary) fallback.push(summary);
101
+ }
102
+ if (fallback.length > 0) {
103
+ const bounded = utf8Tail(fallback.join("\n\n"), ARCHIVE_TEXT_LIMIT_BYTES);
104
+ entries.push({ source: "result-tail", text: bounded.text, ...(bounded.truncated ? { truncated: true } : {}) });
105
+ }
106
+ const archive: CompletionArchive = { version: ARCHIVE_VERSION, runId, createdAt, entries };
107
+ const archivePath = completionArchivePath(resultsDir, runId);
108
+ writePrivateAtomicJson(archivePath, archive);
109
+ return archivePath;
110
+ }
111
+
112
+ function parseCompletion(value: unknown, runId: string): WaitCompletion | undefined {
113
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
114
+ const completion = value as Partial<WaitCompletion>;
115
+ if (completion.runId !== runId) return undefined;
116
+ return completion as WaitCompletion;
117
+ }
118
+
119
+ function parseReplay(value: unknown): CompletionReplayRecord | undefined {
120
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
121
+ const record = value as Partial<CompletionReplayRecord>;
122
+ if (record.version !== REPLAY_VERSION
123
+ || typeof record.runId !== "string"
124
+ || typeof record.sessionId !== "string"
125
+ || typeof record.completedAt !== "number"
126
+ || typeof record.expiresAt !== "number"
127
+ || typeof record.archivePath !== "string") return undefined;
128
+ const completion = parseCompletion(record.completion, record.runId);
129
+ return completion ? { ...record, completion } as CompletionReplayRecord : undefined;
130
+ }
131
+
132
+ function validateReplayRecord(resultsDir: string, runId: string, record: CompletionReplayRecord): CompletionReplayRecord | undefined {
133
+ if (record.runId !== runId) return undefined;
134
+ const archivePath = completionArchivePath(resultsDir, runId);
135
+ return path.resolve(record.archivePath) === path.resolve(archivePath)
136
+ ? { ...record, archivePath, completion: { ...record.completion, archivePath } }
137
+ : undefined;
138
+ }
139
+
140
+ function runIdFromReplayFile(file: string): string | undefined {
141
+ if (!file.endsWith(".json")) return undefined;
142
+ try {
143
+ const runId = decodeURIComponent(file.slice(0, -".json".length));
144
+ return safeRunFile(runId) === file ? runId : undefined;
145
+ } catch {
146
+ return undefined;
147
+ }
148
+ }
149
+
150
+ function removeBestEffort(filePath: string): void {
151
+ try {
152
+ fs.rmSync(filePath, { force: true });
153
+ } catch { /* cleanup only */ }
154
+ }
155
+
156
+ function parseArchive(value: unknown): CompletionArchive | undefined {
157
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
158
+ const archive = value as Partial<CompletionArchive>;
159
+ if (archive.version !== ARCHIVE_VERSION || typeof archive.runId !== "string" || typeof archive.createdAt !== "number" || !Array.isArray(archive.entries)) return undefined;
160
+ const entries = archive.entries.flatMap((value): CompletionArchiveEntry[] => {
161
+ if (!value || typeof value !== "object" || Array.isArray(value)) return [];
162
+ const entry = value as Partial<CompletionArchiveEntry>;
163
+ if (entry.source !== "output-artifact" && entry.source !== "session" && entry.source !== "result-tail") return [];
164
+ return [{
165
+ ...(typeof entry.agent === "string" ? { agent: entry.agent } : {}),
166
+ source: entry.source,
167
+ ...(typeof entry.path === "string" ? { path: entry.path } : {}),
168
+ ...(typeof entry.text === "string" ? { text: entry.text } : {}),
169
+ ...(entry.truncated === true ? { truncated: true } : {}),
170
+ }];
171
+ });
172
+ return { version: ARCHIVE_VERSION, runId: archive.runId, createdAt: archive.createdAt, entries };
173
+ }
174
+
175
+ /** Persist a terminal completion before its one-shot result file is removed. */
176
+ export function writeCompletionReplay(input: {
177
+ resultsDir: string;
178
+ runId: string;
179
+ sessionId: string;
180
+ completion: WaitCompletion;
181
+ data: Record<string, unknown>;
182
+ now: number;
183
+ ttlMs: number;
184
+ }): CompletionReplayRecord {
185
+ const archivePath = writeCompletionArchive(input.resultsDir, input.runId, input.data, input.now);
186
+ const completion = { ...input.completion, archivePath };
187
+ const record: CompletionReplayRecord = {
188
+ version: REPLAY_VERSION,
189
+ runId: input.runId,
190
+ sessionId: input.sessionId,
191
+ completedAt: input.now,
192
+ expiresAt: input.now + input.ttlMs,
193
+ completion,
194
+ archivePath,
195
+ };
196
+ writePrivateAtomicJson(completionReplayPath(input.resultsDir, input.runId), record);
197
+ cleanupCompletionReplay(input.resultsDir, input.now, input.ttlMs);
198
+ return record;
199
+ }
200
+
201
+ /** Read a current replay record. Unknown fields are ignored and unknown versions are skipped. */
202
+ export function readCompletionReplay(resultsDir: string, runId: string, options: { sessionId?: string; now?: number } = {}): CompletionReplayRecord | undefined {
203
+ const replayPath = completionReplayPath(resultsDir, runId);
204
+ let parsed: CompletionReplayRecord | undefined;
205
+ try {
206
+ parsed = parseReplay(JSON.parse(fs.readFileSync(replayPath, "utf-8")));
207
+ } catch (error) {
208
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
209
+ throw error;
210
+ }
211
+ if (!parsed) return undefined;
212
+ const safeRecord = validateReplayRecord(resultsDir, runId, parsed);
213
+ if (!safeRecord) {
214
+ removeBestEffort(replayPath);
215
+ return undefined;
216
+ }
217
+ parsed = safeRecord;
218
+ if (options.sessionId !== undefined && parsed.sessionId !== options.sessionId) return undefined;
219
+ if (parsed.expiresAt <= (options.now ?? Date.now())) {
220
+ removeBestEffort(replayPath);
221
+ removeBestEffort(parsed.archivePath);
222
+ return undefined;
223
+ }
224
+ return parsed;
225
+ }
226
+
227
+ export function readCompletionArchive(archivePath: string): CompletionArchive | undefined {
228
+ try {
229
+ return parseArchive(JSON.parse(fs.readFileSync(archivePath, "utf-8")));
230
+ } catch (error) {
231
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
232
+ throw error;
233
+ }
234
+ }
235
+
236
+ /** Opportunistically remove expired replay and orphan archive files without affecting delivery. */
237
+ export function cleanupCompletionReplay(resultsDir: string, now: number, maxAgeMs: number): void {
238
+ const replayDir = path.join(resultsDir, REPLAY_DIR_NAME);
239
+ try {
240
+ for (const file of fs.readdirSync(replayDir)) {
241
+ const runId = runIdFromReplayFile(file);
242
+ if (!runId) continue;
243
+ const filePath = path.join(replayDir, file);
244
+ try {
245
+ const record = parseReplay(JSON.parse(fs.readFileSync(filePath, "utf-8")));
246
+ const safeRecord = record ? validateReplayRecord(resultsDir, runId, record) : undefined;
247
+ if (record && !safeRecord) {
248
+ fs.rmSync(filePath, { force: true });
249
+ } else if (safeRecord && safeRecord.expiresAt <= now) {
250
+ fs.rmSync(filePath, { force: true });
251
+ fs.rmSync(safeRecord.archivePath, { force: true });
252
+ } else if (!record && now - fs.statSync(filePath).mtimeMs > maxAgeMs) {
253
+ fs.rmSync(filePath, { force: true });
254
+ }
255
+ } catch { /* one bad entry must not block cleanup */ }
256
+ }
257
+ } catch { /* replay directory may not exist yet */ }
258
+ const archiveDir = path.join(resultsDir, ARCHIVE_DIR_NAME);
259
+ try {
260
+ for (const file of fs.readdirSync(archiveDir)) {
261
+ const filePath = path.join(archiveDir, file);
262
+ try {
263
+ if (now - fs.statSync(filePath).mtimeMs > maxAgeMs) fs.rmSync(filePath, { force: true });
264
+ } catch { /* one bad entry must not block cleanup */ }
265
+ }
266
+ } catch { /* archive directory may not exist yet */ }
267
+ }