@flue/sdk 0.3.0 → 0.3.1

package/dist/internal.d.mts

@@ -0,0 +1,29 @@
+import { S as SessionData, T as SessionStore } from "./types-T8pE1xIS.mjs";
+import "./mcp-BVF-sOBZ.mjs";
+import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
+import { bashFactoryToSessionEnv } from "./sandbox.mjs";
+import { getModel } from "@mariozechner/pi-ai";
+import "valibot";
+
+//#region src/session.d.ts
+/** In-memory session store. Sessions persist for the lifetime of the process. */
+declare class InMemorySessionStore implements SessionStore {
+  private store;
+  save(id: string, data: SessionData): Promise<void>;
+  load(id: string): Promise<SessionData | null>;
+  delete(id: string): Promise<void>;
+}
+//#endregion
+//#region src/internal.d.ts
+/**
+ * Resolve a `provider/model-id` string into a pi-ai `Model` object.
+ * Lives here (rather than in the generated entry point) so that user
+ * projects don't have to declare `@mariozechner/pi-ai` as a direct
+ * dependency — wrangler's bundler resolves bare specifiers from the entry
+ * file's location, which on pnpm-isolated installs doesn't see Flue's
+ * transitive deps. Centralizing the resolver here keeps `_entry.ts`
+ * dependency-free apart from `@flue/sdk/*`.
+ */
+declare function resolveModel(modelString: string): ReturnType<typeof getModel>;
+//#endregion
+export { type FlueContextConfig, type FlueContextInternal, InMemorySessionStore, bashFactoryToSessionEnv, createFlueContext, resolveModel };

package/dist/internal.mjs

@@ -0,0 +1,39 @@
+import "./agent-BB4lwAd5.mjs";
+import { t as InMemorySessionStore } from "./session-DukL3zwF.mjs";
+import { bashFactoryToSessionEnv } from "./sandbox.mjs";
+import "./mcp-DOgMtp8y.mjs";
+import { createFlueContext } from "./client.mjs";
+import { getModel } from "@mariozechner/pi-ai";
+
+//#region src/internal.ts
+/**
+* Internal runtime helpers consumed by the generated server entry point.
+*
+* This subpath is NOT part of the public API. It exists solely so the build
+* plugins (Node, Cloudflare) can emit stable bare-specifier imports that
+* resolve through normal package-exports resolution at both build time and
+* runtime, for both workspace-linked and published-npm installs.
+*
+* User agent code should never import from here.
+*/
+/**
+* Resolve a `provider/model-id` string into a pi-ai `Model` object.
+* Lives here (rather than in the generated entry point) so that user
+* projects don't have to declare `@mariozechner/pi-ai` as a direct
+* dependency — wrangler's bundler resolves bare specifiers from the entry
+* file's location, which on pnpm-isolated installs doesn't see Flue's
+* transitive deps. Centralizing the resolver here keeps `_entry.ts`
+* dependency-free apart from `@flue/sdk/*`.
+*/
+function resolveModel(modelString) {
+	const slash = modelString.indexOf("/");
+	if (slash === -1) throw new Error(`[flue] Invalid model "${modelString}". Use the "provider/model-id" format (e.g. "anthropic/claude-haiku-4-5").`);
+	const provider = modelString.slice(0, slash);
+	const modelId = modelString.slice(slash + 1);
+	const resolved = getModel(provider, modelId);
+	if (!resolved) throw new Error(`[flue] Unknown model "${modelString}". Provider "${provider}" / model id "${modelId}" is not registered with @mariozechner/pi-ai.`);
+	return resolved;
+}
+
+//#endregion
+export { InMemorySessionStore, bashFactoryToSessionEnv, createFlueContext, resolveModel };

package/dist/mcp-BVF-sOBZ.d.mts

@@ -0,0 +1,22 @@
+import { j as ToolDef } from "./types-T8pE1xIS.mjs";
+
+//#region src/mcp.d.ts
+type McpTransport = 'streamable-http' | 'sse';
+interface McpServerOptions {
+  url: string | URL;
+  /** Defaults to modern streamable HTTP. Use 'sse' for legacy MCP servers. */
+  transport?: McpTransport;
+  headers?: HeadersInit;
+  requestInit?: RequestInit;
+  fetch?: typeof fetch;
+  clientName?: string;
+  clientVersion?: string;
+}
+interface McpServerConnection {
+  name: string;
+  tools: ToolDef[];
+  close(): Promise<void>;
+}
+declare function connectMcpServer(name: string, options: McpServerOptions): Promise<McpServerConnection>;
+//#endregion
+export { connectMcpServer as i, McpServerOptions as n, McpTransport as r, McpServerConnection as t };

