@bastani/atomic 0.9.5-alpha.9 → 0.9.5

package/dist/builtin/subagents/src/runs/background/result-quarantine.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { errorCode, publishFileExclusive, unlinkIfPresent, type ExclusivePublicationFs } from "../../shared/exclusive-file-publication.js";
+
+interface QuarantineFs extends ExclusivePublicationFs {
+	mkdirSync: typeof fs.mkdirSync;
+	existsSync?: typeof fs.existsSync;
+	openSync?: typeof fs.openSync;
+	readSync?: typeof fs.readSync;
+	closeSync?: typeof fs.closeSync;
+}
+
+function hashFile(file: string, fsApi: QuarantineFs): string {
+	const hash = createHash("sha256");
+	const open = fsApi.openSync ?? fs.openSync;
+	const read = fsApi.readSync ?? fs.readSync;
+	const close = fsApi.closeSync ?? fs.closeSync;
+	const handle = open(file, "r");
+	try {
+		const chunk = Buffer.allocUnsafe(64 * 1024);
+		let offset = 0;
+		while (true) {
+			const count = read(handle, chunk, 0, chunk.length, offset);
+			if (count === 0) break;
+			hash.update(chunk.subarray(0, count));
+			offset += count;
+		}
+	} finally {
+		close(handle);
+	}
+	return hash.digest("hex");
+}
+
+function stableClaimId(resultPath: string): string {
+	const parent = path.dirname(resultPath);
+	if (path.basename(path.dirname(parent)) === ".claims") return path.basename(parent);
+	return createHash("sha256").update(path.resolve(resultPath)).digest("hex").slice(0, 16);
+}
+
+/** Retain one exact claimed result without overwriting or duplicating prior evidence. */
+export function quarantineResultFile(
+	resultsDir: string,
+	file: string,
+	resultPath: string,
+	fsApi: QuarantineFs = fs,
+	createId: () => string = randomUUID,
+): string {
+	const quarantineDir = path.join(resultsDir, ".undelivered");
+	fsApi.mkdirSync(quarantineDir, { recursive: true });
+	const stem = path.basename(file, path.extname(file)).replace(/[^a-zA-Z0-9._-]/g, "_");
+	const contentHash = hashFile(resultPath, fsApi);
+	const claimId = stableClaimId(resultPath);
+	for (let attempt = 0; attempt < 16; attempt += 1) {
+		const suffix = attempt === 0 ? claimId : createId();
+		const destination = path.join(quarantineDir, `${stem}-${suffix}-${contentHash.slice(0, 20)}.json`);
+		const publication = publishFileExclusive(resultPath, destination, fsApi);
+		if (publication === "exists") {
+			try {
+				if (hashFile(destination, fsApi) !== contentHash) continue;
+			} catch (error) {
+				if (errorCode(error) === "ENOENT") continue;
+				throw error;
+			}
+		}
+		// If cleanup fails, the deterministic destination remains authoritative.
+		// A retry recognizes it and retries only this unlink instead of copying again.
+		unlinkIfPresent(resultPath, fsApi);
+		return destination;
+	}
+	throw new Error(`Unable to allocate a collision-free quarantine path for '${resultPath}'`);
+}

package/dist/builtin/subagents/src/runs/background/result-retry-scheduler.ts

@@ -0,0 +1,48 @@
+export interface RetrySchedulerTimers {
+	setTimeout: typeof setTimeout;
+	clearTimeout: typeof clearTimeout;
+}
+
+export interface RetryScheduler {
+	has(key: string): boolean;
+	attempt(key: string): number;
+	schedule(key: string, callback: () => void): boolean;
+	clear(key: string): void;
+	clearAll(): void;
+}
+
+export function createRetryScheduler(
+	timers: RetrySchedulerTimers,
+	baseDelayMs: number,
+	maxDelayMs: number,
+): RetryScheduler {
+	const pending = new Map<string, ReturnType<typeof setTimeout>>();
+	const attempts = new Map<string, number>();
+	const clear = (key: string) => {
+		const timer = pending.get(key);
+		if (timer) timers.clearTimeout(timer);
+		pending.delete(key);
+		attempts.delete(key);
+	};
+	return {
+		has: (key) => pending.has(key),
+		attempt: (key) => attempts.get(key) ?? 0,
+		schedule(key, callback) {
+			if (pending.has(key)) return false;
+			const attempt = (attempts.get(key) ?? 0) + 1;
+			attempts.set(key, attempt);
+			const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.min(attempt - 1, 30));
+			const timer = timers.setTimeout(() => {
+				pending.delete(key);
+				callback();
+			}, delay);
+			timer.unref?.();
+			pending.set(key, timer);
+			return true;
+		},
+		clear,
+		clearAll() {
+			for (const key of [...pending.keys()]) clear(key);
+		},
+	};
+}

