pi-crew 0.2.2 → 0.2.4

package/src/utils/safe-paths.ts

@@ -1,47 +1,47 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export function isSafePathId(value: string): boolean {
-	return /^[A-Za-z0-9_-]+$/.test(value);
-}
-
-export function assertSafePathId(kind: string, value: string): string {
-	if (!isSafePathId(value)) throw new Error(`Invalid ${kind}: ${value}`);
-	return value;
-}
-
-export function resolveContainedPath(baseDir: string, targetPath: string): string {
-	const base = path.resolve(baseDir);
-	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
-	const relative = path.relative(base, resolved);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
-	return resolved;
-}
-
-export function resolveRealContainedPath(baseDir: string, targetPath: string): string {
-	const resolved = resolveContainedPath(baseDir, targetPath);
-	let realBase: string;
-	let realTarget: string;
-	try {
-		realBase = fs.realpathSync.native(baseDir);
-	} catch (baseError) {
-		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${baseError instanceof Error ? baseError.message : String(baseError)}`);
-	}
-	try {
-		realTarget = fs.realpathSync.native(resolved);
-	} catch (targetError) {
-		if ((targetError as NodeJS.ErrnoException).code === "ENOENT") {
-			throw new Error(`Path does not exist: ${resolved}`);
-		}
-		throw new Error(`Cannot resolve real path of ${resolved}: ${targetError instanceof Error ? targetError.message : String(targetError)}`);
-	}
-	const relative = path.relative(realBase, realTarget);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
-	return realTarget;
-}
-
-export function resolveContainedRelativePath(baseDir: string, relativePath: string, kind = "path"): string {
-	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
-	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
-	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function isSafePathId(value: string): boolean {
+	return /^[A-Za-z0-9_-]+$/.test(value);
+}
+
+export function assertSafePathId(kind: string, value: string): string {
+	if (!isSafePathId(value)) throw new Error(`Invalid ${kind}: ${value}`);
+	return value;
+}
+
+export function resolveContainedPath(baseDir: string, targetPath: string): string {
+	const base = path.resolve(baseDir);
+	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
+	const relative = path.relative(base, resolved);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
+	return resolved;
+}
+
+export function resolveRealContainedPath(baseDir: string, targetPath: string): string {
+	const resolved = resolveContainedPath(baseDir, targetPath);
+	let realBase: string;
+	let realTarget: string;
+	try {
+		realBase = fs.realpathSync.native(baseDir);
+	} catch (baseError) {
+		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${baseError instanceof Error ? baseError.message : String(baseError)}`);
+	}
+	try {
+		realTarget = fs.realpathSync.native(resolved);
+	} catch (targetError) {
+		if ((targetError as NodeJS.ErrnoException).code === "ENOENT") {
+			throw new Error(`Path does not exist: ${resolved}`);
+		}
+		throw new Error(`Cannot resolve real path of ${resolved}: ${targetError instanceof Error ? targetError.message : String(targetError)}`);
+	}
+	const relative = path.relative(realBase, realTarget);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
+	return realTarget;
+}
+
+export function resolveContainedRelativePath(baseDir: string, relativePath: string, kind = "path"): string {
+	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
+	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));
+}

package/src/utils/scan-cache.ts

