@flue/sdk 0.3.0 → 0.3.2

package/dist/index.mjs

@@ -0,0 +1,1664 @@
+import { a as parseFrontmatterFile, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BB4lwAd5.mjs";
+import * as esbuild from "esbuild";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { packageUpSync } from "package-up";
+import { spawn } from "node:child_process";
+import { parseEnv } from "node:util";
+
+//#region src/cloudflare-wrangler-merge.ts
+/**
+* Merge Flue's Cloudflare additions into the user's wrangler config.
+*
+* Philosophy: the user's wrangler config 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 delegate parsing and normalization to wrangler's own `unstable_readConfig`
+* (lazy-imported so Node-only Flue users don't pay for it). This gets us:
+*   - Both jsonc and TOML support for free.
+*   - Wrangler's own validation diagnostics (clearer errors than ours).
+*   - Path normalization: relative paths in fields like `containers[].image`
+*     are resolved to absolute paths against the user's config dir before
+*     we merge. This is critical because we write the merged config to
+*     `dist/wrangler.jsonc` — wrangler resolves relative paths against the
+*     config file's own directory, so without normalization a user's
+*     `containers[].image: "./Dockerfile"` would resolve to `dist/Dockerfile`
+*     after the move and fail to deploy.
+*
+* Flue still owns merge semantics (DO binding de-dup by `name`, migration
+* append-if-tag-absent) and Flue-specific validation (compat date floor,
+* required compat flags) — wrangler doesn't know about those.
+*/
+/** Minimum compatibility_date Flue supports. */
+const MIN_COMPATIBILITY_DATE = "2026-04-01";
+/** compatibility_flag Flue requires for pi-ai's process.env-based API key lookup. */
+const REQUIRED_COMPAT_FLAG = "nodejs_compat";
+/**
+* Read and normalize the user's wrangler config from `outputDir`.
+*
+* Looks for `wrangler.jsonc`, `wrangler.json`, then `wrangler.toml` (jsonc is
+* Cloudflare's recommended format for new projects, but all three work).
+* Returns an empty config if no file is present.
+*
+* Delegates parsing + normalization to wrangler via `unstable_readConfig`. This
+* is async only because wrangler is a lazy import (it's a peer dep — Flue users
+* who only target Node should not pay for resolving it). The wrangler call
+* itself is synchronous under the hood.
+*
+* The returned config has been through wrangler's `normalizeAndValidateConfig`,
+* which:
+*   - Resolves relative paths to absolute (notably `containers[].image`).
+*   - Fills in defaults (`compatibility_date` if absent, etc.).
+*   - Merges `env.*` per-environment overrides.
+*   - Throws on validation errors via wrangler's own `UserError`.
+*
+* The verbose / defaulted output is intentional — the cost is a slightly bigger
+* `dist/wrangler.jsonc` and the benefit is correctness without us reimplementing
+* wrangler's path-resolution logic.
+*/
+async function readUserWranglerConfig(outputDir) {
+	const candidates = [
+		"wrangler.jsonc",
+		"wrangler.json",
+		"wrangler.toml"
+	];
+	let foundPath = null;
+	for (const name of candidates) {
+		const candidate = path.join(outputDir, name);
+		if (fs.existsSync(candidate)) {
+			foundPath = candidate;
+			break;
+		}
+	}
+	if (!foundPath) return {
+		config: {},
+		path: null
+	};
+	let wrangler;
+	try {
+		wrangler = await import("wrangler");
+	} catch (err) {
+		throw new Error(`[flue] Reading the Cloudflare wrangler config requires the "wrangler" package as a peer dependency.
+Install it in your project:
+
+  npm install --save-dev wrangler
+
+Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = wrangler.unstable_readConfig({ config: foundPath }, { hideWarnings: true });
+	} catch (err) {
+		throw new Error(`[flue] Failed to read ${foundPath}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	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.
+*
+* Together with `mergeFlueAdditions`, this enforces two invariants on every
+* Flue worker:
+*   1. `nodejs_compat` is in `compatibility_flags` (added if missing).
+*   2. `compatibility_date >= MIN_COMPATIBILITY_DATE` (defaulted if missing).
+*
+* Those invariants are what let `dev.ts` hardcode `nodejsCompatMode: 'v2'`
+* without re-deriving it from the config on every reload.
+*/
+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, nodejs_compat v2, and AsyncLocalStorage. 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 = MIN_COMPATIBILITY_DATE;
+	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;
+}
+/**
+* Strip wrangler-normalizer defaults that cause spurious warnings when wrangler
+* re-parses our generated dist/wrangler.jsonc.
+*
+* Background: `unstable_readConfig` returns a fully-normalized `Unstable_Config`
+* with every section populated to a default — including `unsafe: {}`. Wrangler's
+* own validator then emits a `"unsafe" fields are experimental` warning whenever
+* the field is *present*, regardless of whether it's empty. So our merged file,
+* which inherits the empty default, would trip the warning at every dev start
+* and every deploy.
+*
+* We delete `unsafe` only when it's an empty object (the exact shape wrangler's
+* normalizer produces). If a user has actually written `unsafe: {...}` in their
+* own wrangler.jsonc, the value will be non-empty and we leave it alone — the
+* warning in that case is wrangler's intended diagnostic, not noise.
+*
+* Other normalizer-defaulted-empty fields (`vars: {}`, `kv_namespaces: []`,
+* `python_modules: { exclude: ['**\/*.pyc'] }`, etc.) are left in place. They're
+* harmless: wrangler doesn't warn about them, dist/wrangler.jsonc is an
+* internal build artifact, and stripping them only saves bytes. Only `unsafe`
+* has a user-visible side effect we need to fix.
+*
+* If wrangler adds another field to its `experimental()` warning list in a
+* future version (today there are only two: `unsafe` and `secrets`), this
+* function is the place to extend.
+*
+* Mutates `merged` in place to match the shallow-clone pattern in
+* `mergeFlueAdditions`.
+*/
+function stripNoisyWranglerDefaults(merged) {
+	if ("unsafe" in merged && typeof merged.unsafe === "object" && merged.unsafe !== null && !Array.isArray(merged.unsafe) && Object.keys(merged.unsafe).length === 0) delete merged.unsafe;
+}
+/**
+* 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
+/** Cloudflare build plugin. Produces a Worker + DO entry point with SSE/webhook/sync modes. */
+var CloudflarePlugin = class {
+	name = "cloudflare";
+	bundle = "none";
+	entryFilename = "_entry.ts";
+	/**
+	* Per-build cache of the user's wrangler config. Both `generateEntryPoint`
+	* and `additionalOutputs` need it (for sandbox detection + the merge), and
+	* a fresh `CloudflarePlugin` instance is constructed for each build (see
+	* `resolvePlugin` in build.ts), so the cache is implicitly scoped to a
+	* single build.
+	*/
+	userConfigCache;
+	async getUserConfig(outputDir) {
+		if (!this.userConfigCache) this.userConfigCache = await readUserWranglerConfig(outputDir);
+		return this.userConfigCache;
+	}
+	async generateEntryPoint(ctx) {
+		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});
+  }
+
+  async onFiberRecovered(ctx) {
+    if (ctx.name?.startsWith('flue:')) {
+      return handleFlueFiberRecovered(ctx, this, ${JSON.stringify(a.name)});
+    }
+    if (typeof super.onFiberRecovered === 'function') {
+      return super.onFiberRecovered(ctx);
+    }
+  }
+}`;
+		}).join("\n\n");
+		const { config: userConfig } = await this.getUserConfig(ctx.outputDir);
+		return `
+// Auto-generated by @flue/sdk build (cloudflare)
+import { Agent, routeAgentRequest } from 'agents';
+import { Bash, InMemoryFs } from 'just-bash';
+import {
+  createFlueContext,
+  InMemorySessionStore,
+  bashFactoryToSessionEnv,
+  resolveModel,
+} from '@flue/sdk/internal';
+import { runWithCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
+
+${agentImports}
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+const roles = ${rolesJson};
+const skills = {};
+const systemPrompt = '';
+const manifest = ${manifest};
+
+// ─── Infrastructure ─────────────────────────────────────────────────────────
+
+// No build-time model default. The user sets model at runtime via
+// \`init({ model: "provider/model-id" })\` for an agent default, or via
+// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
+const model = undefined;
+
+// ─── Sandbox Environments ───────────────────────────────────────────────────
+
+/**
+ * Create an empty in-memory sandbox (default).
+ */
+async function createDefaultEnv() {
+  const fs = new InMemoryFs();
+  return bashFactoryToSessionEnv(() => new Bash({
+    fs,
+    network: { dangerouslyAllowFullInternetAccess: true },
+  }));
+}
+
+/**
+ * 'local' sandbox is not available on Cloudflare Workers.
+ */
+async function createLocalEnv() {
+  throw new Error(
+    "[flue] 'local' sandbox is not supported on Cloudflare Workers. " +
+    "Use the default empty sandbox, pass a BashFactory, " +
+    "or pass a sandbox instance (from any SDK — e.g. @cloudflare/sandbox " +
+    "or a Flue connector) to init({ sandbox })."
+  );
+}
+
+/**
+ * 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 (
+    sandbox && typeof sandbox === 'object' &&
+    typeof sandbox.exec === 'function' &&
+    typeof sandbox.readFile === 'function' &&
+    typeof sandbox.destroy === 'function' &&
+    !('getCwd' in sandbox) && !('fs' in sandbox)
+  ) {
+    return cfSandboxToSessionEnv(sandbox);
+  }
+  return null;
+}
+
+// Fallback in-memory store (used if no DO storage is available).
+const memoryStore = new InMemorySessionStore();
+
+// Create a DO-backed session store from the Durable Object's SQL storage.
+function createDOStore(sql) {
+  // Ensure the table exists
+  sql.exec(
+    'CREATE TABLE IF NOT EXISTS flue_sessions (id TEXT PRIMARY KEY, data TEXT NOT NULL, updated_at INTEGER NOT NULL)'
+  );
+  return {
+    async save(id, data) {
+      const json = JSON.stringify(data);
+      sql.exec(
+        'INSERT OR REPLACE INTO flue_sessions (id, data, updated_at) VALUES (?, ?, ?)',
+        id, json, Date.now()
+      );
+    },
+    async load(id) {
+      const rows = sql.exec('SELECT data FROM flue_sessions WHERE id = ?', id).toArray();
+      if (rows.length === 0) return null;
+      return JSON.parse(rows[0].data);
+    },
+    async delete(id) {
+      sql.exec('DELETE FROM flue_sessions WHERE id = ?', id);
+    },
+  };
+}
+
+function createContextForRequest(id, payload, doInstance) {
+  // Use DO SQLite storage by default, fall back to in-memory
+  const defaultStore = doInstance?.ctx?.storage?.sql
+    ? createDOStore(doInstance.ctx.storage.sql)
+    : memoryStore;
+
+  return createFlueContext({
+    id,
+    payload,
+    env: doInstance?.env ?? {},
+    agentConfig: {
+      systemPrompt, skills, roles, model, resolveModel,
+    },
+    createDefaultEnv,
+    createLocalEnv,
+    defaultStore,
+    resolveSandbox,
+  });
+}
+
+function runWithInstanceContext(doInstance, fn) {
+  return runWithCloudflareContext(
+    { env: doInstance.env, agentInstance: doInstance, storage: doInstance.ctx.storage },
+    fn,
+  );
+}
+
+function assertAgentsDurabilityApi(doInstance, method) {
+  if (typeof doInstance[method] !== 'function') {
+		throw new Error(
+			'[flue] The installed "agents" package does not provide the required Cloudflare Agents SDK method "' +
+				method +
+				'". Install or upgrade the "agents" package in your project.',
+		);
+	}
+}
+
+function runHandlerWithKeepAlive(doInstance, ctx, handler) {
+  return runWithInstanceContext(doInstance, () => {
+    assertAgentsDurabilityApi(doInstance, 'keepAliveWhile');
+    return doInstance.keepAliveWhile(() => handler(ctx));
+  });
+}
+
+function startWebhookFiber(doInstance, requestId, agentName, id, payload, handler) {
+  const run = async (fiber) => {
+    fiber?.stash?.({
+      version: 1,
+      kind: 'webhook',
+      agentName,
+      id,
+      requestId,
+      phase: 'running',
+      startedAt: Date.now(),
+    });
+
+    const ctx = createContextForRequest(id, payload, doInstance);
+    return runWithInstanceContext(doInstance, async () => {
+      try {
+        return await handler(ctx);
+      } finally {
+        ctx.setEventCallback(undefined);
+      }
+    });
+  };
+
+  assertAgentsDurabilityApi(doInstance, 'runFiber');
+  return doInstance.runFiber('flue:webhook:' + requestId, run);
+}
+
+async function handleFlueFiberRecovered(ctx, _doInstance, agentName) {
+  if (!ctx.name || !ctx.name.startsWith('flue:')) return;
+  console.warn('[flue] Cloudflare fiber interrupted:', agentName, ctx.name, ctx.snapshot ?? null);
+}
+
+// ─── Shared Request Handler ────────────────────────────────────────────────
+
+async function handleAgentRequest(request, doInstance, agentName, handler) {
+  // Agent id is the DO "room name" set by routeAgentRequest
+  const id = doInstance.name;
+
+  // Parse payload
+  let payload;
+  try {
+    payload = await request.json();
+  } catch {
+    payload = {};
+  }
+
+  const accept = request.headers.get('accept') || '';
+  const isWebhook = request.headers.get('x-webhook') === 'true';
+  const isSSE = accept.includes('text/event-stream') && !isWebhook;
+
+  try {
+    // Fire-and-forget (webhook mode)
+    if (isWebhook) {
+      const requestId = crypto.randomUUID();
+      startWebhookFiber(doInstance, requestId, agentName, id, payload, handler).then(
+        (result) => {
+          console.log('[flue] Webhook handler complete:', agentName,
+            result !== undefined ? JSON.stringify(result) : '(no return)');
+        },
+        (err) => {
+          console.error('[flue] Webhook handler error:', agentName, err);
+        },
+      );
+      return new Response(JSON.stringify({ status: 'accepted', requestId }), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+
+    // SSE streaming mode
+    if (isSSE) {
+      const { readable, writable } = new TransformStream();
+      const writer = writable.getWriter();
+      const encoder = new TextEncoder();
+      let eventId = 0;
+      let isIdle = false;
+
+      const writeSSE = async (data, event) => {
+        const lines = [];
+        if (event) lines.push('event: ' + event);
+        lines.push('id: ' + eventId++);
+        lines.push('data: ' + JSON.stringify(data));
+        lines.push('', '');
+        await writer.write(encoder.encode(lines.join('\\n')));
+      };
+
+      const ctx = createContextForRequest(id, payload, doInstance);
+      ctx.setEventCallback((event) => {
+        if (event.type === 'idle') isIdle = true;
+        writeSSE(event, event.type).catch(() => {});
+      });
+
+      (async () => {
+        try {
+          const result = await runHandlerWithKeepAlive(doInstance, ctx, handler);
+          if (!isIdle) {
+            await writeSSE({ type: 'idle' }, 'idle');
+          }
+          await writeSSE(
+            { type: 'result', data: result !== undefined ? result : null },
+            'result',
+          );
+        } catch (err) {
+          await writeSSE(
+            { type: 'error', error: String(err) },
+            'error',
+          );
+          if (!isIdle) {
+            await writeSSE({ type: 'idle' }, 'idle');
+          }
+        } finally {
+          ctx.setEventCallback(undefined);
+          await writer.close();
+        }
+      })();
+
+      return new Response(readable, {
+        headers: {
+          'content-type': 'text/event-stream',
+          'cache-control': 'no-cache',
+          'connection': 'keep-alive',
+        },
+      });
+    }
+
+    // Sync mode (default)
+    const ctx = createContextForRequest(id, payload, doInstance);
+    try {
+      const result = await runHandlerWithKeepAlive(doInstance, ctx, handler);
+      return new Response(
+        JSON.stringify({ result: result !== undefined ? result : null }),
+        { headers: { 'content-type': 'application/json' } },
+      );
+    } finally {
+      ctx.setEventCallback(undefined);
+    }
+  } catch (err) {
+    console.error('[flue] Agent error:', agentName, err);
+    return new Response(
+      JSON.stringify({ error: String(err) }),
+      { status: 500, headers: { 'content-type': 'application/json' } },
+    );
+  }
+}
+
+// ─── Per-Agent Durable Object Classes ──────────────────────────────────────
+
+${agentClasses}
+
+// ─── 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 ───────────────────────────────────────────────────
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    // Health check
+    if (url.pathname === '/health') {
+      return new Response(JSON.stringify({ status: 'ok' }), {
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+
+    // Agent manifest
+    if (url.pathname === '/agents' && request.method === 'GET') {
+      return new Response(JSON.stringify(manifest), {
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+
+    // Route to per-agent DOs via the Agents SDK
+    // URL: /agents/<agent-name>/<id>
+    const response = await routeAgentRequest(request, env);
+    if (response) return response;
+
+    return new Response('Not found', { status: 404 });
+  },
+};
+`;
+	}
+	async additionalOutputs(ctx) {
+		const outputs = {};
+		const flueBindings = ctx.agents.filter((a) => a.triggers.webhook).map((a) => ({
+			class_name: agentClassName(a.name),
+			name: agentClassName(a.name)
+		}));
+		const flueSqliteClasses = flueBindings.map((b) => b.class_name);
+		const additions = {
+			defaultName: path.basename(ctx.outputDir) || "flue-agents",
+			main: "_entry.ts",
+			doBindings: flueBindings,
+			migration: {
+				tag: "flue-v1",
+				new_sqlite_classes: flueSqliteClasses
+			}
+		};
+		const { config: userConfig, path: userConfigPath } = await this.getUserConfig(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);
+		stripNoisyWranglerDefaults(merged);
+		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;
+	}
+};
+function agentVarName$1(name) {
+	return "handler_" + name.replace(/[^a-zA-Z0-9]/g, "_");
+}
+/**
+* Convert agent name to a PascalCase DO class name.
+* "hello" → "Hello", "with-cloudflare" → "WithCloudflare"
+*
+* routeAgentRequest() converts binding names to kebab-case for URL matching,
+* so "WithCloudflare" → "with-cloudflare" → URL /agents/with-cloudflare/:id
+*/
+function agentClassName(name) {
+	return name.split(/[-_]/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+
+//#endregion
+//#region src/build-plugin-node.ts
+var NodePlugin = class {
+	name = "node";
+	bundle = "esbuild";
+	generateEntryPoint(ctx) {
+		const { agents, roles } = ctx;
+		const rolesJson = JSON.stringify(roles);
+		const webhookAgents = agents.filter((a) => a.triggers.webhook);
+		return `
+// Auto-generated by @flue/sdk build (node)
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { serve } from '@hono/node-server';
+import { Bash, InMemoryFs, MountableFs, ReadWriteFs } from 'just-bash';
+import {
+  createFlueContext,
+  InMemorySessionStore,
+  bashFactoryToSessionEnv,
+  resolveModel,
+} from '@flue/sdk/internal';
+import { randomUUID } from 'node:crypto';
+
+${agents.map((a) => {
+			return `import ${agentVarName(a.name)} from '${a.filePath.replace(/\\/g, "/")}';`;
+		}).join("\n")}
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+const skills = {};
+const roles = ${rolesJson};
+const systemPrompt = '';
+
+const handlers = {
+${agents.map((a) => `  ${JSON.stringify(a.name)}: ${agentVarName(a.name)},`).join("\n")}
+};
+
+const webhookAgents = new Set(${JSON.stringify(webhookAgents.map((a) => a.name))});
+
+// When the CLI starts this server via \`flue run\`, it sets FLUE_MODE=local.
+// In local mode the HTTP route accepts any registered agent (including
+// trigger-less CI-only agents). In any other mode the route is restricted to
+// agents with \`webhook: true\`, preventing accidental public exposure of
+// agents that the user only intended to invoke from their CI pipeline.
+const isLocalMode = process.env.FLUE_MODE === 'local';
+
+const manifest = ${JSON.stringify({ agents: agents.map((a) => ({
+			name: a.name,
+			triggers: a.triggers
+		})) }, null, 2)};
+
+// ─── Infrastructure ─────────────────────────────────────────────────────────
+
+// No build-time model default. The user sets model at runtime via
+// \`init({ model: "provider/model-id" })\` for an agent default, or via
+// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
+const model = undefined;
+
+// ─── Sandbox Environments ───────────────────────────────────────────────────
+
+/**
+ * Create an empty in-memory sandbox (default).
+ * Uses InMemoryFs (no real filesystem access) with sensible defaults:
+ * cwd = /home/user, /tmp exists, /bin and /usr/bin exist.
+ */
+async function createDefaultEnv() {
+  const fs = new InMemoryFs();
+  return bashFactoryToSessionEnv(() => new Bash({
+    fs,
+    network: { dangerouslyAllowFullInternetAccess: true },
+  }));
+}
+
+/**
+ * Create a local sandbox backed by the host filesystem.
+ * Mounts process.cwd() at /workspace via ReadWriteFs + MountableFs.
+ */
+async function createLocalEnv() {
+  const rwfs = new ReadWriteFs({ root: process.cwd() });
+  const fs = new MountableFs({ base: new InMemoryFs() });
+  fs.mount('/workspace', rwfs);
+  return bashFactoryToSessionEnv(() => new Bash({
+    fs,
+    cwd: '/workspace',
+    network: { dangerouslyAllowFullInternetAccess: true },
+  }));
+}
+
+// Default persistence store for Node — in-memory, process lifetime.
+const defaultStore = new InMemorySessionStore();
+
+function createContextForRequest(id, payload) {
+  return createFlueContext({
+    id,
+    payload,
+    env: process.env,
+    agentConfig: {
+      systemPrompt, skills, roles, model, resolveModel,
+    },
+    createDefaultEnv,
+    createLocalEnv,
+    defaultStore,
+  });
+}
+
+// ─── Server ─────────────────────────────────────────────────────────────────
+
+const app = new Hono();
+
+app.get('/health', (c) => c.json({ status: 'ok' }));
+app.get('/agents', (c) => c.json(manifest));
+
+// Agent id is required in the URL
+app.post('/agents/:name', (c) => {
+  return c.json({
+    error: 'Agent id is required. Use /agents/:name/:id',
+  }, 400);
+});
+
+app.post('/agents/:name/:id', async (c) => {
+  const name = c.req.param('name');
+  const id = c.req.param('id');
+
+  if (!handlers[name]) {
+    return c.json({ error: 'Agent not found' }, 404);
+  }
+  if (!webhookAgents.has(name) && !isLocalMode) {
+    return c.json({ error: 'Agent "' + name + '" is not web-accessible (no webhook trigger)' }, 404);
+  }
+
+  const handler = handlers[name];
+  let payload;
+  try {
+    payload = await c.req.json();
+  } catch {
+    payload = {};
+  }
+
+  const accept = c.req.header('accept') || '';
+  const isWebhook = c.req.header('x-webhook') === 'true';
+  const isSSE = accept.includes('text/event-stream') && !isWebhook;
+
+  // Fire-and-forget (webhook mode)
+  if (isWebhook) {
+    const requestId = randomUUID();
+    const ctx = createContextForRequest(id, payload);
+    handler(ctx).then(
+      (result) => {
+        ctx.setEventCallback(undefined);
+        console.log('[flue] Webhook handler complete:', name, result !== undefined ? JSON.stringify(result) : '(no return)');
+      },
+      (err) => {
+        ctx.setEventCallback(undefined);
+        console.error('[flue] Webhook handler error:', name, err);
+      },
+    );
+    return c.json({ status: 'accepted', requestId }, 202);
+  }
+
+  // SSE streaming mode
+  if (isSSE) {
+    return streamSSE(c, async (stream) => {
+      let eventId = 0;
+      let isIdle = false;
+      const ctx = createContextForRequest(id, payload);
+      ctx.setEventCallback((event) => {
+        if (event.type === 'idle') isIdle = true;
+        stream.writeSSE({ data: JSON.stringify(event), event: event.type, id: String(eventId++) }).catch(() => {});
+      });
+
+      try {
+        const result = await handler(ctx);
+        if (!isIdle) {
+          const idle = { type: 'idle' };
+          await stream.writeSSE({ data: JSON.stringify(idle), event: 'idle', id: String(eventId++) });
+        }
+        await stream.writeSSE({
+          data: JSON.stringify({ type: 'result', data: result !== undefined ? result : null }),
+          event: 'result',
+          id: String(eventId++),
+        });
+      } catch (err) {
+        await stream.writeSSE({
+          data: JSON.stringify({ type: 'error', error: String(err) }),
+          event: 'error',
+          id: String(eventId++),
+        });
+        if (!isIdle) {
+          const idle = { type: 'idle' };
+          await stream.writeSSE({ data: JSON.stringify(idle), event: 'idle', id: String(eventId++) });
+        }
+      } finally {
+        ctx.setEventCallback(undefined);
+      }
+    });
+  }
+
+  // Sync mode (default)
+  try {
+    const ctx = createContextForRequest(id, payload);
+    const result = await handler(ctx);
+    ctx.setEventCallback(undefined);
+    return c.json({ result: result !== undefined ? result : null });
+  } catch (err) {
+    console.error('[flue] Agent error:', name, err);
+    return c.json({ error: String(err) }, 500);
+  }
+});
+
+// ─── Start ──────────────────────────────────────────────────────────────────
+
+const port = parseInt(process.env.PORT || '3000', 10);
+
+const server = serve({ fetch: app.fetch, port });
+console.log('[flue] Server listening on http://localhost:' + port);
+if (isLocalMode) {
+  console.log('[flue] Mode: local (all agents invokable, including trigger-less)');
+  console.log('[flue] Available agents: ' + ${JSON.stringify(agents.map((a) => a.name).join(", "))});
+} else {
+  console.log('[flue] Available agents: ' + ${JSON.stringify(webhookAgents.map((a) => a.name).join(", "))});
+}
+
+process.on('SIGINT', () => { server.close(); process.exit(0); });
+process.on('SIGTERM', () => { server.close(); process.exit(0); });
+`;
+	}
+	esbuildOptions(_ctx) {
+		return {
+			platform: "node",
+			target: "node22",
+			external: ["node-liblzma", "@mongodb-js/zstd"]
+		};
+	}
+};
+function agentVarName(name) {
+	return "handler_" + name.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+//#endregion
+//#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 workspaceDir = path.resolve(options.workspaceDir);
+	const outputDir = path.resolve(options.outputDir);
+	const plugin = resolvePlugin(options);
+	console.log(`[flue] Building workspace: ${workspaceDir}`);
+	console.log(`[flue] Output: ${outputDir}/dist`);
+	console.log(`[flue] Target: ${plugin.name}`);
+	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);
+	console.log(`[flue] Found ${Object.keys(roles).length} role(s): ${Object.keys(roles).join(", ") || "(none)"}`);
+	console.log(`[flue] Found ${agents.length} agent(s): ${agents.map((a) => a.name).join(", ")}`);
+	if (webhookAgents.length > 0) console.log(`[flue] Webhook agents: ${webhookAgents.map((a) => a.name).join(", ")}`);
+	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(outputDir, "dist");
+	fs.mkdirSync(distDir, { recursive: true });
+	const manifest = { agents: agents.map((a) => ({
+		name: a.name,
+		triggers: a.triggers
+	})) };
+	const manifestPath = path.join(distDir, "manifest.json");
+	fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+	console.log(`[flue] Generated: ${manifestPath}`);
+	const ctx = {
+		agents,
+		roles,
+		workspaceDir,
+		outputDir,
+		options
+	};
+	const serverCode = await plugin.generateEntryPoint(ctx);
+	const bundleStrategy = plugin.bundle ?? "esbuild";
+	let anyChanged = false;
+	if (bundleStrategy === "esbuild") {
+		const entryPath = path.join(distDir, "_entry_server.ts");
+		const outPath = path.join(distDir, "server.mjs");
+		fs.writeFileSync(entryPath, serverCode, "utf-8");
+		try {
+			const nodePathsSet = collectNodePaths(workspaceDir);
+			const { external: pluginExternal = [], ...pluginEsbuildOpts } = plugin.esbuildOptions ? plugin.esbuildOptions(ctx) : {};
+			const userExternals = getUserExternals(workspaceDir);
+			await esbuild.build({
+				entryPoints: [entryPath],
+				bundle: true,
+				outfile: outPath,
+				format: "esm",
+				external: [...pluginExternal, ...userExternals],
+				nodePaths: [...nodePathsSet],
+				logLevel: "warning",
+				loader: {
+					".ts": "ts",
+					".node": "empty"
+				},
+				treeShaking: true,
+				sourcemap: true,
+				...pluginEsbuildOpts
+			});
+			console.log(`[flue] Built: ${outPath}`);
+			anyChanged = true;
+		} finally {
+			try {
+				fs.unlinkSync(entryPath);
+			} catch {}
+		}
+	} else if (bundleStrategy === "none") {
+		if (!plugin.entryFilename) throw new Error(`[flue] Plugin "${plugin.name}" set bundle: 'none' but did not provide entryFilename.`);
+		const outPath = path.join(distDir, plugin.entryFilename);
+		if (!fs.existsSync(outPath) || fs.readFileSync(outPath, "utf-8") !== serverCode) {
+			fs.writeFileSync(outPath, serverCode, "utf-8");
+			console.log(`[flue] Wrote entry: ${outPath} (no bundle — downstream tool handles it)`);
+			anyChanged = true;
+		} else console.log(`[flue] Entry unchanged: ${outPath}`);
+	} else throw new Error(`[flue] Unknown bundle strategy: ${bundleStrategy}`);
+	if (plugin.additionalOutputs) {
+		const outputs = await plugin.additionalOutputs(ctx);
+		for (const [filename, content] of Object.entries(outputs)) {
+			const filePath = path.join(distDir, filename);
+			fs.mkdirSync(path.dirname(filePath), { recursive: true });
+			if (!fs.existsSync(filePath) || fs.readFileSync(filePath, "utf-8") !== content) {
+				fs.writeFileSync(filePath, content, "utf-8");
+				console.log(`[flue] Generated: ${filePath}`);
+				anyChanged = true;
+			}
+		}
+	}
+	console.log(`[flue] Build complete. Output: ${distDir}`);
+	return { changed: anyChanged };
+}
+function resolvePlugin(options) {
+	if (options.plugin) return options.plugin;
+	if (!options.target) throw new Error("[flue] No build target specified. Use --target to choose a target:\n  flue build --target node\n  flue build --target cloudflare");
+	switch (options.target) {
+		case "node": return new NodePlugin();
+		case "cloudflare": return new CloudflarePlugin();
+		default: throw new Error(`[flue] Unknown target: "${options.target}". Supported targets: node, cloudflare`);
+	}
+}
+/**
+* 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)) {
+		if (!/\.(md|markdown)$/i.test(entry)) continue;
+		const filePath = path.join(rolesDir, entry);
+		const content = fs.readFileSync(filePath, "utf-8");
+		const name = entry.replace(/\.(md|markdown)$/i, "");
+		const parsed = parseFrontmatterFile(content, name);
+		roles[name] = {
+			name,
+			description: parsed.description,
+			instructions: parsed.body,
+			model: parsed.frontmatter.model
+		};
+	}
+	return roles;
+}
+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);
+		return {
+			name: f.replace(/\.(ts|js|mts|mjs)$/, ""),
+			filePath,
+			triggers
+		};
+	});
+}
+/** Extract trigger config via regex. Only triggers are parsed at build time (needed for routing). */
+function parseTriggers(filePath) {
+	const source = fs.readFileSync(filePath, "utf-8");
+	const result = {};
+	const triggersExportMatch = source.match(/export\s+const\s+triggers\s*=\s*\{([^}]*)\}/);
+	if (!triggersExportMatch) return result;
+	const triggersBlock = triggersExportMatch[1] ?? "";
+	if (/webhook\s*:\s*true/.test(triggersBlock)) result.webhook = true;
+	const cronMatch = triggersBlock.match(/cron\s*:\s*['"]([^'"]+)['"]/);
+	if (cronMatch?.[1]) result.cron = cronMatch[1];
+	return result;
+}
+/** Externalize user's direct deps (bare name + subpath wildcard). */
+function getUserExternals(workspaceDir) {
+	const pkgPath = packageUpSync({ cwd: workspaceDir });
+	if (!pkgPath) return [];
+	try {
+		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+		return Object.keys({
+			...pkg.dependencies,
+			...pkg.devDependencies,
+			...pkg.peerDependencies
+		}).flatMap((name) => [name, `${name}/*`]);
+	} catch {
+		return [];
+	}
+}
+function collectNodePaths(workspaceDir) {
+	const nodePathsSet = /* @__PURE__ */ new Set();
+	for (const startDir of [workspaceDir, getSDKDir()]) {
+		let dir = startDir;
+		while (dir !== path.dirname(dir)) {
+			const nm = path.join(dir, "node_modules");
+			if (fs.existsSync(nm)) nodePathsSet.add(nm);
+			dir = path.dirname(dir);
+		}
+	}
+	return nodePathsSet;
+}
+function getSDKDir() {
+	try {
+		return path.dirname(new URL(import.meta.url).pathname);
+	} catch {
+		return __dirname;
+	}
+}
+
+//#endregion
+//#region src/dev.ts
+/**
+* Flue dev server.
+*
+* Watches the user's workspace, rebuilds on file changes, and reloads the
+* underlying server. Distinct from `flue run`: dev is the long-running,
+* edit-and-iterate command, while `flue run` is the one-shot
+* production-style invoker (build → run → exit).
+*
+* # Two very different reload models
+*
+* Node and Cloudflare use fundamentally different rebuild strategies, because
+* what they each provide downstream is fundamentally different:
+*
+* - **Node** has no host bundler. Our esbuild pass produces the final
+*   `dist/server.mjs`. On any change in the workspace we rebuild and respawn
+*   the child Node process. Sub-second restart is fine.
+*
+* - **Cloudflare** uses Wrangler's bundler (the same one `wrangler dev` and
+*   `wrangler deploy` use). Wrangler watches the entry's transitive import
+*   graph itself and reloads workerd on source edits. So we *don't* need to
+*   rebuild for body edits — wrangler handles it. We only need to act when:
+*     1. The set of agents changes (added / removed / triggers changed) →
+*        regenerate `dist/_entry.ts`. Wrangler picks up the new entry
+*        automatically because it's already watching it.
+*     2. The user's `wrangler.jsonc` changes → re-merge our additions and
+*        restart the worker (config changes don't hot-apply).
+*   Pure body edits to agent files: wrangler reloads workerd; we do nothing.
+*
+* # Watching
+*
+* Watching uses `node:fs.watch` recursive (Node 20+). Debounced 150ms. The
+* Node path treats every non-ignored change as a rebuild trigger; the
+* Cloudflare path filters to "structural" changes only.
+*/
+/** Default port for `flue dev`. F=3, L=5, U=8, E=3 on a phone keypad. */
+const DEFAULT_DEV_PORT = 3583;
+/**
+* Start a Flue dev server. Resolves only when the server is shut down (e.g.
+* via SIGINT). Errors during the initial build/start are thrown synchronously;
+* errors during subsequent rebuilds are logged but do NOT exit the dev server
+* — the user is editing code, after all, and we want to recover when they fix it.
+*/
+async function dev(options) {
+	const workspaceDir = path.resolve(options.workspaceDir);
+	const outputDir = path.resolve(options.outputDir);
+	const port = options.port ?? DEFAULT_DEV_PORT;
+	const envFiles = resolveEnvFiles(options.envFiles, outputDir);
+	for (const f of envFiles) console.error(`[flue] Loading env from: ${f}`);
+	const buildOptions = {
+		workspaceDir,
+		outputDir,
+		target: options.target
+	};
+	console.error(`[flue] Starting dev server (target: ${options.target})`);
+	console.error(`[flue] Watching: ${workspaceDir}`);
+	console.error(`[flue] Building...`);
+	const initialStart = Date.now();
+	try {
+		await build(buildOptions);
+	} catch (err) {
+		throw new Error(`[flue] Initial build failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	console.error(`[flue] Built in ${Date.now() - initialStart}ms`);
+	const reloader = options.target === "node" ? new NodeReloader({
+		outputDir,
+		port,
+		envFiles
+	}) : await createCloudflareReloader({
+		outputDir,
+		port,
+		envFiles
+	});
+	await reloader.start();
+	if (reloader.url) {
+		console.error(`[flue] Server: ${reloader.url}`);
+		const exampleAgent = pickExampleAgentName(outputDir, workspaceDir);
+		if (exampleAgent) {
+			console.error(`[flue] Try: curl -X POST ${reloader.url}/agents/${exampleAgent}/test-1 \\`);
+			console.error(`         -H 'Content-Type: application/json' -d '{}'`);
+		}
+	}
+	console.error(`[flue] Press Ctrl+C to stop\n`);
+	const rebuilder = createRebuilder(buildOptions, reloader);
+	const envFileSet = new Set(envFiles);
+	const watcher = createWatcher({
+		workspaceDir,
+		outputDir,
+		target: options.target,
+		envFiles,
+		onChange: (relPath) => {
+			if (!reloader.shouldRebuildOn(relPath)) return;
+			const isEnvFile = envFileSet.has(relPath);
+			console.error(`[flue] Change detected: ${relPath}`);
+			rebuilder.schedule(isEnvFile);
+		}
+	});
+	let shuttingDown = false;
+	const shutdown = async (signal, exitCode) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		console.error(`\n[flue] Received ${signal}, shutting down...`);
+		watcher.close();
+		try {
+			await reloader.stop();
+		} catch (err) {
+			console.error(`[flue] Error during shutdown: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		console.error(`[flue] Stopped.`);
+		process.exit(exitCode);
+	};
+	process.on("SIGINT", () => void shutdown("SIGINT", 130));
+	process.on("SIGTERM", () => void shutdown("SIGTERM", 143));
+	process.on("exit", () => {
+		try {
+			reloader.killSync?.();
+		} catch {}
+	});
+	await new Promise(() => {});
+}
+function createRebuilder(buildOptions, reloader) {
+	let running = false;
+	let queued = false;
+	let queuedForce = false;
+	let pendingForce = false;
+	let debounceTimer = null;
+	const runOnce = async (force) => {
+		running = true;
+		const start = Date.now();
+		console.error(`[flue] Rebuilding...`);
+		try {
+			const { changed } = await build(buildOptions);
+			await reloader.reload(changed || force);
+			console.error(`[flue] Reloaded in ${Date.now() - start}ms\n`);
+		} catch (err) {
+			console.error(`[flue] Rebuild failed: ${err instanceof Error ? err.message : String(err)}\n`);
+		} finally {
+			running = false;
+			if (queued) {
+				const nextForce = queuedForce;
+				queued = false;
+				queuedForce = false;
+				runOnce(nextForce);
+			}
+		}
+	};
+	return { schedule(forceReload = false) {
+		if (forceReload) pendingForce = true;
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			debounceTimer = null;
+			const force = pendingForce;
+			pendingForce = false;
+			if (running) {
+				queued = true;
+				if (force) queuedForce = true;
+			} else runOnce(force);
+		}, 150);
+	} };
+}
+/**
+* Watch the workspace for changes. Uses `fs.watch` recursive (Node 20+).
+*
+* Watched roots:
+*   - `<workspaceDir>` — agents/, roles/, AGENTS.md, .agents/skills/.
+*   - For Cloudflare: also `<outputDir>/wrangler.jsonc` (and `.json`),
+*     since changes there require a worker restart.
+*
+* Ignored:
+*   - `dist/`, `node_modules/`, `.git/`, `.turbo/`
+*   - dotfiles other than the ones we explicitly care about (AGENTS.md is
+*     not a dotfile, so it's fine)
+*   - editor backup/swap suffixes
+*/
+function createWatcher(options) {
+	const { workspaceDir, outputDir, target, envFiles, onChange } = options;
+	const watchers = [];
+	const isIgnoredPath = (relPath) => {
+		const parts = relPath.replace(/\\/g, "/").split("/");
+		for (const part of parts) {
+			if (part === "node_modules") return true;
+			if (part === "dist") return true;
+			if (part === ".git") return true;
+			if (part === ".turbo") return true;
+		}
+		const base = parts[parts.length - 1] ?? "";
+		if (!base) return true;
+		if (base.startsWith(".") && base !== ".flueignore") return true;
+		if (base.endsWith("~") || base.endsWith(".swp") || base.endsWith(".swx")) return true;
+		if (base === ".DS_Store") return true;
+		return false;
+	};
+	try {
+		const w = fs.watch(workspaceDir, { recursive: true }, (_event, filename) => {
+			if (!filename) return;
+			const rel = filename.toString();
+			if (isIgnoredPath(rel)) return;
+			onChange(rel);
+		});
+		watchers.push(w);
+	} catch (err) {
+		console.error(`[flue] Failed to watch ${workspaceDir}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (target === "cloudflare") for (const cfgName of [
+		"wrangler.jsonc",
+		"wrangler.json",
+		"wrangler.toml"
+	]) {
+		const cfgPath = path.join(outputDir, cfgName);
+		if (!fs.existsSync(cfgPath)) continue;
+		try {
+			const w = fs.watch(cfgPath, () => onChange(cfgName));
+			watchers.push(w);
+		} catch {}
+	}
+	for (const envPath of envFiles) try {
+		const w = fs.watch(envPath, () => onChange(envPath));
+		watchers.push(w);
+	} catch {}
+	return { close() {
+		for (const w of watchers) try {
+			w.close();
+		} catch {}
+	} };
+}
+var NodeReloader = class {
+	child = null;
+	serverPath;
+	outputDir;
+	port;
+	envFiles;
+	url;
+	constructor(opts) {
+		this.outputDir = opts.outputDir;
+		this.port = opts.port;
+		this.envFiles = opts.envFiles;
+		this.serverPath = path.join(this.outputDir, "dist", "server.mjs");
+		this.url = `http://localhost:${this.port}`;
+	}
+	async start() {
+		await this.spawnAndWait();
+	}
+	shouldRebuildOn(_relPath) {
+		return true;
+	}
+	async reload(_buildChanged) {
+		await this.killChild();
+		await this.spawnAndWait();
+	}
+	async stop() {
+		await this.killChild();
+	}
+	killSync() {
+		const child = this.child;
+		if (!child || child.killed) return;
+		try {
+			child.kill("SIGKILL");
+		} catch {}
+	}
+	async spawnAndWait() {
+		const fromFiles = parseEnvFiles(this.envFiles);
+		const child = spawn("node", [this.serverPath], {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			cwd: this.outputDir,
+			env: {
+				...fromFiles,
+				...process.env,
+				PORT: String(this.port),
+				FLUE_MODE: "local"
+			}
+		});
+		this.child = child;
+		const pipe = (data) => {
+			const text = data.toString().trimEnd();
+			for (const line of text.split("\n")) {
+				if (!line.trim()) continue;
+				if (line.includes("[flue] Server listening") || line.includes("[flue] Available agents:") || line.includes("[flue] Mode: local")) continue;
+				console.error(line);
+			}
+		};
+		child.stdout?.on("data", pipe);
+		child.stderr?.on("data", pipe);
+		child.on("exit", (code, signal) => {
+			if (this.child === child) {
+				this.child = null;
+				if (code !== 0 && code !== null) console.error(`[flue] Node server exited unexpectedly (code=${code}, signal=${signal ?? "none"})`);
+			}
+		});
+		if (!await waitForHealth(this.url, 15e3)) {
+			await this.killChild();
+			throw new Error("Node server did not become ready within 15s");
+		}
+	}
+	async killChild() {
+		const child = this.child;
+		if (!child || child.killed) {
+			this.child = null;
+			return;
+		}
+		this.child = null;
+		await new Promise((resolve) => {
+			let resolved = false;
+			const done = () => {
+				if (!resolved) {
+					resolved = true;
+					resolve();
+				}
+			};
+			child.once("exit", done);
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				done();
+				return;
+			}
+			setTimeout(() => {
+				try {
+					if (!child.killed) child.kill("SIGKILL");
+				} catch {}
+				done();
+			}, 1e3);
+		});
+	}
+};
+/**
+* Lazy-import wrangler so users targeting only Node don't need it installed.
+* If the import fails, surface a friendly message pointing at the peer-dep.
+*/
+async function createCloudflareReloader(opts) {
+	let wrangler;
+	try {
+		wrangler = await import("wrangler");
+	} catch (err) {
+		throw new Error(`[flue] Cloudflare dev requires the "wrangler" package as a peer dependency.
+Install it in your project:
+
+  npm install --save-dev wrangler
+
+Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return new CloudflareReloader(wrangler, opts);
+}
+var CloudflareReloader = class {
+	worker = null;
+	wrangler;
+	outputDir;
+	port;
+	configPath;
+	envFiles;
+	url;
+	constructor(wrangler, opts) {
+		this.wrangler = wrangler;
+		this.outputDir = opts.outputDir;
+		this.port = opts.port;
+		this.envFiles = opts.envFiles;
+		this.configPath = path.join(this.outputDir, "dist", "wrangler.jsonc");
+	}
+	async start() {
+		await this.startWorker();
+	}
+	/**
+	* On Cloudflare, wrangler watches the entry's transitive imports itself
+	* and hot-reloads workerd when an agent file body changes. We only need
+	* to act when something *structural* changes — i.e. something that
+	* affects what `_entry.ts` or `wrangler.jsonc` look like.
+	*
+	* Concretely, we trigger a Flue-side rebuild for:
+	*   - File adds/removes in `agents/` (the agent set determines DO classes
+	*     and binding declarations).
+	*   - Changes to `agents/*.ts` — these MAY change the exported `triggers`,
+	*     so we have to re-parse them. (Plain body edits redo a tiny amount
+	*     of work but the rebuild is cheap and idempotent.)
+	*   - Changes to `roles/*.md` — roles are baked into the entry as JSON.
+	*   - Changes to the user's `wrangler.jsonc` — affects the merged config.
+	*
+	* Notes we explicitly DO ignore for rebuild purposes (wrangler handles
+	* them): edits to imported source files outside of `agents/`/`roles/`,
+	* AGENTS.md, and `.agents/skills/` (those are runtime-discovered, not
+	* baked into the entry).
+	*/
+	shouldRebuildOn(relPath) {
+		if (this.envFiles.includes(relPath)) return true;
+		const normalized = relPath.replace(/\\/g, "/");
+		if (normalized === "wrangler.jsonc" || normalized === "wrangler.json" || normalized === "wrangler.toml") return true;
+		if (normalized.startsWith("agents/")) return true;
+		if (normalized.startsWith("roles/")) return true;
+		return false;
+	}
+	async reload(buildChanged) {
+		if (!buildChanged) {
+			console.error(`[flue] No structural change — wrangler will hot-reload\n`);
+			return;
+		}
+		await this.disposeWorker();
+		await this.startWorker();
+	}
+	async stop() {
+		await this.disposeWorker();
+	}
+	killSync() {
+		this.worker = null;
+	}
+	async startWorker() {
+		if (!fs.existsSync(this.configPath)) throw new Error(`[flue] Expected ${this.configPath} after build, but it doesn't exist. Did the Cloudflare build succeed?`);
+		this.worker = await this.wrangler.unstable_startWorker({
+			config: this.configPath,
+			envFiles: this.envFiles,
+			build: { nodejsCompatMode: "v2" },
+			dev: {
+				server: {
+					hostname: "localhost",
+					port: this.port
+				},
+				watch: false,
+				logLevel: "info"
+			}
+		});
+		try {
+			this.url = (await this.worker.url).toString().replace(/\/$/, "");
+		} catch {
+			this.url = `http://127.0.0.1:${this.port}`;
+		}
+	}
+	async disposeWorker() {
+		const worker = this.worker;
+		this.worker = null;
+		if (!worker) return;
+		try {
+			await worker.dispose();
+		} catch (err) {
+			console.error(`[flue] Error disposing Cloudflare worker: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+};
+/**
+* Resolve and validate a list of env-file paths. Returns absolute paths.
+*
+* Throws a friendly `[flue]`-prefixed error if any path doesn't exist. The
+* goal of `--env` is explicitness — silent skip on a typo would defeat
+* the purpose.
+*/
+function resolveEnvFiles(envFiles, cwd) {
+	if (!envFiles || envFiles.length === 0) return [];
+	return envFiles.map((p) => {
+		const abs = path.isAbsolute(p) ? p : path.resolve(cwd, p);
+		if (!fs.existsSync(abs)) throw new Error(`[flue] --env points at a path that doesn't exist: ${p}`);
+		return abs;
+	});
+}
+/**
+* Parse one or more `.env`-format files and return their merged contents.
+* Later files override earlier files on key collision.
+*
+* Uses Node's built-in `util.parseEnv` (Node 20.6+; Flue requires Node 22+).
+* No `dotenv` package needed.
+*
+* Parse-only — doesn't touch `process.env`. Caller composes with
+* `process.env` as needed (typical pattern: spread file vars first, then
+* `process.env`, so shell-set values win).
+*/
+function parseEnvFiles(absolutePaths) {
+	const merged = {};
+	for (const p of absolutePaths) {
+		const parsed = parseEnv(fs.readFileSync(p, "utf-8"));
+		Object.assign(merged, parsed);
+	}
+	return merged;
+}
+async function waitForHealth(baseUrl, timeoutMs) {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		try {
+			const controller = new AbortController();
+			const timeout = setTimeout(() => controller.abort(), 1e3);
+			const res = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+			clearTimeout(timeout);
+			if (res.ok) return true;
+		} catch {}
+		await new Promise((r) => setTimeout(r, 200));
+	}
+	return false;
+}
+/**
+* Pick a webhook agent name to print in the friendly curl example. Falls back
+* to any agent if none have webhook triggers (the example would 404 on the
+* dev server in that case, but it's still a hint at the URL shape). Reads the
+* manifest written by the build, with a directory-scan fallback in case the
+* manifest is somehow missing.
+*
+* Best-effort — silently returns null if anything goes wrong.
+*/
+function pickExampleAgentName(outputDir, workspaceDir) {
+	try {
+		const manifestPath = path.join(outputDir, "dist", "manifest.json");
+		if (fs.existsSync(manifestPath)) {
+			const agents = JSON.parse(fs.readFileSync(manifestPath, "utf-8")).agents ?? [];
+			const webhook = agents.find((a) => a.triggers?.webhook);
+			if (webhook) return webhook.name;
+			if (agents[0]) return agents[0].name;
+		}
+	} catch {}
+	try {
+		const agentsDir = path.join(workspaceDir, "agents");
+		if (!fs.existsSync(agentsDir)) return null;
+		for (const e of fs.readdirSync(agentsDir)) {
+			const m = e.match(/^([a-zA-Z0-9_-]+)\.(ts|js|mts|mjs)$/);
+			if (m && m[1]) return m[1];
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { BUILTIN_TOOL_NAMES, DEFAULT_DEV_PORT, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };