@flue/sdk 0.3.11 → 0.4.0

package/dist/index.mjs

@@ -1,88 +1,13 @@
-import { a as parseFrontmatterFile, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-Cahthgu3.mjs";
+import { c as createTools, d as parseFrontmatterFile, s as BUILTIN_TOOL_NAMES, t as ResultUnavailableError } from "./result-K1IRhWKM.mjs";
 import * as esbuild from "esbuild";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { packageUpSync } from "package-up";
 import * as ts from "typescript";
+import { packageUpSync } from "package-up";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { parseEnv } from "node:util";
 
-//#region src/agent-parser.ts
-/** Extract static agent metadata at build time without evaluating the agent module. */
-function parseAgentFile(filePath) {
-	return { triggers: parseTriggers(filePath) };
-}
-function parseTriggers(filePath) {
-	const source = fs.readFileSync(filePath, "utf-8");
-	const ast = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, scriptKindForFile(filePath));
-	let result;
-	for (const statement of ast.statements) {
-		if (isTriggersReExport(statement)) throwUnsupportedTriggers(filePath, "re-exported triggers are not supported");
-		if (!ts.isVariableStatement(statement) || !hasExportModifier(statement)) continue;
-		for (const declaration of statement.declarationList.declarations) {
-			if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "triggers") continue;
-			if (result) throwUnsupportedTriggers(filePath, "multiple triggers exports were found");
-			if (!declaration.initializer) throwUnsupportedTriggers(filePath, "missing initializer");
-			result = parseTriggersInitializer(filePath, declaration.initializer);
-		}
-	}
-	return result ?? {};
-}
-function scriptKindForFile(filePath) {
-	if (/\.m?js$/.test(filePath)) return ts.ScriptKind.JS;
-	return ts.ScriptKind.TS;
-}
-function hasExportModifier(statement) {
-	return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
-}
-function isTriggersReExport(statement) {
-	if (!ts.isExportDeclaration(statement) || !statement.exportClause) return false;
-	if (!ts.isNamedExports(statement.exportClause)) return false;
-	return statement.exportClause.elements.some((element) => element.name.text === "triggers");
-}
-function parseTriggersInitializer(filePath, initializer) {
-	const expr = unwrapExpression(initializer);
-	if (!ts.isObjectLiteralExpression(expr)) throwUnsupportedTriggers(filePath, "expected a static object literal");
-	const result = {};
-	for (const property of expr.properties) {
-		if (ts.isSpreadAssignment(property)) throwUnsupportedTriggers(filePath, "spread properties are not supported");
-		if (ts.isShorthandPropertyAssignment(property)) {
-			const name = property.name.text;
-			if (name === "webhook") throwUnsupportedTriggers(filePath, `"${name}" must use an explicit static value`);
-			continue;
-		}
-		if (!ts.isPropertyAssignment(property)) {
-			const name = propertyNameText(filePath, property.name);
-			if (name === "webhook") throwUnsupportedTriggers(filePath, `"${name}" must use an explicit static value`);
-			continue;
-		}
-		if (propertyNameText(filePath, property.name) === "webhook") {
-			const value = unwrapExpression(property.initializer);
-			if (value.kind === ts.SyntaxKind.TrueKeyword) result.webhook = true;
-			else if (value.kind === ts.SyntaxKind.FalseKeyword) delete result.webhook;
-			else throwUnsupportedTriggers(filePath, "\"webhook\" must be true or false");
-		}
-	}
-	return result;
-}
-function unwrapExpression(expr) {
-	while (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr) || ts.isTypeAssertionExpression(expr) || ts.isParenthesizedExpression(expr)) expr = expr.expression;
-	return expr;
-}
-function propertyNameText(filePath, name) {
-	if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
-	if (ts.isComputedPropertyName(name)) {
-		const expression = unwrapExpression(name.expression);
-		if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
-		throwUnsupportedTriggers(filePath, "computed property names must be static");
-	}
-}
-function throwUnsupportedTriggers(filePath, reason) {
-	throw new Error(`[flue] Unsupported triggers export in ${filePath}: ${reason}. Use a static object literal, for example: export const triggers = { webhook: true }.`);
-}
-
-//#endregion
 //#region src/cloudflare-wrangler-merge.ts
 /**
 * Merge Flue's Cloudflare additions into the user's wrangler config.
@@ -114,7 +39,7 @@ 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`.
+* Read and normalize the user's wrangler config from `root`.
 *
 * Looks for `wrangler.jsonc`, `wrangler.json`, then `wrangler.toml` (jsonc is
 * Cloudflare's recommended format for new projects, but all three work).
@@ -136,7 +61,7 @@ const REQUIRED_COMPAT_FLAG = "nodejs_compat";
 * `dist/wrangler.jsonc` and the benefit is correctness without us reimplementing
 * wrangler's path-resolution logic.
 */
