@bastani/atomic 0.9.16-alpha.1 → 0.9.16-alpha.3

package/dist/builtin/subagents/src/shared/artifacts.ts

@@ -1,240 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getAgentConfigPaths } from "@bastani/atomic";
-import { appendToActiveEventWriter } from "./event-jsonl-writer.js";
-import { publishFileExclusive, unlinkIfPresent } from "./exclusive-file-publication.js";
-import { type ArtifactPaths, TEMP_ARTIFACTS_DIR } from "./types.js";
-
-const CLEANUP_MARKER_FILE = ".last-cleanup";
-const CLEANUP_LOCK_FILE = ".cleanup.lock";
-const CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const CLEANUP_LOCK_STALE_MS = 60 * 60 * 1000;
-
-export function getArtifactsDir(sessionFile: string | null): string {
-	if (sessionFile) {
-		const sessionDir = path.dirname(sessionFile);
-		return path.join(sessionDir, "subagent-artifacts");
-	}
-	return TEMP_ARTIFACTS_DIR;
-}
-
-export function getArtifactPaths(artifactsDir: string, runId: string, agent: string, index?: number): ArtifactPaths {
-	const suffix = index !== undefined ? `_${index}` : "";
-	const safeAgent = agent.replace(/[^\w.-]/g, "_");
-	const base = `${runId}_${safeAgent}${suffix}`;
-	return {
-		inputPath: path.join(artifactsDir, `${base}_input.md`),
-		outputPath: path.join(artifactsDir, `${base}_output.md`),
-		jsonlPath: path.join(artifactsDir, `${base}.jsonl`),
-		metadataPath: path.join(artifactsDir, `${base}_meta.json`),
-	};
-}
-
-export function ensureArtifactsDir(dir: string): void {
-	fs.mkdirSync(dir, { recursive: true });
-}
-
-export function writeArtifact(filePath: string, content: string): void {
-	fs.writeFileSync(filePath, content, "utf-8");
-}
-
-export function writeMetadata(filePath: string, metadata: object): void {
-	fs.writeFileSync(filePath, JSON.stringify(metadata, null, 2), "utf-8");
-}
-
-export function appendJsonl(filePath: string, line: string): void {
-	if (!appendToActiveEventWriter(filePath, line)) fs.appendFileSync(filePath, `${line}\n`);
-}
-
-function cleanupOldArtifactEntry(entryPath: string, cutoff: number): void {
-	try {
-		const stat = fs.lstatSync(entryPath);
-		if (stat.isDirectory()) {
-			for (const child of fs.readdirSync(entryPath)) {
-				cleanupOldArtifactEntry(path.join(entryPath, child), cutoff);
-			}
-			if (fs.readdirSync(entryPath).length === 0 && stat.mtimeMs < cutoff) {
-				fs.rmSync(entryPath, { recursive: true, force: true });
-			}
-			return;
-		}
-		if (stat.mtimeMs < cutoff) fs.unlinkSync(entryPath);
-	} catch {
-		// Artifact cleanup is best-effort housekeeping. Skip entries that disappear
-		// or become unreadable while scanning so one bad entry does not block the rest.
-	}
-}
-
-export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
-	if (!fs.existsSync(dir)) return;
-
-	const markerPath = path.join(dir, CLEANUP_MARKER_FILE);
-	const now = Date.now();
-
-	if (fs.existsSync(markerPath)) {
-		const stat = fs.statSync(markerPath);
-		if (now - stat.mtimeMs < CLEANUP_INTERVAL_MS) return;
-	}
-
-	const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
-	const cutoff = now - maxAgeMs;
-
-	for (const file of fs.readdirSync(dir)) {
-		if (file === CLEANUP_MARKER_FILE) continue;
-		cleanupOldArtifactEntry(path.join(dir, file), cutoff);
-	}
-
-	fs.writeFileSync(markerPath, String(now));
-}
-
-function markerIsFresh(markerPath: string, now: number): boolean {
-	try {
-		return now - fs.statSync(markerPath).mtimeMs < CLEANUP_INTERVAL_MS;
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Take an exclusive lock at lockPath so concurrent activations never race the same
- * sessions-root scan. A lock left behind by a crashed process is broken once stale.
- * Returns an ownership token on success; release only removes a lock that still
- * carries the caller's token, so a holder whose stale lock was taken over cannot
- * erase the new holder's lock.
- */
-function acquireCleanupLock(lockPath: string, now: number): string | null {
-	const token = `${process.pid}.${now}.${Math.random().toString(36).slice(2)}`;
-	const source = `${lockPath}.${token}.tmp`;
-	try {
-		fs.writeFileSync(source, token);
-		for (let attempt = 0; attempt < 2; attempt++) {
-			if (publishFileExclusive(source, lockPath) === "published") return token;
-			let lockMtimeMs: number;
-			try {
-				lockMtimeMs = fs.statSync(lockPath).mtimeMs;
-			} catch {
-				// The holder released between publish and stat; retry once.
-				continue;
-			}
-			if (now - lockMtimeMs < CLEANUP_LOCK_STALE_MS) return null;
-			if (!breakStaleLock(lockPath, lockMtimeMs)) return null;
-		}
-		return null;
-	} catch {
-		return null;
-	} finally {
-		try {
-			unlinkIfPresent(source);
-		} catch {
-			// Lock acquisition is best-effort; a leftover temp source is harmless.
-		}
-	}
-}
-
-/**
- * Atomically claim a stale lock via rename, then verify it is still the lock
- * observed during stale detection. A lock that changed identity in between
- * belongs to a new holder: it is handed back and the takeover is treated as
- * contention instead of deleting the fresh lock.
- */
-function breakStaleLock(lockPath: string, observedMtimeMs: number): boolean {
-	const breakPath = `${lockPath}.break.${process.pid}.${Math.random().toString(36).slice(2)}`;
-	try {
-		fs.renameSync(lockPath, breakPath);
-	} catch {
-		// Another activation released or broke the lock first; contend for publish.
-		return false;
-	}
-	let displacedFreshLock = false;
-	try {
-		displacedFreshLock = fs.statSync(breakPath).mtimeMs !== observedMtimeMs;
-	} catch {
-		displacedFreshLock = false;
-	}
-	try {
-		if (displacedFreshLock) publishFileExclusive(breakPath, lockPath);
-	} catch {
-		// Best-effort hand-back. A holder whose lock could not be restored notices the
-		// loss at its next ownership recheck and aborts its scan.
-	}
-	try {
-		unlinkIfPresent(breakPath);
-	} catch {
-		// A leftover break file is harmless.
-	}
-	return !displacedFreshLock;
-}
-
-function ownsCleanupLock(lockPath: string, token: string): boolean {
-	try {
-		return fs.readFileSync(lockPath, "utf-8") === token;
-	} catch {
-		return false;
-	}
-}
-
-function releaseCleanupLock(lockPath: string, token: string): void {
-	try {
-		if (fs.readFileSync(lockPath, "utf-8") === token) fs.unlinkSync(lockPath);
-	} catch {
-		// Lock release is best-effort; a failure only means the lock goes stale and is
-		// broken by a later scan, and must never abort cleanup of the remaining roots.
-	}
-}
-
-function cleanupSessionsRoot(sessionsBase: string, maxAgeDays: number): void {
-	if (!fs.existsSync(sessionsBase)) return;
-
-	const now = Date.now();
-	const markerPath = path.join(sessionsBase, CLEANUP_MARKER_FILE);
-	if (markerIsFresh(markerPath, now)) return;
-
-	const lockPath = path.join(sessionsBase, CLEANUP_LOCK_FILE);
-	const lockToken = acquireCleanupLock(lockPath, now);
-	if (lockToken === null) return;
-	try {
-		let dirs: string[];
-		try {
-			dirs = fs.readdirSync(sessionsBase);
-		} catch {
-			// Session artifact cleanup is best-effort. If the sessions root cannot be read,
-			// skip cleanup instead of failing extension startup.
-			return;
-		}
-
-		for (const dir of dirs) {
-			if (dir === CLEANUP_MARKER_FILE || dir === CLEANUP_LOCK_FILE) continue;
-			// A holder displaced by a stale-lock takeover that could not be handed its
-			// lock back must not keep deleting alongside the new lock owner; recheck
-			// ownership before every destructive per-session cleanup and abort the
-			// scan as soon as the lock is lost.
-			if (!ownsCleanupLock(lockPath, lockToken)) return;
-			const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
-			try {
-				cleanupOldArtifacts(artifactsDir, maxAgeDays);
-			} catch {
-				// Session cleanup is best-effort. Keep going so one unreadable session dir
-				// does not block cleanup for the rest.
-			}
-		}
-
-		try {
-			if (ownsCleanupLock(lockPath, lockToken)) fs.writeFileSync(markerPath, String(now));
-		} catch {
-			// Failing to record the marker only means the scan may repeat sooner.
-		}
-	} finally {
-		releaseCleanupLock(lockPath, lockToken);
-	}
-}
-
-export function cleanupAllArtifactDirs(maxAgeDays: number, sessionsRoots?: readonly string[]): void {
-	cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
-
-	// Host-provided sessions roots keep isolated/programmatic agent directories from
-	// leaking into the real global (and legacy) session roots; only the env/global
-	// derivation scans those.
-	for (const sessionsBase of sessionsRoots ?? getAgentConfigPaths("sessions")) {
-		cleanupSessionsRoot(sessionsBase, maxAgeDays);
-	}
-}

package/dist/builtin/subagents/src/shared/atomic-json.ts

@@ -1,16 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export function writeAtomicJson(filePath: string, payload: object): void {
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	const tempPath = path.join(
-		path.dirname(filePath),
-		`.${path.basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
-	);
-	try {
-		fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), "utf-8");
-		fs.renameSync(tempPath, filePath);
-	} finally {
-		fs.rmSync(tempPath, { force: true });
-	}
-}

package/dist/builtin/subagents/src/shared/event-jsonl-writer.ts

@@ -1,330 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { DrainableSource, JsonlWriteStream } from "./jsonl-writer.js";
-
-interface TelemetryState {
-	telemetryBytes: number;
-	telemetryTruncated: boolean;
-}
-
-interface SharedEventWriter extends TelemetryState {
-	stream: JsonlWriteStream;
-	sources: Set<DrainableSource>;
-	refs: number;
-	backpressured: boolean;
-	closed: boolean;
-	failed: boolean;
-	filePath: string;
-	key: string;
-	closingLines: string[];
-	settled: Promise<void>;
-	resolveSettled: () => void;
-}
-
-const writers = new Map<string, SharedEventWriter>();
-
-interface TelemetryHydration extends TelemetryState {
-	dev: number;
-	ino: number;
-	size: number;
-	mtimeMs: number;
-	ctimeMs: number;
-}
-
-const hydrationCache = new Map<string, TelemetryHydration>();
-const MAX_HYDRATION_ENTRIES = 512;
-const HYDRATION_CHUNK_BYTES = 64 * 1024;
-const TRUNCATION_MARKER = '"type":"subagent.child.telemetry_truncated"';
-let hydrationScanCount = 0;
-let hydrationScannedBytes = 0;
-
-function keyFor(filePath: string): string {
-	return path.resolve(filePath);
-}
-
-function cacheHydration(key: string, hydration: TelemetryHydration): void {
-	hydrationCache.delete(key);
-	hydrationCache.set(key, hydration);
-	while (hydrationCache.size > MAX_HYDRATION_ENTRIES) {
-		const oldest = hydrationCache.keys().next().value as string | undefined;
-		if (oldest === undefined) break;
-		hydrationCache.delete(oldest);
-	}
-}
-
-function scanForTruncationMarker(filePath: string): boolean {
-	hydrationScanCount += 1;
-	const handle = fs.openSync(filePath, "r");
-	try {
-		const buffer = Buffer.allocUnsafe(HYDRATION_CHUNK_BYTES);
-		let offset = 0;
-		let overlap = "";
-		while (true) {
-			const count = fs.readSync(handle, buffer, 0, buffer.length, offset);
-			if (count === 0) return false;
-			hydrationScannedBytes += count;
-			const text = overlap + buffer.subarray(0, count).toString("utf-8");
-			if (text.includes(TRUNCATION_MARKER)) return true;
-			overlap = text.slice(-(TRUNCATION_MARKER.length - 1));
-			offset += count;
-		}
-	} finally {
-		fs.closeSync(handle);
-	}
-}
-
-function hydrationFromStat(stat: fs.Stats, state: TelemetryState): TelemetryHydration {
-	return {
-		dev: Number(stat.dev),
-		ino: Number(stat.ino),
-		size: stat.size,
-		mtimeMs: stat.mtimeMs,
-		ctimeMs: stat.ctimeMs,
-		...state,
-	};
-}
-
-function existingTelemetryState(filePath: string, seed?: TelemetryState): TelemetryState {
-	const key = keyFor(filePath);
-	try {
-		const stat = fs.statSync(filePath);
-		const telemetryTruncated = Boolean(seed?.telemetryTruncated) || scanForTruncationMarker(filePath);
-		const telemetryBytes = Math.max(stat.size, seed?.telemetryBytes ?? 0);
-		cacheHydration(key, hydrationFromStat(stat, { telemetryBytes, telemetryTruncated }));
-		return { telemetryBytes, telemetryTruncated };
-	} catch {
-		hydrationCache.delete(key);
-		return seed
-			? { telemetryBytes: seed.telemetryBytes, telemetryTruncated: seed.telemetryTruncated }
-			: { telemetryBytes: 0, telemetryTruncated: false };
-	}
-}
-
-function cacheSettledWriter(writer: SharedEventWriter): void {
-	try {
-		const stat = fs.statSync(writer.filePath);
-		cacheHydration(
-			writer.key,
-			hydrationFromStat(stat, {
-				telemetryBytes: Math.max(stat.size, writer.telemetryBytes),
-				telemetryTruncated: writer.telemetryTruncated,
-			}),
-		);
-	} catch {
-		hydrationCache.delete(writer.key);
-	}
-}
-
-export function resetEventWriterHydrationCacheForTests(): void {
-	hydrationCache.clear();
-	hydrationScanCount = 0;
-	hydrationScannedBytes = 0;
-}
-
-export function eventWriterHydrationCacheSizeForTests(): number {
-	return hydrationCache.size;
-}
-
-export function eventWriterHydrationScanStatsForTests(): { scans: number; bytes: number } {
-	return { scans: hydrationScanCount, bytes: hydrationScannedBytes };
-}
-
-function resumeSources(writer: SharedEventWriter): void {
-	for (const source of writer.sources) source.resume();
-	writer.sources.clear();
-	writer.backpressured = false;
-}
-
-function settleWriter(writer: SharedEventWriter): void {
-	if (!writer.failed) cacheSettledWriter(writer);
-	if (writers.get(writer.key) === writer) writers.delete(writer.key);
-	resumeSources(writer);
-	writer.resolveSettled();
-}
-
-function failWriter(writer: SharedEventWriter): void {
-	if (writer.failed) return;
-	writer.failed = true;
-	writer.closed = true;
-	settleWriter(writer);
-}
-
-function write(writer: SharedEventWriter, chunk: string): void {
-	if (writer.closed || writer.failed) return;
-	try {
-		const accepted = writer.stream.write(chunk);
-		if (!accepted && !writer.backpressured) {
-			writer.backpressured = true;
-			for (const source of writer.sources) source.pause();
-			writer.stream.once("drain", () => {
-				writer.backpressured = false;
-				if (!writer.closed && !writer.failed) for (const source of writer.sources) source.resume();
-			});
-		}
-	} catch {
-		failWriter(writer);
-	}
-}
-
-export interface EventWriterLease {
-	reserveTelemetry(bytes: number, maxBytes: number): boolean;
-	claimTruncationMarker(): boolean;
-	writeLine(line: string): void;
-	close(): Promise<void>;
-}
-
-type StreamFactory = (filePath: string) => JsonlWriteStream;
-
-function createDeferredLease(
-	closingWriter: SharedEventWriter,
-	filePath: string,
-	source: DrainableSource,
-	createWriteStream: StreamFactory,
-): EventWriterLease {
-	const bufferedLines: string[] = [];
-	let inner: EventWriterLease | undefined;
-	let closePromise: Promise<void> | undefined;
-	const activate = async (): Promise<void> => {
-		await closingWriter.settled;
-		inner = acquireEventWriterInternal(filePath, source, createWriteStream, closingWriter);
-		if (!inner) return;
-		for (const line of bufferedLines) inner.writeLine(line);
-		bufferedLines.length = 0;
-	};
-	const activated = activate();
-	return {
-		reserveTelemetry(bytes, maxBytes) {
-			if (inner) return inner.reserveTelemetry(bytes, maxBytes);
-			if (closingWriter.telemetryTruncated || closingWriter.telemetryBytes + bytes > maxBytes) return false;
-			closingWriter.telemetryBytes += bytes;
-			return true;
-		},
-		claimTruncationMarker() {
-			if (inner) return inner.claimTruncationMarker();
-			if (closingWriter.telemetryTruncated) return false;
-			closingWriter.telemetryTruncated = true;
-			return true;
-		},
-		writeLine(line) {
-			if (!line.trim()) return;
-			if (inner) inner.writeLine(line);
-			else bufferedLines.push(line);
-		},
-		close() {
-			closePromise ??= activated.then(() => inner?.close());
-			return closePromise;
-		},
-	};
-}
-
-function createWriter(
-	filePath: string,
-	key: string,
-	createWriteStream: StreamFactory,
-	seed?: TelemetryState,
-): SharedEventWriter | undefined {
-	let stream: JsonlWriteStream;
-	try {
-		stream = createWriteStream(filePath);
-	} catch {
-		return undefined;
-	}
-	let resolveSettled = () => {};
-	const settled = new Promise<void>((resolve) => {
-		resolveSettled = resolve;
-	});
-	const writer: SharedEventWriter = {
-		stream,
-		sources: new Set(),
-		refs: 0,
-		backpressured: false,
-		...existingTelemetryState(filePath, seed),
-		closed: false,
-		failed: false,
-		filePath,
-		key,
-		closingLines: [],
-		settled,
-		resolveSettled,
-	};
-	stream.on?.("error", () => failWriter(writer));
-	writers.set(key, writer);
-	return writer;
-}
-
-function acquireEventWriterInternal(
-	filePath: string,
-	source: DrainableSource,
-	createWriteStream: StreamFactory,
-	seed?: TelemetryState,
-): EventWriterLease | undefined {
-	const key = keyFor(filePath);
-	let writer = writers.get(key);
-	if (writer?.closed) return createDeferredLease(writer, filePath, source, createWriteStream);
-	writer ??= createWriter(filePath, key, createWriteStream, seed);
-	if (!writer) return undefined;
-	writer.refs += 1;
-	writer.sources.add(source);
-	if (writer.backpressured) source.pause();
-	let closePromise: Promise<void> | undefined;
-	return {
-		reserveTelemetry(bytes, maxBytes) {
-			if (writer!.failed || writer!.telemetryTruncated || writer!.telemetryBytes + bytes > maxBytes) return false;
-			writer!.telemetryBytes += bytes;
-			return true;
-		},
-		claimTruncationMarker() {
-			if (writer!.failed || writer!.telemetryTruncated) return false;
-			writer!.telemetryTruncated = true;
-			return true;
-		},
-		writeLine(line) {
-			if (line.trim()) write(writer!, `${line}\n`);
-		},
-		close() {
-			if (closePromise) return closePromise;
-			writer!.sources.delete(source);
-			writer!.refs -= 1;
-			if (writer!.refs > 0 || writer!.failed) {
-				closePromise = Promise.resolve();
-				return closePromise;
-			}
-			writer!.closed = true;
-			try {
-				writer!.stream.end(() => {
-					if (!writer!.failed) {
-						for (const line of writer!.closingLines) {
-							try {
-								fs.appendFileSync(writer!.filePath, line);
-							} catch {
-								/* telemetry failure is non-fatal */
-							}
-						}
-						settleWriter(writer!);
-					}
-				});
-			} catch {
-				failWriter(writer!);
-			}
-			closePromise = writer!.settled;
-			return closePromise;
-		},
-	};
-}
-
-export function acquireEventWriter(
-	filePath: string,
-	source: DrainableSource,
-	createWriteStream: StreamFactory = (target) => fs.createWriteStream(target, { flags: "a" }),
-): EventWriterLease | undefined {
-	return acquireEventWriterInternal(filePath, source, createWriteStream);
-}
-
-/** Route lifecycle/control appends through an active child writer to avoid mixed handles. */
-export function appendToActiveEventWriter(filePath: string, line: string): boolean {
-	const writer = writers.get(keyFor(filePath));
-	if (!writer) return false;
-	if (writer.closed) writer.closingLines.push(`${line}\n`);
-	else write(writer, `${line}\n`);
-	return true;
-}

package/dist/builtin/subagents/src/shared/exclusive-file-publication.ts

@@ -1,44 +0,0 @@
-import * as fs from "node:fs";
-
-export interface ExclusivePublicationFs {
-	linkSync?: typeof fs.linkSync;
-	copyFileSync?: typeof fs.copyFileSync;
-	unlinkSync: typeof fs.unlinkSync;
-}
-
-export function errorCode(error: unknown): string | undefined {
-	return typeof error === "object" && error !== null && "code" in error
-		? (error as NodeJS.ErrnoException).code
-		: undefined;
-}
-
-/** Publish an existing file without ever replacing the destination. */
-export function publishFileExclusive(
-	source: string,
-	destination: string,
-	fsApi: ExclusivePublicationFs = fs,
-): "published" | "exists" {
-	try {
-		(fsApi.linkSync ?? fs.linkSync)(source, destination);
-		return "published";
-	} catch (error) {
-		const code = errorCode(error);
-		if (code === "EEXIST") return "exists";
-		if (code !== "EPERM" && code !== "EACCES" && code !== "ENOTSUP" && code !== "EXDEV") throw error;
-	}
-	try {
-		(fsApi.copyFileSync ?? fs.copyFileSync)(source, destination, fs.constants.COPYFILE_EXCL);
-		return "published";
-	} catch (error) {
-		if (errorCode(error) === "EEXIST") return "exists";
-		throw error;
-	}
-}
-
-export function unlinkIfPresent(file: string, fsApi: Pick<typeof fs, "unlinkSync"> = fs): void {
-	try {
-		fsApi.unlinkSync(file);
-	} catch (error) {
-		if (errorCode(error) !== "ENOENT") throw error;
-	}
-}