@@ -1,137 +1,137 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-export interface ScanEntry {
-	/** Unique key for this entry (e.g., runId, artifactPath) */
-	key: string;
-	/** Filesystem path */
-	path: string;
-	/** Raw content (parsed JSON or text) */
-	raw: unknown;
-	/** File modification time */
-	mtimeMs: number;
-	/** File size in bytes */
-	sizeBytes: number;
-	/** When this entry was loaded */
-	loadedAtMs: number;
-}
-
-export interface ScanCacheOptions {
-	/** TTL in ms for cached entries. Default 1000. */
-	ttlMs?: number;
-	/** Maximum number of entries. Default 100. */
-	maxEntries?: number;
-}
-
-interface CacheBucket {
-	entries: Map<string, ScanEntry>;
-	expireAtMs: number;
-}
-
-/**
- * Shared raw scan-entry cache for runs, artifacts, mailbox, transcripts.
- * Provides deterministic sort order and invalidation on mutation.
- */
-export class SharedScanCache {
-	#buckets = new Map<string, CacheBucket>();
-	#ttlMs: number;
-	#maxEntries: number;
-	#now: () => number;
-
-	constructor(options: ScanCacheOptions = {}) {
-		this.#ttlMs = options.ttlMs ?? 1000;
-		this.#maxEntries = options.maxEntries ?? 100;
-		this.#now = () => Date.now();
-	}
-
-	/** Get a cached entry by bucket and key. Returns undefined if not cached or expired. */
-	get(bucket: string, key: string): ScanEntry | undefined {
-		const b = this.#buckets.get(bucket);
-		if (!b) return undefined;
-		if (this.#now() > b.expireAtMs) {
-			this.#buckets.delete(bucket);
-			return undefined;
-		}
-		return b.entries.get(key);
-	}
-
-	/** Get all entries in a bucket. Returns empty array if expired or missing. */
-	list(bucket: string): ScanEntry[] {
-		const b = this.#buckets.get(bucket);
-		if (!b) return [];
-		if (this.#now() > b.expireAtMs) {
-			this.#buckets.delete(bucket);
-			return [];
-		}
-		return [...b.entries.values()].sort((a, b) => a.key.localeCompare(b.key));
-	}
-
-	/** Set an entry in a bucket. */
-	set(bucket: string, entry: ScanEntry): void {
-		let b = this.#buckets.get(bucket);
-		if (!b || this.#now() > b.expireAtMs) {
-			b = { entries: new Map(), expireAtMs: this.#now() + this.#ttlMs };
-			this.#buckets.set(bucket, b);
-		}
-		if (b.entries.size >= this.#maxEntries) {
-			// Evict oldest entry
-			const firstKey = b.entries.keys().next().value;
-			if (firstKey !== undefined) b.entries.delete(firstKey);
-		}
-		b.entries.set(entry.key, entry);
-	}
-
-	/** Invalidate a specific key in a bucket. */
-	invalidate(bucket: string, key: string): void {
-		const b = this.#buckets.get(bucket);
-		if (b) b.entries.delete(key);
-	}
-
-	/** Invalidate an entire bucket. */
-	invalidateBucket(bucket: string): void {
-		this.#buckets.delete(bucket);
-	}
-
-	/** Invalidate all buckets. */
-	clear(): void {
-		this.#buckets.clear();
-	}
-
-	/** Read a file, parse if JSON, and cache the result. */
-	readAndCache(bucket: string, key: string, filePath: string, parseJson = true): ScanEntry | undefined {
-		try {
-			if (!fs.existsSync(filePath)) return undefined;
-			const stat = fs.statSync(filePath);
-			const cached = this.get(bucket, key);
-			if (cached && cached.mtimeMs >= stat.mtimeMs && cached.sizeBytes === stat.size) return cached;
-			const content = fs.readFileSync(filePath, "utf-8");
-			const raw = parseJson ? JSON.parse(content) : content;
-			const entry: ScanEntry = { key, path: filePath, raw, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, loadedAtMs: this.#now() };
-			this.set(bucket, entry);
-			return entry;
-		} catch {
-			return undefined;
-		}
-	}
-
-	/** Read a directory and cache entries for each file. */
-	scanAndCache(bucket: string, dirPath: string, parseJson = true): ScanEntry[] {
-		try {
-			if (!fs.existsSync(dirPath)) return [];
-			const entries = fs.readdirSync(dirPath, { withFileTypes: true });
-			const results: ScanEntry[] = [];
-			for (const entry of entries) {
-				if (!entry.isFile()) continue;
-				const filePath = path.join(dirPath, entry.name);
-				const cached = this.readAndCache(bucket, entry.name, filePath, parseJson);
-				if (cached) results.push(cached);
-			}
-			return results.sort((a, b) => a.key.localeCompare(b.key));
-		} catch {
-			return [];
-		}
-	}
-}
-
-/** Global shared scan cache instance. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ScanEntry {
+	/** Unique key for this entry (e.g., runId, artifactPath) */
+	key: string;
+	/** Filesystem path */
+	path: string;
+	/** Raw content (parsed JSON or text) */
+	raw: unknown;
+	/** File modification time */
+	mtimeMs: number;
+	/** File size in bytes */
+	sizeBytes: number;
+	/** When this entry was loaded */
+	loadedAtMs: number;
+}
+
+export interface ScanCacheOptions {
+	/** TTL in ms for cached entries. Default 1000. */
+	ttlMs?: number;
+	/** Maximum number of entries. Default 100. */
+	maxEntries?: number;
+}
+
+interface CacheBucket {
+	entries: Map<string, ScanEntry>;
+	expireAtMs: number;
+}
+
+/**
+ * Shared raw scan-entry cache for runs, artifacts, mailbox, transcripts.
+ * Provides deterministic sort order and invalidation on mutation.
+ */
+export class SharedScanCache {
+	#buckets = new Map<string, CacheBucket>();
+	#ttlMs: number;
+	#maxEntries: number;
+	#now: () => number;
+
+	constructor(options: ScanCacheOptions = {}) {
+		this.#ttlMs = options.ttlMs ?? 1000;
+		this.#maxEntries = options.maxEntries ?? 100;
+		this.#now = () => Date.now();
+	}
+
+	/** Get a cached entry by bucket and key. Returns undefined if not cached or expired. */
+	get(bucket: string, key: string): ScanEntry | undefined {
+		const b = this.#buckets.get(bucket);
+		if (!b) return undefined;
+		if (this.#now() > b.expireAtMs) {
+			this.#buckets.delete(bucket);
+			return undefined;
+		}
+		return b.entries.get(key);
+	}
+
+	/** Get all entries in a bucket. Returns empty array if expired or missing. */
+	list(bucket: string): ScanEntry[] {
+		const b = this.#buckets.get(bucket);
+		if (!b) return [];
+		if (this.#now() > b.expireAtMs) {
+			this.#buckets.delete(bucket);
+			return [];
+		}
+		return [...b.entries.values()].sort((a, b) => a.key.localeCompare(b.key));
+	}
+
+	/** Set an entry in a bucket. */
+	set(bucket: string, entry: ScanEntry): void {
+		let b = this.#buckets.get(bucket);
+		if (!b || this.#now() > b.expireAtMs) {
+			b = { entries: new Map(), expireAtMs: this.#now() + this.#ttlMs };
+			this.#buckets.set(bucket, b);
+		}
+		if (b.entries.size >= this.#maxEntries) {
+			// Evict oldest entry
+			const firstKey = b.entries.keys().next().value;
+			if (firstKey !== undefined) b.entries.delete(firstKey);
+		}
+		b.entries.set(entry.key, entry);
+	}
+
+	/** Invalidate a specific key in a bucket. */
+	invalidate(bucket: string, key: string): void {
+		const b = this.#buckets.get(bucket);
+		if (b) b.entries.delete(key);
+	}
+
+	/** Invalidate an entire bucket. */
+	invalidateBucket(bucket: string): void {
+		this.#buckets.delete(bucket);
+	}
+
+	/** Invalidate all buckets. */
+	clear(): void {
+		this.#buckets.clear();
+	}
+
+	/** Read a file, parse if JSON, and cache the result. */
+	readAndCache(bucket: string, key: string, filePath: string, parseJson = true): ScanEntry | undefined {
+		try {
+			if (!fs.existsSync(filePath)) return undefined;
+			const stat = fs.statSync(filePath);
+			const cached = this.get(bucket, key);
+			if (cached && cached.mtimeMs >= stat.mtimeMs && cached.sizeBytes === stat.size) return cached;
+			const content = fs.readFileSync(filePath, "utf-8");
+			const raw = parseJson ? JSON.parse(content) : content;
+			const entry: ScanEntry = { key, path: filePath, raw, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, loadedAtMs: this.#now() };
+			this.set(bucket, entry);
+			return entry;
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Read a directory and cache entries for each file. */
+	scanAndCache(bucket: string, dirPath: string, parseJson = true): ScanEntry[] {
+		try {
+			if (!fs.existsSync(dirPath)) return [];
+			const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+			const results: ScanEntry[] = [];
+			for (const entry of entries) {
+				if (!entry.isFile()) continue;
+				const filePath = path.join(dirPath, entry.name);
+				const cached = this.readAndCache(bucket, entry.name, filePath, parseJson);
+				if (cached) results.push(cached);
+			}
+			return results.sort((a, b) => a.key.localeCompare(b.key));
+		} catch {
+			return [];
+		}
+	}
+}
+
+/** Global shared scan cache instance. */
 export const sharedScanCache = new SharedScanCache();

package/src/utils/sleep.ts

@@ -1,3 +1,5 @@
+import { execFileSync } from "node:child_process";
+
 /**
  * Synchronous sleep using Atomics.wait (non-busy) with low-CPU fallback.
  *
@@ -14,7 +16,6 @@ export function sleepSync(ms: number): void {
 		// On Unix, try spawning the `sleep` command to avoid CPU busy-wait.
 		if (process.platform !== "win32" && ms >= 10) {
 			try {
-				const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
 				execFileSync("sleep", [(ms / 1000).toFixed(3)], { timeout: ms + 1000, stdio: "pipe" });
 				return;
 			} catch {

package/src/utils/sse-parser.ts

@@ -1,134 +1,134 @@
-/** A single Server-Sent Event */
-export interface ServerSentEvent {
-	event: string | null;
-	data: string;
-	raw: string[];
-}
-
-/** L1: Maximum number of raw lines before discarding an oversized event. */
-const MAX_EVENT_LINES = 1000;
-
-/** Read newline-delimited lines from a text ReadableStream, buffering partial chunks. */
-async function* readLines(
-	stream: ReadableStream<string>,
-	signal?: AbortSignal,
-): AsyncGenerator<string> {
-	const reader = stream.getReader();
-	let buffer = "";
-	try {
-		while (true) {
-			if (signal?.aborted) return;
-			const { done, value } = await reader.read();
-			if (done) {
-				if (buffer.length > 0) yield buffer;
-				return;
-			}
-			buffer += value;
-			let idx: number;
-			while ((idx = buffer.indexOf("\n")) !== -1) {
-				const line = buffer.endsWith("\r\n", idx + 1)
-					? buffer.slice(0, idx - 1)
-					: buffer.slice(0, idx);
-				yield line;
-				buffer = buffer.slice(idx + 1);
-			}
-		}
-	} finally {
-		reader.releaseLock();
-	}
-}
-
-/** Parse SSE events from a byte stream */
-export async function* readSseEvents(
-	stream: ReadableStream<Uint8Array>,
-	signal?: AbortSignal,
-): AsyncGenerator<ServerSentEvent> {
-	const textStream = stream.pipeThrough(new TextDecoderStream() as unknown as TransformStream<Uint8Array, string>);
-	let currentEvent: string | null = null;
-	let currentData: string[] = [];
-	let currentRaw: string[] = [];
-
-	function flush(): ServerSentEvent | null {
-		if (currentData.length === 0 && currentEvent === null) return null;
-		const evt: ServerSentEvent = {
-			event: currentEvent,
-			data: currentData.join("\n"),
-			raw: currentRaw,
-		};
-		currentEvent = null;
-		currentData = [];
-		currentRaw = [];
-		return evt;
-	}
-
-	for await (const line of readLines(textStream, signal)) {
-		if (signal?.aborted) return;
-
-		// Empty line → dispatch
-		if (line === "") {
-			const evt = flush();
-			if (evt) yield evt;
-			continue;
-		}
-
-		// Comment
-		if (line.startsWith(":")) continue;
-
-		// [DONE] sentinel
-		if (line === "[DONE]") return;
-
-		const colonIdx = line.indexOf(":");
-		if (colonIdx === -1) {
-			// Field with no value
-			const field = line;
-			if (field === "event") {
-				currentEvent = "";
-			} else if (field === "data") {
-				currentData.push("");
-			}
-			currentRaw.push(line);
-			continue;
-		}
-
-		const field = line.slice(0, colonIdx);
-		let value = line.slice(colonIdx + 1);
-		// Remove leading space after colon per SSE spec
-		if (value.startsWith(" ")) value = value.slice(1);
-
-		currentRaw.push(line);
-
-		// L1: Guard against unbounded memory growth
-		if (currentRaw.length > MAX_EVENT_LINES) {
-			const evt = flush();
-			if (evt) yield evt;
-			continue;
-		}
-
-		if (field === "event") {
-			currentEvent = value;
-		} else if (field === "data") {
-			currentData.push(value);
-		}
-		// id / retry fields ignored
-	}
-
-	// Flush any remaining event at end of stream
-	const evt = flush();
-	if (evt) yield evt;
-}
-
-/** Parse SSE events and yield parsed JSON data objects */
-export async function* readSseJson<T>(
-	stream: ReadableStream<Uint8Array>,
-	signal?: AbortSignal,
-): AsyncGenerator<T> {
-	for await (const evt of readSseEvents(stream, signal)) {
-		try {
-			const parsed: T = JSON.parse(evt.data) as T;
-			yield parsed;
-		} catch {
-			// Skip non-JSON SSE data events (e.g., ping, error messages, sentinels)
-			continue;
-		}
-	}
-}
+/** A single Server-Sent Event */
+export interface ServerSentEvent {
+	event: string | null;
+	data: string;
+	raw: string[];
+}
+
+/** L1: Maximum number of raw lines before discarding an oversized event. */
+const MAX_EVENT_LINES = 1000;
+
+/** Read newline-delimited lines from a text ReadableStream, buffering partial chunks. */
+async function* readLines(
+	stream: ReadableStream<string>,
+	signal?: AbortSignal,
+): AsyncGenerator<string> {
+	const reader = stream.getReader();
+	let buffer = "";
+	try {
+		while (true) {
+			if (signal?.aborted) return;
+			const { done, value } = await reader.read();
+			if (done) {
+				if (buffer.length > 0) yield buffer;
+				return;
+			}
+			buffer += value;
+			let idx: number;
+			while ((idx = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.endsWith("\r\n", idx + 1)
+					? buffer.slice(0, idx - 1)
+					: buffer.slice(0, idx);
+				yield line;
+				buffer = buffer.slice(idx + 1);
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+/** Parse SSE events from a byte stream */
+export async function* readSseEvents(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+): AsyncGenerator<ServerSentEvent> {
+	const textStream = stream.pipeThrough(new TextDecoderStream() as unknown as TransformStream<Uint8Array, string>);
+	let currentEvent: string | null = null;
+	let currentData: string[] = [];
+	let currentRaw: string[] = [];
+
+	function flush(): ServerSentEvent | null {
+		if (currentData.length === 0 && currentEvent === null) return null;
+		const evt: ServerSentEvent = {
+			event: currentEvent,
+			data: currentData.join("\n"),
+			raw: currentRaw,
+		};
+		currentEvent = null;
+		currentData = [];
+		currentRaw = [];
+		return evt;
+	}
+
+	for await (const line of readLines(textStream, signal)) {
+		if (signal?.aborted) return;
+
+		// Empty line → dispatch
+		if (line === "") {
+			const evt = flush();
+			if (evt) yield evt;
+			continue;
+		}
+
+		// Comment
+		if (line.startsWith(":")) continue;
+
+		// [DONE] sentinel
+		if (line === "[DONE]") return;
+
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) {
+			// Field with no value
+			const field = line;
+			if (field === "event") {
+				currentEvent = "";
+			} else if (field === "data") {
+				currentData.push("");
+			}
+			currentRaw.push(line);
+			continue;
+		}
+
+		const field = line.slice(0, colonIdx);
+		let value = line.slice(colonIdx + 1);
+		// Remove leading space after colon per SSE spec
+		if (value.startsWith(" ")) value = value.slice(1);
+
+		currentRaw.push(line);
+
+		// L1: Guard against unbounded memory growth
+		if (currentRaw.length > MAX_EVENT_LINES) {
+			const evt = flush();
+			if (evt) yield evt;
+			continue;
+		}
+
+		if (field === "event") {
+			currentEvent = value;
+		} else if (field === "data") {
+			currentData.push(value);
+		}
+		// id / retry fields ignored
+	}
+
+	// Flush any remaining event at end of stream
+	const evt = flush();
+	if (evt) yield evt;
+}
+
+/** Parse SSE events and yield parsed JSON data objects */
+export async function* readSseJson<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+): AsyncGenerator<T> {
+	for await (const evt of readSseEvents(stream, signal)) {
+		try {
+			const parsed: T = JSON.parse(evt.data) as T;
+			yield parsed;
+		} catch {
+			// Skip non-JSON SSE data events (e.g., ping, error messages, sentinels)
+			continue;
+		}
+	}
+}