@flue/sdk 0.3.4 → 0.3.6

package/README.md

@@ -4,11 +4,13 @@
 
 # Flue
 
-Flue is **The Sandbox Agent Framework.** If you know how to use Claude Code (or OpenCode, Codex, Gemini, etc)... then you already know the basics of how to build agents with Flue.
+Flue is **The Agent Harness Framework.** If you know how to use Claude Code (or OpenCode, Codex, Gemini, etc)... then you already know the basics of how to build agents with Flue.
 
-A [Sandbox Agent](https://developers.openai.com/api/docs/guides/agents/sandboxes) pairs an **agent harness** (like Claude Code) with a secure, isolated container workspace. Sandbox Agents can edit files, write and execute code, spin up subagents, run terminal commands, and drive themselves autonomously to solve any given task. This pattern unlocks more powerful, intelligent agents that traditional AI frameworks wouldn't otherwise let you build.
+Flue is a TypeScript framework for building the next generation of agents, designed around a built-in **agent harness**. It's like Claude Code, but 100% headless and programmable. There's no baked-in assumption like requiring a human operator to function. No TUI. No GUI. Just TypeScript.
 
-Our take is that 1) any agent can be represented as a Sandbox Agent, and 2) any agent is _best_ represented as a Sandbox Agent. So we designed Flue to deliver on this vision.
+But using Flue feels like using Claude Code. The agents you build act autonomously to solve problems and complete tasks. They require very little code to run — most of the "logic" lives in Markdown: skills, context, and `AGENTS.md`.
+
+Flue isn't another AI SDK. It's a proper runtime-agnostic framework — think Astro or Next.js, but for agents. Write once, build, and deploy your agents anywhere (Node.js, Cloudflare, GitHub Actions, GitLab CI/CD, etc).
 
 ## Packages
 

package/dist/{agent-BB4lwAd5.mjs → agent-BTB0809P.mjs}

@@ -287,7 +287,7 @@ function createBashTool(env) {
 		}),
 		async execute(_toolCallId, params, signal) {
 			throwIfAborted(signal);
-			return formatBashResult(await env.exec(params.command), params.command);
+			return formatBashResult(await env.exec(params.command, { timeout: params.timeout }), params.command);
 		}
 	};
 }

package/dist/client.d.mts

@@ -1,5 +1,5 @@
-import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, p as FlueContext, r as AgentInit, t as AgentConfig, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-T8pE1xIS.mjs";
-import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-BVF-sOBZ.mjs";
+import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, p as FlueContext, r as AgentInit, t as AgentConfig, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-CItTrBsU.mjs";
+import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-EZy-Vb5M.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts

package/dist/client.mjs

@@ -1,7 +1,7 @@
-import { r as discoverSessionContext } from "./agent-BB4lwAd5.mjs";
-import { a as assertRoleExists } from "./session-DukL3zwF.mjs";
+import { r as discoverSessionContext } from "./agent-BTB0809P.mjs";
+import { a as assertRoleExists } from "./session-BaaSQTWS.mjs";
 import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
-import { n as AgentClient, t as connectMcpServer } from "./mcp-DOgMtp8y.mjs";
+import { n as AgentClient, t as connectMcpServer } from "./mcp-DTFRe9vh.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.ts

package/dist/cloudflare/index.d.mts

@@ -1,5 +1,5 @@
-import { C as SessionEnv, T as SessionStore, l as Command } from "../types-T8pE1xIS.mjs";
-import { t as CommandExecutor } from "../command-helpers-DdAfbnom.mjs";
+import { C as SessionEnv, T as SessionStore, l as Command } from "../types-CItTrBsU.mjs";
+import { t as CommandExecutor } from "../command-helpers-CXzopT_-.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {

package/dist/cloudflare/index.mjs

@@ -1,5 +1,5 @@
-import "../agent-BB4lwAd5.mjs";
-import "../session-DukL3zwF.mjs";
+import "../agent-BTB0809P.mjs";
+import "../session-BaaSQTWS.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
 import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
