@bastani/atomic 0.9.5-alpha.8 → 0.9.5

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

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import type { GroupedResultIntercomMessageInput } from "../../intercom/result-intercom.js";
+import type { ResultFileData } from "./result-watcher-data.js";
+
+const CLAIMS_DIR = ".claims";
+const CLAIM_SCHEDULE_PREFIX = "@claim/";
+
+export interface FrozenCompletionEnvelope {
+	local: Record<string, unknown>;
+	intercom?: GroupedResultIntercomMessageInput;
+}
+export interface ResultFileClaimMeta {
+	version: 1;
+	id: string;
+	originalFile: string;
+	state: "active" | "delivered" | "undelivered";
+	createdAt: number;
+	sourceSignature?: string;
+	envelope?: FrozenCompletionEnvelope;
+	intercomDelivered?: boolean;
+	localDelivered?: boolean;
+	noProgressFailures?: number;
+}
+
+export interface ResultFileClaim {
+	id: string;
+	dir: string;
+	payloadPath: string;
+	metaPath: string;
+	meta: ResultFileClaimMeta;
+}
+
+export interface ResultClaimFs {
+	mkdirSync?: typeof fs.mkdirSync;
+	renameSync?: typeof fs.renameSync;
+	readFileSync?: typeof fs.readFileSync;
+	writeFileSync?: typeof fs.writeFileSync;
+	readdirSync?: typeof fs.readdirSync;
+	rmSync?: typeof fs.rmSync;
+	rmdirSync?: typeof fs.rmdirSync;
+}
+
+function api(fsApi: ResultClaimFs) {
+	return {
+		mkdirSync: fsApi.mkdirSync ?? fs.mkdirSync,
+		renameSync: fsApi.renameSync ?? fs.renameSync,
+		readFileSync: fsApi.readFileSync ?? fs.readFileSync,
+		writeFileSync: fsApi.writeFileSync ?? fs.writeFileSync,
+		rmSync: fsApi.rmSync ?? fs.rmSync,
+		rmdirSync: fsApi.rmdirSync ?? fs.rmdirSync,
+	};
+}
+
+export function claimScheduleKey(id: string): string {
+	return `${CLAIM_SCHEDULE_PREFIX}${id}`;
+}
+
+export function claimIdFromScheduleKey(key: string): string | undefined {
+	return key.startsWith(CLAIM_SCHEDULE_PREFIX) ? key.slice(CLAIM_SCHEDULE_PREFIX.length) : undefined;
+}
+
+export function loadResultClaim(resultsDir: string, id: string, fsApi: ResultClaimFs = fs): ResultFileClaim | undefined {
+	try {
+		const dir = path.join(resultsDir, CLAIMS_DIR, id);
+		const metaPath = path.join(dir, "claim.json");
+		const payloadPath = path.join(dir, "result.json");
+		const meta = JSON.parse((fsApi.readFileSync ?? fs.readFileSync)(metaPath, "utf-8")) as ResultFileClaimMeta;
+		if (meta.version !== 1 || meta.id !== id || !path.basename(meta.originalFile)) return undefined;
+		return { id, dir, payloadPath, metaPath, meta };
+	} catch {
+		return undefined;
+	}
+}
+
+export function listResultClaims(resultsDir: string, fsApi: ResultClaimFs = fs): ResultFileClaim[] {
+	const claimsDir = path.join(resultsDir, CLAIMS_DIR);
+	try {
+		return (fsApi.readdirSync ?? fs.readdirSync)(claimsDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => loadResultClaim(resultsDir, entry.name, fsApi))
+			.filter((claim): claim is ResultFileClaim => Boolean(claim));
+	} catch {
+		return [];
+	}
+}
+
+export function claimPublicResult(
+	resultsDir: string,
+	file: string,
+	fsApi: ResultClaimFs = fs,
+	createId: () => string = randomUUID,
+): ResultFileClaim {
+	const f = api(fsApi);
+	const claimsDir = path.join(resultsDir, CLAIMS_DIR);
+	f.mkdirSync(claimsDir, { recursive: true });
+	for (let attempt = 0; attempt < 16; attempt += 1) {
+		const id = createId();
+		const dir = path.join(claimsDir, id);
+		try {
+			f.mkdirSync(dir);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+			throw error;
+		}
+		const metaPath = path.join(dir, "claim.json");
+		const payloadPath = path.join(dir, "result.json");
+		const meta: ResultFileClaimMeta = {
+			version: 1, id, originalFile: path.basename(file), state: "active", createdAt: Date.now(),
+		};
+		try {
+			f.writeFileSync(metaPath, `${JSON.stringify(meta)}\n`, "utf-8");
+			f.renameSync(path.join(resultsDir, file), payloadPath);
+			return { id, dir, payloadPath, metaPath, meta };
+		} catch (error) {
+			f.rmSync(dir, { recursive: true, force: true });
+			throw error;
+		}
+	}
+	throw new Error(`Unable to allocate a result claim for '${file}'`);
+}
+
+export function readClaimData(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): { raw: string; data: ResultFileData } {
+	const raw = (fsApi.readFileSync ?? fs.readFileSync)(claim.payloadPath, "utf-8");
+	return { raw, data: JSON.parse(raw) as ResultFileData };
+}
+
+export function updateResultClaim(
+	claim: ResultFileClaim,
+	patch: Partial<Omit<ResultFileClaimMeta, "version" | "id" | "originalFile" | "createdAt">>,
+	fsApi: ResultClaimFs = fs,
+): void {
+	const f = api(fsApi);
+	claim.meta = { ...claim.meta, ...patch };
+	const temporary = path.join(claim.dir, `.claim-${randomUUID()}.tmp`);
+	f.writeFileSync(temporary, `${JSON.stringify(claim.meta)}\n`, "utf-8");
+	f.renameSync(temporary, claim.metaPath);
+}
+
+export function removeResultClaim(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): void {
+	const f = api(fsApi);
+	f.rmSync(claim.dir, { recursive: true, force: true });
+	try { f.rmdirSync(path.dirname(claim.dir)); } catch { /* another active claim keeps the shared directory */ }
+}
+
+export function recoverTerminalClaim(claim: ResultFileClaim, fsApi: ResultClaimFs = fs): "active" | "removed" {
+	if (claim.meta.state === "active") return "active";
+	removeResultClaim(claim, fsApi);
+	return "removed";
+}

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;
+}