@flue/sdk 0.3.5 → 0.3.7

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,6 +404,7 @@ 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';
@@ -405,6 +414,13 @@ import {
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
+  parseJsonBody,
+  toHttpResponse,
+  toSseData,
+  AgentNotFoundError,
+  MethodNotAllowedError,
+  RouteNotFoundError,
+  InvalidRequestError,
 } from '@flue/sdk/internal';
 import { runWithCloudflareContext, cfSandboxToSessionEnv } from '@flue/sdk/cloudflare';
 
@@ -417,12 +433,11 @@ const skills = {};
 const systemPrompt = '';
 const manifest = ${manifest};
 
-// ─── Infrastructure ─────────────────────────────────────────────────────────
-
-// No build-time model default. The user sets model at runtime via
-// \`init({ model: "provider/model-id" })\` for an agent default, or via
-// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
-const model = undefined;
+// 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))});
 
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
@@ -527,7 +542,7 @@ function createContextForRequest(id, payload, doInstance) {
     payload,
     env: doInstance?.env ?? {},
     agentConfig: {
-      systemPrompt, skills, roles, model, resolveModel,
+      systemPrompt, skills, roles, model: undefined, resolveModel,
     },
     createDefaultEnv,
     createLocalEnv,
@@ -597,19 +612,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();
@@ -628,7 +640,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();
@@ -640,7 +658,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')));
       };
@@ -662,10 +680,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');
           }
@@ -696,11 +711,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);
   }
 }
 
@@ -710,38 +724,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);
+    }
   },
 };
 `;
@@ -766,7 +819,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);
@@ -810,6 +863,11 @@ import {
   InMemorySessionStore,
   bashFactoryToSessionEnv,
   resolveModel,
+  parseJsonBody,
+  validateAgentRequest,
+  toHttpResponse,
+  toSseData,
+  RouteNotFoundError,
 } from '@flue/sdk/internal';
 import { randomUUID } from 'node:crypto';
 
@@ -827,7 +885,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
@@ -841,13 +902,6 @@ const manifest = ${JSON.stringify({ agents: agents.map((a) => ({
 			triggers: a.triggers
 		})) }, null, 2)};
 
-// ─── Infrastructure ─────────────────────────────────────────────────────────
-
-// No build-time model default. The user sets model at runtime via
-// \`init({ model: "provider/model-id" })\` for an agent default, or via
-// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
-const model = undefined;
-
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
 /**
@@ -887,7 +941,7 @@ function createContextForRequest(id, payload) {
     payload,
     env: process.env,
     agentConfig: {
-      systemPrompt, skills, roles, model, resolveModel,
+      systemPrompt, skills, roles, model: undefined, resolveModel,
     },
     createDefaultEnv,
     createLocalEnv,
@@ -902,31 +956,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';
@@ -949,7 +1001,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;
@@ -973,7 +1031,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++),
         });
@@ -987,18 +1045,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);
@@ -1594,6 +1663,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;
@@ -1601,6 +1693,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();
@@ -1659,9 +1752,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 {
@@ -1670,8 +1772,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) {