@@ -195,9 +195,11 @@ async function cfSandboxToSessionEnv(sandbox, cwd = "/workspace") {
 			} else await sandbox.deleteFile(path);
 		},
 		async exec(command, execOpts) {
+			const timeoutMs = typeof execOpts?.timeout === "number" ? execOpts.timeout * 1e3 : void 0;
 			const result = await sandbox.exec(command, {
 				cwd: execOpts?.cwd,
-				env: execOpts?.env
+				env: execOpts?.env,
+				timeout: timeoutMs
 			});
 			return {
 				stdout: result.stdout ?? "",

package/dist/{command-helpers-DdAfbnom.d.mts → command-helpers-CXzopT_-.d.mts}

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

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, O as Skill, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, b as Role, c as BuildPlugin, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, n as AgentInfo, o as BuildContext, p as FlueContext, r as AgentInit, s as BuildOptions, t as AgentConfig, u as CommandDef, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-T8pE1xIS.mjs";
+import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, O as Skill, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, b as Role, c as BuildPlugin, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, n as AgentInfo, o as BuildContext, p as FlueContext, r as AgentInit, s as BuildOptions, t as AgentConfig, u as CommandDef, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-CItTrBsU.mjs";
 import { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
 
 //#region src/build.d.ts

package/dist/index.mjs

@@ -1,9 +1,10 @@
-import { a as parseFrontmatterFile, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BB4lwAd5.mjs";
+import { a as parseFrontmatterFile, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BTB0809P.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 { randomUUID } from "node:crypto";
 import { parseEnv } from "node:util";
 
 //#region src/cloudflare-wrangler-merge.ts
@@ -267,11 +268,11 @@ function stripNoisyWranglerDefaults(merged) {
 }
 /**
 * Return the list of `class_name`s declared in the user's wrangler
-* `durable_objects.bindings` that contain the literal substring `Sandbox`
+* `durable_objects.bindings` that end with the literal suffix `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
+* whose class name ends with `Sandbox` triggers an automatic re-export in the
 * generated Worker entry:
 *
 *   export { Sandbox as <class_name> } from '@cloudflare/sandbox';
@@ -281,6 +282,13 @@ function stripNoisyWranglerDefaults(merged) {
 * `@cloudflare/sandbox` package. Each distinct `class_name` can be paired with
 * a different container image in the user's `containers[]` config.
 *
+* The match is intentionally a suffix (not substring) so that user-defined
+* classes whose names merely contain "Sandbox" mid-word — e.g. `MySandboxV2`,
+* `MySandboxedAgent`, `LegacySandboxedThing` — are not silently overridden
+* by the `@cloudflare/sandbox` re-export. Note that classes whose names
+* still end in `Sandbox` (e.g. `MockSandbox`, `NotASandbox`) will match;
+* to opt out, rename the class to not end in `Sandbox`.
+*
 * Returns unique, sorted class names. Non-object bindings or bindings without
 * a string `class_name` are ignored.
 */
@@ -294,7 +302,7 @@ function detectSandboxBindings(userConfig) {
 		if (typeof entry !== "object" || entry === null) continue;
 		const className = entry.class_name;
 		if (typeof className !== "string") continue;
-		if (className.includes("Sandbox")) found.add(className);
+		if (className.endsWith("Sandbox")) found.add(className);
 	}
 	return Array.from(found).sort();
 }
@@ -328,7 +336,7 @@ function assertSandboxPackageInstalled(sandboxClassNames, searchDirs) {
 			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\`.`);
+	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`
@@ -396,16 +404,23 @@ var CloudflarePlugin = class {
 }`;
 		}).join("\n\n");
 		const { config: userConfig } = await this.getUserConfig(ctx.outputDir);
+		const sandboxReExports = detectSandboxBindings(userConfig).map((name) => `export { Sandbox as ${name} } from '@cloudflare/sandbox';`).join("\n");
 		return `
 // Auto-generated by @flue/sdk build (cloudflare)
 import { Agent, routeAgentRequest } from 'agents';
-import { DurableObject } from 'cloudflare:workers';
 import { Bash, InMemoryFs } from 'just-bash';
 import {
   createFlueContext,
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
+  parseJsonBody,
+  toHttpResponse,
+  toSseData,
+  AgentNotFoundError,
+  MethodNotAllowedError,
+  RouteNotFoundError,
+  InvalidRequestError,
 } from '@flue/sdk/internal';
 import { runWithCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
 
@@ -418,6 +433,12 @@ 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))});
+
 // ─── Infrastructure ─────────────────────────────────────────────────────────
 
 // No build-time model default. The user sets model at runtime via
@@ -456,24 +477,34 @@ async function createLocalEnv() {
  * RPC stub, null otherwise.
  *
  * NOTE on detection: The value returned by \`getSandbox()\` is a workerd RPC
- * Proxy. \`in\` and \`typeof\` against it return \`true\`/\`'function'\` for any
- * property name, so structural duck-typing is unreliable.
+ * Proxy. None of the obvious detection strategies work:
  *
- * \`instanceof <UserSandboxClass>\` ALSO does not work: the RPC stub's
- * prototype chain is workerd's internal \`DurableObject\` runtime class, not
- * the user-defined \`Sandbox\` class (the user's class only exists on the
- * in-DO side; the caller side gets a generic stub). Empirically:
- *   typeof stub === 'object'
- *   Object.getPrototypeOf(stub).constructor.name === 'DurableObject'
+ *   - Structural duck-typing (\`'X' in stub\`, \`typeof stub.X === 'function'\`):
+ *     the proxy lies positively for any property name, so any check returns
+ *     \`true\` regardless of what's actually on the remote.
+ *   - \`instanceof <UserSandboxClass>\` (e.g. \`Sandbox\` from
+ *     \`@cloudflare/sandbox\`): the user's class only exists on the in-DO
+ *     side; over RPC the caller gets a generic stub.
+ *   - \`instanceof DurableObject\` (imported from \`cloudflare:workers\`): the
+ *     stub's prototype chain has a class *named* \`DurableObject\`, but it's a
+ *     workerd-internal class with a different identity than the importable
+ *     one. \`instanceof\` checks identity, not name, so it returns \`false\`.
  *
- * \`instanceof DurableObject\` (imported from \`cloudflare:workers\`) is the
- * one signal that holds: it walks the prototype chain via the runtime and
- * matches any DO RPC stub. We treat any DO stub passed to \`init({ sandbox })\`
- * as intended for \`@cloudflare/sandbox\`, since that's the only documented
- * use case for that argument shape on the Cloudflare target.
+ * The one signal that does work — verified by runtime probe — is the string
+ * name of the prototype's constructor. Workerd's internal RPC stub class is
+ * named \`DurableObject\`, and \`Object.getPrototypeOf(stub).constructor.name\`
+ * returns that string. This is a heuristic (it relies on a workerd-internal
+ * naming convention, not a contractual API), but it's empirically correct
+ * today and will misroute only if a user passes some other DO stub to
+ * \`init({ sandbox })\` — in which case \`cfSandboxToSessionEnv\` will fail
+ * loudly on first method call.
  */
 function resolveSandbox(sandbox) {
-  if (sandbox instanceof DurableObject) {
+  if (
+    sandbox &&
+    typeof sandbox === 'object' &&
+    Object.getPrototypeOf(sandbox)?.constructor?.name === 'DurableObject'
+  ) {
     return cfSandboxToSessionEnv(sandbox);
   }
   return null;
@@ -588,19 +619,16 @@ 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 = {};
-  }
+    // 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;
+    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();
@@ -619,7 +647,13 @@ async function handleAgentRequest(request, doInstance, agentName, handler) {
       });
     }
 
-    // SSE streaming mode
+    // 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();
@@ -631,7 +665,7 @@ async function handleAgentRequest(request, doInstance, agentName, handler) {
         const lines = [];
         if (event) lines.push('event: ' + event);
         lines.push('id: ' + eventId++);
-        lines.push('data: ' + JSON.stringify(data));
+        lines.push('data: ' + (typeof data === 'string' ? data : JSON.stringify(data)));
         lines.push('', '');
         await writer.write(encoder.encode(lines.join('\\n')));
       };
@@ -653,10 +687,7 @@ async function handleAgentRequest(request, doInstance, agentName, handler) {
             'result',
           );
         } catch (err) {
-          await writeSSE(
-            { type: 'error', error: String(err) },
-            'error',
-          );
+          await writeSSE(toSseData(err), 'error');
           if (!isIdle) {
             await writeSSE({ type: 'idle' }, 'idle');
           }
@@ -687,11 +718,10 @@ async function handleAgentRequest(request, doInstance, agentName, handler) {
       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' } },
-    );
+    // 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);
   }
 }
 
@@ -701,38 +731,77 @@ ${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
+// ends with "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")}
+${sandboxReExports}
 
 // ─── Worker Fetch Handler ───────────────────────────────────────────────────
 
 export default {
   async fetch(request, env) {
-    const url = new URL(request.url);
+    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' },
-      });
-    }
+      // 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' },
-      });
-    }
+      // Agent manifest
+      if (url.pathname === '/agents' && 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;
+      // 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 });
+      }
 
-    return new Response('Not found', { status: 404 });
+      // 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);
+    }
   },
 };
 `;
@@ -757,7 +826,7 @@ export default {
 		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.`);
+			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);
@@ -801,6 +870,11 @@ import {
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
+  parseJsonBody,
+  validateAgentRequest,
+  toHttpResponse,
+  toSseData,
+  RouteNotFoundError,
 } from '@flue/sdk/internal';
 import { randomUUID } from 'node:crypto';
 
@@ -818,7 +892,10 @@ 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))});
+// 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))});
 
 // 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
@@ -893,31 +970,29 @@ 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) => {
+// 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');
 
-  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);
-  }
+  // 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];
-  let payload;
-  try {
-    payload = await c.req.json();
-  } catch {
-    payload = {};
-  }
+
+  // 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';
@@ -940,7 +1015,13 @@ app.post('/agents/:name/:id', async (c) => {
     return c.json({ status: 'accepted', requestId }, 202);
   }
 
-  // SSE streaming mode
+  // 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;
@@ -964,7 +1045,7 @@ app.post('/agents/:name/:id', async (c) => {
         });
       } catch (err) {
         await stream.writeSSE({
-          data: JSON.stringify({ type: 'error', error: String(err) }),
+          data: toSseData(err),
           event: 'error',
           id: String(eventId++),
         });
@@ -978,18 +1059,29 @@ app.post('/agents/:name/:id', async (c) => {
     });
   }
 
-  // Sync mode (default)
+  // Sync mode (default). Errors propagate to app.onError.
+  const ctx = createContextForRequest(id, payload);
   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);
+  } finally {
+    ctx.setEventCallback(undefined);
   }
 });
 
+// 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 });
+});
+
+// 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));
+
 // ─── Start ──────────────────────────────────────────────────────────────────
 
 const port = parseInt(process.env.PORT || '3000', 10);
@@ -1585,6 +1677,29 @@ var CloudflareReloader = class {
 	port;
 	configPath;
 	envFiles;
+	/**
+	* Stable container build ID for the lifetime of this reloader instance.
+	*
+	* `unstable_startWorker` does NOT default this field — only wrangler's CLI
+	* path does, via `generateContainerBuildId()`. When the user's wrangler
+	* config declares `containers[]` (e.g. via `@cloudflare/sandbox`), the
+	* first `onBundleComplete` calls `getImageNameFromDOClassName(...)` which
+	* asserts that `options.containerBuildId` is set; without this, the
+	* assertion throws, the `ProxyController` never gets `reloadComplete`,
+	* and every request hangs (including `/health`). See issue #22.
+	*
+	* We generate it once per reloader and reuse it across reloads so that
+	* wrangler's container-prep cache hits when nothing about the image
+	* changed. Format matches wrangler's own helper: an 8-char UUID slice.
+	*/
+	containerBuildId;
+	/**
+	* Bound listener for `DevEnv` `'error'` events. Stored so we can detach
+	* it on `disposeWorker()` — the underlying `EventEmitter` outlives the
+	* worker handle, so if the listener stayed attached we'd leak (and
+	* double-fire) across reloads.
+	*/
+	errorListener = null;
 	url;
 	constructor(wrangler, opts) {
 		this.wrangler = wrangler;
@@ -1592,6 +1707,7 @@ var CloudflareReloader = class {
 		this.port = opts.port;
 		this.envFiles = opts.envFiles;
 		this.configPath = path.join(this.outputDir, "dist", "wrangler.jsonc");
+		this.containerBuildId = randomUUID().slice(0, 8);
 	}
 	async start() {
 		await this.startWorker();
@@ -1650,9 +1766,18 @@ var CloudflareReloader = class {
 					port: this.port
 				},
 				watch: false,
-				logLevel: "info"
+				logLevel: "info",
+				containerBuildId: this.containerBuildId
 			}
 		});
+		this.errorListener = (event) => {
+			const reason = event?.reason ?? "unknown error";
+			const cause = event?.cause;
+			const causeMsg = cause && typeof cause === "object" && "message" in cause ? cause.message : void 0;
+			console.error(`[flue] Wrangler error (${event?.source ?? "unknown"}): ${reason}`);
+			if (causeMsg) console.error(`[flue]   ${causeMsg}`);
+		};
+		this.worker.raw.on("error", this.errorListener);
 		try {
 			this.url = (await this.worker.url).toString().replace(/\/$/, "");
 		} catch {
@@ -1661,8 +1786,13 @@ var CloudflareReloader = class {
 	}
 	async disposeWorker() {
 		const worker = this.worker;
+		const listener = this.errorListener;
 		this.worker = null;
+		this.errorListener = null;
 		if (!worker) return;
+		if (listener) try {
+			worker.raw.off("error", listener);
+		} catch {}
 		try {
 			await worker.dispose();
 		} catch (err) {