pi-subagents 0.69.0 → 0.70.0

package/src/runs/background/terminal-run-index.ts

@@ -1,138 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { AsyncStatus } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { encodeIndexSegment } from "./index-segment.ts";
-
-export const TERMINAL_RUN_INDEX_DIR = ".terminal-runs";
-
-const TERMINAL_RUN_INDEX_VERSION = 1;
-const TIMESTAMP_WIDTH = 16;
-
-interface TerminalRunIndexEntry {
-	version: 1;
-	runId: string;
-	sessionId: string;
-	endedAt: number;
-}
-
-function isTerminalState(state: AsyncStatus["state"]): boolean {
-	return state === "complete" || state === "failed" || state === "partial" || state === "paused" || state === "stopped" || state === "rejected";
-}
-
-function indexRoot(asyncDirRoot: string): string {
-	return path.join(asyncDirRoot, TERMINAL_RUN_INDEX_DIR);
-}
-
-function sessionIndexDir(asyncDirRoot: string, sessionId: string): string {
-	return path.join(indexRoot(asyncDirRoot), encodeIndexSegment(sessionId));
-}
-
-function markerName(endedAt: number, runId: string): string {
-	return `${Math.max(0, Math.floor(endedAt)).toString().padStart(TIMESTAMP_WIDTH, "0")}-${encodeIndexSegment(runId)}.json`;
-}
-
-function markerPath(asyncDir: string, sessionId: string, endedAt: number): string {
-	return path.join(sessionIndexDir(path.dirname(asyncDir), sessionId), markerName(endedAt, path.basename(asyncDir)));
-}
-
-function parseEntry(value: unknown): TerminalRunIndexEntry | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const entry = value as Partial<TerminalRunIndexEntry>;
-	if (entry.version !== TERMINAL_RUN_INDEX_VERSION
-		|| typeof entry.runId !== "string" || !entry.runId
-		|| typeof entry.sessionId !== "string" || !entry.sessionId
-		|| typeof entry.endedAt !== "number" || !Number.isFinite(entry.endedAt)) return undefined;
-	return { version: TERMINAL_RUN_INDEX_VERSION, runId: entry.runId, sessionId: entry.sessionId, endedAt: entry.endedAt };
-}
-
-export function updateTerminalRunIndex(asyncDir: string, status: AsyncStatus): void {
-	if (!isTerminalState(status.state) || typeof status.sessionId !== "string" || !status.sessionId) return;
-	const endedAt = status.endedAt ?? status.lastUpdate ?? status.startedAt;
-	const marker = markerPath(asyncDir, status.sessionId, endedAt);
-	const entry: TerminalRunIndexEntry = {
-		version: TERMINAL_RUN_INDEX_VERSION,
-		runId: status.runId || path.basename(asyncDir),
-		sessionId: status.sessionId,
-		endedAt,
-	};
-	writeAtomicJson(marker, entry);
-}
-
-function removeInvalidMarker(marker: string): void {
-	try {
-		fs.rmSync(marker, { force: true });
-	} catch {
-		// An advisory marker can remain for a later read when cleanup is contended.
-	}
-}
-
-interface MarkerFile {
-	dir: string;
-	name: string;
-}
-
-function markerFiles(dir: string): MarkerFile[] {
-	try {
-		return fs.readdirSync(dir, { withFileTypes: true })
-			.filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-			.map((entry) => ({ dir, name: entry.name }));
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT" || code === "ENOTDIR") return [];
-		throw error;
-	}
-}
-
-function sessionDirs(asyncDirRoot: string, sessionId: string | undefined): string[] {
-	if (sessionId) return [sessionIndexDir(asyncDirRoot, sessionId)];
-	try {
-		return fs.readdirSync(indexRoot(asyncDirRoot), { withFileTypes: true })
-			.filter((entry) => entry.isDirectory())
-			.map((entry) => path.join(indexRoot(asyncDirRoot), entry.name));
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT" || code === "ENOTDIR") return [];
-		throw error;
-	}
-}
-
-function recentMarkerFiles(dirs: string[], limit: number): string[] {
-	return dirs.flatMap(markerFiles)
-		.sort((left, right) => right.name.localeCompare(left.name))
-		.slice(0, limit)
-		.map((marker) => path.join(marker.dir, marker.name));
-}
-
-export function readRecentTerminalRunIndex(asyncDirRoot: string, options: { sessionId?: string; limit?: number } = {}): string[] {
-	const limit = options.limit === undefined ? Number.POSITIVE_INFINITY : Math.max(0, Math.floor(options.limit));
-	const candidates = recentMarkerFiles(sessionDirs(asyncDirRoot, options.sessionId), limit);
-	const runIds: string[] = [];
-	const seen = new Set<string>();
-	for (const marker of candidates) {
-		let entry: TerminalRunIndexEntry | undefined;
-		try {
-			entry = parseEntry(JSON.parse(fs.readFileSync(marker, "utf-8")));
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
-		}
-		if (!entry || (options.sessionId !== undefined && entry.sessionId !== options.sessionId)) {
-			removeInvalidMarker(marker);
-			continue;
-		}
-		const asyncDir = path.join(asyncDirRoot, entry.runId);
-		const status = readStatus(asyncDir);
-		if (!status || !isTerminalState(status.state) || status.sessionId !== entry.sessionId || (status.runId && status.runId !== entry.runId)) {
-			removeInvalidMarker(marker);
-			continue;
-		}
-		if (seen.has(entry.runId)) {
-			removeInvalidMarker(marker);
-			continue;
-		}
-		seen.add(entry.runId);
-		runIds.push(entry.runId);
-	}
-	return runIds;
-}

package/src/runs/background/top-level-async.ts

@@ -1,14 +0,0 @@
-interface AsyncOverrideParams {
-	async?: boolean;
-	clarify?: boolean;
-	foregroundOnly?: boolean;
-}
-
-export function applyForceTopLevelAsyncOverride<T extends AsyncOverrideParams>(
-	params: T,
-	depth: number,
-	forceTopLevelAsync: boolean,
-): T {
-	if (params.foregroundOnly || !(depth === 0 && forceTopLevelAsync)) return params;
-	return { ...params, async: true, clarify: false };
-}

package/src/runs/background/wait-completions.ts

@@ -1,261 +0,0 @@
-import * as fs from "node:fs";
-import type { ArtifactPaths, SubagentState, Usage, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
-import type { AsyncRunSummary } from "./async-status.ts";
-import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
-import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadMatchesSessionRun, resultPayloadPathForSessionRun } from "./result-files.ts";
-import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
-import { projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
-
-function asNonEmptyString(value: unknown): string | undefined {
-	return typeof value === "string" && value ? value : undefined;
-}
-
-function nonNegativeNumber(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
-}
-
-function projectedUsage(value: unknown): Usage | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const record = value as Record<string, unknown>;
-	const input = nonNegativeNumber(record.input);
-	const output = nonNegativeNumber(record.output);
-	const cacheRead = nonNegativeNumber(record.cacheRead);
-	const cacheWrite = nonNegativeNumber(record.cacheWrite);
-	const cost = nonNegativeNumber(record.cost);
-	const turns = nonNegativeNumber(record.turns);
-	if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || cost === undefined || turns === undefined || !Number.isSafeInteger(turns)) return undefined;
-	return { input, output, cacheRead, cacheWrite, cost, turns };
-}
-
-function errorCode(error: unknown): string | undefined {
-	return typeof error === "object" && error !== null && "code" in error
-		? (error as NodeJS.ErrnoException).code
-		: undefined;
-}
-
-function isAccessDenied(error: unknown): boolean {
-	const code = errorCode(error);
-	return code === "EPERM" || code === "EACCES";
-}
-
-function errorMessage(error: unknown): string {
-	return error instanceof Error ? error.message : String(error);
-}
-
-const STRUCTURED_OUTPUT_INLINE_LIMIT_BYTES = 4 * 1024;
-
-function waitResultPayloadCandidate(resultsDir: string, run: AsyncRunSummary): string {
-	const publicPath = resultFilePath(resultsDir, run.id);
-	if (!run.sessionId) return publicPath;
-	try {
-		const indexedPath = resultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
-		return indexedPath ?? publicPath;
-	} catch (error) {
-		if (!isAccessDenied(error)) throw error;
-		const pendingPath = fallbackResultPayloadPathForSessionRun(resultsDir, run.sessionId, run.id);
-		return pendingPath ?? publicPath;
-	}
-}
-
-function readWaitResultPayload(candidatePath: string, run: AsyncRunSummary): Record<string, unknown> | undefined {
-	// A terminal run without session ownership cannot safely claim a payload.
-	if (!run.sessionId) return undefined;
-	const payload: unknown = JSON.parse(fs.readFileSync(candidatePath, "utf-8"));
-	if (!resultPayloadMatchesSessionRun(payload, run.sessionId, run.id)) return undefined;
-	return payload as Record<string, unknown>;
-}
-
-export function projectStructuredOutput(value: unknown): unknown {
-	if (value === undefined) return undefined;
-	const serialized = JSON.stringify(value);
-	if (typeof serialized !== "string") throw new Error("Structured output must be JSON-serializable");
-	return Buffer.byteLength(serialized, "utf8") <= STRUCTURED_OUTPUT_INLINE_LIMIT_BYTES ? JSON.parse(serialized) : undefined;
-}
-
-/**
- * Project a terminal result payload into the slim shape that is safe to surface in
- * tool_result details: run identity, per-child outcome, and the artifact trail.
- * Output text is deliberately excluded — it already travels in the tool result
- * content, and duplicating it in details would double the payload for every wait.
- */
-export function toWaitCompletion(data: Record<string, unknown>, runId: string): WaitCompletion {
-	const results = Array.isArray(data.results)
-		? data.results.flatMap((entry): WaitCompletionChild[] => {
-			if (entry === null || typeof entry !== "object") return [];
-			const child = entry as Record<string, unknown>;
-			const outputState = child.outputState === "present" || child.outputState === "absent" || child.outputState === "unknown"
-				? child.outputState
-				: undefined;
-			const artifactPaths = child.artifactPaths !== null && typeof child.artifactPaths === "object"
-				? (child.artifactPaths as Partial<ArtifactPaths>)
-				: undefined;
-			const agent = asNonEmptyString(child.agent);
-			const childRunId = asNonEmptyString(child.runId);
-			const usage = projectedUsage(child.usage);
-			const sessionFile = asNonEmptyString(child.sessionFile);
-			const error = asNonEmptyString(child.error);
-			const model = asNonEmptyString(child.model);
-			const structuredOutput = projectStructuredOutput(child.structuredOutput);
-			const structuredOutputPath = asNonEmptyString(child.structuredOutputPath);
-			const contextOverflow = child.contextOverflow === true;
-			const timeoutRecovery = projectTimeoutRecovery(child.timeoutRecovery);
-			return [{
-				...(agent ? { agent } : {}),
-				...(childRunId ? { runId: childRunId } : {}),
-				...(usage ? { usage } : {}),
-				...(sessionFile ? { sessionFile } : {}),
-				...(typeof child.success === "boolean" ? { success: child.success } : {}),
-				...(outputState ? { outputState } : {}),
-				...(structuredOutput !== undefined ? { structuredOutput } : {}),
-				...(structuredOutputPath ? { structuredOutputPath } : {}),
-				...(error ? { error } : {}),
-				...(model ? { model } : {}),
-				...(contextOverflow ? { contextOverflow: true } : {}),
-				...(artifactPaths ? { artifactPaths } : {}),
-				...(timeoutRecovery ? { timeoutRecovery } : {}),
-			}];
-		})
-		: undefined;
-	const agent = asNonEmptyString(data.agent);
-	const receipt = data.workflowReceipt;
-	const workflowReceiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
-		? asNonEmptyString((receipt as Record<string, unknown>).path) : undefined;
-	const mode = asNonEmptyString(data.mode);
-	const state = asNonEmptyString(data.state);
-	const workflowChildren = parseWorkflowChildSummary(data.workflowChildren);
-	if (workflowChildren && workflowChildren.workflowRunId !== runId) throw new Error("workflowChildren.workflowRunId does not match its completion run id.");
-	return {
-		runId,
-		...(agent ? { agent } : {}),
-		...(mode ? { mode } : {}),
-		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
-		...(state ? { state } : {}),
-		...(typeof data.success === "boolean" ? { success: data.success } : {}),
-		...(results && results.length > 0 ? { results } : {}),
-		...(workflowChildren ? { workflowChildren } : {}),
-	};
-}
-
-/**
- * Record a consumed terminal payload for later surfacing by bg_wait, pruning
- * stale entries with the same TTL that dedupes completion notifications. The result
- * file is deleted after durable replay succeeds, so this record is the in-process
- * source once the watcher has consumed it. Payload ownership must be explicit and
- * agree with persistence ownership. Returns whether that replay is durable.
- */
-export function recordWaitCompletion(
-	state: SubagentState,
-	runId: string,
-	data: Record<string, unknown>,
-	now: number,
-	ttlMs: number,
-	persistence?: { resultsDir: string; sessionId: string },
-): boolean {
-	const sessionId = asNonEmptyString(data.sessionId);
-	if (!sessionId || !resultPayloadMatchesSessionRun(data, sessionId, runId)) return false;
-	if (persistence && persistence.sessionId !== sessionId) return false;
-	const store = state.completedResults ??= new Map();
-	for (const [key, entry] of store) {
-		if (now - entry.seenAt > ttlMs) store.delete(key);
-	}
-	let completion = toWaitCompletion(data, runId);
-	if (persistence) {
-		try {
-			completion = writeCompletionReplay({
-				...persistence,
-				runId,
-				completion,
-				data,
-				now,
-				ttlMs,
-			}).completion;
-		} catch (error) {
-			console.error(`Failed to persist completion replay for '${runId}':`, error);
-		}
-	}
-	store.set(runId, { sessionId, seenAt: now, completion });
-	return completion.archivePath !== undefined;
-}
-
-/**
- * Terminal payloads for the runs a wait covered: the watcher's in-memory record
- * first, then the not-yet-consumed result file. Result files are written atomically,
- * so a direct read never observes a torn write; the read is deliberately read-only —
- * the watcher owns notification and cleanup.
- */
-export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string, onReference?: (text: string) => void): WaitCompletion[] | undefined {
-	if (terminal.length === 0) return undefined;
-	const completions: WaitCompletion[] = [];
-	const add = (completion: WaitCompletion, resultPath?: string): void => {
-		completions.push(completion);
-		// Tool details are not model context. Publish the evidence address in content
-		// without copying potentially unbounded reviewer output into every wait.
-		const reference = completion.archivePath ?? resultPath;
-		if (reference) onReference?.(`Result [${completion.runId}]: ${reference}`);
-	};
-	for (const run of terminal) {
-		const recorded = state.completedResults?.get(run.id);
-		if (recorded && recorded.sessionId === run.sessionId) {
-			if (recorded.completion.archivePath) {
-				add(recorded.completion);
-				continue;
-			}
-			try {
-				const candidatePath = waitResultPayloadCandidate(resultsDir, run);
-				if (!readWaitResultPayload(candidatePath, run)) {
-					const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
-					add(replay?.completion ?? recorded.completion);
-					continue;
-				}
-				add(recorded.completion, candidatePath);
-				continue;
-			} catch (error) {
-				if (errorCode(error) !== "ENOENT") throw error;
-			}
-			const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
-			add(replay?.completion ?? recorded.completion);
-			continue;
-		}
-		let candidatePath: string;
-		try {
-			candidatePath = waitResultPayloadCandidate(resultsDir, run);
-		} catch (error) {
-			const publicResultPath = resultFilePath(resultsDir, run.id);
-			throw new Error(`Failed to read subagent result '${publicResultPath}': ${errorMessage(error)}`, {
-				cause: error instanceof Error ? error : undefined,
-			});
-		}
-		try {
-			const payload = readWaitResultPayload(candidatePath, run);
-			if (!payload) {
-				const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
-				if (replay) add(replay.completion);
-				continue;
-			}
-			add(toWaitCompletion(payload, run.id), candidatePath);
-		} catch (error) {
-			if (errorCode(error) !== "ENOENT") {
-				throw new Error(`Failed to read subagent result '${candidatePath}': ${errorMessage(error)}`, {
-					cause: error instanceof Error ? error : undefined,
-				});
-			}
-			// The watcher may have consumed the file between the store check and the
-			// read. Prefer its in-memory record, then the durable replay written before
-			// result cleanup so watcher reloads do not lose completion details.
-			const late = state.completedResults?.get(run.id);
-			if (late && late.sessionId === run.sessionId) {
-				add(late.completion);
-				continue;
-			}
-			try {
-				const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
-				if (replay) add(replay.completion);
-			} catch (replayError) {
-				throw new Error(`Failed to read completion replay for '${run.id}': ${errorMessage(replayError)}`, {
-					cause: replayError instanceof Error ? replayError : undefined,
-				});
-			}
-		}
-	}
-	return completions.length > 0 ? completions : undefined;
-}

package/src/runs/background/wait-config.ts

@@ -1,50 +0,0 @@
-import type { WaitToolConfig } from "../../shared/types.ts";
-
-export const WAIT_TOOL_ENABLED_ENV = "PI_SUBAGENT_WAIT_TOOL_ENABLED";
-export const WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV = "PI_SUBAGENT_WAIT_TOOL_DEFAULT_TIMEOUT_MS";
-
-export interface ResolvedWaitToolConfig {
-	enabled: boolean;
-	defaultTimeoutMs?: number;
-}
-
-const TRUE_VALUES = new Set(["1", "true", "yes", "on", "enabled"]);
-const FALSE_VALUES = new Set(["0", "false", "no", "off", "disabled"]);
-
-function environmentValue(value: string | undefined): boolean | undefined {
-	if (value === undefined) return undefined;
-	const normalized = value.trim().toLowerCase();
-	if (TRUE_VALUES.has(normalized)) return true;
-	if (FALSE_VALUES.has(normalized)) return false;
-	throw new Error(`${WAIT_TOOL_ENABLED_ENV} must be one of true/false, 1/0, yes/no, on/off, or enabled/disabled.`);
-}
-
-function environmentDefaultTimeoutMs(value: string | undefined): number | undefined {
-	if (value === undefined) return undefined;
-	const parsed = Number(value);
-	if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`${WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV} must be a positive integer.`);
-	return parsed;
-}
-
-function configuredValue(config: unknown): { enabled?: boolean; defaultTimeoutMs?: number } {
-	if (config === undefined) return {};
-	if (typeof config === "boolean") return { enabled: config };
-	if (!config || typeof config !== "object" || Array.isArray(config)) {
-		throw new Error("config.waitTool must be a boolean or an object with optional enabled and defaultTimeoutMs values.");
-	}
-	const { enabled, defaultTimeoutMs } = config as { enabled?: unknown; defaultTimeoutMs?: unknown };
-	if (enabled !== undefined && typeof enabled !== "boolean") throw new Error("config.waitTool.enabled must be a boolean.");
-	if (defaultTimeoutMs !== undefined && (!Number.isInteger(defaultTimeoutMs) || (defaultTimeoutMs as number) < 1)) {
-		throw new Error("config.waitTool.defaultTimeoutMs must be a positive integer.");
-	}
-	return { enabled, ...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs: defaultTimeoutMs as number } : {}) };
-}
-
-export function resolveWaitToolConfig(config?: WaitToolConfig, env: Record<string, string | undefined> = process.env): ResolvedWaitToolConfig {
-	const configured = configuredValue(config);
-	const envDefaultTimeoutMs = environmentDefaultTimeoutMs(env[WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV]);
-	return {
-		enabled: environmentValue(env[WAIT_TOOL_ENABLED_ENV]) ?? configured.enabled ?? true,
-		...(envDefaultTimeoutMs ?? configured.defaultTimeoutMs !== undefined ? { defaultTimeoutMs: envDefaultTimeoutMs ?? configured.defaultTimeoutMs } : {}),
-	};
-}