@flue/sdk 0.3.0 → 0.3.2

package/README.md

@@ -240,18 +240,18 @@ POST /agents/<agent-name>/<id>
 By default, `agent.session()` opens the default session for that agent ID. Reuse the same agent ID to continue the same default conversation. Use a new agent ID to start fresh.
 
 ```bash
-# Start a conversation
-curl http://localhost:8787/agents/hello/session-abc \
+# Start a conversation (port 3583 is `flue dev`'s default)
+curl http://localhost:3583/agents/hello/session-abc \
   -H "Content-Type: application/json" \
   -d '{"name": "Alice"}'
 
 # Continue that conversation
-curl http://localhost:8787/agents/hello/session-abc \
+curl http://localhost:3583/agents/hello/session-abc \
   -H "Content-Type: application/json" \
   -d '{"name": "Alice"}'
 
 # Start a separate conversation
-curl http://localhost:8787/agents/hello/session-xyz \
+curl http://localhost:3583/agents/hello/session-xyz \
   -H "Content-Type: application/json" \
   -d '{"name": "Alice"}'
 ```
@@ -305,22 +305,48 @@ const session = await agent.session();
 
 ## Running Agents
 
-### Trigger From the CLI
+### Local Development (`flue dev`)
 
-Build and run any agent locally, perfect for fast local testing or running in CI.
+Long-running watch-mode dev server. Rebuilds and reloads on file changes — edit an agent, re-run `curl`, see your change.
+
+```bash
+flue dev --target node          # Node.js dev server
+flue dev --target cloudflare    # Cloudflare Workers (via wrangler) dev server
+```
+
+Defaults to port `3583` ("FLUE" on a phone keypad). Override with `--port`.
+
+`flue dev --target cloudflare` requires `wrangler` as a peer dependency in your project (`npm install --save-dev wrangler`).
+
+#### Loading environment variables
+
+Pass `--env <path>` to load a `.env`-format file. Works for both targets:
+
+```bash
+flue dev --target node --env .env
+flue dev --target cloudflare --env .env
+```
+
+Repeatable; later files override earlier ones on key collision. Shell-set env vars win over file values. Edits to the file trigger a reload. Same flag works for `flue run`.
+
+### Trigger From the CLI (`flue run`)
+
+Build and run any agent locally, perfect for running in CI or for one-shot scripted invocations. Production-shaped — builds the deployable artifact and starts it once.
 
 ```bash
 flue run hello --target node --id test-1 \
   --payload '{"text": "Hello world", "language": "French"}'
 ```
 
-### Trigger From HTTP Endpoint
+### Trigger From HTTP Endpoint (`flue build`)
 
 Build and deploy your agents as a web server, perfect for hosted agents.
 
-`flue build` builds to a `./dist` directory, which you can then deploy anywhere. Cloudflare and any Node.js host are supported today, with more coming in the future.
+`flue build` builds to a `./dist` directory, which you can then deploy. Cloudflare and any Node.js host are supported today, with more coming in the future.
 
 ```
-flue build --target node          # Node.js server
+flue build --target node          # Node.js server (single bundled .mjs)
 flue build --target cloudflare    # Cloudflare Workers + Durable Objects
 ```
+
+For Cloudflare, `flue build` produces an unbundled TypeScript entry that `wrangler deploy` bundles itself — the same path `flue dev --target cloudflare` uses. Dev and deploy go through the same bundler, so what works in dev will work in production.

package/dist/agent-BB4lwAd5.mjs