package/dist/mcp-DOgMtp8y.mjs

@@ -0,0 +1,285 @@
+import { r as discoverSessionContext } from "./agent-BB4lwAd5.mjs";
+import { a as assertRoleExists, n as Session, o as createScopedEnv, r as deleteSessionTree, s as mergeCommands } from "./session-DukL3zwF.mjs";
+import { createCwdSessionEnv } from "./sandbox.mjs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+//#region src/agent-client.ts
+const DEFAULT_SESSION_ID = "default";
+var AgentClient = class {
+	sessions = {
+		get: (id, options) => this.openSession(id, "get", options),
+		create: (id, options) => this.openSession(id, "create", options),
+		delete: (id) => this.deleteSession(id)
+	};
+	openSessions = /* @__PURE__ */ new Map();
+	destroyed = false;
+	constructor(id, config, env, store, eventCallback, agentCommands = [], agentTools = []) {
+		this.id = id;
+		this.config = config;
+		this.env = env;
+		this.store = store;
+		this.eventCallback = eventCallback;
+		this.agentCommands = agentCommands;
+		this.agentTools = agentTools;
+	}
+	async session(id, options) {
+		return this.openSession(id, "get-or-create", options);
+	}
+	async shell(command, options) {
+		this.assertActive();
+		const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
+		const result = await (await createScopedEnv(this.env, effectiveCommands)).exec(command, {
+			env: options?.env,
+			cwd: options?.cwd
+		});
+		return {
+			stdout: result.stdout,
+			stderr: result.stderr,
+			exitCode: result.exitCode
+		};
+	}
+	async destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		for (const session of Array.from(this.openSessions.values())) session.close();
+		this.openSessions.clear();
+		await this.env.cleanup();
+	}
+	async openSession(id, mode, options) {
+		this.assertActive();
+		assertRoleExists(this.config.roles, options?.role);
+		const sessionId = normalizeSessionId(id);
+		const open = this.openSessions.get(sessionId);
+		if (open) {
+			if (mode === "create") throw new Error(`[flue] Session "${sessionId}" already exists for agent "${this.id}".`);
+			if (options?.role !== void 0 && options.role !== open.role) throw new Error(`[flue] Session "${sessionId}" is already open with role ${JSON.stringify(open.role ?? null)}; cannot reopen with role ${JSON.stringify(options.role)}.`);
+			return open;
+		}
+		const storageKey = createSessionStorageKey(this.id, sessionId);
+		const existingData = await this.store.load(storageKey);
+		if (mode === "get" && !existingData) throw new Error(`[flue] Session "${sessionId}" does not exist for agent "${this.id}".`);
+		if (mode === "create" && existingData) throw new Error(`[flue] Session "${sessionId}" already exists for agent "${this.id}".`);
+		let data = existingData;
+		if (!data && mode !== "get") {
+			data = createEmptySessionData();
+			await this.store.save(storageKey, data);
+		}
+		const session = new Session({
+			id: sessionId,
+			storageKey,
+			config: this.config,
+			env: this.env,
+			store: this.store,
+			existingData: data,
+			onAgentEvent: this.eventCallback,
+			agentCommands: this.agentCommands,
+			agentTools: this.agentTools,
+			sessionRole: options?.role,
+			taskDepth: 0,
+			createTaskSession: (taskOptions) => this.createTaskSession(taskOptions),
+			onDelete: () => this.openSessions.delete(sessionId)
+		});
+		this.openSessions.set(sessionId, session);
+		return session;
+	}
+	async deleteSession(id) {
+		this.assertActive();
+		const sessionId = normalizeSessionId(id);
+		const open = this.openSessions.get(sessionId);
+		if (open) {
+			await open.delete();
+			return;
+		}
+		await deleteSessionTree(this.store, createSessionStorageKey(this.id, sessionId));
+	}
+	async createTaskSession(options) {
+		this.assertActive();
+		assertRoleExists(this.config.roles, options.role);
+		const sessionId = `task:${options.parentSessionId}:${options.taskId}`;
+		const taskEnv = options.cwd ? createCwdSessionEnv(options.parentEnv, options.parentEnv.resolvePath(options.cwd)) : options.parentEnv;
+		const localContext = await discoverSessionContext(taskEnv);
+		const taskConfig = {
+			...this.config,
+			systemPrompt: localContext.systemPrompt,
+			skills: localContext.skills
+		};
+		const storageKey = createSessionStorageKey(this.id, sessionId);
+		const data = createEmptySessionData();
+		data.metadata = {
+			parentSessionId: options.parentSessionId,
+			taskId: options.taskId,
+			cwd: taskEnv.cwd,
+			role: options.role,
+			depth: options.depth
+		};
+		await this.store.save(storageKey, data);
+		const eventCallback = this.eventCallback ? (event) => {
+			this.eventCallback?.({
+				...event,
+				parentSessionId: event.parentSessionId ?? options.parentSessionId,
+				taskId: event.taskId ?? options.taskId
+			});
+		} : void 0;
+		return new Session({
+			id: sessionId,
+			storageKey,
+			config: taskConfig,
+			env: taskEnv,
+			store: this.store,
+			existingData: data,
+			onAgentEvent: eventCallback,
+			agentCommands: options.commands,
+			agentTools: this.agentTools,
+			sessionRole: options.role,
+			taskDepth: options.depth,
+			createTaskSession: (childOptions) => this.createTaskSession(childOptions)
+		});
+	}
+	assertActive() {
+		if (this.destroyed) throw new Error(`[flue] Agent "${this.id}" has been destroyed.`);
+	}
+};
+function normalizeSessionId(id) {
+	return id ?? DEFAULT_SESSION_ID;
+}
+function createSessionStorageKey(agentId, sessionId) {
+	return `agent-session:${JSON.stringify([agentId, sessionId])}`;
+}
+function createEmptySessionData() {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		version: 2,
+		entries: [],
+		leafId: null,
+		metadata: {},
+		createdAt: now,
+		updatedAt: now
+	};
+}
+
+//#endregion
+//#region src/mcp.ts
+async function connectMcpServer(name, options) {
+	const url = options.url instanceof URL ? options.url : new URL(options.url);
+	const requestInit = mergeRequestInit(options.requestInit, options.headers);
+	const transport = await createTransport(url, options.transport ?? "streamable-http", requestInit, options.fetch);
+	const client = new Client({
+		name: options.clientName ?? "flue",
+		version: options.clientVersion ?? "0.0.0"
+	});
+	try {
+		await client.connect(transport);
+		const { tools } = await client.listTools();
+		return {
+			name,
+			tools: createMcpTools(name, client, tools),
+			close: () => client.close()
+		};
+	} catch (error) {
+		await client.close().catch(() => void 0);
+		throw error;
+	}
+}
+async function createTransport(url, transport, requestInit, fetchImpl) {
+	if (transport === "sse") {
+		const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+		return new SSEClientTransport(url, {
+			requestInit,
+			fetch: fetchImpl
+		});
+	}
+	return new StreamableHTTPClientTransport(url, {
+		requestInit,
+		fetch: fetchImpl
+	});
+}
+function createMcpTools(serverName, client, tools) {
+	const names = /* @__PURE__ */ new Set();
+	return tools.map((tool) => {
+		const toolName = createToolName(serverName, tool.name);
+		if (names.has(toolName)) throw new Error(`[flue] MCP tools from server "${serverName}" produced duplicate tool name "${toolName}".`);
+		names.add(toolName);
+		return {
+			name: toolName,
+			description: createToolDescription(serverName, tool),
+			parameters: normalizeInputSchema(tool.inputSchema),
+			async execute(args, signal) {
+				if (signal?.aborted) throw new Error("Operation aborted");
+				const result = await client.callTool({
+					name: tool.name,
+					arguments: args
+				}, void 0, { signal });
+				const text = formatMcpResult(result);
+				if (result.isError) throw new Error(text);
+				return text;
+			}
+		};
+	});
+}
+function mergeRequestInit(requestInit, headers) {
+	if (!headers) return requestInit ?? {};
+	const mergedHeaders = new Headers(requestInit?.headers);
+	for (const [key, value] of new Headers(headers)) mergedHeaders.set(key, value);
+	return {
+		...requestInit,
+		headers: mergedHeaders
+	};
+}
+function createToolName(serverName, toolName) {
+	return `mcp__${sanitizeToolNamePart(serverName)}__${sanitizeToolNamePart(toolName)}`;
+}
+function sanitizeToolNamePart(value) {
+	return value.replace(/[^A-Za-z0-9_-]/g, "_").replace(/^_+|_+$/g, "") || "unnamed";
+}
+function createToolDescription(serverName, tool) {
+	const originalName = tool.name;
+	const title = tool.title ?? tool.annotations?.title;
+	const parts = [`MCP tool "${originalName}" from server "${serverName}".`];
+	if (title && title !== originalName) parts.push(`Title: ${title}.`);
+	if (tool.description) parts.push(tool.description);
+	return parts.join(" ");
+}
+function normalizeInputSchema(schema) {
+	return {
+		...schema,
+		type: schema.type ?? "object",
+		properties: schema.properties ?? {},
+		required: schema.required
+	};
+}
+function formatMcpResult(result) {
+	const parts = [];
+	if (result.structuredContent !== void 0) parts.push(`Structured content:\n${JSON.stringify(result.structuredContent, null, 2)}`);
+	for (const item of result.content ?? []) {
+		if (item.type === "text") {
+			parts.push(item.text);
+			continue;
+		}
+		if (item.type === "image") {
+			parts.push(`[Image: ${item.mimeType}, ${item.data.length} base64 chars]`);
+			continue;
+		}
+		if (item.type === "audio") {
+			parts.push(`[Audio: ${item.mimeType}, ${item.data.length} base64 chars]`);
+			continue;
+		}
+		if (item.type === "resource") {
+			const resource = item.resource;
+			if ("text" in resource) parts.push(`[Resource: ${resource.uri}]\n${resource.text}`);
+			else parts.push(`[Resource: ${resource.uri}, ${resource.blob.length} base64 chars]`);
+			continue;
+		}
+		if (item.type === "resource_link") {
+			const description = item.description ? ` - ${item.description}` : "";
+			parts.push(`[Resource link: ${item.name} (${item.uri})${description}]`);
+			continue;
+		}
+		parts.push(JSON.stringify(item));
+	}
+	if (parts.length === 0 && "toolResult" in result) parts.push(JSON.stringify(result.toolResult, null, 2));
+	return parts.filter(Boolean).join("\n\n") || "(MCP tool returned no content)";
+}
+
+//#endregion
+export { AgentClient as n, connectMcpServer as t };

