refactor(agent): isolate node filesystem session dependencies

packages/agent/src/harness/compaction/branch-summarization.ts

@@ -5,7 +5,7 @@
  * a summary of the branch being left so context isn't lost.
  */
 
-import type { ImageContent, Model, TextContent } from "@earendil-works/pi-ai";
+import type { Model } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "../../types.js";
 import {
@@ -148,16 +148,10 @@ function getMessageFromEntry(entry: SessionTreeEntry): AgentMessage | undefined
 		case "message":
 			// Skip tool results - context is in assistant's tool call
 			if (entry.message.role === "toolResult") return undefined;
-			return entry.message as AgentMessage;
+			return entry.message;
 
 		case "custom_message":
-			return createCustomMessage(
-				entry.customType,
-				entry.content as string | (TextContent | ImageContent)[],
-				entry.display,
-				entry.details,
-				entry.timestamp,
-			);
+			return createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp);
 
 		case "branch_summary":
 			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);

packages/agent/src/harness/env/nodejs.ts

@@ -218,6 +218,20 @@ export class NodeExecutionEnv implements ExecutionEnv {
 		this.shellEnv = options.shellEnv;
 	}
 
+	async absolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
+		const resolved = resolvePath(this.cwd, path);
+		const aborted = abortResult<string>(abortSignal, resolved);
+		if (aborted) return aborted;
+		return ok(resolved);
+	}
+
+	async joinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
+		const joined = join(...parts);
+		const aborted = abortResult<string>(abortSignal, joined);
+		if (aborted) return aborted;
+		return ok(joined);
+	}
+
 	async exec(
 		command: string,
 		options?: {
@@ -438,7 +452,7 @@ export class NodeExecutionEnv implements ExecutionEnv {
 		}
 	}
 
-	async realPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
+	async canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>> {
 		const resolved = resolvePath(this.cwd, path);
 		const aborted = abortResult<string>(abortSignal, resolved);
 		if (aborted) return aborted;

packages/agent/src/harness/execution-env.ts

@@ -1,10 +0,0 @@
-export type {
-	ExecutionEnv,
-	ExecutionEnvExecOptions,
-	ExecutionErrorCode,
-	FileErrorCode,
-	FileInfo,
-	FileKind,
-	Result,
-} from "./types.js";
-export { ExecutionError, err, FileError, getOrThrow, getOrUndefined, ok } from "./types.js";

packages/agent/src/harness/prompt-templates.ts

@@ -148,9 +148,9 @@ async function loadTemplateFromFile(
 
 async function resolveKind(env: ExecutionEnv, info: FileInfo): Promise<"file" | "directory" | undefined> {
 	if (info.kind === "file" || info.kind === "directory") return info.kind;
-	const realPath = await env.realPath(info.path);
-	if (!realPath.ok) return undefined;
-	const target = getOrUndefined(await env.fileInfo(realPath.value));
+	const canonicalPath = await env.canonicalPath(info.path);
+	if (!canonicalPath.ok) return undefined;
+	const target = getOrUndefined(await env.fileInfo(canonicalPath.value));
 	if (!target) return undefined;
 	return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
 }

packages/agent/src/harness/session/jsonl-repo.ts

@@ -0,0 +1,138 @@
+import type {
+	FileSystem,
+	JsonlSessionCreateOptions,
+	JsonlSessionListOptions,
+	JsonlSessionMetadata,
+	JsonlSessionRepoApi,
+	Session,
+} from "../types.js";
+import { getOrThrow } from "../types.js";
+import { JsonlSessionStorage, loadJsonlSessionMetadata } from "./jsonl-storage.js";
+import { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./repo-utils.js";
+
+type JsonlSessionRepoFileSystem = Pick<
+	FileSystem,
+	| "cwd"
+	| "absolutePath"
+	| "joinPath"
+	| "readTextFile"
+	| "writeFile"
+	| "appendFile"
+	| "listDir"
+	| "exists"
+	| "createDir"
+	| "remove"
+>;
+
+function encodeCwd(cwd: string): string {
+	return `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
+export class JsonlSessionRepo implements JsonlSessionRepoApi {
+	private readonly fs: JsonlSessionRepoFileSystem;
+	private readonly sessionsRootInput: string;
+	private sessionsRoot: string | undefined;
+
+	constructor(options: { fs: JsonlSessionRepoFileSystem; sessionsRoot: string }) {
+		this.fs = options.fs;
+		this.sessionsRootInput = options.sessionsRoot;
+	}
+
+	private async getSessionsRoot(): Promise<string> {
+		if (!this.sessionsRoot) {
+			this.sessionsRoot = getOrThrow(await this.fs.absolutePath(this.sessionsRootInput));
+		}
+		return this.sessionsRoot;
+	}
+
+	private async getSessionDir(cwd: string): Promise<string> {
+		return getOrThrow(await this.fs.joinPath([await this.getSessionsRoot(), encodeCwd(cwd)]));
+	}
+
+	private async createSessionFilePath(cwd: string, sessionId: string, timestamp: string): Promise<string> {
+		return getOrThrow(
+			await this.fs.joinPath([
+				await this.getSessionDir(cwd),
+				`${timestamp.replace(/[:.]/g, "-")}_${sessionId}.jsonl`,
+			]),
+		);
+	}
+
+	async create(options: JsonlSessionCreateOptions): Promise<Session<JsonlSessionMetadata>> {
+		const id = options.id ?? createSessionId();
+		const createdAt = createTimestamp();
+		const sessionDir = await this.getSessionDir(options.cwd);
+		getOrThrow(await this.fs.createDir(sessionDir, { recursive: true }));
+		const filePath = await this.createSessionFilePath(options.cwd, id, createdAt);
+		const storage = await JsonlSessionStorage.create(this.fs, filePath, {
+			cwd: options.cwd,
+			sessionId: id,
+			parentSessionPath: options.parentSessionPath,
+		});
+		return toSession(storage);
+	}
+
+	async open(metadata: JsonlSessionMetadata): Promise<Session<JsonlSessionMetadata>> {
+		if (!getOrThrow(await this.fs.exists(metadata.path))) {
+			throw new Error(`Session not found: ${metadata.path}`);
+		}
+		const storage = await JsonlSessionStorage.open(this.fs, metadata.path);
+		return toSession(storage);
+	}
+
+	async list(options: JsonlSessionListOptions = {}): Promise<JsonlSessionMetadata[]> {
+		const dirs = options.cwd ? [await this.getSessionDir(options.cwd)] : await this.listSessionDirs();
+		const sessions: JsonlSessionMetadata[] = [];
+		for (const dir of dirs) {
+			if (!getOrThrow(await this.fs.exists(dir))) continue;
+			const files = getOrThrow(await this.fs.listDir(dir)).filter(
+				(file) => file.kind !== "directory" && file.name.endsWith(".jsonl"),
+			);
+			for (const file of files) {
+				try {
+					sessions.push(await loadJsonlSessionMetadata(this.fs, file.path));
+				} catch {
+					// Ignore invalid session files when listing a directory.
+				}
+			}
+		}
+		sessions.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+		return sessions;
+	}
+
+	async delete(metadata: JsonlSessionMetadata): Promise<void> {
+		getOrThrow(await this.fs.remove(metadata.path, { force: true }));
+	}
+
+	async fork(
+		sourceMetadata: JsonlSessionMetadata,
+		options: JsonlSessionCreateOptions & { entryId?: string; position?: "before" | "at"; id?: string },
+	): Promise<Session<JsonlSessionMetadata>> {
+		const source = await this.open(sourceMetadata);
+		const forkedEntries = await getEntriesToFork(source.getStorage(), options);
+		const id = options.id ?? createSessionId();
+		const createdAt = createTimestamp();
+		const sessionDir = await this.getSessionDir(options.cwd);
+		getOrThrow(await this.fs.createDir(sessionDir, { recursive: true }));
+		const storage = await JsonlSessionStorage.create(
+			this.fs,
+			await this.createSessionFilePath(options.cwd, id, createdAt),
+			{
+				cwd: options.cwd,
+				sessionId: id,
+				parentSessionPath: options.parentSessionPath ?? sourceMetadata.path,
+			},
+		);
+		for (const entry of forkedEntries) {
+			await storage.appendEntry(entry);
+		}
+		return toSession(storage);
+	}
+
+	private async listSessionDirs(): Promise<string[]> {
+		const sessionsRoot = await this.getSessionsRoot();
+		if (!getOrThrow(await this.fs.exists(sessionsRoot))) return [];
+		const entries = getOrThrow(await this.fs.listDir(sessionsRoot));
+		return entries.filter((entry) => entry.kind === "directory").map((entry) => entry.path);
+	}
+}

packages/agent/src/harness/session/jsonl-storage.ts

@@ -1,9 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { createInterface } from "node:readline";
-import type { JsonlSessionMetadata, SessionStorage, SessionTreeEntry } from "../../types.js";
+import type { FileSystem, JsonlSessionMetadata, SessionStorage, SessionTreeEntry } from "../types.js";
+import { getOrThrow } from "../types.js";
+import { uuidv7 } from "./uuid.js";
+
+type JsonlSessionStorageFileSystem = Pick<FileSystem, "readTextFile" | "writeFile" | "appendFile">;
 
 interface SessionHeader {
 	type: "session";
@@ -34,10 +33,10 @@ function buildLabelsById(entries: SessionTreeEntry[]): Map<string, string> {
 
 function generateEntryId(byId: { has(id: string): boolean }): string {
 	for (let i = 0; i < 100; i++) {
-		const id = randomUUID().slice(0, 8);
+		const id = uuidv7().slice(0, 8);
 		if (!byId.has(id)) return id;
 	}
-	return randomUUID();
+	return uuidv7();
 }
 
 function headerToSessionMetadata(header: SessionHeader, path: string): JsonlSessionMetadata {
@@ -50,32 +49,32 @@ function headerToSessionMetadata(header: SessionHeader, path: string): JsonlSess
 	};
 }
 
-export async function loadJsonlSessionMetadata(filePath: string): Promise<JsonlSessionMetadata> {
-	const stream = createReadStream(filePath, { encoding: "utf8" });
-	const lines = createInterface({ input: stream, crlfDelay: Infinity });
-	try {
-		for await (const line of lines) {
-			if (!line.trim()) break;
-			try {
-				const header = JSON.parse(line) as SessionHeader;
-				return headerToSessionMetadata(header, resolve(filePath));
-			} catch {
-				throw new Error(`Invalid JSONL session file ${filePath}: first line is not a valid session header`);
-			}
+export async function loadJsonlSessionMetadata(
+	fs: JsonlSessionStorageFileSystem,
+	filePath: string,
+): Promise<JsonlSessionMetadata> {
+	const content = getOrThrow(await fs.readTextFile(filePath));
+	for (const line of content.split("\n")) {
+		if (!line.trim()) break;
+		try {
+			const header = JSON.parse(line) as SessionHeader;
+			return headerToSessionMetadata(header, filePath);
+		} catch {
+			throw new Error(`Invalid JSONL session file ${filePath}: first line is not a valid session header`);
 		}
-		throw new Error(`Invalid JSONL session file ${filePath}: missing session header`);
-	} finally {
-		lines.close();
-		stream.destroy();
 	}
+	throw new Error(`Invalid JSONL session file ${filePath}: missing session header`);
 }
 
-async function loadJsonlStorage(filePath: string): Promise<{
+async function loadJsonlStorage(
+	fs: JsonlSessionStorageFileSystem,
+	filePath: string,
+): Promise<{
 	header: SessionHeader;
 	entries: SessionTreeEntry[];
 	leafId: string | null;
 }> {
-	const content = await readFile(filePath, "utf8");
+	const content = getOrThrow(await fs.readTextFile(filePath));
 	const lines = content.split("\n").filter((line) => line.trim());
 	if (lines.length === 0) {
 		throw new Error(`Invalid JSONL session file ${filePath}: missing session header`);
@@ -103,6 +102,7 @@ async function loadJsonlStorage(filePath: string): Promise<{
 }
 
 export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata> {
+	private readonly fs: JsonlSessionStorageFileSystem;
 	private readonly filePath: string;
 	private readonly metadata: JsonlSessionMetadata;
 	private entries: SessionTreeEntry[];
@@ -110,8 +110,15 @@ export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata>
 	private labelsById: Map<string, string>;
 	private currentLeafId: string | null;
 
-	private constructor(filePath: string, header: SessionHeader, entries: SessionTreeEntry[], leafId: string | null) {
-		this.filePath = resolve(filePath);
+	private constructor(
+		fs: JsonlSessionStorageFileSystem,
+		filePath: string,
+		header: SessionHeader,
+		entries: SessionTreeEntry[],
+		leafId: string | null,
+	) {
+		this.fs = fs;
+		this.filePath = filePath;
 		this.metadata = headerToSessionMetadata(header, this.filePath);
 		this.entries = entries;
 		this.byId = new Map(entries.map((entry) => [entry.id, entry]));
@@ -119,13 +126,13 @@ export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata>
 		this.currentLeafId = leafId;
 	}
 
-	static async open(filePath: string): Promise<JsonlSessionStorage> {
-		const resolvedPath = resolve(filePath);
-		const loaded = await loadJsonlStorage(resolvedPath);
-		return new JsonlSessionStorage(resolvedPath, loaded.header, loaded.entries, loaded.leafId);
+	static async open(fs: JsonlSessionStorageFileSystem, filePath: string): Promise<JsonlSessionStorage> {
+		const loaded = await loadJsonlStorage(fs, filePath);
+		return new JsonlSessionStorage(fs, filePath, loaded.header, loaded.entries, loaded.leafId);
 	}
 
 	static async create(
+		fs: JsonlSessionStorageFileSystem,
 		filePath: string,
 		options: {
 			cwd: string;
@@ -133,7 +140,6 @@ export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata>
 			parentSessionPath?: string;
 		},
 	): Promise<JsonlSessionStorage> {
-		const resolvedPath = resolve(filePath);
 		const header: SessionHeader = {
 			type: "session",
 			version: 3,
@@ -142,9 +148,8 @@ export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata>
 			cwd: options.cwd,
 			parentSession: options.parentSessionPath,
 		};
-		await mkdir(dirname(resolvedPath), { recursive: true });
-		await writeFile(resolvedPath, `${JSON.stringify(header)}\n`);
-		return new JsonlSessionStorage(resolvedPath, header, [], null);
+		getOrThrow(await fs.writeFile(filePath, `${JSON.stringify(header)}\n`));
+		return new JsonlSessionStorage(fs, filePath, header, [], null);
 	}
 
 	async getMetadata(): Promise<JsonlSessionMetadata> {
@@ -167,7 +172,7 @@ export class JsonlSessionStorage implements SessionStorage<JsonlSessionMetadata>
 	}
 
 	async appendEntry(entry: SessionTreeEntry): Promise<void> {
-		await appendFile(this.filePath, `${JSON.stringify(entry)}\n`);
+		getOrThrow(await this.fs.appendFile(this.filePath, `${JSON.stringify(entry)}\n`));
 		this.entries.push(entry);
 		this.byId.set(entry.id, entry);
 		updateLabelCache(this.labelsById, entry);

packages/agent/src/harness/session/memory-repo.ts

@@ -1,6 +1,6 @@
-import type { Session, SessionMetadata, SessionRepo } from "../../types.js";
-import { InMemorySessionStorage } from "../storage/memory.js";
-import { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./shared.js";
+import type { Session, SessionMetadata, SessionRepo } from "../types.js";
+import { InMemorySessionStorage } from "./memory-storage.js";
+import { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./repo-utils.js";
 
 export class InMemorySessionRepo implements SessionRepo<SessionMetadata, { id?: string }, void> {
 	private sessions = new Map<string, Session<SessionMetadata>>();

packages/agent/src/harness/session/memory-storage.ts

@@ -1,6 +1,5 @@
-import { randomUUID } from "node:crypto";
-import type { SessionMetadata, SessionStorage, SessionTreeEntry } from "../../types.js";
-import { uuidv7 } from "../uuid.js";
+import type { SessionMetadata, SessionStorage, SessionTreeEntry } from "../types.js";
+import { uuidv7 } from "./uuid.js";
 
 function updateLabelCache(labelsById: Map<string, string>, entry: SessionTreeEntry): void {
 	if (entry.type !== "label") return;
@@ -22,10 +21,10 @@ function buildLabelsById(entries: SessionTreeEntry[]): Map<string, string> {
 
 function generateEntryId(byId: { has(id: string): boolean }): string {
 	for (let i = 0; i < 100; i++) {
-		const id = randomUUID().slice(0, 8);
+		const id = uuidv7().slice(0, 8);
 		if (!byId.has(id)) return id;
 	}
-	return randomUUID();
+	return uuidv7();
 }
 
 export class InMemorySessionStorage implements SessionStorage {

packages/agent/src/harness/session/repo-utils.ts

@@ -1,6 +1,6 @@
-import type { SessionMetadata, SessionStorage, SessionTreeEntry } from "../../types.js";
-import { Session } from "../session.js";
-import { uuidv7 } from "../uuid.js";
+import type { SessionMetadata, SessionStorage, SessionTreeEntry } from "../types.js";
+import { Session } from "./session.js";
+import { uuidv7 } from "./uuid.js";
 
 export function createSessionId(): string {
 	return uuidv7();

packages/agent/src/harness/session/repo/jsonl.ts

@@ -1,109 +0,0 @@
-import { constants } from "node:fs";
-import { access, mkdir, readdir, rm } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import type {
-	JsonlSessionCreateOptions,
-	JsonlSessionListOptions,
-	JsonlSessionMetadata,
-	JsonlSessionRepoApi,
-	Session,
-} from "../../types.js";
-import { JsonlSessionStorage, loadJsonlSessionMetadata } from "../storage/jsonl.js";
-import { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./shared.js";
-
-async function exists(path: string): Promise<boolean> {
-	try {
-		await access(path, constants.F_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function encodeCwd(cwd: string): string {
-	return `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
-}
-
-export class JsonlSessionRepo implements JsonlSessionRepoApi {
-	private sessionsRoot: string;
-
-	constructor(options: { sessionsRoot: string }) {
-		this.sessionsRoot = resolve(options.sessionsRoot);
-	}
-
-	private getSessionDir(cwd: string): string {
-		return join(this.sessionsRoot, encodeCwd(cwd));
-	}
-
-	private createSessionFilePath(cwd: string, sessionId: string, timestamp: string): string {
-		return join(this.getSessionDir(cwd), `${timestamp.replace(/[:.]/g, "-")}_${sessionId}.jsonl`);
-	}
-
-	async create(options: JsonlSessionCreateOptions): Promise<Session<JsonlSessionMetadata>> {
-		await mkdir(this.sessionsRoot, { recursive: true });
-		const id = options.id ?? createSessionId();
-		const createdAt = createTimestamp();
-		const filePath = this.createSessionFilePath(options.cwd, id, createdAt);
-		const storage = await JsonlSessionStorage.create(filePath, {
-			cwd: options.cwd,
-			sessionId: id,
-			parentSessionPath: options.parentSessionPath,
-		});
-		return toSession(storage);
-	}
-
-	async open(metadata: JsonlSessionMetadata): Promise<Session<JsonlSessionMetadata>> {
-		if (!(await exists(metadata.path))) {
-			throw new Error(`Session not found: ${metadata.path}`);
-		}
-		const storage = await JsonlSessionStorage.open(metadata.path);
-		return toSession(storage);
-	}
-
-	async list(options: JsonlSessionListOptions = {}): Promise<JsonlSessionMetadata[]> {
-		const dirs = options.cwd ? [this.getSessionDir(options.cwd)] : await this.listSessionDirs();
-		const sessions: JsonlSessionMetadata[] = [];
-		for (const dir of dirs) {
-			if (!(await exists(dir))) continue;
-			const files = (await readdir(dir)).filter((file) => file.endsWith(".jsonl")).map((file) => join(dir, file));
-			for (const filePath of files) {
-				try {
-					sessions.push(await loadJsonlSessionMetadata(filePath));
-				} catch {
-					// Ignore invalid session files when listing a directory.
-				}
-			}
-		}
-		sessions.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
-		return sessions;
-	}
-
-	async delete(metadata: JsonlSessionMetadata): Promise<void> {
-		await rm(metadata.path, { force: true });
-	}
-
-	async fork(
-		sourceMetadata: JsonlSessionMetadata,
-		options: JsonlSessionCreateOptions & { entryId?: string; position?: "before" | "at"; id?: string },
-	): Promise<Session<JsonlSessionMetadata>> {
-		const source = await this.open(sourceMetadata);
-		const forkedEntries = await getEntriesToFork(source.getStorage(), options);
-		const id = options.id ?? createSessionId();
-		const createdAt = createTimestamp();
-		const storage = await JsonlSessionStorage.create(this.createSessionFilePath(options.cwd, id, createdAt), {
-			cwd: options.cwd,
-			sessionId: id,
-			parentSessionPath: options.parentSessionPath ?? sourceMetadata.path,
-		});
-		for (const entry of forkedEntries) {
-			await storage.appendEntry(entry);
-		}
-		return toSession(storage);
-	}
-
-	private async listSessionDirs(): Promise<string[]> {
-		if (!(await exists(this.sessionsRoot))) return [];
-		const entries = await readdir(this.sessionsRoot, { withFileTypes: true });
-		return entries.filter((entry) => entry.isDirectory()).map((entry) => join(this.sessionsRoot, entry.name));
-	}
-}

packages/agent/src/harness/session/uuid.ts

@@ -1,10 +1,20 @@
-import { randomBytes } from "node:crypto";
-
 let lastTimestamp = -Infinity;
 let sequence = 0;
 
+function fillRandomBytes(bytes: Uint8Array): void {
+	const crypto = globalThis.crypto;
+	if (crypto?.getRandomValues) {
+		crypto.getRandomValues(bytes);
+		return;
+	}
+	for (let i = 0; i < bytes.length; i++) {
+		bytes[i] = Math.floor(Math.random() * 256);
+	}
+}
+
 export function uuidv7(): string {
-	const random = randomBytes(16);
+	const random = new Uint8Array(16);
+	fillRandomBytes(random);
 	const timestamp = Date.now();
 
 	if (timestamp > lastTimestamp) {

packages/agent/src/harness/skills.ts

@@ -261,9 +261,9 @@ function parseFrontmatter<T extends Record<string, unknown>>(
 
 async function resolveKind(env: ExecutionEnv, info: FileInfo): Promise<"file" | "directory" | undefined> {
 	if (info.kind === "file" || info.kind === "directory") return info.kind;
-	const realPath = await env.realPath(info.path);
-	if (!realPath.ok) return undefined;
-	const target = getOrUndefined(await env.fileInfo(realPath.value));
+	const canonicalPath = await env.canonicalPath(info.path);
+	if (!canonicalPath.ok) return undefined;
+	const target = getOrUndefined(await env.fileInfo(canonicalPath.value));
 	if (!target) return undefined;
 	return target.kind === "file" || target.kind === "directory" ? target.kind : undefined;
 }

packages/agent/src/harness/types.ts

@@ -93,10 +93,10 @@ export interface AgentHarnessStreamOptionsPatch
 	metadata?: Record<string, unknown | undefined>;
 }
 
-/** Kind of filesystem object as addressed by an {@link ExecutionEnv}. Symlinks are not followed automatically. */
+/** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */
 export type FileKind = "file" | "directory" | "symlink";
 
-/** Stable, backend-independent file error codes returned by {@link ExecutionEnv} file operations. */
+/** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
 export type FileErrorCode =
 	| "aborted"
 	| "not_found"
@@ -107,7 +107,7 @@ export type FileErrorCode =
 	| "not_supported"
 	| "unknown";
 
-/** Error returned by {@link ExecutionEnv} file operations. */
+/** Error returned by {@link FileSystem} file operations. */
 export class FileError extends Error {
 	constructor(
 		/** Backend-independent error code. */
@@ -154,13 +154,13 @@ export class CompactionError extends Error {
 	}
 }
 
-/** Metadata for one filesystem object in an {@link ExecutionEnv}. */
+/** Metadata for one filesystem object in a {@link FileSystem}. */
 export interface FileInfo {
 	/** Basename of {@link path}. */
 	name: string;
 	/** Absolute, syntactically normalized addressed path in the execution environment. Symlinks are not followed. */
 	path: string;
-	/** Object kind. Symlink targets are not followed; use {@link ExecutionEnv.resolvePath} explicitly. */
+	/** Object kind. Symlink targets are not followed; use {@link FileSystem.canonicalPath} explicitly. */
 	kind: FileKind;
 	/** Size in bytes for the addressed filesystem object. */
 	size: number;
@@ -168,7 +168,7 @@ export interface FileInfo {
 	mtimeMs: number;
 }
 
-/** Options for {@link ExecutionEnv.exec}. */
+/** Options for {@link Shell.exec}. */
 export interface ExecutionEnvExecOptions {
 	/** Working directory for the command. Relative paths are resolved against {@link ExecutionEnv.cwd}. Defaults to {@link ExecutionEnv.cwd}. */
 	cwd?: string;
@@ -185,24 +185,22 @@ export interface ExecutionEnvExecOptions {
 }
 
 /**
- * Filesystem and process execution environment used by the harness.
+ * Filesystem capability used by the harness.
  *
- * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by this interface are absolute
- * addressed paths in the environment, but are not canonicalized through symlinks unless returned by {@link resolvePath}.
+ * Paths passed to methods may be absolute or relative to {@link cwd}. Paths returned by file operations are addressed paths
+ * in the filesystem namespace, but are not canonicalized through symlinks unless returned by {@link canonicalPath}.
  *
- * Operation methods must never throw or reject. All filesystem/process failures, including unexpected backend failures,
- * must be encoded in the returned {@link Result}. Implementations must preserve this invariant.
+ * Operation methods must never throw or reject. All filesystem failures, including unexpected backend failures, must be
+ * encoded in the returned {@link Result}. Implementations must preserve this invariant.
  */
-export interface ExecutionEnv {
-	/** Current working directory for relative paths and command execution. */
+export interface FileSystem {
+	/** Current working directory for relative paths. */
 	cwd: string;
 
-	/** Execute a shell command in {@link cwd} unless `options.cwd` is provided. */
-	exec(
-		command: string,
-		options?: ExecutionEnvExecOptions,
-	): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>>;
-
+	/** Return an absolute addressed path without requiring it to exist and without resolving symlinks. */
+	absolutePath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+	/** Join path segments in the filesystem namespace without requiring the result to exist. */
+	joinPath(parts: string[], abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
 	/** Read a UTF-8 text file. */
 	readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
 	/** Read a binary file. */
@@ -215,8 +213,8 @@ export interface ExecutionEnv {
 	fileInfo(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileError>>;
 	/** List direct children of a directory without following symlinks. */
 	listDir(path: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileError>>;
-	/** Return the canonical path for a path, following symlinks. */
-	realPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+	/** Return the canonical path for an existing path, resolving symlinks where supported. */
+	canonicalPath(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
 	/** Return false for missing paths. Other errors, such as permission failures, return a {@link FileError}. */
 	exists(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
 	/** Create a directory. Defaults: `recursive: true`, no abort signal. */
@@ -238,10 +236,24 @@ export interface ExecutionEnv {
 		abortSignal?: AbortSignal;
 	}): Promise<Result<string, FileError>>;
 
-	/** Release resources owned by the environment. Must be best-effort and must not throw or reject. */
+	/** Release filesystem resources. Must be best-effort and must not throw or reject. */
 	cleanup(): Promise<void>;
 }
 
+/** Shell execution capability used by the harness. */
+export interface Shell {
+	/** Execute a shell command in {@link FileSystem.cwd} unless `options.cwd` is provided. */
+	exec(
+		command: string,
+		options?: ExecutionEnvExecOptions,
+	): Promise<Result<{ stdout: string; stderr: string; exitCode: number }, ExecutionError>>;
+	/** Release shell resources. Must be best-effort and must not throw or reject. */
+	cleanup(): Promise<void>;
+}
+
+/** Filesystem and process execution environment used by the harness. */
+export interface ExecutionEnv extends FileSystem, Shell {}
+
 export interface SessionTreeEntryBase {
 	type: string;
 	id: string;

packages/agent/src/index.ts

@@ -22,12 +22,11 @@ export {
 	serializeConversation,
 	shouldCompact,
 } from "./harness/compaction/compaction.js";
-export * from "./harness/execution-env.js";
 export * from "./harness/messages.js";
 export * from "./harness/prompt-templates.js";
-export * from "./harness/session/repo/jsonl.js";
-export * from "./harness/session/repo/memory.js";
-export * from "./harness/session/repo/shared.js";
+export * from "./harness/session/jsonl-repo.js";
+export * from "./harness/session/memory-repo.js";
+export * from "./harness/session/repo-utils.js";
 export * from "./harness/session/session.js";
 export { uuidv7 } from "./harness/session/uuid.js";
 export * from "./harness/skills.js";

packages/agent/src/node.ts

@@ -0,0 +1,2 @@
+export { NodeExecutionEnv } from "./harness/env/nodejs.js";
+export * from "./index.js";