@@ -0,0 +1,453 @@
+import { Type } from "@mariozechner/pi-ai";
+
+//#region src/context.ts
+/** Parse optional YAML frontmatter (--- delimited). Basic `key: value` only. */
+function parseFrontmatterFile(content, defaultName) {
+	const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+	if (!frontmatterMatch) return {
+		name: defaultName,
+		description: "",
+		body: content.trim(),
+		frontmatter: {}
+	};
+	const rawFrontmatter = frontmatterMatch[1] ?? "";
+	const body = frontmatterMatch[2] ?? "";
+	const frontmatter = {};
+	for (const line of rawFrontmatter.split("\n")) {
+		const match = line.match(/^(\w+):\s*(.+)$/);
+		if (match?.[1] && match[2]) frontmatter[match[1]] = match[2].trim();
+	}
+	return {
+		name: frontmatter.name || defaultName,
+		description: frontmatter.description || "",
+		body: body.trim(),
+		frontmatter
+	};
+}
+/** Read AGENTS.md (and CLAUDE.md if present) from a directory. Returns concatenated contents. */
+async function readAgentsMd(env, basePath) {
+	const parts = [];
+	for (const filename of ["AGENTS.md", "CLAUDE.md"]) {
+		const filePath = basePath.endsWith("/") ? basePath + filename : `${basePath}/${filename}`;
+		if (await env.exists(filePath)) {
+			const content = await env.readFile(filePath);
+			parts.push(content.trim());
+		}
+	}
+	return parts.join("\n\n");
+}
+/**
+* Load a skill directly by relative path under `.agents/skills/`.
+*
+* The path is taken as-is — no extension is auto-appended. Callers reference
+* the full filename, e.g. `'triage/reproduce.md'`. Returns `null` if the file
+* doesn't exist.
+*
+* Used as a fallback by `session.skill()` when the requested name doesn't match
+* a discovered skill's frontmatter `name:` field. Lets users organise skills as
+* a pack of sibling markdown files under one directory (orchestration SKILL.md
+* + stage files) without forcing each stage into its own `SKILL.md` subdirectory.
+*/
+async function loadSkillByPath(env, basePath, relPath) {
+	const filePath = `${basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`}/${relPath}`;
+	if (!await env.exists(filePath)) return null;
+	const parsed = parseFrontmatterFile(await env.readFile(filePath), relPath.replace(/\.(md|markdown)$/i, ""));
+	return {
+		name: parsed.name,
+		description: parsed.description,
+		instructions: parsed.body
+	};
+}
+/** Discover skills from .agents/skills/<name>/SKILL.md under basePath. */
+async function discoverLocalSkills(env, basePath) {
+	const skillsDir = basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`;
+	if (!await env.exists(skillsDir)) return {};
+	const skills = {};
+	const entries = await env.readdir(skillsDir);
+	for (const entry of entries) {
+		const skillDir = `${skillsDir}/${entry}`;
+		try {
+			if (!(await env.stat(skillDir)).isDirectory) continue;
+		} catch {
+			continue;
+		}
+		const skillMdPath = `${skillDir}/SKILL.md`;
+		if (!await env.exists(skillMdPath)) continue;
+		const parsed = parseFrontmatterFile(await env.readFile(skillMdPath), entry);
+		skills[parsed.name] = {
+			name: parsed.name,
+			description: parsed.description,
+			instructions: parsed.body
+		};
+	}
+	return skills;
+}
+function composeSystemPrompt(agentsMd, skills, env) {
+	const parts = [];
+	if (agentsMd) parts.push(agentsMd);
+	const skillEntries = Object.values(skills);
+	if (skillEntries.length > 0) {
+		parts.push("", "## Available Skills", "");
+		for (const skill of skillEntries) {
+			const desc = skill.description ? ` - ${skill.description}` : "";
+			parts.push(`- **${skill.name}**${desc}`);
+		}
+	}
+	if (env) {
+		const date = (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+			weekday: "short",
+			year: "numeric",
+			month: "short",
+			day: "numeric"
+		});
+		parts.push("", `Date: ${date}`);
+		parts.push(`Working directory: ${env.cwd}`);
+		if (env.directoryListing && env.directoryListing.length > 0) parts.push("", "Directory structure:", env.directoryListing.join("\n"));
+	}
+	return parts.join("\n");
+}
+/** Discover AGENTS.md, local skills, and directory listing from the session's cwd. */
+async function discoverSessionContext(env) {
+	const cwd = env.cwd;
+	const agentsMd = await readAgentsMd(env, cwd);
+	const skills = await discoverLocalSkills(env, cwd);
+	let directoryListing;
+	try {
+		directoryListing = await env.readdir(cwd);
+	} catch {}
+	return {
+		systemPrompt: composeSystemPrompt(agentsMd, skills, {
+			cwd,
+			directoryListing
+		}),
+		skills
+	};
+}
+
+//#endregion
+//#region src/agent.ts
+const MAX_READ_LINES = 2e3;
+const MAX_READ_BYTES = 50 * 1024;
+const MAX_GREP_MATCHES = 100;
+const MAX_GREP_LINE_LENGTH = 500;
+const MAX_GLOB_RESULTS = 1e3;
+const BUILTIN_TOOL_NAMES = new Set([
+	"read",
+	"write",
+	"edit",
+	"bash",
+	"grep",
+	"glob",
+	"task"
+]);
+function createTools(env, options) {
+	const tools = [
+		createReadTool(env),
+		createWriteTool(env),
+		createEditTool(env),
+		createBashTool(env),
+		createGrepTool(env),
+		createGlobTool(env)
+	];
+	if (options?.task) tools.push(createTaskTool(options.task, options.roles ?? {}));
+	return tools;
+}
+function createReadTool(env) {
+	return {
+		name: "read",
+		label: "Read File",
+		description: "Read a file or list a directory. For files, output is truncated to 2000 lines or 50KB — use offset/limit for large files. For directories, returns the list of entries.",
+		parameters: Type.Object({
+			path: Type.String({ description: "Path to the file to read" }),
+			offset: Type.Optional(Type.Number({ description: "Line number to start from (1-indexed)" })),
+			limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			try {
+				if ((await env.stat(params.path)).isDirectory) {
+					const entries = await env.readdir(params.path);
+					return {
+						content: [{
+							type: "text",
+							text: entries.join("\n") || "(empty directory)"
+						}],
+						details: {
+							path: params.path,
+							isDirectory: true,
+							entries: entries.length
+						}
+					};
+				}
+			} catch {}
+			const allLines = (await env.readFile(params.path)).split("\n");
+			const startLine = params.offset ? Math.max(0, params.offset - 1) : 0;
+			if (startLine >= allLines.length) throw new Error(`Offset ${params.offset} is beyond end of file (${allLines.length} lines total)`);
+			const endLine = params.limit ? startLine + params.limit : allLines.length;
+			const { text: truncatedText, wasTruncated } = truncateHead(allLines.slice(startLine, endLine), MAX_READ_LINES, MAX_READ_BYTES);
+			let output = truncatedText;
+			if (wasTruncated) {
+				const shownEnd = startLine + truncatedText.split("\n").length;
+				output += `\n\n[Showing lines ${startLine + 1}-${shownEnd} of ${allLines.length}. Use offset=${shownEnd + 1} to continue.]`;
+			}
+			return {
+				content: [{
+					type: "text",
+					text: output
+				}],
+				details: {
+					path: params.path,
+					lines: allLines.length
+				}
+			};
+		}
+	};
+}
+function createWriteTool(env) {
+	return {
+		name: "write",
+		label: "Write File",
+		description: "Write content to a file. Creates the file and parent directories if they do not exist.",
+		parameters: Type.Object({
+			path: Type.String({ description: "Path to the file to write" }),
+			content: Type.String({ description: "Content to write to the file" })
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const resolved = env.resolvePath(params.path);
+			const dir = resolved.replace(/\/[^/]*$/, "");
+			if (dir && dir !== resolved) await env.mkdir(dir, { recursive: true });
+			await env.writeFile(resolved, params.content);
+			return {
+				content: [{
+					type: "text",
+					text: `Successfully wrote ${params.content.length} bytes to ${params.path}`
+				}],
+				details: {
+					path: params.path,
+					size: params.content.length
+				}
+			};
+		}
+	};
+}
+function createEditTool(env) {
+	return {
+		name: "edit",
+		label: "Edit File",
+		description: "Edit a file using exact text replacement. The oldText must match a unique region of the file. Use replaceAll to replace all occurrences.",
+		parameters: Type.Object({
+			path: Type.String({ description: "Path to the file to edit" }),
+			oldText: Type.String({ description: "Exact text to find (must be unique)" }),
+			newText: Type.String({ description: "Replacement text" }),
+			replaceAll: Type.Optional(Type.Boolean({ description: "Replace all occurrences" }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const content = await env.readFile(params.path);
+			if (params.replaceAll) {
+				const newContent = content.replaceAll(params.oldText, params.newText);
+				if (newContent === content) throw new Error(`Could not find the text in ${params.path}. No changes made.`);
+				await env.writeFile(params.path, newContent);
+				const count = content.split(params.oldText).length - 1;
+				return {
+					content: [{
+						type: "text",
+						text: `Replaced ${count} occurrences in ${params.path}`
+					}],
+					details: {
+						path: params.path,
+						replacements: count
+					}
+				};
+			}
+			const occurrences = countOccurrences(content, params.oldText);
+			if (occurrences === 0) throw new Error(`Could not find the exact text in ${params.path}. Make sure your oldText matches exactly, including whitespace and indentation.`);
+			if (occurrences > 1) throw new Error(`Found ${occurrences} occurrences of the text in ${params.path}. Provide more surrounding context to make the match unique, or use replaceAll.`);
+			const newContent = content.replace(params.oldText, params.newText);
+			await env.writeFile(params.path, newContent);
+			return {
+				content: [{
+					type: "text",
+					text: `Successfully edited ${params.path}`
+				}],
+				details: { path: params.path }
+			};
+		}
+	};
+}
+function createBashTool(env) {
+	return {
+		name: "bash",
+		label: "Run Command",
+		description: "Execute a bash command. Returns stdout and stderr. Output is truncated to the last 2000 lines or 50KB.",
+		parameters: Type.Object({
+			command: Type.String({ description: "Bash command to execute" }),
+			timeout: Type.Optional(Type.Number({ description: "Timeout in seconds" }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			return formatBashResult(await env.exec(params.command), params.command);
+		}
+	};
+}
+function createTaskTool(runTask, roles) {
+	const roleNames = Object.keys(roles);
+	return {
+		name: "task",
+		label: "Run Task",
+		description: "Delegate a focused task to a detached child agent with its own context. Use this for independent research, file exploration, or parallel work. The task returns only its final answer to this conversation." + (roleNames.length > 0 ? ` Available roles: ${roleNames.join(", ")}.` : " No roles are currently defined."),
+		parameters: Type.Object({
+			description: Type.Optional(Type.String({ description: "Short human-readable label for the delegated work" })),
+			prompt: Type.String({ description: "Focused instructions for the child agent" }),
+			role: Type.Optional(Type.String({ description: "Role to use for the child agent" })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for the child agent. AGENTS.md and skills are discovered from here." }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			return runTask(params, signal);
+		}
+	};
+}
+function formatBashResult(result, command) {
+	const { text: output } = truncateTail((result.stdout + (result.stderr ? "\n" + result.stderr : "")).trim(), MAX_READ_LINES, MAX_READ_BYTES);
+	if (result.exitCode !== 0) throw new Error(`${output}\n\nCommand exited with code ${result.exitCode}`);
+	return {
+		content: [{
+			type: "text",
+			text: output || "(no output)"
+		}],
+		details: {
+			command,
+			exitCode: result.exitCode
+		}
+	};
+}
+function createGrepTool(env) {
+	return {
+		name: "grep",
+		label: "Search Files",
+		description: "Search file contents for a regex pattern. Returns matching lines with file paths and line numbers.",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "Search pattern (regex)" }),
+			path: Type.Optional(Type.String({ description: "Directory or file to search (default: .)" })),
+			include: Type.Optional(Type.String({ description: "Glob filter, e.g. \"*.ts\"" }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const searchPath = params.path || ".";
+			let cmd = `grep -rn "${escapeShellArg(params.pattern)}" ${escapeShellArg(searchPath)}`;
+			if (params.include) cmd = `grep -rn --include="${escapeShellArg(params.include)}" "${escapeShellArg(params.pattern)}" ${escapeShellArg(searchPath)}`;
+			const result = await env.exec(cmd);
+			if (result.exitCode === 1 && !result.stdout.trim()) return {
+				content: [{
+					type: "text",
+					text: "No matches found."
+				}],
+				details: { matchCount: 0 }
+			};
+			if (result.exitCode > 1) throw new Error(`grep failed: ${result.stderr}`);
+			const lines = result.stdout.trim().split("\n");
+			let finalOutput = lines.slice(0, MAX_GREP_MATCHES).map((line) => line.length > MAX_GREP_LINE_LENGTH ? line.slice(0, MAX_GREP_LINE_LENGTH) + "..." : line).join("\n");
+			if (lines.length > MAX_GREP_MATCHES) finalOutput += `\n\n[Showing ${MAX_GREP_MATCHES} of ${lines.length} matches. Narrow your search.]`;
+			return {
+				content: [{
+					type: "text",
+					text: finalOutput
+				}],
+				details: { matchCount: Math.min(lines.length, MAX_GREP_MATCHES) }
+			};
+		}
+	};
+}
+function createGlobTool(env) {
+	return {
+		name: "glob",
+		label: "Find Files",
+		description: "Find files by glob pattern. Returns matching file paths.",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "Glob pattern, e.g. \"**/*.ts\"" }),
+			path: Type.Optional(Type.String({ description: "Directory to search in (default: .)" }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const cmd = `find ${escapeShellArg(params.path || ".")} -type f -name "${escapeShellArg(params.pattern)}" 2>/dev/null | head -${MAX_GLOB_RESULTS}`;
+			const result = await env.exec(cmd);
+			if (result.exitCode !== 0 && !result.stdout.trim()) return {
+				content: [{
+					type: "text",
+					text: "No files found matching pattern."
+				}],
+				details: { matchCount: 0 }
+			};
+			const paths = result.stdout.trim().split("\n").filter(Boolean);
+			if (paths.length === 0) return {
+				content: [{
+					type: "text",
+					text: "No files found matching pattern."
+				}],
+				details: { matchCount: 0 }
+			};
+			return {
+				content: [{
+					type: "text",
+					text: paths.join("\n")
+				}],
+				details: { matchCount: paths.length }
+			};
+		}
+	};
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw new Error("Operation aborted");
+}
+function countOccurrences(str, substr) {
+	let count = 0;
+	let pos = str.indexOf(substr, 0);
+	while (pos !== -1) {
+		count++;
+		pos = str.indexOf(substr, pos + substr.length);
+	}
+	return count;
+}
+function escapeShellArg(arg) {
+	return arg.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+function truncateHead(lines, maxLines, maxBytes) {
+	let result = "";
+	let lineCount = 0;
+	let wasTruncated = false;
+	for (const line of lines) {
+		if (lineCount >= maxLines) {
+			wasTruncated = true;
+			break;
+		}
+		const next = lineCount === 0 ? line : "\n" + line;
+		if (result.length + next.length > maxBytes) {
+			wasTruncated = true;
+			break;
+		}
+		result += next;
+		lineCount++;
+	}
+	return {
+		text: result,
+		wasTruncated
+	};
+}
+function truncateTail(text, maxLines, maxBytes) {
+	const lines = text.split("\n");
+	if (lines.length <= maxLines && text.length <= maxBytes) return {
+		text,
+		wasTruncated: false
+	};
+	let result = lines.slice(-maxLines).join("\n");
+	if (result.length > maxBytes) result = result.slice(-maxBytes);
+	return {
+		text: result,
+		wasTruncated: true
+	};
+}
+
+//#endregion
+export { parseFrontmatterFile as a, loadSkillByPath as i, createTools as n, discoverSessionContext as r, BUILTIN_TOOL_NAMES as t };

package/dist/client.d.mts

@@ -0,0 +1,26 @@
+import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, p as FlueContext, r as AgentInit, t as AgentConfig, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-T8pE1xIS.mjs";
+import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-BVF-sOBZ.mjs";
+import { Type } from "@mariozechner/pi-ai";
+
+//#region src/client.d.ts
+interface FlueContextConfig {
+  id: string;
+  payload: any;
+  env: Record<string, any>;
+  agentConfig: AgentConfig;
+  createDefaultEnv: () => Promise<SessionEnv>;
+  createLocalEnv: () => Promise<SessionEnv>;
+  defaultStore: SessionStore;
+  /**
+   * Platform-specific sandbox resolver hook. Called before default resolution.
+   * Returns SessionEnv to use, or null to fall through to default logic.
+   */
+  resolveSandbox?: (sandbox: unknown) => Promise<SessionEnv> | null;
+}
+/** Extends FlueContext with server-only methods. Agent handlers only see FlueContext. */
+interface FlueContextInternal extends FlueContext {
+  setEventCallback(callback: FlueEventCallback | undefined): void;
+}
+declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
+//#endregion
+export { type AgentInit, type BashFactory, type BashLike, type Command, type FileStat, type FlueAgent, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type McpServerConnection, type McpServerOptions, type McpTransport, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, Type, connectMcpServer, createFlueContext };

package/dist/client.mjs

@@ -0,0 +1,78 @@
+import { r as discoverSessionContext } from "./agent-BB4lwAd5.mjs";
+import { a as assertRoleExists } from "./session-DukL3zwF.mjs";
+import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
+import { n as AgentClient, t as connectMcpServer } from "./mcp-DOgMtp8y.mjs";
+import { Type } from "@mariozechner/pi-ai";
+
+//#region src/client.ts
+function createFlueContext(config) {
+	let currentEventCallback;
+	const initializedAgentIds = /* @__PURE__ */ new Set();
+	return {
+		get id() {
+			return config.id;
+		},
+		get payload() {
+			return config.payload;
+		},
+		get env() {
+			return config.env;
+		},
+		async init(options) {
+			const id = options?.id ?? config.id;
+			if (initializedAgentIds.has(id)) throw new Error(`[flue] init() has already been called for agent "${id}" in this request.`);
+			initializedAgentIds.add(id);
+			try {
+				assertRoleExists(config.agentConfig.roles, options?.role);
+				const sandbox = options?.sandbox;
+				const baseEnv = await resolveSessionEnv(id, sandbox, config, options?.cwd);
+				const env = options?.cwd ? createCwdSessionEnv(baseEnv, options.cwd) : baseEnv;
+				const store = options?.persist ?? config.defaultStore;
+				const localContext = await discoverSessionContext(env);
+				const agentModel = options?.model && config.agentConfig.resolveModel ? config.agentConfig.resolveModel(options.model) : config.agentConfig.model;
+				return new AgentClient(id, {
+					...config.agentConfig,
+					systemPrompt: localContext.systemPrompt,
+					skills: localContext.skills,
+					model: agentModel,
+					role: options?.role ?? config.agentConfig.role
+				}, env, store, currentEventCallback, options?.commands, options?.tools);
+			} catch (error) {
+				initializedAgentIds.delete(id);
+				throw error;
+			}
+		},
+		setEventCallback(callback) {
+			currentEventCallback = callback;
+		}
+	};
+}
+/** Duck-type detection for just-bash Bash instances. */
+function isBashLike(value) {
+	return 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";
+}
+function isBashFactory(value) {
+	return typeof value === "function";
+}
+function isSandboxFactory(value) {
+	return typeof value === "object" && value !== null && "createSessionEnv" in value && typeof value.createSessionEnv === "function";
+}
+/** Resolve sandbox option to SessionEnv: empty → local → BashFactory → platform hook → SandboxFactory. */
+async function resolveSessionEnv(id, sandbox, config, cwd) {
+	if (sandbox === void 0 || sandbox === "empty") return config.createDefaultEnv();
+	if (sandbox === "local") return config.createLocalEnv();
+	if (isBashFactory(sandbox)) return bashFactoryToSessionEnv(sandbox);
+	if (isBashLike(sandbox)) throw new Error("[flue] init({ sandbox }) no longer accepts a Bash-like object directly. Pass a BashFactory instead, e.g. `sandbox: () => new Bash({ fs })`.");
+	if (config.resolveSandbox) {
+		const resolved = await config.resolveSandbox(sandbox);
+		if (resolved) return resolved;
+	}
+	if (isSandboxFactory(sandbox)) return sandbox.createSessionEnv({
+		id,
+		cwd
+	});
+	throw new Error("[flue] Invalid sandbox option passed to init().");
+}
+
+//#endregion
+export { Type, connectMcpServer, createFlueContext };

package/dist/cloudflare/index.d.mts

@@ -0,0 +1,35 @@
+import { C as SessionEnv, T as SessionStore, l as Command } from "../types-T8pE1xIS.mjs";
+import { t as CommandExecutor } from "../command-helpers-DdAfbnom.mjs";
+
+//#region src/cloudflare/virtual-sandbox.d.ts
+interface VirtualSandboxOptions {
+  /** R2 key prefix for session isolation. */
+  prefix?: string;
+}
+declare function getVirtualSandbox(): Promise<any>;
+declare function getVirtualSandbox(bucket: unknown, options?: VirtualSandboxOptions): Promise<any>;
+//#endregion
+//#region src/cloudflare/define-command.d.ts
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+//#endregion
+//#region src/cloudflare/cf-sandbox.d.ts
+declare function cfSandboxToSessionEnv(sandbox: any, cwd?: string): Promise<SessionEnv>;
+//#endregion
+//#region src/cloudflare/session-store.d.ts
+declare function store(): SessionStore;
+//#endregion
+//#region src/cloudflare/context.d.ts
+interface CloudflareContext {
+  env: Record<string, any>;
+  agentInstance: {
+    state: any;
+    setState(state: any): void;
+  };
+  storage: {
+    sql: any;
+  };
+}
+declare function runWithCloudflareContext<T>(ctx: CloudflareContext, fn: () => T): T;
+declare function getCloudflareContext(): CloudflareContext;
+//#endregion
+export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, defineCommand, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };