@flue/sdk 0.1.2 → 0.2.0

package/README.md

@@ -94,9 +94,8 @@ A triage agent that runs in CI whenever an issue is opened on GitHub. The `"loca
 
 ```ts
 // .flue/agents/triage.ts
-import { defineCommand, type FlueContext } from '@flue/sdk/client';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { type FlueContext } from '@flue/sdk/client';
+import { defineCommand } from '@flue/sdk/node';
 import * as v from 'valibot';
 
 // Because we are running this in CI, we don't need to expose this as an HTTP endpoint.
@@ -106,12 +105,8 @@ export const triggers = {};
 // Connect privileged CLIs to your agent without leaking sensitive keys and secrets.
 // Secrets are hooked up inside the command definition here, so your agent never sees them.
 // Commands are controlled per-prompt, so you can be as granular with access as you need.
-const npm = defineCommand('npm', async (args) => promisify(execFile)('npm', args));
-const gh = defineCommand('gh', async (args) =>
-  promisify(execFile)('gh', args, {
-    env: { GH_TOKEN: process.env.GH_TOKEN },
-  }),
-);
+const npm = defineCommand('npm');
+const gh = defineCommand('gh', { env: { GH_TOKEN: process.env.GH_TOKEN } });
 
 export default async function ({ init, payload }: FlueContext) {
   // 'local' mounts the host filesystem at /workspace — ideal for CI

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C0nqbu6Z.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts
@@ -21,10 +21,5 @@ interface FlueContextInternal extends FlueContext {
   setEventCallback(callback: FlueEventCallback | undefined): void;
 }
 declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
-declare function defineCommand(name: string, execute: (args: string[]) => Promise<{
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}>): Command;
 //#endregion
-export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, createFlueContext, defineCommand };
+export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, createFlueContext };

package/dist/client.mjs

@@ -1,5 +1,5 @@
 import { r as discoverSessionContext } from "./agent-BYG0nVbQ.mjs";
-import { n as Session } from "./session-BRLCNVG1.mjs";
+import { n as Session } from "./session-CiAMTsLZ.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
@@ -32,7 +32,7 @@ function createFlueContext(config) {
 				skills: localContext.skills,
 				model: sessionModel
 			};
-			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback);
+			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback, options?.commands);
 		},
 		setEventCallback(callback) {
 			currentEventCallback = callback;
@@ -54,12 +54,6 @@ async function resolveSessionEnv(sessionId, sandbox, config) {
 	}
 	return sandbox.createSessionEnv({ sessionId });
 }
-function defineCommand(name, execute) {
-	return {
-		name,
-		execute
-	};
-}
 
 //#endregion
-export { Type, createFlueContext, defineCommand };
+export { Type, createFlueContext };

package/dist/cloudflare/index.d.mts

@@ -1,4 +1,5 @@
-import { S as SessionStore, b as SessionEnv } from "../types-C8tsaK1j.mjs";
+import { S as SessionStore, b as SessionEnv, s as Command } from "../types-C0nqbu6Z.mjs";
+import { t as CommandExecutor } from "../command-helpers-C8SHLdaA.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {
@@ -8,6 +9,9 @@ interface VirtualSandboxOptions {
 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
@@ -33,4 +37,4 @@ declare function setCloudflareContext(ctx: CloudflareContext): void;
 declare function getCloudflareContext(): CloudflareContext;
 declare function clearCloudflareContext(): void;
 //#endregion
-export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };

package/dist/cloudflare/index.mjs

@@ -1,6 +1,7 @@
 import "../agent-BYG0nVbQ.mjs";
-import "../session-BRLCNVG1.mjs";
+import "../session-CiAMTsLZ.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
+import { t as normalizeExecutor } from "../command-helpers-CxRhK1my.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
 
 //#region src/cloudflare/context.ts
@@ -105,6 +106,28 @@ async function getVirtualSandbox(bucket, options) {
 	});
 }
 
+//#endregion
+//#region src/cloudflare/define-command.ts
+/**
+* Cloudflare-specific `defineCommand`. Function form only — Workers cannot
+* spawn host processes, so there is no pass-through sugar. The user supplies
+* an executor (typically `fetch`-based or SDK-based) and benefits from
+* return-shape normalization plus automatic throw-catching.
+*
+* ```ts
+* const issues = defineCommand('issues', async (args) => {
+*   const res = await fetch(`https://api.github.com/...`);
+*   return { stdout: await res.text() };
+* });
+* ```
+*/
+function defineCommand(name, execute) {
+	return {
+		name,
+		execute: normalizeExecutor(execute)
+	};
+}
+
 //#endregion
 //#region src/cloudflare/cf-sandbox.ts
 /** Wraps a @cloudflare/sandbox instance (from getSandbox()) into SessionEnv. */
@@ -204,4 +227,4 @@ function store() {
 }
 
 //#endregion
-export { cfSandboxToSessionEnv, clearCloudflareContext, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };

package/dist/command-helpers-C8SHLdaA.d.mts