package/dist/builtin/subagents/src/runs/background/result-status.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ASYNC_DIR } from "../../shared/types.js";
+import { NESTED_RUNS_DIR } from "../shared/nested-events.js";
+import type { ResultFileData } from "./result-watcher-data.js";
+
+const TERMINAL_ASYNC_STATES = new Set(["complete", "failed", "paused"]);
+export const DEFAULT_MAX_STATUS_BYTES = 1024 * 1024;
+
+export interface ResultStatusFs {
+	realpathSync: typeof fs.realpathSync;
+	lstatSync: typeof fs.lstatSync;
+	openSync: typeof fs.openSync;
+	fstatSync: typeof fs.fstatSync;
+	readSync: typeof fs.readSync;
+	closeSync: typeof fs.closeSync;
+}
+
+export interface ResultStatusOptions {
+	allowedRoots?: string[];
+	maxBytes?: number;
+}
+
+function contained(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function canonicalRoots(fsApi: ResultStatusFs, roots: string[]): string[] {
+	const resolved: string[] = [];
+	for (const root of roots) {
+		try { resolved.push(fsApi.realpathSync(root)); } catch { /* unavailable roots cannot authorize a status path */ }
+	}
+	return resolved;
+}
+
+function readBoundedRegularFile(statusPath: string, fsApi: ResultStatusFs, maxBytes: number): string | undefined {
+	const linkStat = fsApi.lstatSync(statusPath);
+	if (linkStat.isSymbolicLink() || !linkStat.isFile() || linkStat.size > maxBytes) return undefined;
+	const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+	const handle = fsApi.openSync(statusPath, fs.constants.O_RDONLY | noFollow);
+	try {
+		const stat = fsApi.fstatSync(handle);
+		if (!stat.isFile() || stat.size > maxBytes) return undefined;
+		const buffer = Buffer.alloc(stat.size);
+		let offset = 0;
+		while (offset < buffer.length) {
+			const count = fsApi.readSync(handle, buffer, offset, buffer.length - offset, offset);
+			if (count === 0) break;
+			offset += count;
+		}
+		return buffer.subarray(0, offset).toString("utf-8");
+	} finally {
+		fsApi.closeSync(handle);
+	}
+}
+
+export function modernResultHasTerminalStatus(
+	data: ResultFileData,
+	fsApi: ResultStatusFs = fs,
+	options: ResultStatusOptions = {},
+): boolean {
+	if (!Object.prototype.hasOwnProperty.call(data, "asyncDir")) return true;
+	const asyncDir = data.asyncDir?.trim();
+	const resultRunId = data.runId?.trim() || data.id?.trim();
+	if (!asyncDir || !resultRunId) return false;
+	try {
+		const canonicalAsyncDir = fsApi.realpathSync(asyncDir);
+		const roots = canonicalRoots(fsApi, options.allowedRoots ?? [ASYNC_DIR, NESTED_RUNS_DIR]);
+		if (!roots.some((root) => contained(root, canonicalAsyncDir))) return false;
+		const statusPath = path.join(canonicalAsyncDir, "status.json");
+		const content = readBoundedRegularFile(statusPath, fsApi, options.maxBytes ?? DEFAULT_MAX_STATUS_BYTES);
+		if (content === undefined) return false;
+		const status = JSON.parse(content) as { state?: string; runId?: string };
+		return status.runId?.trim() === resultRunId
+			&& typeof status.state === "string"
+			&& TERMINAL_ASYNC_STATES.has(status.state);
+	} catch {
+		return false;
+	}
+}

package/dist/builtin/subagents/src/runs/background/result-watcher-data.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import type { NestedRunSummary } from "../../shared/types.js";
+import { sanitizeSummary } from "../shared/nested-events.js";
+
+export interface ResultFileChild {
+	agent?: string;
+	output?: string;
+	error?: string;
+	success?: boolean;
+	sessionFile?: string;
+	artifactPaths?: { outputPath?: string };
+	intercomTarget?: string;
+	children?: unknown;
+}
+
+export interface ResultFileData {
+	id?: string;
+	runId?: string;
+	agent?: string;
+	success?: boolean;
+	state?: string;
+	mode?: string;
+	summary?: string;
+	results?: ResultFileChild[];
+	nestedChildren?: unknown;
+	sessionId?: string;
+	cwd?: string;
+	sessionFile?: string;
+	asyncDir?: string;
+	intercomTarget?: string;
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || value === undefined || typeof value !== "object") {
+		const serialized = JSON.stringify(value);
+		return serialized === undefined ? "undefined" : serialized;
+	}
+	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+	const object = value as Record<string, unknown>;
+	return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
+
+/** Stable identity for every value exposed through local or Intercom completion delivery. */
+export function buildCompletionSignature(delivery: Record<string, unknown>): string {
+	return createHash("sha256").update(stableStringify(delivery)).digest("hex");
+}
+
+export function sanitizeNestedResultChildren(value: unknown, resultPath: string, label: string): NestedRunSummary[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) {
+		console.error(`Ignoring invalid nested children in subagent result file '${resultPath}' at ${label}: expected an array.`);
+		return undefined;
+	}
+	const children = value.map((child) => sanitizeSummary(child)).filter((child): child is NestedRunSummary => Boolean(child));
+	if (children.length !== value.length) {
+		console.error(`Ignoring ${value.length - children.length} invalid nested child record(s) in subagent result file '${resultPath}' at ${label}.`);
+	}
+	return children.length ? children : undefined;
+}