-async function readUserWranglerConfig(outputDir) {
+async function readUserWranglerConfig(root) {
 	const candidates = [
 		"wrangler.jsonc",
 		"wrangler.json",
@@ -144,7 +69,7 @@ async function readUserWranglerConfig(outputDir) {
 	];
 	let foundPath = null;
 	for (const name of candidates) {
-		const candidate = path.join(outputDir, name);
+		const candidate = path.join(root, name);
 		if (fs.existsSync(candidate)) {
 			foundPath = candidate;
 			break;
@@ -392,43 +317,48 @@ function detectSandboxBindings(userConfig) {
 * silently and let esbuild's own error path take over. This avoids false
 * positives in unusual project layouts.
 */
-function assertSandboxPackageInstalled(sandboxClassNames, searchDirs) {
+function assertSandboxPackageInstalled(sandboxClassNames, root) {
 	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);
+	let current = root;
+	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 ends with "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`.
+* Write the wrangler deploy-redirect file at
+* `<root>/.wrangler/deploy/config.json` so that `wrangler deploy` run from
+* the project root automatically picks up the generated wrangler config at
+* `<output>/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.
+*
+* `output` may be anywhere (typically `<root>/dist`, but the user
+* can redirect it via `--output`). We compute a relative path so the
+* redirect file is portable across machines / repos.
 */
-function writeDeployRedirectIfMissing(outputDir) {
-	const redirectDir = path.join(outputDir, ".wrangler", "deploy");
+function writeDeployRedirectIfMissing(root, output) {
+	const redirectDir = path.join(root, ".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");
+	const targetPath = path.join(output, "wrangler.jsonc");
+	const relConfigPath = path.relative(redirectDir, targetPath).split(path.sep).join("/");
+	fs.writeFileSync(redirectPath, JSON.stringify({ configPath: relConfigPath }, null, 2) + "\n", "utf-8");
 }
 
 //#endregion
@@ -446,28 +376,30 @@ var CloudflarePlugin = class {
 	* single build.
 	*/
 	userConfigCache;
-	async getUserConfig(outputDir) {
-		if (!this.userConfigCache) this.userConfigCache = await readUserWranglerConfig(outputDir);
+	/**
+	* Read the user's wrangler config from `root`. The user's config always
+	* lives at the project root, regardless of where the build artifacts get
+	* written via `output`. We only re-locate the *generated*
+	* `wrangler.jsonc` (the merged one) — never the source one.
+	*/
+	async getUserConfig(root) {
+		if (!this.userConfigCache) this.userConfigCache = await readUserWranglerConfig(root);
 		return this.userConfigCache;
 	}
 	async generateEntryPoint(ctx) {
-		const { agents, roles } = ctx;
+		const { agents, roles, appEntry } = ctx;
 		const rolesJson = JSON.stringify(roles);
 		validateCloudflareAgentNames(ctx);
 		const webhookAgents = agents.filter((a) => a.triggers.webhook);
 		const agentImports = agents.map((a, index) => {
 			return `import ${agentVarName$1(a.name, index)} 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, agents.indexOf(a));
 			return `export class ${className} extends Agent {
   async onRequest(request) {
-    return handleAgentRequest(request, this, ${JSON.stringify(a.name)}, ${handlerVar});
+    return dispatchAgent(request, this, ${JSON.stringify(a.name)}, ${handlerVar});
   }
 
   async onFiberRecovered(ctx) {
@@ -480,10 +412,11 @@ var CloudflarePlugin = class {
   }
 }`;
 		}).join("\n\n");
-		const { config: userConfig } = await this.getUserConfig(ctx.outputDir);
+		const { config: userConfig } = await this.getUserConfig(ctx.root);
 		const sandboxReExports = detectSandboxBindings(userConfig).map((name) => `export { Sandbox as ${name} } from '@cloudflare/sandbox';`).join("\n");
 		return `
 // Auto-generated by @flue/sdk build (cloudflare)
+import { env } from 'cloudflare:workers';
 import { Agent, routeAgentRequest } from 'agents';
 import { Bash, InMemoryFs } from 'just-bash';
 import {
@@ -491,30 +424,43 @@ import {
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
-  parseJsonBody,
-  toHttpResponse,
-  toSseData,
-  AgentNotFoundError,
-  MethodNotAllowedError,
-  RouteNotFoundError,
-  InvalidRequestError,
+  handleAgentRequest,
+  configureFlueRuntime,
+  createDefaultFlueApp,
 } from '@flue/sdk/internal';
-import { runWithCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
+import {
+  runWithCloudflareContext,
+  cfSandboxToSessionEnv,
+  getCloudflareAIBindingApiProvider,
+} from '@flue/sdk/cloudflare';
+import { registerApiProvider, registerProvider } from '@flue/sdk/app';
 
 ${agentImports}
 
+${appEntry ? `import userApp from '${appEntry.replace(/\\/g, "/")}';` : ""}
+
+// ─── Internal provider registrations ────────────────────────────────────────
+// Imports evaluate before this file's top-level body, so these built-ins
+// reserve the \`cloudflare\` prefix after any user app.ts registrations run.
+
+// Wire-protocol handler for the cloudflare-ai-binding api.
+registerApiProvider(getCloudflareAIBindingApiProvider());
+
+// Capture the binding reference at module init; invoke it only per request.
+registerProvider('cloudflare', {
+  api: 'cloudflare-ai-binding',
+  binding: env.AI,
+});
+
 // ─── Config ─────────────────────────────────────────────────────────────────
 
 const roles = ${rolesJson};
 const skills = {};
 const systemPrompt = '';
-const manifest = ${manifest};
 
-// Set of webhook-accessible agent names (raw form, as used in URL segments).
-// Used by the worker fetch handler to pre-route requests and reject unknown
-// agents with a JSON 404 envelope before the request hits the partyserver
-// dispatcher (which would otherwise return text/plain "Invalid request").
-const webhookAgentNames = new Set(${JSON.stringify(webhookAgents.map((a) => a.name))});
+// Webhook-accessible agent names. Consumed by the seeded flue() runtime
+// for the "is this name registered?" check inside the agent route.
+const webhookAgentNames = ${JSON.stringify(webhookAgents.map((a) => a.name))};
 
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
@@ -608,7 +554,7 @@ function createDOStore(sql) {
   };
 }
 
-function createContextForRequest(id, payload, doInstance) {
+function createContextForRequest(id, payload, doInstance, req) {
   // Use DO SQLite storage by default, fall back to in-memory
   const defaultStore = doInstance?.ctx?.storage?.sql
     ? createDOStore(doInstance.ctx.storage.sql)
@@ -618,6 +564,7 @@ function createContextForRequest(id, payload, doInstance) {
     id,
     payload,
     env: doInstance?.env ?? {},
+    req,
     agentConfig: {
       systemPrompt, skills, roles, model: undefined, resolveModel,
     },
@@ -645,154 +592,54 @@ function assertAgentsDurabilityApi(doInstance, method) {
 	}
 }
 
-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;
-
-  try {
-    // Parse the request body. Throws on invalid Content-Type or malformed
-    // JSON; returns {} for genuinely empty bodies (so no-payload agents
-    // still work).
-    const payload = await parseJsonBody(request);
-
-    const accept = request.headers.get('accept') || '';
-    const isWebhook = request.headers.get('x-webhook') === 'true';
-    const isSSE = accept.includes('text/event-stream') && !isWebhook;
-
-    // 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' },
-      });
-    }
+// ─── Per-DO Dispatch ───────────────────────────────────────────────────────
 
-    // SSE streaming mode. Two error regimes meet here:
-    //   - Pre-stream errors (body parsing, etc.) have already thrown above
-    //     and are caught by the outer try/catch — rendered as plain HTTP
-    //     responses by toHttpResponse, since headers haven't been sent yet.
-    //   - Errors during agent execution surface as in-stream \`error\`
-    //     events with the canonical envelope (via toSseData), since by
-    //     then the 200 + text/event-stream headers are already on the wire.
-    if (isSSE) {
-      const { readable, writable } = new TransformStream();
-      const writer = writable.getWriter();
-      const encoder = new TextEncoder();
-      let eventId = 0;
-      let isIdle = false;
+/**
+ * Per-DO entry point invoked from each generated agent class's onRequest().
+ * Wraps the shared handleAgentRequest with CF-specific bits:
+ *
+ *   - keepAliveWhile around the foreground handler so the DO doesn't
+ *     hibernate mid-stream.
+ *   - runFiber for fire-and-forget webhook execution so it survives across
+ *     hibernation.
+ *   - runWithCloudflareContext for AsyncLocalStorage-based env propagation
+ *     (the workers-ai provider reads env.AI through it).
+ */
+async function dispatchAgent(request, doInstance, agentName, handler) {
+  const id = doInstance.name; // DO room name set by routeAgentRequest
 
-      const writeSSE = async (data, event) => {
-        const lines = [];
-        if (event) lines.push('event: ' + event);
-        lines.push('id: ' + eventId++);
-        lines.push('data: ' + (typeof data === 'string' ? data : JSON.stringify(data)));
-        lines.push('', '');
-        await writer.write(encoder.encode(lines.join('\\n')));
+  return handleAgentRequest({
+    request,
+    agentName,
+    id,
+    handler,
+    createContext: (id_, payload, req) => createContextForRequest(id_, payload, doInstance, req),
+    startWebhook: (requestId, run) => {
+      const wrapped = (fiber) => {
+        fiber?.stash?.({
+          version: 1,
+          kind: 'webhook',
+          agentName,
+          id,
+          requestId,
+          phase: 'running',
+          startedAt: Date.now(),
+        });
+        return runWithInstanceContext(doInstance, run);
       };
-
-      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(toSseData(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) {
-    // toHttpResponse logs unknowns via flueLog.error — no extra console.error
-    // needed here. The agentName tag is captured in the wrapped error's
-    // server-side log line via flueLog's prefix.
-    return toHttpResponse(err);
-  }
+      assertAgentsDurabilityApi(doInstance, 'runFiber');
+      return doInstance.runFiber('flue:webhook:' + requestId, wrapped);
+    },
+    runHandler: (ctx, h) => runWithInstanceContext(doInstance, () => {
+      assertAgentsDurabilityApi(doInstance, 'keepAliveWhile');
+      return doInstance.keepAliveWhile(() => h(ctx));
+    }),
+  });
 }
 
 // ─── Per-Agent Durable Object Classes ──────────────────────────────────────
@@ -807,71 +654,43 @@ ${agentClasses}
 // by the user's wrangler.jsonc.
 ${sandboxReExports}
 
-// ─── Worker Fetch Handler ───────────────────────────────────────────────────
-
-export default {
-  async fetch(request, env) {
-    try {
-      const url = new URL(request.url);
-      const method = request.method;
-
-      // Health check
-      if (url.pathname === '/health') {
-        return new Response(JSON.stringify({ status: 'ok' }), {
-          headers: { 'content-type': 'application/json' },
-        });
-      }
+// ─── Runtime seed ───────────────────────────────────────────────────────────
+
+// Seed the public flue() sub-app's runtime. On Cloudflare the agent route
+// forwards to routeAgentRequest() (provided by the Agents SDK), which
+// dispatches into the per-agent DO's onRequest → dispatchAgent above.
+// Validation (method, name, id) happens inside flue() before forwarding,
+// which suppresses partyserver's noisy default text/plain "Invalid
+// request" response for unknown / malformed routes.
+configureFlueRuntime({
+  target: 'cloudflare',
+  webhookAgents: webhookAgentNames,
+  // Cloudflare deploys never run in local mode — the trigger-less agents
+  // simply have no DO class to land in.
+  allowNonWebhook: false,
+  routeAgentRequest: (request, env) => routeAgentRequest(request, env),
+});
 
-      // Agent manifest
-      if (url.pathname === '/agents' && method === 'GET') {
-        return new Response(JSON.stringify(manifest), {
-          headers: { 'content-type': 'application/json' },
-        });
-      }
+// ─── App composition ────────────────────────────────────────────────────────
 
-      // Webhook agent route: /agents/<name>/<id>
-      //
-      // We pre-check method and agent registration here, BEFORE delegating to
-      // routeAgentRequest. Without this, partyserver (the transitive
-      // dispatcher behind routeAgentRequest) returns a text/plain
-      // "Invalid request" 400 for unknown agent namespaces — visibly
-      // inconsistent with the rest of the API and with the Node target.
-      // Pre-routing means every error path in the agent route flows through
-      // the same JSON envelope.
-      const agentRouteMatch = url.pathname.match(/^\\/agents\\/([^/]+)\\/([^/]+)\\/?$/);
-      if (agentRouteMatch) {
-        if (method !== 'POST') {
-          throw new MethodNotAllowedError({ method, allowed: ['POST'] });
-        }
-        const name = decodeURIComponent(agentRouteMatch[1]);
-        const id = decodeURIComponent(agentRouteMatch[2]);
-        if (name.trim() === '' || id.trim() === '') {
-          throw new InvalidRequestError({
-            reason: 'Webhook URLs must have the shape /agents/<name>/<id> with non-empty segments.',
-          });
-        }
-        if (!webhookAgentNames.has(name)) {
-          throw new AgentNotFoundError({
-            name,
-            available: Array.from(webhookAgentNames),
-          });
-        }
-        // All gating passed. Delegate to the Agents SDK / partyserver, which
-        // dispatches into the per-agent DO's onRequest → handleAgentRequest.
-        // routeAgentRequest may still return null for shape mismatches we
-        // didn't anticipate; treat that as a route_not_found with a hint.
-        const response = await routeAgentRequest(request, env);
-        if (response) return response;
-        throw new RouteNotFoundError({ method, path: url.pathname });
-      }
+${appEntry ? `// User-supplied app.ts. Their default export owns the entire request
+// pipeline — the worker just verifies a fetch method exists and pipes
+// through. The default flue() handler is available for them to mount
+// however they want; this file does not impose a composition.
+const app = userApp;
+if (!app || typeof app.fetch !== 'function') {
+  throw new Error(
+    '[flue] app.ts default export must be a Hono app or an object with a fetch(request, env, ctx) method.'
+  );
+}` : `// No app.ts: build the default app via the SDK so the generated entry
+// stays \`hono\`-free (users only need hono in their node_modules when
+// they author their own app.ts). The default mounts \`flue()\` at root
+// and renders canonical Flue envelopes for unmatched paths.
+const app = createDefaultFlueApp();`}
 
-      // Anything else: canonical 404 envelope.
-      throw new RouteNotFoundError({ method, path: url.pathname });
-    } catch (err) {
-      // toHttpResponse logs unknowns via flueLog.error — no extra
-      // console.error needed at this layer.
-      return toHttpResponse(err);
-    }
+export default {
+  fetch(request, env, ctx) {
+    return app.fetch(request, env, ctx);
   },
 };
 `;
@@ -883,26 +702,26 @@ export default {
 			name: agentClassName(a.name)
 		}));
 		const flueSqliteClasses = flueBindings.map((b) => b.class_name);
-		const { config: userConfig, path: userConfigPath } = await this.getUserConfig(ctx.outputDir);
+		const { config: userConfig, path: userConfigPath } = await this.getUserConfig(ctx.root);
 		if (userConfigPath) console.log(`[flue] Merging with user wrangler config: ${userConfigPath}`);
 		validateUserWranglerConfig(userConfig);
 		const flueMigrations = computeFlueMigrations(flueSqliteClasses, userConfig.migrations);
 		const additions = {
-			defaultName: path.basename(ctx.outputDir) || "flue-agents",
+			defaultName: path.basename(ctx.root) || "flue-agents",
 			main: "_entry.ts",
 			doBindings: flueBindings,
 			migrations: flueMigrations
 		};
 		const sandboxClassNames = detectSandboxBindings(userConfig);
 		if (sandboxClassNames.length > 0) {
-			assertSandboxPackageInstalled(sandboxClassNames, [ctx.outputDir, ctx.workspaceDir]);
+			assertSandboxPackageInstalled(sandboxClassNames, ctx.root);
 			for (const className of sandboxClassNames) console.log(`[flue] Auto-wiring DO binding "${className}" to @cloudflare/sandbox's Sandbox class.`);
 		}
 		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);
+		writeDeployRedirectIfMissing(ctx.root, ctx.output);
 		return outputs;
 	}
 };
@@ -914,7 +733,7 @@ function validateCloudflareAgentNames(ctx) {
 	const invalidAgents = ctx.agents.filter((agent) => !CLOUDFLARE_AGENT_NAME_PATTERN.test(agent.name));
 	if (invalidAgents.length === 0) return;
 	const invalidList = invalidAgents.map((agent) => {
-		return `${path.relative(ctx.workspaceDir, agent.filePath)} (${agent.name})`;
+		return `${path.relative(ctx.root, agent.filePath)} (${agent.name})`;
 	}).join(", ");
 	throw new Error(`[flue] Cloudflare target requires agent filenames to use lower-kebab-case so Durable Object bindings route correctly. Invalid agent file(s): ${invalidList}. Rename them to match ${CLOUDFLARE_AGENT_NAME_PATTERN}.`);
 }
@@ -935,31 +754,30 @@ var NodePlugin = class {
 	name = "node";
 	bundle = "esbuild";
 	generateEntryPoint(ctx) {
-		const { agents, roles } = ctx;
+		const { agents, roles, appEntry } = ctx;
 		const rolesJson = JSON.stringify(roles);
 		const webhookAgents = agents.filter((a) => a.triggers.webhook);
+		const agentImports = agents.map((a, index) => {
+			return `import ${agentVarName(a.name, index)} from '${a.filePath.replace(/\\/g, "/")}';`;
+		}).join("\n");
+		const handlerMapEntries = agents.map((a, index) => `  ${JSON.stringify(a.name)}: ${agentVarName(a.name, index)},`).join("\n");
+		const webhookNames = JSON.stringify(webhookAgents.map((a) => a.name));
 		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 { Bash, InMemoryFs } from 'just-bash';
 import {
   createFlueContext,
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
-  parseJsonBody,
-  validateAgentRequest,
-  toHttpResponse,
-  toSseData,
-  RouteNotFoundError,
+  configureFlueRuntime,
+  createDefaultFlueApp,
 } from '@flue/sdk/internal';
-import { randomUUID } from 'node:crypto';
+import { createLocalSessionEnv } from '@flue/sdk/node';
 
-${agents.map((a, index) => {
-			return `import ${agentVarName(a.name, index)} from '${a.filePath.replace(/\\/g, "/")}';`;
-		}).join("\n")}
+${agentImports}
+${appEntry ? `import userApp from '${appEntry.replace(/\\/g, "/")}';` : ""}
 
 // ─── Config ─────────────────────────────────────────────────────────────────
 
@@ -968,13 +786,11 @@ const roles = ${rolesJson};
 const systemPrompt = '';
 
 const handlers = {
-${agents.map((a, index) => `  ${JSON.stringify(a.name)}: ${agentVarName(a.name, index)},`).join("\n")}
+${handlerMapEntries}
 };
 
-// Set of webhook-accessible agent names. Named distinctly from the
-// validateAgentRequest \`webhookAgents\` parameter to keep the call site
-// below readable.
-const webhookAgentSet = new Set(${JSON.stringify(webhookAgents.map((a) => a.name))});
+// Webhook-accessible agent names.
+const webhookAgentNames = ${webhookNames};
 
 // 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
@@ -983,11 +799,6 @@ const webhookAgentSet = new Set(${JSON.stringify(webhookAgents.map((a) => a.name
 // 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)};
-
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
 /**
@@ -1004,28 +815,25 @@ async function createDefaultEnv() {
 }
 
 /**
- * Create a local sandbox backed by the host filesystem.
- * Mounts process.cwd() at /workspace via ReadWriteFs + MountableFs.
+ * Create a local SessionEnv backed directly by the host filesystem and
+ * child_process. No virtual filesystem, no sandbox layer — file methods
+ * call node:fs/promises and shell commands run on the host. Use this
+ * when flue itself is running inside an external sandbox / container /
+ * CI runner that already provides the isolation boundary.
  */
 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 },
-  }));
+  return createLocalSessionEnv();
 }
 
 // Default persistence store for Node — in-memory, process lifetime.
 const defaultStore = new InMemorySessionStore();
 
-function createContextForRequest(id, payload) {
+function createContextForRequest(id, payload, req) {
   return createFlueContext({
     id,
     payload,
     env: process.env,
+    req,
     agentConfig: {
       systemPrompt, skills, roles, model: undefined, resolveModel,
     },
@@ -1035,130 +843,49 @@ function createContextForRequest(id, payload) {
   });
 }
 
-// ─── Server ─────────────────────────────────────────────────────────────────
-
-const app = new Hono();
-
-app.get('/health', (c) => c.json({ status: 'ok' }));
-app.get('/agents', (c) => c.json(manifest));
-
-// Catch any method on the agent route so non-POSTs become 405 (instead of
-// Hono's default 404 for unmatched method). Throws are translated by the
-// onError handler into the canonical error envelope.
-app.all('/agents/:name/:id', async (c) => {
-  const name = c.req.param('name');
-  const id = c.req.param('id');
-
-  // Validate method, name shape, registration, webhook-accessibility.
-  // Throws FlueHttpError on any failure; caught by app.onError below.
-  validateAgentRequest({
-    method: c.req.method,
-    name,
-    id,
-    registeredAgents: Object.keys(handlers),
-    webhookAgents: Array.from(webhookAgentSet),
-    allowNonWebhook: isLocalMode,
-  });
-
-  const handler = handlers[name];
-
-  // Parse the request body. Throws on invalid Content-Type or malformed JSON;
-  // returns {} for genuinely empty bodies (so no-payload agents still work).
-  const payload = await parseJsonBody(c.req.raw);
-
-  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. Two error regimes meet here:
-  //   - Pre-stream errors (validation, body parsing, agent lookup) have
-  //     already thrown above and are rendered as plain HTTP responses by
-  //     app.onError — headers haven't been sent yet, so this works.
-  //   - Errors during agent execution surface as in-stream \`error\` events
-  //     with the canonical envelope (via toSseData), since by then the
-  //     200 + text/event-stream headers are already on the wire.
-  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: toSseData(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). Errors propagate to app.onError.
-  const ctx = createContextForRequest(id, payload);
-  try {
-    const result = await handler(ctx);
-    return c.json({ result: result !== undefined ? result : null });
-  } finally {
-    ctx.setEventCallback(undefined);
-  }
+// ─── Runtime seed ───────────────────────────────────────────────────────────
+
+// Seed the public flue() sub-app with everything it needs to dispatch agent
+// requests in-process. Must run before \`flue()\` handles any request — by
+// virtue of being a top-level statement, it executes before \`serve(...)\`
+// below binds the listener. User app.ts files that call \`flue()\` at top
+// level are also fine because Hono routes are lazy: they read this config
+// only when a request arrives.
+configureFlueRuntime({
+  target: 'node',
+  webhookAgents: webhookAgentNames,
+  allowNonWebhook: isLocalMode,
+  handlers,
+  createContext: createContextForRequest,
 });
 
-// 404 handler — fires for any URL that didn't match a registered route.
-app.notFound((c) => {
-  // Throw rather than return so the onError handler is the single source of
-  // truth for error-envelope shaping.
-  throw new RouteNotFoundError({ method: c.req.method, path: new URL(c.req.url).pathname });
-});
+// ─── App composition ────────────────────────────────────────────────────────
 
-// Single-source-of-truth error renderer. Every thrown FlueError (and every
-// thrown unknown) is converted to the canonical JSON envelope here.
-// toHttpResponse takes care of logging unknowns — no extra console.error
-// needed at this layer.
-app.onError((err) => toHttpResponse(err));
+${appEntry ? `// User-supplied app.ts: their default export owns the entire request
+// pipeline. We just verify it exposes a fetch method and pass the
+// listener through. flue() is available for them to mount, but the
+// composition is theirs to author.
+const app = userApp;
+if (!app || typeof app.fetch !== 'function') {
+  throw new Error(
+    '[flue] app.ts default export must be a Hono app or an object with a fetch(request) method.'
+  );
+}` : `// No app.ts: build the default app via the SDK so the generated entry
+// stays \`hono\`-free (users only need hono in their node_modules when
+// they author their own app.ts). The default mounts \`flue()\` at root
+// and renders canonical Flue envelopes for unmatched paths.
+const app = createDefaultFlueApp();`}
 
 // ─── Start ──────────────────────────────────────────────────────────────────
 
 const port = parseInt(process.env.PORT || '3000', 10);
 
-const server = serve({ fetch: app.fetch, port });
+const server = serve({
+  fetch: app.fetch,
+  port,
+  // SSE requests can outlive Node's default 300s request timeout.
+  serverOptions: { requestTimeout: 0 },
+});
 console.log('[flue] Server listening on http://localhost:' + port);
 if (isLocalMode) {
   console.log('[flue] Mode: local (all agents invokable, including trigger-less)');
@@ -1185,26 +912,123 @@ function agentVarName(name, index) {
 
 //#endregion
 //#region src/build.ts
+/** Extract static agent metadata at build time without evaluating the agent module. */
+function parseAgentFile(filePath) {
+	return { triggers: parseTriggers(filePath) };
+}
+function parseTriggers(filePath) {
+	const source = fs.readFileSync(filePath, "utf-8");
+	const ast = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, scriptKindForFile(filePath));
+	let result;
+	for (const statement of ast.statements) {
+		if (isTriggersReExport(statement)) throwUnsupportedTriggers(filePath, "re-exported triggers are not supported");
+		if (!ts.isVariableStatement(statement) || !hasExportModifier(statement)) continue;
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "triggers") continue;
+			if (result) throwUnsupportedTriggers(filePath, "multiple triggers exports were found");
+			if (!declaration.initializer) throwUnsupportedTriggers(filePath, "missing initializer");
+			result = parseTriggersInitializer(filePath, declaration.initializer);
+		}
+	}
+	return result ?? {};
+}
+function scriptKindForFile(filePath) {
+	if (/\.m?js$/.test(filePath)) return ts.ScriptKind.JS;
+	return ts.ScriptKind.TS;
+}
+function hasExportModifier(statement) {
+	return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+function isTriggersReExport(statement) {
+	if (!ts.isExportDeclaration(statement) || !statement.exportClause) return false;
+	if (!ts.isNamedExports(statement.exportClause)) return false;
+	return statement.exportClause.elements.some((element) => element.name.text === "triggers");
+}
+function parseTriggersInitializer(filePath, initializer) {
+	const expr = unwrapExpression(initializer);
+	if (!ts.isObjectLiteralExpression(expr)) throwUnsupportedTriggers(filePath, "expected a static object literal");
+	const result = {};
+	for (const property of expr.properties) {
+		if (ts.isSpreadAssignment(property)) throwUnsupportedTriggers(filePath, "spread properties are not supported");
+		if (ts.isShorthandPropertyAssignment(property)) {
+			const name = property.name.text;
+			if (name === "webhook") throwUnsupportedTriggers(filePath, `"${name}" must use an explicit static value`);
+			continue;
+		}
+		if (!ts.isPropertyAssignment(property)) {
+			const name = propertyNameText(filePath, property.name);
+			if (name === "webhook") throwUnsupportedTriggers(filePath, `"${name}" must use an explicit static value`);
+			continue;
+		}
+		if (propertyNameText(filePath, property.name) === "webhook") {
+			const value = unwrapExpression(property.initializer);
+			if (value.kind === ts.SyntaxKind.TrueKeyword) result.webhook = true;
+			else if (value.kind === ts.SyntaxKind.FalseKeyword) delete result.webhook;
+			else throwUnsupportedTriggers(filePath, "\"webhook\" must be true or false");
+		}
+	}
+	return result;
+}
+function unwrapExpression(expr) {
+	while (ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr) || ts.isTypeAssertionExpression(expr) || ts.isParenthesizedExpression(expr)) expr = expr.expression;
+	return expr;
+}
+function propertyNameText(filePath, name) {
+	if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+	if (ts.isComputedPropertyName(name)) {
+		const expression = unwrapExpression(name.expression);
+		if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
+		throwUnsupportedTriggers(filePath, "computed property names must be static");
+	}
+}
+function throwUnsupportedTriggers(filePath, reason) {
+	throw new Error(`[flue] Unsupported triggers export in ${filePath}: ${reason}. Use a static object literal, for example: export const triggers = { webhook: true }.`);
+}
+const VALID_THINKING_LEVELS = {
+	off: true,
+	minimal: true,
+	low: true,
+	medium: true,
+	high: true,
+	xhigh: true
+};
+function parseThinkingLevel(value, source) {
+	if (value === void 0) return void 0;
+	const normalized = value.trim();
+	if (!normalized) return void 0;
+	if (!(normalized in VALID_THINKING_LEVELS)) throw new Error(`[flue] Invalid thinkingLevel ${JSON.stringify(value)} in ${source}. Expected one of: ${Object.keys(VALID_THINKING_LEVELS).join(", ")}.`);
+	return normalized;
+}
 /**
-* Build a workspace into a deployable artifact.
+* Build a project into a deployable artifact.
+*
+* `options.root` is the project root — typically the user's cwd. Source files
+* (agents, roles) are discovered from one of two locations inside the root,
+* with the same precedence rule the CLI uses:
 *
-* `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.
+*   - If `<root>/.flue/` exists, it is the source root. Look for
+*     `.flue/agents/` and `.flue/roles/`. The bare `<root>/agents/` and
+*     `<root>/roles/` are ignored entirely (no mixing).
+*   - Otherwise, look at `<root>/agents/` and `<root>/roles/`.
+*
+* Build output lands in `options.output` (defaults to `<root>/dist`).
 *
 * 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 root = path.resolve(options.root);
+	const output = path.resolve(options.output ?? path.join(root, "dist"));
 	const plugin = resolvePlugin(options);
-	console.log(`[flue] Building workspace: ${workspaceDir}`);
-	console.log(`[flue] Output: ${outputDir}/dist`);
+	const sourceRoot = resolveSourceRoot(root);
+	console.log(`[flue] Building: ${root}`);
+	if (sourceRoot !== root) console.log(`[flue] Source root: ${sourceRoot}`);
+	console.log(`[flue] Output: ${output}`);
 	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 roles = discoverRoles(sourceRoot);
+	const agents = discoverAgents(sourceRoot);
+	const appEntry = discoverAppEntry(sourceRoot);
+	if (agents.length === 0) throw new Error(`[flue] No agent files found.\n\nExpected at: ${path.join(sourceRoot, "agents")}/\nAdd at least one agent file (e.g. hello.ts).`);
+	if (appEntry) console.log(`[flue] Custom app entry: ${path.relative(root, appEntry) || appEntry}`);
 	const webhookAgents = agents.filter((a) => a.triggers.webhook);
 	const triggerlessAgents = agents.filter((a) => !a.triggers.webhook);
 	console.log(`[flue] Found ${Object.keys(roles).length} role(s): ${Object.keys(roles).join(", ") || "(none)"}`);
@@ -1212,33 +1036,33 @@ async function build(options) {
 	if (webhookAgents.length > 0) console.log(`[flue] Webhook agents: ${webhookAgents.map((a) => a.name).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 });
+	fs.mkdirSync(output, { recursive: true });
 	const manifest = { agents: agents.map((a) => ({
 		name: a.name,
 		triggers: a.triggers
 	})) };
-	const manifestPath = path.join(distDir, "manifest.json");
+	const manifestPath = path.join(output, "manifest.json");
 	fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
 	console.log(`[flue] Generated: ${manifestPath}`);
 	const ctx = {
 		agents,
 		roles,
-		workspaceDir,
-		outputDir,
+		root,
+		output,
+		appEntry,
 		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");
+		const entryPath = path.join(output, "_entry_server.ts");
+		const outPath = path.join(output, "server.mjs");
 		fs.writeFileSync(entryPath, serverCode, "utf-8");
 		try {
-			const nodePathsSet = collectNodePaths(workspaceDir);
+			const nodePathsSet = collectNodePaths(root);
 			const { external: pluginExternal = [], ...pluginEsbuildOpts } = plugin.esbuildOptions ? plugin.esbuildOptions(ctx) : {};
-			const userExternals = getUserExternals(workspaceDir);
+			const userExternals = getUserExternals(root);
 			await esbuild.build({
 				entryPoints: [entryPath],
 				bundle: true,
@@ -1264,7 +1088,7 @@ async function build(options) {
 		}
 	} 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);
+		const outPath = path.join(output, 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)`);
@@ -1274,7 +1098,7 @@ async function build(options) {
 	if (plugin.additionalOutputs) {
 		const outputs = await plugin.additionalOutputs(ctx);
 		for (const [filename, content] of Object.entries(outputs)) {
-			const filePath = path.join(distDir, filename);
+			const filePath = path.join(output, filename);
 			fs.mkdirSync(path.dirname(filePath), { recursive: true });
 			if (!fs.existsSync(filePath) || fs.readFileSync(filePath, "utf-8") !== content) {
 				fs.writeFileSync(filePath, content, "utf-8");
@@ -1283,7 +1107,7 @@ async function build(options) {
 			}
 		}
 	}
-	console.log(`[flue] Build complete. Output: ${distDir}`);
+	console.log(`[flue] Build complete. Output: ${output}`);
 	return { changed: anyChanged };
 }
 function resolvePlugin(options) {
@@ -1296,26 +1120,25 @@ function resolvePlugin(options) {
 	}
 }
 /**
-* 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()`.
+* Resolve the source root for a project, using the `.flue/`-as-src
+* convention (analogous to Next.js's `src/` folder).
 *
-* 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 `<root>/.flue/` exists, it is the source root. Otherwise the source root
+* is the project root itself. The two layouts never mix — if `.flue/` exists,
+* the bare layout is ignored entirely (even if a `<root>/agents/` directory
+* also happens to be present).
 *
-* 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.
+* The project root (cwd) stays the same in both cases — `.flue/` only shifts
+* where source files are discovered from. The build output directory is
+* independent (defaults to `<root>/dist`, override with `output`).
 */
-function resolveWorkspaceFromCwd(cwd) {
-	const dotFlue = path.join(cwd, ".flue");
+function resolveSourceRoot(root) {
+	const dotFlue = path.join(root, ".flue");
 	if (fs.existsSync(dotFlue)) return dotFlue;
-	if (fs.existsSync(path.join(cwd, "agents"))) return cwd;
-	return null;
+	return root;
 }
-function discoverRoles(workspaceRoot) {
-	const rolesDir = path.join(workspaceRoot, "roles");
+function discoverRoles(sourceRoot) {
+	const rolesDir = path.join(sourceRoot, "roles");
 	if (!fs.existsSync(rolesDir)) return {};
 	const roles = {};
 	for (const entry of fs.readdirSync(rolesDir)) {
@@ -1324,17 +1147,19 @@ function discoverRoles(workspaceRoot) {
 		const content = fs.readFileSync(filePath, "utf-8");
 		const name = entry.replace(/\.(md|markdown)$/i, "");
 		const parsed = parseFrontmatterFile(content, name);
+		const thinkingLevel = parseThinkingLevel(parsed.frontmatter.thinkingLevel, `role "${name}" frontmatter`);
 		roles[name] = {
 			name,
 			description: parsed.description,
 			instructions: parsed.body,
-			model: parsed.frontmatter.model
+			model: parsed.frontmatter.model,
+			thinkingLevel
 		};
 	}
 	return roles;
 }
-function discoverAgents(workspaceRoot) {
-	const agentsDir = path.join(workspaceRoot, "agents");
+function discoverAgents(sourceRoot) {
+	const agentsDir = path.join(sourceRoot, "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);
@@ -1346,9 +1171,29 @@ function discoverAgents(workspaceRoot) {
 		};
 	});
 }
+/**
+* Discover an optional `app.{ts,mts,js,mjs}` entry alongside `agents/`
+* and `roles/`. Returns the absolute path to the first match found, or
+* undefined when no app entry is present.
+*
+* Extension priority matches {@link discoverAgents}: `.ts` > `.mts`
+* > `.js` > `.mjs`. Source-files-only — we don't probe inside the
+* `agents/` or `roles/` subdirs.
+*/
+function discoverAppEntry(sourceRoot) {
+	for (const ext of [
+		"ts",
+		"mts",
+		"js",
+		"mjs"
+	]) {
+		const candidate = path.join(sourceRoot, `app.${ext}`);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+}
 /** Externalize user's direct deps (bare name + subpath wildcard). */
-function getUserExternals(workspaceDir) {
-	const pkgPath = packageUpSync({ cwd: workspaceDir });
+function getUserExternals(root) {
+	const pkgPath = packageUpSync({ cwd: root });
 	if (!pkgPath) return [];
 	try {
 		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -1361,9 +1206,9 @@ function getUserExternals(workspaceDir) {
 		return [];
 	}
 }
-function collectNodePaths(workspaceDir) {
+function collectNodePaths(root) {
 	const nodePathsSet = /* @__PURE__ */ new Set();
-	for (const startDir of [workspaceDir, getSDKDir()]) {
+	for (const startDir of [root, getSDKDir()]) {
 		let dir = startDir;
 		while (dir !== path.dirname(dir)) {
 			const nm = path.join(dir, "node_modules");
@@ -1386,7 +1231,7 @@ function getSDKDir() {
 /**
 * Flue dev server.
 *
-* Watches the user's workspace, rebuilds on file changes, and reloads the
+* Watches the project root, 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).
@@ -1397,7 +1242,7 @@ function getSDKDir() {
 * 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
+*   `dist/server.mjs`. On any change in the root we rebuild and respawn
 *   the child Node process. Sub-second restart is fine.
 *
 * - **Cloudflare** uses Wrangler's bundler (the same one `wrangler dev` and
@@ -1426,18 +1271,18 @@ const DEFAULT_DEV_PORT = 3583;
 * — 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 root = path.resolve(options.root);
+	const output = path.resolve(options.output ?? path.join(root, "dist"));
 	const port = options.port ?? DEFAULT_DEV_PORT;
-	const envFiles = resolveEnvFiles(options.envFiles, outputDir);
+	const envFiles = resolveEnvFiles(options.envFiles, root);
 	for (const f of envFiles) console.error(`[flue] Loading env from: ${f}`);
 	const buildOptions = {
-		workspaceDir,
-		outputDir,
+		root,
+		output,
 		target: options.target
 	};
 	console.error(`[flue] Starting dev server (target: ${options.target})`);
-	console.error(`[flue] Watching: ${workspaceDir}`);
+	console.error(`[flue] Watching: ${root}`);
 	console.error(`[flue] Building...`);
 	const initialStart = Date.now();
 	try {
@@ -1447,18 +1292,19 @@ async function dev(options) {
 	}
 	console.error(`[flue] Built in ${Date.now() - initialStart}ms`);
 	const reloader = options.target === "node" ? new NodeReloader({
-		outputDir,
+		root,
+		output,
 		port,
 		envFiles
 	}) : await createCloudflareReloader({
-		outputDir,
+		output,
 		port,
 		envFiles
 	});
 	await reloader.start();
 	if (reloader.url) {
 		console.error(`[flue] Server: ${reloader.url}`);
-		const exampleAgent = pickExampleAgentName(outputDir, workspaceDir);
+		const exampleAgent = pickExampleAgentName(output, root);
 		if (exampleAgent) {
 			console.error(`[flue] Try: curl -X POST ${reloader.url}/agents/${exampleAgent}/test-1 \\`);
 			console.error(`         -H 'Content-Type: application/json' -d '{}'`);
@@ -1468,8 +1314,8 @@ async function dev(options) {
 	const rebuilder = createRebuilder(buildOptions, reloader);
 	const envFileSet = new Set(envFiles);
 	const watcher = createWatcher({
-		workspaceDir,
-		outputDir,
+		root,
+		output,
 		target: options.target,
 		envFiles,
 		onChange: (relPath) => {
@@ -1543,39 +1389,46 @@ function createRebuilder(buildOptions, reloader) {
 	} };
 }
 /**
-* Watch the workspace for changes. Uses `fs.watch` recursive (Node 20+).
+* Watch the root 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`),
+*   - `<root>` — agents/, roles/, AGENTS.md, .agents/skills/, plus
+*     `.flue/agents/` and `.flue/roles/` if the root uses the .flue/
+*     source layout.
+*   - For Cloudflare: also `<root>/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
+*   - The build output directory (`output`, defaults to `<root>/dist`).
+*     Critical to break the build → file-change → rebuild loop.
+*   - `node_modules/`, `.git/`, `.turbo/`
+*   - Dotfiles and dotdirs at the project root, with one exception: the
+*     `.flue/` source directory and everything inside it is allowed through
+*     (since that's a valid source location under the .flue-as-src layout).
+*   - Editor backup/swap suffixes
 */
 function createWatcher(options) {
-	const { workspaceDir, outputDir, target, envFiles, onChange } = options;
+	const { root, output, target, envFiles, onChange } = options;
 	const watchers = [];
+	const outputRelToRoot = path.relative(root, output).split(path.sep).join("/");
 	const isIgnoredPath = (relPath) => {
-		const parts = relPath.replace(/\\/g, "/").split("/");
+		const normalized = relPath.replace(/\\/g, "/");
+		if (normalized === ".flue" || normalized.startsWith(".flue/")) return false;
+		if (outputRelToRoot && !outputRelToRoot.startsWith("..") && (normalized === outputRelToRoot || normalized.startsWith(outputRelToRoot + "/"))) return true;
+		const parts = normalized.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.startsWith(".")) 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) => {
+		const w = fs.watch(root, { recursive: true }, (_event, filename) => {
 			if (!filename) return;
 			const rel = filename.toString();
 			if (isIgnoredPath(rel)) return;
@@ -1583,14 +1436,14 @@ function createWatcher(options) {
 		});
 		watchers.push(w);
 	} catch (err) {
-		console.error(`[flue] Failed to watch ${workspaceDir}: ${err instanceof Error ? err.message : String(err)}`);
+		console.error(`[flue] Failed to watch ${root}: ${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);
+		const cfgPath = path.join(root, cfgName);
 		if (!fs.existsSync(cfgPath)) continue;
 		try {
 			const w = fs.watch(cfgPath, () => onChange(cfgName));
@@ -1610,15 +1463,15 @@ function createWatcher(options) {
 var NodeReloader = class {
 	child = null;
 	serverPath;
-	outputDir;
+	root;
 	port;
 	envFiles;
 	url;
 	constructor(opts) {
-		this.outputDir = opts.outputDir;
+		this.root = opts.root;
 		this.port = opts.port;
 		this.envFiles = opts.envFiles;
-		this.serverPath = path.join(this.outputDir, "dist", "server.mjs");
+		this.serverPath = path.join(opts.output, "server.mjs");
 		this.url = `http://localhost:${this.port}`;
 	}
 	async start() {
@@ -1649,7 +1502,7 @@ var NodeReloader = class {
 				"pipe",
 				"pipe"
 			],
-			cwd: this.outputDir,
+			cwd: this.root,
 			env: {
 				...fromFiles,
 				...process.env,
@@ -1674,10 +1527,6 @@ var NodeReloader = class {
 				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;
@@ -1731,7 +1580,6 @@ Underlying error: ${err instanceof Error ? err.message : String(err)}`);
 var CloudflareReloader = class {
 	worker = null;
 	wrangler;
-	outputDir;
 	port;
 	configPath;
 	envFiles;
@@ -1761,10 +1609,9 @@ var CloudflareReloader = class {
 	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");
+		this.configPath = path.join(opts.output, "wrangler.jsonc");
 		this.containerBuildId = randomUUID().slice(0, 8);
 	}
 	async start() {
@@ -1783,19 +1630,26 @@ var CloudflareReloader = class {
 	*     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.
+	*   - Adds/removes/edits of `app.{ts,mts,js,mjs}` — discovery flips the
+	*     entry between the user-app form and the default-app fallback,
+	*     and the import path is baked into `_entry.ts`. Body edits are
+	*     handled by wrangler's source watcher, but emitting a rebuild on
+	*     the path itself is cheap and means add/remove is correctly
+	*     observed even when the user toggles the file in/out.
 	*   - 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).
+	* them): edits to imported source files outside of `agents/`/`roles/`/
+	* `app.*`, 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;
+		if (normalized.startsWith("agents/") || normalized.startsWith(".flue/agents/")) return true;
+		if (normalized.startsWith("roles/") || normalized.startsWith(".flue/roles/")) return true;
+		if (/^(?:\.flue\/)?app\.(?:ts|mts|js|mjs)$/.test(normalized)) return true;
 		return false;
 	}
 	async reload(buildChanged) {
@@ -1892,32 +1746,18 @@ function parseEnvFiles(absolutePaths) {
 	}
 	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.
+* manifest written by the build at `<output>/manifest.json`, with a
+* source-tree scan fallback in case the manifest is somehow missing.
 *
 * Best-effort — silently returns null if anything goes wrong.
 */
-function pickExampleAgentName(outputDir, workspaceDir) {
+function pickExampleAgentName(output, root) {
 	try {
-		const manifestPath = path.join(outputDir, "dist", "manifest.json");
+		const manifestPath = path.join(output, "manifest.json");
 		if (fs.existsSync(manifestPath)) {
 			const agents = JSON.parse(fs.readFileSync(manifestPath, "utf-8")).agents ?? [];
 			const webhook = agents.find((a) => a.triggers?.webhook);
@@ -1926,7 +1766,7 @@ function pickExampleAgentName(outputDir, workspaceDir) {
 		}
 	} catch {}
 	try {
-		const agentsDir = path.join(workspaceDir, "agents");
+		const agentsDir = path.join(resolveSourceRoot(root), "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)$/);
@@ -1939,4 +1779,4 @@ function pickExampleAgentName(outputDir, workspaceDir) {
 }
 
 //#endregion
-export { BUILTIN_TOOL_NAMES, DEFAULT_DEV_PORT, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };
+export { BUILTIN_TOOL_NAMES, DEFAULT_DEV_PORT, ResultUnavailableError, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveSourceRoot };