pi-subagents 0.50.0 → 0.52.0

package/src/runs/background/result-files.ts

@@ -2,14 +2,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { MISSION_BINDING_FILE } from "../../missions/lifecycle.ts";
+import { encodeIndexSegment, indexSegmentAliases, MAX_INDEX_SEGMENT_BYTES } from "./index-segment.ts";
 
 const RESULT_INDEX_VERSION = 1;
 const RESULT_INDEX_DIR = "result-index";
 const SESSION_INDEX_DIR = "sessions";
+const RUN_INDEX_DIR = "runs";
 const OBSERVER_INDEX_DIR = "observers";
 const TOOL_CALL_INDEX_DIR = "tool-calls";
 const RESULT_PENDING_DIR = "result-pending";
 const MISSION_OBSERVER = "mission";
+const JSON_EXTENSION = ".json";
+const MAX_JSON_FILE_STEM_BYTES = MAX_INDEX_SEGMENT_BYTES - Buffer.byteLength(JSON_EXTENSION, "utf-8");
 
 export interface ResultIndexEntry {
 	version: 1;
@@ -21,7 +25,15 @@ export interface ResultIndexEntry {
 }
 
 function encodeSegment(value: string): string {
-	return encodeURIComponent(value);
+	return encodeIndexSegment(value);
+}
+
+function encodedJsonFileName(value: string): string {
+	return `${encodeIndexSegment(value, MAX_JSON_FILE_STEM_BYTES)}${JSON_EXTENSION}`;
+}
+
+function encodedJsonFileNames(value: string): string[] {
+	return indexSegmentAliases(value, MAX_JSON_FILE_STEM_BYTES).map((segment) => `${segment}${JSON_EXTENSION}`);
 }
 
 function nonEmptyString(value: unknown): string | undefined {
@@ -29,7 +41,7 @@ function nonEmptyString(value: unknown): string | undefined {
 }
 
 export function resultFileName(runId: string): string {
-	return `${runId}.json`;
+	return `${runId}${JSON_EXTENSION}`;
 }
 
 export function resultFilePath(resultsDir: string, runId: string): string {
@@ -40,12 +52,39 @@ function sessionIndexDir(resultsDir: string, sessionId: string): string {
 	return path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR, encodeSegment(sessionId));
 }
 
+function sessionIndexDirs(resultsDir: string, sessionId: string): string[] {
+	return indexSegmentAliases(sessionId).map((segment) => path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR, segment));
+}
+
 function resultIndexPath(resultsDir: string, sessionId: string, runId: string): string {
-	return path.join(sessionIndexDir(resultsDir, sessionId), `${encodeSegment(runId)}.json`);
+	return path.join(sessionIndexDir(resultsDir, sessionId), encodedJsonFileName(runId));
+}
+
+function resultIndexPaths(resultsDir: string, sessionId: string, runId: string): string[] {
+	return sessionIndexDirs(resultsDir, sessionId).flatMap((dir) => encodedJsonFileNames(runId).map((fileName) => path.join(dir, fileName)));
+}
+
+function runIndexPath(resultsDir: string, runId: string): string {
+	return path.join(resultsDir, RESULT_INDEX_DIR, RUN_INDEX_DIR, encodedJsonFileName(runId));
 }
 
 function resultPendingPath(resultsDir: string, sessionId: string, runId: string): string {
-	return path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId), `${encodeSegment(runId)}.json`);
+	return path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId), encodedJsonFileName(runId));
+}
+
+function resultPendingPaths(resultsDir: string, sessionId: string, runId: string): string[] {
+	return indexSegmentAliases(sessionId).flatMap((segment) => encodedJsonFileNames(runId).map((fileName) => path.join(resultsDir, RESULT_PENDING_DIR, segment, fileName)));
+}
+
+function pendingSessionDirs(resultsDir: string, sessionId: string): string[] {
+	return indexSegmentAliases(sessionId).map((segment) => path.join(resultsDir, RESULT_PENDING_DIR, segment));
+}
+
+function firstExistingResultFile(paths: string[]): string | undefined {
+	for (const filePath of paths) {
+		if (existingResultFile(filePath)) return filePath;
+	}
+	return undefined;
 }
 
 function observerIndexDir(resultsDir: string, observer: string): string {
@@ -53,15 +92,15 @@ function observerIndexDir(resultsDir: string, observer: string): string {
 }
 
 function observerIndexPath(resultsDir: string, observer: string, runId: string): string {
-	return path.join(observerIndexDir(resultsDir, observer), `${encodeSegment(runId)}.json`);
+	return path.join(observerIndexDir(resultsDir, observer), encodedJsonFileName(runId));
 }
 
 function toolCallIndexDir(resultsDir: string, toolCallId: string): string {
-	return path.join(resultsDir, RESULT_INDEX_DIR, TOOL_CALL_INDEX_DIR, encodeSegment(toolCallId));
+	return path.join(resultsDir, RESULT_INDEX_DIR, TOOL_CALL_INDEX_DIR, encodeIndexSegment(toolCallId));
 }
 
 function toolCallIndexPath(resultsDir: string, toolCallId: string, runId: string): string {
-	return path.join(toolCallIndexDir(resultsDir, toolCallId), `${encodeSegment(runId)}.json`);
+	return path.join(toolCallIndexDir(resultsDir, toolCallId), encodedJsonFileName(runId));
 }
 
 function parseResultIndexEntry(value: unknown): ResultIndexEntry | undefined {
@@ -97,6 +136,11 @@ export function writeResultIndexForData(resultPath: string, data: Record<string,
 	};
 	const resultsDir = path.dirname(resultPath);
 	writeAtomicJson(resultIndexPath(resultsDir, sessionId, runId), entry);
+	try {
+		writeAtomicJson(runIndexPath(resultsDir, runId), entry);
+	} catch (error) {
+		console.error(`Failed to write async result run index for '${resultPath}':`, error);
+	}
 	const toolCallId = nonEmptyString(data.toolCallId);
 	try {
 		if (toolCallId) writeAtomicJson(toolCallIndexPath(resultsDir, toolCallId, runId), entry);
@@ -136,17 +180,26 @@ export function writeAsyncResultFile(resultPath: string, data: Record<string, un
 export function removeResultIndex(resultsDir: string, sessionId: string | undefined, runId: string | undefined, toolCallId?: string): void {
 	if (!runId) return;
 	if (sessionId) {
-		try {
-			fs.rmSync(resultIndexPath(resultsDir, sessionId, runId), { force: true });
-		} catch {
-			// Index cleanup must not affect result delivery.
+		for (const indexPath of resultIndexPaths(resultsDir, sessionId, runId)) {
+			try {
+				fs.rmSync(indexPath, { force: true });
+			} catch {
+				// Index cleanup must not affect result delivery.
+			}
 		}
-		try {
-			fs.rmSync(resultPendingPath(resultsDir, sessionId, runId), { force: true });
-		} catch {
-			// Pending cleanup must not affect result delivery.
+		for (const pendingPath of resultPendingPaths(resultsDir, sessionId, runId)) {
+			try {
+				fs.rmSync(pendingPath, { force: true });
+			} catch {
+				// Pending cleanup must not affect result delivery.
+			}
 		}
 	}
+	try {
+		fs.rmSync(runIndexPath(resultsDir, runId), { force: true });
+	} catch {
+		// Index cleanup must not affect result delivery.
+	}
 	if (toolCallId) {
 		try {
 			fs.rmSync(toolCallIndexPath(resultsDir, toolCallId, runId), { force: true });
@@ -180,7 +233,7 @@ function existingResultFile(resultPath: string): boolean {
 }
 
 function pendingResultExists(resultsDir: string, sessionId: string, runId: string): boolean {
-	return existingResultFile(resultPendingPath(resultsDir, sessionId, runId));
+	return firstExistingResultFile(resultPendingPaths(resultsDir, sessionId, runId)) !== undefined;
 }
 
 function pendingResultPayloadMatches(filePath: string, sessionId: string, runId: string): boolean {
@@ -193,16 +246,34 @@ function pendingResultPayloadMatches(filePath: string, sessionId: string, runId:
 	}
 }
 
+function assertPendingResultPayloadMatches(filePath: string, sessionId: string, runId: string): boolean {
+	const data = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>;
+	return (nonEmptyString(data.runId) ?? nonEmptyString(data.id)) === runId && nonEmptyString(data.sessionId) === sessionId;
+}
+
 export function promotePendingResultFile(resultsDir: string, sessionId: string, runId: string, file = resultFileName(runId), options: { logFailure?: boolean } = {}): "none" | "promoted" | "pending" {
 	if (file !== path.basename(file) || !file.endsWith(".json")) return "none";
-	const pendingPath = resultPendingPath(resultsDir, sessionId, runId);
-	if (!existingResultFile(pendingPath)) return "none";
+	const pendingPath = firstExistingResultFile(resultPendingPaths(resultsDir, sessionId, runId));
+	if (!pendingPath) return "none";
 	const resultPath = path.join(resultsDir, file);
 	try {
-		fs.rmSync(resultPath, { force: true });
+		// POSIX rename replaces the destination atomically. Deleting it first lets a
+		// losing promoter unlink the result that another promoter just published.
 		fs.renameSync(pendingPath, resultPath);
 		return existingResultFile(resultPath) ? "promoted" : "pending";
 	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "EEXIST" || code === "EPERM" || code === "EACCES") {
+			const pendingExists = existingResultFile(pendingPath);
+			const resultExists = existingResultFile(resultPath);
+			if (pendingExists) {
+				if (!resultExists && options.logFailure !== false) console.error(`Failed to promote pending async result '${pendingPath}' to '${resultPath}':`, error);
+				return "pending";
+			}
+			if (resultExists) return "promoted";
+			if (options.logFailure !== false) console.error(`Pending async result '${pendingPath}' disappeared without a promoted result at '${resultPath}'.`);
+			return "none";
+		}
 		if (options.logFailure !== false) console.error(`Failed to promote pending async result '${pendingPath}' to '${resultPath}':`, error);
 		return "pending";
 	}
@@ -216,33 +287,15 @@ interface ResultPayloadLocation {
 
 function pendingResultLocationForSessionRun(resultsDir: string, sessionId: string, runId: string, file = resultFileName(runId)): ResultPayloadLocation | undefined {
 	if (file !== path.basename(file) || !file.endsWith(".json")) return undefined;
-	const pendingPath = resultPendingPath(resultsDir, sessionId, runId);
-	return existingResultFile(pendingPath) && pendingResultPayloadMatches(pendingPath, sessionId, runId)
-		? { file, path: pendingPath, state: "pending" }
-		: undefined;
+	const pendingPath = firstExistingResultFile(resultPendingPaths(resultsDir, sessionId, runId));
+	if (!pendingPath || !pendingResultPayloadMatches(pendingPath, sessionId, runId)) return undefined;
+	return { file, path: pendingPath, state: "pending" };
 }
 
-function pendingResultLocationForIndexedRun(resultsDir: string, runId: string): ResultPayloadLocation | undefined {
-	const root = path.join(resultsDir, RESULT_PENDING_DIR);
-	let sessions: fs.Dirent[];
-	try {
-		sessions = fs.readdirSync(root, { withFileTypes: true });
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Failed to inspect pending async result root '${root}':`, error);
-		return undefined;
-	}
-	for (const session of sessions) {
-		if (!session.isDirectory()) continue;
-		let sessionId: string;
-		try {
-			sessionId = decodeURIComponent(session.name);
-		} catch {
-			continue;
-		}
-		const location = pendingResultLocationForSessionRun(resultsDir, sessionId, runId);
-		if (location) return location;
-	}
-	return undefined;
+export function fallbackResultPayloadPathForSessionRun(resultsDir: string, sessionId: string, runId: string): string | undefined {
+	const pendingPath = firstExistingResultFile(resultPendingPaths(resultsDir, sessionId, runId));
+	if (!pendingPath || !assertPendingResultPayloadMatches(pendingPath, sessionId, runId)) return undefined;
+	return pendingPath;
 }
 
 function resultPayloadLocationFromIndex(resultsDir: string, entry: ResultIndexEntry): ResultPayloadLocation | undefined {
@@ -257,15 +310,20 @@ function resultPayloadLocationFromIndex(resultsDir: string, entry: ResultIndexEn
 }
 
 function readResultIndexForSessionRun(resultsDir: string, sessionId: string, runId: string): ResultIndexEntry | undefined {
-	try {
-		const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(resultIndexPath(resultsDir, sessionId, runId), "utf-8")));
-		if (!entry || entry.sessionId !== sessionId || entry.runId !== runId) return undefined;
-		return entry;
-	} catch (error) {
-		const code = (error as NodeJS.ErrnoException).code;
-		if (code !== "ENOENT" && code !== "ENOTDIR") console.error(`Ignoring invalid async result index for '${runId}':`, error);
-		return undefined;
+	for (const indexPath of resultIndexPaths(resultsDir, sessionId, runId)) {
+		try {
+			const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(indexPath, "utf-8")));
+			if (!entry || entry.sessionId !== sessionId || entry.runId !== runId) continue;
+			return entry;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "EPERM" || code === "EACCES") throw error;
+			if (code !== "ENOENT" && code !== "ENOTDIR") {
+				console.error(`Ignoring invalid async result index for '${runId}':`, error);
+			}
+		}
 	}
+	return undefined;
 }
 
 export function resultPayloadPathForSessionRun(resultsDir: string, sessionId: string, runId: string): string | undefined {
@@ -286,27 +344,24 @@ export function resultPayloadPathForMissionObserverRun(resultsDir: string, runId
 }
 
 export function resultPayloadPathForIndexedRun(resultsDir: string, runId: string): string | undefined {
-	const root = path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR);
-	let sessions: fs.Dirent[] = [];
+	const entryPath = runIndexPath(resultsDir, runId);
 	try {
-		sessions = fs.readdirSync(root, { withFileTypes: true });
+		const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(entryPath, "utf-8")));
+		if (!entry || entry.runId !== runId) {
+			fs.rmSync(entryPath, { force: true });
+			return undefined;
+		}
+		const location = resultPayloadLocationFromIndex(resultsDir, entry);
+		if (location) return location.path;
+		fs.rmSync(entryPath, { force: true });
 	} catch (error) {
 		const code = (error as NodeJS.ErrnoException).code;
-		if (code !== "ENOENT" && code !== "ENOTDIR") console.error(`Failed to inspect async result session index root '${root}':`, error);
-	}
-	for (const session of sessions) {
-		if (!session.isDirectory()) continue;
-		const entryPath = path.join(root, session.name, `${encodeSegment(runId)}.json`);
-		try {
-			const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(entryPath, "utf-8")));
-			if (!entry || entry.runId !== runId) continue;
-			const location = resultPayloadLocationFromIndex(resultsDir, entry);
-			if (location) return location.path;
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid async result index '${entryPath}':`, error);
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			console.error(`Ignoring invalid async result run index '${entryPath}':`, error);
+			try { fs.rmSync(entryPath, { force: true }); } catch {}
 		}
 	}
-	return pendingResultLocationForIndexedRun(resultsDir, runId)?.path;
+	return undefined;
 }
 
 function indexedResultFile(resultsDir: string, entry: ResultIndexEntry, includePending = false): string | undefined {
@@ -323,7 +378,7 @@ function listIndexFiles(dir: string): string[] {
 			.map((entry) => path.join(dir, entry.name));
 	} catch (error) {
 		const code = (error as NodeJS.ErrnoException).code;
-		if (code === "ENOENT" || code === "ENOTDIR") return [];
+		if (code === "ENOENT" || code === "ENOTDIR" || code === "EPERM" || code === "EACCES") return [];
 		throw error;
 	}
 	return files;
@@ -348,44 +403,56 @@ function resultFilesFromIndexDir(resultsDir: string, dir: string, includePending
 }
 
 export function resultFilesForSession(resultsDir: string, sessionId: string): string[] {
-	return resultFilesFromIndexDir(resultsDir, sessionIndexDir(resultsDir, sessionId));
+	const files = new Set<string>();
+	for (const dir of sessionIndexDirs(resultsDir, sessionId)) {
+		for (const file of resultFilesFromIndexDir(resultsDir, dir)) files.add(file);
+	}
+	return [...files];
 }
 
 function pendingResultFilesForSession(resultsDir: string, sessionId: string): string[] {
-	const dir = path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId));
-	let entries: fs.Dirent[];
-	try {
-		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-		throw error;
-	}
 	const files = new Set<string>();
-	for (const entry of entries) {
-		if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
-		const pendingPath = path.join(dir, entry.name);
+	for (const dir of pendingSessionDirs(resultsDir, sessionId)) {
+		let entries: fs.Dirent[];
 		try {
-			const data = JSON.parse(fs.readFileSync(pendingPath, "utf-8")) as Record<string, unknown>;
-			const runId = nonEmptyString(data.runId) ?? nonEmptyString(data.id);
-			if (runId && nonEmptyString(data.sessionId) === sessionId) files.add(resultFileName(runId));
+			entries = fs.readdirSync(dir, { withFileTypes: true });
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid pending async result '${pendingPath}':`, error);
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || code === "ENOTDIR" || code === "EPERM" || code === "EACCES") continue;
+			throw error;
+		}
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+			const pendingPath = path.join(dir, entry.name);
+			try {
+				const data = JSON.parse(fs.readFileSync(pendingPath, "utf-8")) as Record<string, unknown>;
+				const runId = nonEmptyString(data.runId) ?? nonEmptyString(data.id);
+				if (runId && nonEmptyString(data.sessionId) === sessionId) files.add(resultFileName(runId));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid pending async result '${pendingPath}':`, error);
+			}
 		}
 	}
 	return [...files];
 }
 
 export function resultCandidateFilesForSession(resultsDir: string, sessionId: string): string[] {
-	return [...new Set([
-		...resultFilesFromIndexDir(resultsDir, sessionIndexDir(resultsDir, sessionId), true),
-		...pendingResultFilesForSession(resultsDir, sessionId),
-	])];
+	const files = new Set<string>();
+	for (const dir of sessionIndexDirs(resultsDir, sessionId)) {
+		for (const file of resultFilesFromIndexDir(resultsDir, dir, true)) files.add(file);
+	}
+	for (const file of pendingResultFilesForSession(resultsDir, sessionId)) files.add(file);
+	return [...files];
 }
 
 export function resultFilesForToolCall(resultsDir: string, toolCallId: string): string[] {
 	return resultFilesFromIndexDir(resultsDir, toolCallIndexDir(resultsDir, toolCallId));
 }
 
+export function resultCandidateFilesForToolCall(resultsDir: string, toolCallId: string): string[] {
+	return resultFilesFromIndexDir(resultsDir, toolCallIndexDir(resultsDir, toolCallId), true);
+}
+
 export function missionObserverResultFiles(resultsDir: string): string[] {
 	return resultFilesFromIndexDir(resultsDir, observerIndexDir(resultsDir, MISSION_OBSERVER));
 }
@@ -403,7 +470,8 @@ export function cleanupResultIndexes(resultsDir: string, now = Date.now(), maxAg
 		try {
 			entries = fs.readdirSync(dir, { withFileTypes: true });
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || code === "ENOTDIR" || code === "EPERM" || code === "EACCES") return;
 			throw error;
 		}
 		for (const entry of entries) {