@flue/sdk 0.1.3 → 0.2.0

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-BZPltYah.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

package/dist/cloudflare/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SessionStore, b as SessionEnv, s as Command } from "../types-BZPltYah.mjs";
-import { t as CommandExecutor } from "../command-helpers-BPcSV93o.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 {

package/dist/{command-helpers-BPcSV93o.d.mts → command-helpers-C8SHLdaA.d.mts}

@@ -1,4 +1,4 @@
-import { w as ShellResult } from "./types-BZPltYah.mjs";
+import { w as ShellResult } from "./types-C0nqbu6Z.mjs";
 
 //#region src/command-helpers.d.ts
 /**

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-BZPltYah.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-BZPltYah.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/node/index.d.mts

@@ -1,5 +1,5 @@
-import { s as Command } from "../types-BZPltYah.mjs";
-import { t as CommandExecutor } from "../command-helpers-BPcSV93o.mjs";
+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

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-BZPltYah.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/{types-BZPltYah.d.mts → types-C0nqbu6Z.d.mts}

@@ -322,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. */
@@ -334,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.3",
+  "version": "0.2.0",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -43,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"