package/dist/node/index.d.mts

@@ -0,0 +1,14 @@
+import { l as Command } from "../types-T8pE1xIS.mjs";
+import { t as CommandExecutor } from "../command-helpers-DdAfbnom.mjs";
+import { execFile } from "node:child_process";
+
+//#region src/node/define-command.d.ts
+/**
+ * Options forwarded directly to Node's `child_process.execFile`. Full pass-through.
+ */
+type CommandOptions = NonNullable<Parameters<typeof execFile>[2]>;
+declare function defineCommand(name: string): Command;
+declare function defineCommand(name: string, options: CommandOptions): Command;
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+//#endregion
+export { type CommandOptions, defineCommand };

package/dist/node/index.mjs

@@ -0,0 +1,75 @@
+import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+//#region src/node/define-command.ts
+/**
+* Node-specific `defineCommand`. Supports three forms:
+*
+* ```ts
+* defineCommand('agent-browser');
+* defineCommand('gh', { env: { GH_TOKEN: process.env.GH_TOKEN } });
+* defineCommand('gh', async (args) => ({ stdout: '...' }));
+* ```
+*
+* Forms A and B shell out via `child_process.execFile`. Form C lets the user
+* implement the command however they like. All three forms benefit from
+* return-shape normalization and throw-catching — no `try`/`catch` or
+* `return { stdout, stderr, exitCode: 0 }` boilerplate required.
+*/
+const execFileAsync = promisify(execFile);
+/**
+* Essential, non-sensitive environment variables automatically forwarded to
+* pass-through commands (forms A and B). Users can override any of these —
+* or add their own (e.g. `GH_TOKEN`) — via `options.env`. Anything not listed
+* here (API keys, tokens, secrets, etc.) stays on the host and is NEVER
+* exposed to the spawned process unless the caller opts in explicitly.
+*
+* If you need full control over the env, use the function form:
+* `defineCommand('gh', async (args) => { ... })`.
+*/
+const DEFAULT_ENV = {
+	PATH: process.env.PATH,
+	HOME: process.env.HOME,
+	USER: process.env.USER,
+	LOGNAME: process.env.LOGNAME,
+	HOSTNAME: process.env.HOSTNAME,
+	SHELL: process.env.SHELL,
+	LANG: process.env.LANG,
+	LC_ALL: process.env.LC_ALL,
+	LC_CTYPE: process.env.LC_CTYPE,
+	TZ: process.env.TZ,
+	TERM: process.env.TERM,
+	TMPDIR: process.env.TMPDIR,
+	TMP: process.env.TMP,
+	TEMP: process.env.TEMP
+};
+function defineCommand(name, arg) {
+	if (typeof arg === "function") return {
+		name,
+		execute: normalizeExecutor(arg)
+	};
+	const userOpts = arg ?? {};
+	const mergedOpts = {
+		maxBuffer: 50 * 1024 * 1024,
+		...userOpts,
+		env: {
+			...DEFAULT_ENV,
+			...userOpts.env ?? {}
+		}
+	};
+	const executor = async (args) => {
+		const { stdout, stderr } = await execFileAsync(name, args, mergedOpts);
+		return {
+			stdout: String(stdout ?? ""),
+			stderr: String(stderr ?? "")
+		};
+	};
+	return {
+		name,
+		execute: normalizeExecutor(executor)
+	};
+}
+
+//#endregion
+export { defineCommand };

package/dist/sandbox.d.mts

@@ -0,0 +1,29 @@
+import { C as SessionEnv, D as ShellResult, d as FileStat, i as BashFactory, u as CommandDef, x as SandboxFactory } from "./types-T8pE1xIS.mjs";
+
+//#region src/sandbox.d.ts
+declare function createCwdSessionEnv(parentEnv: SessionEnv, cwd: string): SessionEnv;
+declare function bashFactoryToSessionEnv(factory: BashFactory): Promise<SessionEnv>;
+/** Interface that remote sandbox providers must implement. */
+interface SandboxApi {
+  readFile(path: string): Promise<string>;
+  readFileBuffer(path: string): Promise<Uint8Array>;
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  stat(path: string): Promise<FileStat>;
+  readdir(path: string): Promise<string[]>;
+  exists(path: string): Promise<boolean>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  rm(path: string, options?: {
+    recursive?: boolean;
+    force?: boolean;
+  }): Promise<void>;
+  exec(command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+  }): Promise<ShellResult>;
+}
+/** Wrap a SandboxApi into SessionEnv. No just-bash, no intermediate filesystem layer. */
+declare function createSandboxSessionEnv(api: SandboxApi, cwd: string, cleanup?: () => Promise<void>): SessionEnv;
+//#endregion
+export { type CommandDef, type FileStat, SandboxApi, type SandboxFactory, type SessionEnv, bashFactoryToSessionEnv, createCwdSessionEnv, createSandboxSessionEnv };

package/dist/sandbox.mjs

@@ -0,0 +1,132 @@
+import "./agent-BB4lwAd5.mjs";
+import { i as normalizePath, o as createScopedEnv } from "./session-DukL3zwF.mjs";
+
+//#region src/sandbox.ts
+function createCwdSessionEnv(parentEnv, cwd) {
+	const scopedCwd = normalizePath(cwd);
+	const resolvePath = (p) => {
+		if (p.startsWith("/")) return normalizePath(p);
+		if (scopedCwd === "/") return normalizePath("/" + p);
+		return normalizePath(scopedCwd + "/" + p);
+	};
+	return {
+		exec: (cmd, opts) => parentEnv.exec(cmd, {
+			cwd: opts?.cwd ?? scopedCwd,
+			env: opts?.env
+		}),
+		scope: async (options) => createCwdSessionEnv(await createScopedEnv(parentEnv, options?.commands ?? []), scopedCwd),
+		readFile: (p) => parentEnv.readFile(resolvePath(p)),
+		readFileBuffer: (p) => parentEnv.readFileBuffer(resolvePath(p)),
+		writeFile: (p, c) => parentEnv.writeFile(resolvePath(p), c),
+		stat: (p) => parentEnv.stat(resolvePath(p)),
+		readdir: (p) => parentEnv.readdir(resolvePath(p)),
+		exists: (p) => parentEnv.exists(resolvePath(p)),
+		mkdir: (p, o) => parentEnv.mkdir(resolvePath(p), o),
+		rm: (p, o) => parentEnv.rm(resolvePath(p), o),
+		cwd: scopedCwd,
+		resolvePath,
+		cleanup: () => parentEnv.cleanup()
+	};
+}
+async function bashFactoryToSessionEnv(factory) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	async function createBash() {
+		const bash = await factory();
+		assertBashLike(bash);
+		if (seen.has(bash)) throw new Error("[flue] BashFactory must return a fresh Bash-like instance for each operation. Share the filesystem object in the factory closure to persist files across calls.");
+		seen.add(bash);
+		return bash;
+	}
+	async function createBashScopedEnv(commands) {
+		const scoped = await createBash();
+		registerCommands(scoped, commands);
+		return createBashSessionEnv(scoped, createBashScopedEnv);
+	}
+	return createBashSessionEnv(await createBash(), createBashScopedEnv);
+}
+function createBashSessionEnv(bash, createScope) {
+	const fs = bash.fs;
+	const cwd = bash.getCwd();
+	const resolve = (p) => p.startsWith("/") ? p : fs.resolvePath(cwd, p);
+	return {
+		exec: (cmd, opts) => bash.exec(cmd, opts),
+		scope: (options) => createScope(options?.commands ?? []),
+		readFile: (p) => fs.readFile(resolve(p)),
+		readFileBuffer: (p) => fs.readFileBuffer(resolve(p)),
+		writeFile: async (p, content) => {
+			const resolved = resolve(p);
+			const dir = resolved.replace(/\/[^/]*$/, "");
+			if (dir && dir !== resolved) try {
+				await fs.mkdir(dir, { recursive: true });
+			} catch {}
+			await fs.writeFile(resolved, content);
+		},
+		stat: (p) => fs.stat(resolve(p)),
+		readdir: (p) => fs.readdir(resolve(p)),
+		exists: (p) => fs.exists(resolve(p)),
+		mkdir: (p, o) => fs.mkdir(resolve(p), o),
+		rm: (p, o) => fs.rm(resolve(p), o),
+		cwd,
+		resolvePath: resolve,
+		cleanup: async () => {}
+	};
+}
+function registerCommands(bash, commands) {
+	if (commands.length === 0) return;
+	if (typeof bash.registerCommand !== "function") throw new Error("[flue] Cannot use commands: this Bash-like sandbox does not support command registration.");
+	for (const cmd of commands) bash.registerCommand({
+		name: cmd.name,
+		execute: cmd.execute
+	});
+}
+function assertBashLike(value) {
+	if (typeof value !== "object" || value === null || !("exec" in value) || !("getCwd" in value) || !("fs" in value) || typeof value.exec !== "function" || typeof value.getCwd !== "function" || typeof value.fs !== "object") throw new Error("[flue] BashFactory must return a Bash-like object.");
+}
+/** Wrap a SandboxApi into SessionEnv. No just-bash, no intermediate filesystem layer. */
+function createSandboxSessionEnv(api, cwd, cleanup) {
+	const resolvePath = (p) => {
+		if (p.startsWith("/")) return normalizePath(p);
+		if (cwd === "/") return normalizePath("/" + p);
+		return normalizePath(cwd + "/" + p);
+	};
+	return {
+		async exec(command, options) {
+			return api.exec(command, {
+				cwd: options?.cwd ?? cwd,
+				env: options?.env
+			});
+		},
+		async readFile(path) {
+			return api.readFile(resolvePath(path));
+		},
+		async readFileBuffer(path) {
+			return api.readFileBuffer(resolvePath(path));
+		},
+		async writeFile(path, content) {
+			return api.writeFile(resolvePath(path), content);
+		},
+		async stat(path) {
+			return api.stat(resolvePath(path));
+		},
+		async readdir(path) {
+			return api.readdir(resolvePath(path));
+		},
+		async exists(path) {
+			return api.exists(resolvePath(path));
+		},
+		async mkdir(path, options) {
+			return api.mkdir(resolvePath(path), options);
+		},
+		async rm(path, options) {
+			return api.rm(resolvePath(path), options);
+		},
+		cwd,
+		resolvePath,
+		async cleanup() {
+			if (cleanup) await cleanup();
+		}
+	};
+}
+
+//#endregion
+export { bashFactoryToSessionEnv, createCwdSessionEnv, createSandboxSessionEnv };