@@ -0,0 +1,21 @@
+import { w as ShellResult } from "./types-C0nqbu6Z.mjs";
+
+//#region src/command-helpers.d.ts
+/**
+ * Loose return shape accepted from user-supplied command executors. All forms
+ * are normalized to a full `ShellResult` by `normalizeExecutor()`.
+ */
+type CommandExecutorResult = ShellResult | {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+} | string | void;
+/**
+ * User-supplied command executor. Can return a full `ShellResult`, a partial
+ * `{ stdout?, stderr?, exitCode? }` object, a bare string (treated as stdout),
+ * or void (empty success). Thrown errors are caught and converted to an
+ * `exitCode`-bearing `ShellResult` — no `try`/`catch` needed at the call site.
+ */
+type CommandExecutor = (args: string[]) => Promise<CommandExecutorResult>;
+//#endregion
+export { CommandExecutor as t };

package/dist/command-helpers-CxRhK1my.mjs

@@ -0,0 +1,37 @@
+//#region src/command-helpers.ts
+/**
+* Wrap a user-supplied `CommandExecutor` to always resolve with a full
+* `ShellResult`. Applies loose-return normalization and catches throws.
+*/
+function normalizeExecutor(executor) {
+	return async (args) => {
+		try {
+			const raw = await executor(args);
+			if (raw === void 0 || raw === null) return {
+				stdout: "",
+				stderr: "",
+				exitCode: 0
+			};
+			if (typeof raw === "string") return {
+				stdout: raw,
+				stderr: "",
+				exitCode: 0
+			};
+			return {
+				stdout: raw.stdout ?? "",
+				stderr: raw.stderr ?? "",
+				exitCode: raw.exitCode ?? 0
+			};
+		} catch (err) {
+			const e = err ?? {};
+			return {
+				stdout: typeof e.stdout === "string" ? e.stdout : "",
+				stderr: typeof e.stderr === "string" ? e.stderr : String(err),
+				exitCode: typeof e.code === "number" ? e.code : 1
+			};
+		}
+	};
+}
+
+//#endregion
+export { normalizeExecutor as t };

package/dist/index.d.mts

@@ -1,15 +1,35 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C0nqbu6Z.mjs";
 import { AgentTool } from "@mariozechner/pi-agent-core";
 
 //#region src/build.d.ts
 /**
  * Build a workspace into a deployable artifact.
+ *
+ * `options.workspaceDir` is treated as an explicit workspace root — the directory
+ * directly containing agents/ and roles/. No .flue/ waterfall is performed here;
+ * callers that want waterfall behavior (e.g. the CLI when --workspace is omitted)
+ * should use `resolveWorkspaceFromCwd` first.
+ *
  * AGENTS.md and .agents/skills/ are NOT bundled — discovered at runtime from session cwd.
  */
 declare function build(options: BuildOptions): Promise<void>;
+/**
+ * Resolve a Flue workspace directory from the current working directory,
+ * using the two-layout convention. Intended for the CLI when `--workspace` is
+ * not provided — callers that pass an explicit workspace path should skip this
+ * and pass the path straight to `build()`.
+ *
+ * Two supported layouts, checked in order:
+ *   1. `<cwd>/.flue/` — use this when Flue is embedded in an existing project.
+ *   2. `<cwd>/` — use this when the project itself is the Flue workspace.
+ *
+ * If `.flue/` exists, it wins unconditionally — no mixing with the bare layout.
+ * Returns null if neither is present so the caller can produce a helpful error.
+ */
+declare function resolveWorkspaceFromCwd(cwd: string): string | null;
 //#endregion
 //#region src/agent.d.ts
 declare const BUILTIN_TOOL_NAMES: Set<string>;
 declare function createTools(env: SessionEnv): AgentTool<any>[];
 //#endregion
-export { type AgentConfig, type AgentInfo, BUILTIN_TOOL_NAMES, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, type CommandSupport, type FileStat, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, build, createTools };
+export { type AgentConfig, type AgentInfo, BUILTIN_TOOL_NAMES, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, type CommandSupport, type FileStat, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, build, createTools, resolveWorkspaceFromCwd };

package/dist/index.mjs

@@ -3,7 +3,189 @@ import * as esbuild from "esbuild";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { packageUpSync } from "package-up";
+import { parse } from "jsonc-parser";
 
+//#region src/cloudflare-wrangler-merge.ts
+/**
+* Merge Flue's Cloudflare additions into the user's wrangler config.
+*
+* Philosophy: the user's wrangler.jsonc is the source of truth. Flue contributes
+* the pieces it owns (the Worker entrypoint, its per-agent Durable Object
+* bindings, the Sandbox DO, the migration tag) and leaves everything else
+* untouched. The merged result is written to `dist/wrangler.jsonc` so the
+* deployed Worker sees both.
+*
+* We use `jsonc-parser` (the same library wrangler uses internally) for
+* reading. TOML is intentionally unsupported — Cloudflare itself recommends
+* wrangler.jsonc for new projects, and supporting both formats here would
+* double the surface area for no real benefit. Users with wrangler.toml get a
+* clear error directing them to convert.
+*/
+/** Minimum compatibility_date Flue supports. */
+const MIN_COMPATIBILITY_DATE = "2024-04-03";
+/** compatibility_flag Flue requires for pi-ai's process.env-based API key lookup. */
+const REQUIRED_COMPAT_FLAG = "nodejs_compat";
+/**
+* Read the user's wrangler config from `outputDir` if present.
+*
+* Looks for `wrangler.jsonc` then `wrangler.json` (in that order — jsonc is the
+* recommended format). If a `wrangler.toml` is present instead, throws with a
+* clear conversion hint. Returns an empty config if no file is present.
+*/
+function readUserWranglerConfig(outputDir) {
+	const jsoncPath = path.join(outputDir, "wrangler.jsonc");
+	const jsonPath = path.join(outputDir, "wrangler.json");
+	const tomlPath = path.join(outputDir, "wrangler.toml");
+	const foundPath = fs.existsSync(jsoncPath) ? jsoncPath : fs.existsSync(jsonPath) ? jsonPath : null;
+	if (!foundPath) {
+		if (fs.existsSync(tomlPath)) throw new Error(`[flue] Found wrangler.toml at ${tomlPath}. Flue only supports wrangler.jsonc (the format Cloudflare recommends for new projects). Convert your config to wrangler.jsonc — you can use any online TOML-to-JSON converter, or copy the fields over by hand.`);
+		return {
+			config: {},
+			path: null
+		};
+	}
+	const source = fs.readFileSync(foundPath, "utf-8");
+	const errors = [];
+	const parsed = parse(source, errors, { allowTrailingComma: true });
+	if (errors.length > 0) {
+		const summary = errors.slice(0, 3).map((e) => `offset ${e.offset}: error code ${e.error}`).join("; ");
+		throw new Error(`[flue] Failed to parse ${foundPath}: ${summary}. Please fix syntax errors in your wrangler config before building.`);
+	}
+	if (parsed === void 0 || parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`[flue] ${foundPath} did not contain a JSON object at the top level. A wrangler config must be an object.`);
+	return {
+		config: parsed,
+		path: foundPath
+	};
+}
+/**
+* Validate that the user's wrangler config meets Flue's minimum runtime
+* requirements. Throws a clear error describing the fix if it doesn't.
+*
+* We're intentionally strict here rather than silently massaging bad configs —
+* the failure modes when these are wrong (missing nodejs_compat, old
+* compat_date) produce confusing runtime errors, and surfacing the problem at
+* build time is much friendlier.
+*/
+function validateUserWranglerConfig(config) {
+	if (Array.isArray(config.compatibility_flags)) {
+		if (!config.compatibility_flags.includes(REQUIRED_COMPAT_FLAG)) throw new Error(`[flue] Your wrangler config's "compatibility_flags" is missing "${REQUIRED_COMPAT_FLAG}". Flue relies on it at runtime (e.g. for API key resolution via process.env). Add "${REQUIRED_COMPAT_FLAG}" to the list.`);
+	}
+	if (typeof config.compatibility_date === "string") {
+		const userDate = config.compatibility_date;
+		if (!/^\d{4}-\d{2}-\d{2}$/.test(userDate)) throw new Error(`[flue] Your wrangler config's "compatibility_date" ("${userDate}") is not in YYYY-MM-DD format.`);
+		if (userDate < MIN_COMPATIBILITY_DATE) throw new Error(`[flue] Your wrangler config's "compatibility_date" is "${userDate}". Flue requires at least "${MIN_COMPATIBILITY_DATE}" for SQLite-backed Durable Object support and nodejs_compat v2. Bump the date (set it to today unless you have a specific reason).`);
+	}
+}
+/**
+* Produce the merged wrangler config: start from the user's, layer Flue's
+* contributions on top. Pure function — caller handles reading and writing.
+*/
+function mergeFlueAdditions(userConfig, additions) {
+	const merged = { ...userConfig };
+	merged.main = additions.main;
+	if (typeof merged.name !== "string" || merged.name.length === 0) merged.name = additions.defaultName;
+	if (typeof merged.compatibility_date !== "string") merged.compatibility_date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+	const existingFlags = Array.isArray(merged.compatibility_flags) ? merged.compatibility_flags.filter((f) => typeof f === "string") : [];
+	if (!existingFlags.includes(REQUIRED_COMPAT_FLAG)) existingFlags.push(REQUIRED_COMPAT_FLAG);
+	merged.compatibility_flags = existingFlags;
+	const existingDo = typeof merged.durable_objects === "object" && merged.durable_objects !== null ? merged.durable_objects : {};
+	const existingBindings = Array.isArray(existingDo.bindings) ? existingDo.bindings : [];
+	const existingBindingNames = new Set(existingBindings.filter((b) => typeof b === "object" && b !== null).map((b) => b.name).filter((n) => typeof n === "string"));
+	const flueBindingsToAdd = additions.doBindings.filter((b) => !existingBindingNames.has(b.name));
+	merged.durable_objects = {
+		...existingDo,
+		bindings: [...existingBindings, ...flueBindingsToAdd]
+	};
+	const existingMigrations = Array.isArray(merged.migrations) ? merged.migrations : [];
+	const existingMigrationTags = new Set(existingMigrations.filter((m) => typeof m === "object" && m !== null).map((m) => m.tag).filter((t) => typeof t === "string"));
+	const migrationsOut = [...existingMigrations];
+	if (!existingMigrationTags.has(additions.migration.tag)) migrationsOut.push(additions.migration);
+	merged.migrations = migrationsOut;
+	return merged;
+}
+/**
+* Return the list of `class_name`s declared in the user's wrangler
+* `durable_objects.bindings` that contain the literal substring `Sandbox`
+* (case-sensitive).
+*
+* This is Flue's convention for wiring `@cloudflare/sandbox`: any DO binding
+* whose class name contains `Sandbox` triggers an automatic re-export in the
+* generated Worker entry:
+*
+*   export { Sandbox as <class_name> } from '@cloudflare/sandbox';
+*
+* The alias lets users pick arbitrary class names (e.g. `PyBoxSandbox`,
+* `SupportSandbox`) while still pointing at the single class shipped by the
+* `@cloudflare/sandbox` package. Each distinct `class_name` can be paired with
+* a different container image in the user's `containers[]` config.
+*
+* Returns unique, sorted class names. Non-object bindings or bindings without
+* a string `class_name` are ignored.
+*/
+function detectSandboxBindings(userConfig) {
+	const doObj = userConfig.durable_objects;
+	if (typeof doObj !== "object" || doObj === null) return [];
+	const bindings = doObj.bindings;
+	if (!Array.isArray(bindings)) return [];
+	const found = /* @__PURE__ */ new Set();
+	for (const entry of bindings) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const className = entry.class_name;
+		if (typeof className !== "string") continue;
+		if (className.includes("Sandbox")) found.add(className);
+	}
+	return Array.from(found).sort();
+}
+/**
+* When the user has declared one or more `Sandbox`-named DO bindings, verify
+* that `@cloudflare/sandbox` is declared in the nearest package.json. Surfaces
+* a friendly, actionable error at build time rather than letting esbuild emit
+* a confusing module-resolution failure.
+*
+* The check is lenient: if no package.json can be located or parsed, we skip
+* silently and let esbuild's own error path take over. This avoids false
+* positives in unusual project layouts.
+*/
+function assertSandboxPackageInstalled(sandboxClassNames, searchDirs) {
+	if (sandboxClassNames.length === 0) return;
+	for (const dir of searchDirs) {
+		let current = dir;
+		while (current !== path.dirname(current)) {
+			const pkgPath = path.join(current, "package.json");
+			if (fs.existsSync(pkgPath)) try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+				if ("@cloudflare/sandbox" in {
+					...pkg.dependencies ?? {},
+					...pkg.devDependencies ?? {},
+					...pkg.peerDependencies ?? {},
+					...pkg.optionalDependencies ?? {}
+				}) return;
+			} catch {
+				return;
+			}
+			current = path.dirname(current);
+		}
+	}
+	throw new Error(`[flue] Your wrangler config declares DO binding(s) whose class_name contains "Sandbox" (${sandboxClassNames.join(", ")}), but @cloudflare/sandbox is not in your package.json. Install it: \`npm install @cloudflare/sandbox\`.`);
+}
+/**
+* Write the wrangler deploy-redirect file at `<outputDir>/.wrangler/deploy/config.json`
+* so that `wrangler deploy` run from `outputDir` automatically picks up the
+* generated `dist/wrangler.jsonc`.
+*
+* This is wrangler's own native redirection mechanism (the same one Astro's
+* Cloudflare adapter uses). We only write the file if one doesn't already
+* exist — if the user has set one up, respect their intent.
+*/
+function writeDeployRedirectIfMissing(outputDir) {
+	const redirectDir = path.join(outputDir, ".wrangler", "deploy");
+	const redirectPath = path.join(redirectDir, "config.json");
+	if (fs.existsSync(redirectPath)) return;
+	fs.mkdirSync(redirectDir, { recursive: true });
+	fs.writeFileSync(redirectPath, JSON.stringify({ configPath: "../../dist/wrangler.jsonc" }, null, 2) + "\n", "utf-8");
+}
+
+//#endregion
 //#region src/build-plugin-cloudflare.ts
 var CloudflarePlugin = class {
 	name = "cloudflare";
@@ -11,6 +193,23 @@ var CloudflarePlugin = class {
 		const { agents, roles } = ctx;
 		const rolesJson = JSON.stringify(roles);
 		const webhookAgents = agents.filter((a) => a.triggers.webhook);
+		const agentImports = agents.map((a) => {
+			return `import ${agentVarName$1(a.name)} from '${a.filePath.replace(/\\/g, "/")}';`;
+		}).join("\n");
+		const manifest = JSON.stringify({ agents: agents.map((a) => ({
+			name: a.name,
+			triggers: a.triggers
+		})) }, null, 2);
+		const agentClasses = webhookAgents.map((a) => {
+			const className = agentClassName(a.name);
+			const handlerVar = agentVarName$1(a.name);
+			return `export class ${className} extends Agent {
+  async onRequest(request) {
+    return handleAgentRequest(request, this, ${JSON.stringify(a.name)}, ${handlerVar});
+  }
+}`;
+		}).join("\n\n");
+		const { config: userConfig } = readUserWranglerConfig(ctx.outputDir);
 		return `
 // Auto-generated by @flue/sdk build (cloudflare)
 import { Agent, routeAgentRequest } from 'agents';
@@ -19,19 +218,14 @@ import { getModel } from '@mariozechner/pi-ai';
 import { createFlueContext, InMemorySessionStore, bashToSessionEnv } from '@flue/sdk/internal';
 import { setCloudflareContext, clearCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
 
-${agents.map((a) => {
-			return `import ${agentVarName$1(a.name)} from '${a.filePath.replace(/\\/g, "/")}';`;
-		}).join("\n")}
+${agentImports}
 
 // ─── Config ─────────────────────────────────────────────────────────────────
 
 const roles = ${rolesJson};
 const skills = {};
 const systemPrompt = '';
-const manifest = ${JSON.stringify({ agents: agents.map((a) => ({
-			name: a.name,
-			triggers: a.triggers
-		})) }, null, 2)};
+const manifest = ${manifest};
 
 // ─── Infrastructure ─────────────────────────────────────────────────────────
 
@@ -81,13 +275,15 @@ async function createLocalEnv() {
   throw new Error(
     "[flue] 'local' sandbox is not supported on Cloudflare Workers. " +
     "Use the default empty sandbox, pass a custom Bash instance, " +
-    "or use getSandbox() from @cloudflare/sandbox for container sandboxes."
+    "or pass a sandbox instance (from any SDK — e.g. @cloudflare/sandbox " +
+    "or a Flue connector) to init({ sandbox })."
   );
 }
 
 /**
- * Detect and wrap @cloudflare/sandbox instances (from getSandbox()).
- * Returns SessionEnv if the sandbox is a CF sandbox, null otherwise.
+ * Detect and wrap external sandbox instances (e.g. from @cloudflare/sandbox's
+ * getSandbox()). Returns SessionEnv if the object quacks like a container
+ * sandbox, null otherwise.
  */
 function resolveSandbox(sandbox) {
   if (
@@ -265,18 +461,15 @@ async function handleAgentRequest(request, doInstance, agentName, handler) {
 
 // ─── Per-Agent Durable Object Classes ──────────────────────────────────────
 
-${webhookAgents.map((a) => {
-			const className = agentClassName(a.name);
-			const handlerVar = agentVarName$1(a.name);
-			return `export class ${className} extends Agent {
-  async onRequest(request) {
-    return handleAgentRequest(request, this, ${JSON.stringify(a.name)}, ${handlerVar});
-  }
-}`;
-		}).join("\n\n")}
+${agentClasses}
 
-// Re-export Sandbox DO class for wrangler binding
-export { Sandbox } from '@cloudflare/sandbox';
+// ─── User-declared Sandbox re-exports ──────────────────────────────────────
+// One line per DO binding in the user's wrangler.jsonc whose class_name
+// contains "Sandbox". Flue aliases the single \`Sandbox\` class shipped by
+// \`@cloudflare/sandbox\` so each user-chosen class_name resolves at the
+// bundle's top level. The binding + container image configuration is owned
+// by the user's wrangler.jsonc.
+${detectSandboxBindings(userConfig).map((name) => `export { Sandbox as ${name} } from '@cloudflare/sandbox';`).join("\n")}
 
 // ─── Worker Fetch Handler ───────────────────────────────────────────────────
 
@@ -311,51 +504,42 @@ export default {
 	esbuildOptions(_ctx) {
 		return {
 			target: "esnext",
-			external: ["node:*", "cloudflare:*"]
+			external: [
+				"node:*",
+				"cloudflare:*",
+				"node-liblzma",
+				"@mongodb-js/zstd"
+			]
 		};
 	}
 	additionalOutputs(ctx) {
 		const outputs = {};
-		const allBindings = [...ctx.agents.filter((a) => a.triggers.webhook).map((a) => ({
+		const flueBindings = ctx.agents.filter((a) => a.triggers.webhook).map((a) => ({
 			class_name: agentClassName(a.name),
 			name: agentClassName(a.name)
-		})), {
-			class_name: "Sandbox",
-			name: "Sandbox"
-		}];
-		const allSqliteClasses = allBindings.map((b) => b.class_name);
-		const workerName = ctx.agentDir.split("/").pop() ?? "flue-agents";
-		outputs["wrangler.jsonc"] = JSON.stringify({
-			$schema: "https://workers.cloudflare.com/schema/wrangler.json",
-			name: workerName,
+		}));
+		const flueSqliteClasses = flueBindings.map((b) => b.class_name);
+		const additions = {
+			defaultName: ctx.outputDir.split("/").pop() ?? "flue-agents",
 			main: "server.mjs",
-			compatibility_date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
-			compatibility_flags: ["nodejs_compat"],
-			containers: [{
-				class_name: "Sandbox",
-				image: "./Dockerfile"
-			}],
-			durable_objects: { bindings: allBindings },
-			migrations: [{
-				new_sqlite_classes: allSqliteClasses,
-				tag: "v1"
-			}]
-		}, null, 2);
-		outputs["Dockerfile"] = [
-			"FROM node:22-slim",
-			"",
-			"# Install common tools for agent sandboxes",
-			"RUN apt-get update && apt-get install -y \\",
-			"    git curl wget \\",
-			"    python3 python3-pip \\",
-			"    && rm -rf /var/lib/apt/lists/*",
-			"",
-			"WORKDIR /workspace",
-			"",
-			"# Keep container alive",
-			"CMD [\"sleep\", \"infinity\"]",
-			""
-		].join("\n");
+			doBindings: flueBindings,
+			migration: {
+				tag: "flue-v1",
+				new_sqlite_classes: flueSqliteClasses
+			}
+		};
+		const { config: userConfig, path: userConfigPath } = readUserWranglerConfig(ctx.outputDir);
+		if (userConfigPath) console.log(`[flue] Merging with user wrangler config: ${userConfigPath}`);
+		validateUserWranglerConfig(userConfig);
+		const sandboxClassNames = detectSandboxBindings(userConfig);
+		if (sandboxClassNames.length > 0) {
+			assertSandboxPackageInstalled(sandboxClassNames, [ctx.outputDir, ctx.workspaceDir]);
+			for (const className of sandboxClassNames) console.log(`[flue] Detected Sandbox-named DO binding "${className}" — re-exporting from @cloudflare/sandbox.`);
+		}
+		const merged = mergeFlueAdditions(userConfig, additions);
+		if (typeof merged.$schema !== "string") merged.$schema = "https://workers.cloudflare.com/schema/wrangler.json";
+		outputs["wrangler.jsonc"] = JSON.stringify(merged, null, 2);
+		writeDeployRedirectIfMissing(ctx.outputDir);
 		return outputs;
 	}
 };
@@ -609,7 +793,8 @@ process.on('SIGTERM', () => { server.close(); process.exit(0); });
 	esbuildOptions(_ctx) {
 		return {
 			platform: "node",
-			target: "node22"
+			target: "node22",
+			external: ["node-liblzma", "@mongodb-js/zstd"]
 		};
 	}
 };
@@ -621,16 +806,24 @@ function agentVarName(name) {
 //#region src/build.ts
 /**
 * Build a workspace into a deployable artifact.
+*
+* `options.workspaceDir` is treated as an explicit workspace root — the directory
+* directly containing agents/ and roles/. No .flue/ waterfall is performed here;
+* callers that want waterfall behavior (e.g. the CLI when --workspace is omitted)
+* should use `resolveWorkspaceFromCwd` first.
+*
 * AGENTS.md and .agents/skills/ are NOT bundled — discovered at runtime from session cwd.
 */
 async function build(options) {
-	const agentDir = path.resolve(options.agentDir);
+	const workspaceDir = path.resolve(options.workspaceDir);
+	const outputDir = path.resolve(options.outputDir);
 	const plugin = resolvePlugin(options);
-	console.log(`[flue] Building workspace: ${agentDir}`);
+	console.log(`[flue] Building workspace: ${workspaceDir}`);
+	console.log(`[flue] Output: ${outputDir}/dist`);
 	console.log(`[flue] Target: ${plugin.name}`);
-	const roles = discoverRoles(agentDir);
-	const agents = discoverAgents(agentDir);
-	if (agents.length === 0) throw new Error(`No agents found in ${path.join(agentDir, ".flue/agents/")}`);
+	const roles = discoverRoles(workspaceDir);
+	const agents = discoverAgents(workspaceDir);
+	if (agents.length === 0) throw new Error(`[flue] No agent files found.\n\nExpected at: ${path.join(workspaceDir, "agents")}/\nAdd at least one agent file (e.g. hello.ts).`);
 	const webhookAgents = agents.filter((a) => a.triggers.webhook);
 	const cronAgents = agents.filter((a) => a.triggers.cron);
 	const triggerlessAgents = agents.filter((a) => !a.triggers.webhook && !a.triggers.cron);
@@ -640,7 +833,7 @@ async function build(options) {
 	if (cronAgents.length > 0) console.log(`[flue] Cron agents (manifest only): ${cronAgents.map((a) => `${a.name} (${a.triggers.cron})`).join(", ")}`);
 	if (triggerlessAgents.length > 0) console.log(`[flue] CLI-only agents (no HTTP route in deployed build): ${triggerlessAgents.map((a) => a.name).join(", ")}`);
 	console.log(`[flue] AGENTS.md and .agents/skills/ will be discovered at runtime from session cwd`);
-	const distDir = path.join(agentDir, "dist");
+	const distDir = path.join(outputDir, "dist");
 	fs.mkdirSync(distDir, { recursive: true });
 	const manifest = { agents: agents.map((a) => ({
 		name: a.name,
@@ -652,7 +845,8 @@ async function build(options) {
 	const ctx = {
 		agents,
 		roles,
-		agentDir,
+		workspaceDir,
+		outputDir,
 		options
 	};
 	const serverCode = plugin.generateEntryPoint(ctx);
@@ -660,9 +854,9 @@ async function build(options) {
 	const outPath = path.join(distDir, "server.mjs");
 	fs.writeFileSync(entryPath, serverCode, "utf-8");
 	try {
-		const nodePathsSet = collectNodePaths(agentDir);
+		const nodePathsSet = collectNodePaths(workspaceDir);
 		const { external: pluginExternal = [], ...pluginEsbuildOpts } = plugin.esbuildOptions(ctx);
-		const userExternals = getUserExternals(agentDir);
+		const userExternals = getUserExternals(workspaceDir);
 		await esbuild.build({
 			entryPoints: [entryPath],
 			bundle: true,
@@ -705,8 +899,27 @@ function resolvePlugin(options) {
 		default: throw new Error(`[flue] Unknown target: "${options.target}". Supported targets: node, cloudflare`);
 	}
 }
-function discoverRoles(agentDir) {
-	const rolesDir = path.join(agentDir, ".flue", "roles");
+/**
+* Resolve a Flue workspace directory from the current working directory,
+* using the two-layout convention. Intended for the CLI when `--workspace` is
+* not provided — callers that pass an explicit workspace path should skip this
+* and pass the path straight to `build()`.
+*
+* Two supported layouts, checked in order:
+*   1. `<cwd>/.flue/` — use this when Flue is embedded in an existing project.
+*   2. `<cwd>/` — use this when the project itself is the Flue workspace.
+*
+* If `.flue/` exists, it wins unconditionally — no mixing with the bare layout.
+* Returns null if neither is present so the caller can produce a helpful error.
+*/
+function resolveWorkspaceFromCwd(cwd) {
+	const dotFlue = path.join(cwd, ".flue");
+	if (fs.existsSync(dotFlue)) return dotFlue;
+	if (fs.existsSync(path.join(cwd, "agents"))) return cwd;
+	return null;
+}
+function discoverRoles(workspaceRoot) {
+	const rolesDir = path.join(workspaceRoot, "roles");
 	if (!fs.existsSync(rolesDir)) return {};
 	const roles = {};
 	for (const entry of fs.readdirSync(rolesDir)) {
@@ -724,12 +937,9 @@ function discoverRoles(agentDir) {
 	}
 	return roles;
 }
-function discoverAgents(agentDir) {
-	let agentsDir = path.join(agentDir, ".flue", "agents");
-	if (!fs.existsSync(agentsDir)) {
-		agentsDir = path.join(agentDir, ".flue", "workflows");
-		if (!fs.existsSync(agentsDir)) return [];
-	}
+function discoverAgents(workspaceRoot) {
+	const agentsDir = path.join(workspaceRoot, "agents");
+	if (!fs.existsSync(agentsDir)) return [];
 	return fs.readdirSync(agentsDir).filter((f) => /\.(ts|js|mts|mjs)$/.test(f)).map((f) => {
 		const filePath = path.join(agentsDir, f);
 		const triggers = parseTriggers(filePath);
@@ -753,8 +963,8 @@ function parseTriggers(filePath) {
 	return result;
 }
 /** Externalize user's direct deps (bare name + subpath wildcard). */
-function getUserExternals(agentDir) {
-	const pkgPath = packageUpSync({ cwd: agentDir });
+function getUserExternals(workspaceDir) {
+	const pkgPath = packageUpSync({ cwd: workspaceDir });
 	if (!pkgPath) return [];
 	try {
 		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -767,9 +977,9 @@ function getUserExternals(agentDir) {
 		return [];
 	}
 }
-function collectNodePaths(agentDir) {
+function collectNodePaths(workspaceDir) {
 	const nodePathsSet = /* @__PURE__ */ new Set();
-	for (const startDir of [agentDir, getSDKDir()]) {
+	for (const startDir of [workspaceDir, getSDKDir()]) {
 		let dir = startDir;
 		while (dir !== path.dirname(dir)) {
 			const nm = path.join(dir, "node_modules");
@@ -788,4 +998,4 @@ function getSDKDir() {
 }
 
 //#endregion
-export { BUILTIN_TOOL_NAMES, build, createTools };
+export { BUILTIN_TOOL_NAMES, build, createTools, resolveWorkspaceFromCwd };

package/dist/internal.d.mts

@@ -1,4 +1,4 @@
-import { S as SessionStore, y as SessionData } from "./types-C8tsaK1j.mjs";
+import { S as SessionStore, y as SessionData } from "./types-C0nqbu6Z.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import "valibot";

package/dist/internal.mjs

@@ -1,5 +1,5 @@
 import "./agent-BYG0nVbQ.mjs";
-import { t as InMemorySessionStore } from "./session-BRLCNVG1.mjs";
+import { t as InMemorySessionStore } from "./session-CiAMTsLZ.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import { createFlueContext } from "./client.mjs";
 

package/dist/node/index.d.mts

@@ -0,0 +1,14 @@
+import { s as Command } from "../types-C0nqbu6Z.mjs";
+import { t as CommandExecutor } from "../command-helpers-C8SHLdaA.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-CxRhK1my.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

@@ -1,4 +1,4 @@
-import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-C8tsaK1j.mjs";
+import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-C0nqbu6Z.mjs";
 
 //#region src/sandbox.d.ts
 declare function bashToSessionEnv(bash: BashLike): SessionEnv;

package/dist/sandbox.mjs

@@ -1,5 +1,5 @@
 import "./agent-BYG0nVbQ.mjs";
-import { r as normalizePath } from "./session-BRLCNVG1.mjs";
+import { r as normalizePath } from "./session-CiAMTsLZ.mjs";
 
 //#region src/sandbox.ts
 function bashToSessionEnv(bash) {

package/dist/{session-BRLCNVG1.mjs → session-CiAMTsLZ.mjs}

@@ -508,11 +508,13 @@ var Session = class Session {
 	compactionAbortController;
 	eventCallback;
 	builtinTools;
-	constructor(id, config, env, store, existingData, onAgentEvent) {
+	sessionCommands;
+	constructor(id, config, env, store, existingData, onAgentEvent, sessionCommands) {
 		this.id = id;
 		this.config = config;
 		this.env = env;
 		this.store = store;
+		this.sessionCommands = sessionCommands ?? [];
 		this.metadata = existingData?.metadata ?? {};
 		this.createdAt = existingData?.createdAt;
 		this.lastCompaction = existingData?.lastCompaction;
@@ -586,8 +588,9 @@ var Session = class Session {
 		const promptWithRole = this.injectRoleInstructions(text, options?.role);
 		const schema = options?.result;
 		const fullPrompt = buildPromptText(promptWithRole, schema);
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredCommandNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredCommandNames = this.registerCommands(effectiveCommands);
 		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
 		try {
 			await this.agent.prompt(fullPrompt);
@@ -616,8 +619,9 @@ var Session = class Session {
 		const schema = options?.result;
 		const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
 		const promptWithRole = this.injectRoleInstructions(skillPrompt, options?.role);
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredCommandNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredCommandNames = this.registerCommands(effectiveCommands);
 		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
 		try {
 			await this.agent.prompt(promptWithRole);
@@ -632,8 +636,9 @@ var Session = class Session {
 		}
 	}
 	async shell(command, options) {
-		if (options?.commands) this.assertCommandSupport(options.commands);
-		const registeredNames = options?.commands ? this.registerCommands(options.commands) : [];
+		const effectiveCommands = this.mergeCommands(options?.commands);
+		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
+		const registeredNames = this.registerCommands(effectiveCommands);
 		try {
 			const result = await this.env.exec(command, {
 				env: options?.env,
@@ -750,6 +755,19 @@ var Session = class Session {
 		if (commands.length === 0) return;
 		if (!this.env.commandSupport) throw new Error("[flue] Cannot use commands: this environment does not support command registration. Commands are only available in isolate sandbox mode. Remote sandboxes handle command execution at the platform level.");
 	}
+	/**
+	* Merge session-wide `commands` (from init()) with per-call commands. When
+	* both define a command with the same name, the per-call entry wins for
+	* that call.
+	*/
+	mergeCommands(perCall) {
+		if (!perCall || perCall.length === 0) return this.sessionCommands;
+		if (this.sessionCommands.length === 0) return perCall;
+		const byName = /* @__PURE__ */ new Map();
+		for (const cmd of this.sessionCommands) byName.set(cmd.name, cmd);
+		for (const cmd of perCall) byName.set(cmd.name, cmd);
+		return Array.from(byName.values());
+	}
 	registerCommands(commands) {
 		if (!this.env.commandSupport || commands.length === 0) return [];
 		const names = [];

package/dist/{types-C8tsaK1j.d.mts → types-C0nqbu6Z.d.mts}

@@ -146,6 +146,13 @@ interface SessionInit {
    * Precedence (highest wins): per-call `model` > role `model` > session `model` > build-time default.
    */
   model?: string;
+  /**
+   * Session-wide commands. Every prompt(), skill(), and shell() call inherits
+   * this list. Per-call `commands` are merged on top — if a per-call command
+   * shares a name with a session command, the per-call version wins for that
+   * call.
+   */
+  commands?: Command[];
 }
 interface FlueSession {
   prompt<S extends v.GenericSchema>(text: string, options: PromptOptions<S> & {
@@ -315,7 +322,10 @@ interface AgentInfo {
 interface BuildContext {
   agents: AgentInfo[];
   roles: Record<string, Role>;
-  agentDir: string;
+  /** The workspace root: the directory directly containing agents/ and roles/. */
+  workspaceDir: string;
+  /** Where dist/ is written. Typically the project root, independent of workspaceDir. */
+  outputDir: string;
   options: BuildOptions;
 }
 /** Controls the build output format for a target platform. */
@@ -327,7 +337,19 @@ interface BuildPlugin {
   additionalOutputs?(ctx: BuildContext): Record<string, string>;
 }
 interface BuildOptions {
-  agentDir: string;
+  /**
+   * The workspace directory: the directory directly containing agents/ and
+   * roles/. Pass an explicit path — no .flue/ waterfall is performed here.
+   * Callers that want the waterfall behavior (e.g. the CLI when --workspace
+   * is omitted) should resolve it themselves with `resolveWorkspaceFromCwd`.
+   */
+  workspaceDir: string;
+  /**
+   * Where to write the dist/ directory. Independent of workspaceDir — typically
+   * the project root, so platform config like wrangler.jsonc ends up where the
+   * deploy tool expects it.
+   */
+  outputDir: string;
   target?: 'node' | 'cloudflare';
   /** Overrides `target` when provided. */
   plugin?: BuildPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -23,6 +23,10 @@
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.mts",
       "import": "./dist/cloudflare/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.mts",
+      "import": "./dist/node/index.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -39,6 +43,7 @@
     "agentfs-sdk": "^0.6.4",
     "esbuild": "^0.25.0",
     "hono": "^4.7.0",
+    "jsonc-parser": "^3.3.1",
     "just-bash": "^2.14.2",
     "package-up": "^5.0.0",
     "valibot": "^1.0.0"