@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.
- package/CHANGELOG.md +135 -0
- package/README.md +4 -0
- package/agents/reviewer.md +3 -4
- package/docs/agents.md +343 -0
- package/docs/configuration.md +395 -0
- package/docs/extension-api.md +308 -0
- package/docs/missions.md +121 -0
- package/docs/models.md +192 -0
- package/docs/observability.md +198 -0
- package/docs/tool-reference.md +343 -0
- package/docs/watchdog.md +176 -0
- package/docs/workflows.md +163 -0
- package/package.json +13 -11
- package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
- package/skills/pi-subagents/references/execution-controls.md +7 -7
- package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
- package/src/agents/agents.ts +53 -23
- package/src/agents/frontmatter.ts +7 -3
- package/src/agents/skills.ts +2 -9
- package/src/api/preflight.ts +1 -1
- package/src/api/project-panes.ts +30 -0
- package/src/extension/config.ts +54 -1
- package/src/extension/doctor.ts +40 -0
- package/src/extension/fanout-child.ts +5 -4
- package/src/extension/index.ts +114 -38
- package/src/extension/public-execution.ts +35 -4
- package/src/extension/rpc.ts +10 -15
- package/src/extension/schemas.ts +33 -11
- package/src/extension/subagent-guide.ts +39 -0
- package/src/extension/tool-description.ts +38 -18
- package/src/inspectors/herdr/actions.ts +11 -2
- package/src/inspectors/herdr/inspector-runner.ts +16 -3
- package/src/inspectors/herdr/project-panes.ts +459 -63
- package/src/intercom/intercom-bridge.ts +7 -2
- package/src/intercom/native-supervisor-channel.ts +102 -4
- package/src/missions/actions.ts +25 -2
- package/src/missions/lifecycle.ts +25 -9
- package/src/missions/store.ts +89 -7
- package/src/missions/types.ts +33 -0
- package/src/missions/workflow-state.ts +25 -15
- package/src/runs/background/active-async-capacity.ts +431 -0
- package/src/runs/background/active-run-index.ts +46 -0
- package/src/runs/background/async-execution.ts +158 -71
- package/src/runs/background/async-job-tracker.ts +297 -133
- package/src/runs/background/async-resume.ts +37 -5
- package/src/runs/background/async-status.ts +39 -5
- package/src/runs/background/chain-append.ts +33 -15
- package/src/runs/background/completion-replay.ts +267 -0
- package/src/runs/background/control-channel.ts +95 -54
- package/src/runs/background/fleet-view.ts +18 -5
- package/src/runs/background/owned-process-tree.ts +104 -0
- package/src/runs/background/process-terminal.ts +17 -3
- package/src/runs/background/result-watcher.ts +113 -10
- package/src/runs/background/resume-guidance.ts +53 -0
- package/src/runs/background/retained-children.ts +14 -6
- package/src/runs/background/run-status.ts +119 -5
- package/src/runs/background/scheduled-runs.ts +25 -1
- package/src/runs/background/stale-run-reconciler.ts +12 -24
- package/src/runs/background/subagent-runner.ts +127 -41
- package/src/runs/background/subagent-wait.ts +5 -2
- package/src/runs/background/wait-completions.ts +39 -5
- package/src/runs/background/wait-subscriptions.ts +21 -5
- package/src/runs/foreground/async-dismiss-action.ts +85 -0
- package/src/runs/foreground/async-steering-action.ts +7 -8
- package/src/runs/foreground/chain-execution.ts +40 -2
- package/src/runs/foreground/execution.ts +97 -19
- package/src/runs/foreground/foreground-control.ts +12 -0
- package/src/runs/foreground/foreground-history.ts +137 -0
- package/src/runs/foreground/prompt-audit.ts +172 -0
- package/src/runs/foreground/subagent-executor.ts +1274 -243
- package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
- package/src/runs/shared/acceptance.ts +13 -4
- package/src/runs/shared/completion-guard.ts +17 -1
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/llm-intent-arbiter.ts +302 -0
- package/src/runs/shared/model-fallback.ts +8 -4
- package/src/runs/shared/model-scope.ts +12 -2
- package/src/runs/shared/parallel-utils.ts +3 -0
- package/src/runs/shared/pi-args.ts +44 -1
- package/src/runs/shared/run-fanout-budget.ts +280 -0
- package/src/runs/shared/single-output.ts +4 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
- package/src/runs/shared/task-intent.ts +19 -3
- package/src/runs/shared/worktree.ts +20 -7
- package/src/shared/agent-stream-options.ts +5 -0
- package/src/shared/artifacts.ts +17 -21
- package/src/shared/display-text.ts +150 -0
- package/src/shared/file-coalescer.ts +9 -0
- package/src/shared/fork-context.ts +13 -0
- package/src/shared/formatters.ts +4 -6
- package/src/shared/node-executable.ts +21 -0
- package/src/shared/prompt-resources.ts +51 -0
- package/src/shared/settings.ts +15 -2
- package/src/shared/types.ts +158 -4
- package/src/shared/utf8.ts +11 -0
- package/src/shared/utils.ts +46 -34
- package/src/slash/prompt-workflows.ts +2 -15
- package/src/slash/slash-commands.ts +22 -2
- package/src/tui/fleet-status.ts +29 -17
- package/src/tui/fleet-transcript.ts +1 -48
- package/src/tui/fleet.ts +362 -37
- package/src/tui/render.ts +235 -71
- package/src/watchdog/change-signature.ts +4 -3
- package/src/watchdog/permission-arbiter.ts +2 -1
- package/src/watchdog/review.ts +4 -3
- package/src/workflows/chat-progress.ts +8 -2
- 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)
|
|
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
|
-
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
139
|
-
|
|
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
|
+
}
|