@flue/sdk 0.3.11 → 0.4.0

package/dist/flue-app-DeTOZjPs.mjs

@@ -0,0 +1,730 @@
+import { Hono } from "hono";
+
+//#region src/errors.ts
+/**
+* Complete error framework for Flue.
+*
+* This file contains both the error vocabulary (concrete error classes) and
+* the framework utilities (renderers, type guards, request parsing helpers).
+* Previously split across `errors.ts` and `error-utils.ts`, but consolidated
+* for better LLM comprehension.
+*
+* ──── Why this file exists ────────────────────────────────────────────────
+*
+* Concentrating every error in one file is deliberate. When all errors are
+* visible together, it's easy to:
+*
+*   - Keep message tone and detail level consistent across the codebase.
+*   - Notice duplicates ("oh, we already have an error for this case").
+*   - Establish norms by example — when adding a new error, look at the
+*     neighbors above and copy the pattern.
+*
+* Application code throughout the codebase should reach for one of these
+* classes rather than constructing a `FlueError` ad hoc. If no existing class
+* fits, add one here. That's the entire convention.
+*
+* ──── Two audiences: caller vs. developer ─────────────────────────────────
+*
+* The reader of an error message is one of two distinct audiences:
+*
+*   - The *caller*: an HTTP client. Possibly third-party, possibly hostile,
+*     possibly an end user who shouldn't even know we're built on Flue.
+*     Sees `message` and `details` always.
+*
+*   - The *developer*: the human running the service (`flue dev`, `flue run`,
+*     local debugging). Sees `dev` in addition, but only when the server is
+*     running in local/dev mode (gated by `FLUE_MODE=local`).
+*
+* Every error class must classify its prose by audience. The required-but-
+* possibly-empty shape of both `details` and `dev` is the discipline:
+* forgetting either field is a TypeScript error, and writing `''` is a
+* deliberate "I have nothing for that audience" decision.
+*
+* Concretely:
+*
+*   - `message`     One sentence. Caller-safe. Always rendered.
+*   - `details`     Longer caller-safe prose. About the request itself, the
+*                   contract, what the caller can do to fix it. Always
+*                   rendered. NEVER includes:
+*                     - sibling/neighbor enumeration (leaks namespace)
+*                     - filesystem paths or "agents/" / "skills/" / etc.
+*                       (leaks framework internals)
+*                     - source-code-level fix instructions ("add ... to your
+*                       agent definition") (caller can't act on these)
+*                     - build-time or runtime mechanics
+*   - `dev`         Longer dev-audience prose. Available alternatives,
+*                   filesystem layout, framework guidance, source-code-level
+*                   fix instructions. Rendered ONLY when FLUE_MODE=local.
+*
+* When in doubt, put information in `dev`. The default is conservative.
+*
+* ──── Conventions for new error classes ───────────────────────────────────
+*
+*   - Class name: PascalCase, suffixed with `Error`. E.g. `AgentNotFoundError`.
+*   - The class owns its `type` constant (snake_case). Set once in the
+*     subclass constructor, never passed by callers. Renaming the wire type
+*     is then a one-line change.
+*   - Constructor takes ONLY structured input data (the values used to build
+*     the message). The constructor assembles `message`, `details`, and
+*     `dev` from that data, so call sites never reinvent phrasing.
+*   - `details` and `dev` are both required strings. Pass `''` only when
+*     there's genuinely nothing more to say for that audience.
+*   - For HTTP errors, the class sets its own `status` (and `headers` where
+*     relevant). Callers do not pick HTTP status codes ad-hoc.
+*
+* Worked example (matches `AgentNotFoundError` below):
+*
+*     new AgentNotFoundError({ name, available });
+*     // builds:
+*     //   message: `Agent "foo" is not registered.`
+*     //   details: `Verify the agent name is correct.`
+*     //   dev:     `Available agents: "echo", "greeter". Agents are
+*     //            loaded from the project root's "agents/" directory at
+*     //            build time. ...`
+*
+* The wire response in production omits `dev`; in `flue dev` / `flue run`
+* it includes `dev`. That separation is what lets the dev field be richly
+* helpful without leaking namespace state to public callers.
+*
+* Counter-example to avoid:
+*
+*     class AgentNotFoundError extends FlueHttpError {
+*       constructor(message: string) {                       // ✗ free-form
+*         super({                                            // ✗ wrong type
+*           type: 'agent_error',
+*           message,
+*           details: 'Available: "x", "y", "z"',             // ✗ leaks names
+*           dev: '',                                         // ✗ wasted channel
+*           status: 500,                                     // ✗ wrong status
+*         });
+*       }
+*     }
+*
+* The structured-constructor pattern below is what prevents that drift.
+*/
+/**
+* Format a list of items for inclusion in error details. Empty lists render
+* as the supplied fallback (default `(none)`), so messages read naturally
+* regardless of whether anything is registered.
+*
+* Module-private: only used by the concrete error subclasses below. Promote
+* to `export` if/when a real cross-file caller appears.
+*/
+function formatList(items, fallback = "(none)") {
+	if (items.length === 0) return fallback;
+	return items.map((item) => `"${String(item)}"`).join(", ");
+}
+/**
+* Base class for every error Flue throws. Do not instantiate directly in
+* application code — extend it via a subclass below. If a use case isn't
+* covered, add a new subclass here rather than throwing a raw `FlueError`.
+*/
+var FlueError = class extends Error {
+	type;
+	details;
+	dev;
+	meta;
+	cause;
+	constructor(options) {
+		super(options.message);
+		this.name = "FlueError";
+		this.type = options.type;
+		this.details = options.details;
+		this.dev = options.dev;
+		this.meta = options.meta;
+		this.cause = options.cause;
+	}
+};
+/**
+* Base class for HTTP-layer errors. Adds `status` and optional `headers`.
+* Subclasses set these in the `super({...})` call so the call site doesn't
+* have to think about HTTP semantics.
+*/
+var FlueHttpError = class extends FlueError {
+	status;
+	headers;
+	constructor(options) {
+		super(options);
+		this.name = "FlueHttpError";
+		this.status = options.status;
+		this.headers = options.headers;
+	}
+};
+var MethodNotAllowedError = class extends FlueHttpError {
+	constructor({ method, allowed }) {
+		super({
+			type: "method_not_allowed",
+			message: `HTTP method ${method} is not allowed on this endpoint.`,
+			details: `This endpoint accepts ${formatList(allowed)} only.`,
+			dev: "",
+			status: 405,
+			headers: { Allow: allowed.join(", ") }
+		});
+	}
+};
+var UnsupportedMediaTypeError = class extends FlueHttpError {
+	constructor({ received }) {
+		const detailLines = [];
+		if (received) detailLines.push(`Received Content-Type: "${received}".`);
+		else detailLines.push(`No Content-Type header was sent.`);
+		detailLines.push("Send the request body as JSON with the header \"Content-Type: application/json\", or omit the body entirely (and the Content-Type header) if the request doesn't have a payload.");
+		super({
+			type: "unsupported_media_type",
+			message: `Request body must be sent as application/json.`,
+			details: detailLines.join("\n"),
+			dev: "",
+			status: 415
+		});
+	}
+};
+var InvalidJsonError = class extends FlueHttpError {
+	constructor({ parseError }) {
+		super({
+			type: "invalid_json",
+			message: `Request body is not valid JSON.`,
+			details: `The JSON parser reported: ${parseError}\nVerify the body is well-formed JSON, or omit the body entirely if the request doesn't have a payload.`,
+			dev: "",
+			status: 400
+		});
+	}
+};
+var AgentNotFoundError = class extends FlueHttpError {
+	constructor({ name, available }) {
+		super({
+			type: "agent_not_found",
+			message: `Agent "${name}" is not registered.`,
+			details: `Verify the agent name is correct.`,
+			dev: `Available agents: ${formatList(available)}.\nAgents are loaded from the project root's "agents/" directory at build time. Verify the agent file is present in the project root being served.`,
+			status: 404
+		});
+	}
+};
+var AgentNotWebhookError = class extends FlueHttpError {
+	constructor({ name }) {
+		super({
+			type: "agent_not_webhook",
+			message: `Agent "${name}" is not web-accessible.`,
+			details: `This endpoint is not exposed over HTTP.`,
+			dev: "This agent has no webhook trigger configured. To expose it, add a webhook trigger to its definition (`triggers: { webhook: true }`). Trigger-less agents remain invokable via \"flue run\" in local mode.",
+			status: 404
+		});
+	}
+};
+var RouteNotFoundError = class extends FlueHttpError {
+	constructor({ method, path }) {
+		super({
+			type: "route_not_found",
+			message: `No route matches ${method} ${path}.`,
+			details: `Webhook agents are served at POST /agents/<name>/<id>.`,
+			dev: "",
+			status: 404
+		});
+	}
+};
+var InvalidRequestError = class extends FlueHttpError {
+	constructor({ reason }) {
+		super({
+			type: "invalid_request",
+			message: `Request is malformed.`,
+			details: reason,
+			dev: "",
+			status: 400
+		});
+	}
+};
+/**
+* Error framework utilities: renderers, type guards, request parsing helpers.
+* 
+* Wire envelope (HTTP body + SSE `data:` payload for error events):
+*
+*     {
+*       "error": {
+*         "type":    "...",
+*         "message": "...",
+*         "details": "...",
+*         "dev":     "..."   // present only in local/dev mode AND when non-empty
+*       }
+*     }
+*
+* Field rules:
+*   - `type`, `message`, `details` are always present on the wire.
+*   - `dev` is gated by `FLUE_MODE === 'local'` (set by `flue run` and
+*     `flue dev --target node`). Even in dev mode, `dev` is omitted when
+*     the error class set it to `''` — so its presence is not a reliable
+*     signal of mode by itself; clients should not depend on it that way.
+*     See the error classes above for the two-audience rationale.
+*   - `meta` is included on the wire only when an error subclass sets it
+*     (rare).
+*   - `cause` is never included on the wire (it's logged server-side only).
+*/
+function isFlueError(value) {
+	return value instanceof FlueError;
+}
+/**
+* Module-private for now: when an external call site appears we can promote
+* to `export` and decide the right shape for `warn`/`info` (FlueError
+* subclasses with severity? plain strings? structured data?) — rather than
+* committing to a shape now without any usage to validate it.
+*/
+function formatForLog(prefix, err) {
+	if (isFlueError(err)) {
+		const lines = [`${prefix} [${err.type}] ${err.message}`];
+		if (err.details) for (const line of err.details.split("\n")) lines.push(`  ${line}`);
+		if (err.dev) for (const line of err.dev.split("\n")) lines.push(`  ${line}`);
+		if (err.cause !== void 0) lines.push(`  cause: ${err.cause instanceof Error ? err.cause.stack ?? err.cause.message : String(err.cause)}`);
+		return lines.join("\n");
+	}
+	if (err instanceof Error) return `${prefix} ${err.stack ?? err.message}`;
+	return `${prefix} ${String(err)}`;
+}
+const flueLog = { error(err) {
+	console.error(formatForLog("[flue]", err));
+} };
+/**
+* Detect whether the server is running in local/dev mode. Gates whether the
+* `dev` field is included on the wire — see the convention doc in the error
+* classes above.
+*
+* Currently keyed off the `FLUE_MODE=local` env var, which is set by
+* `flue run` and `flue dev --target node`. On Cloudflare workers there is
+* no global `process` and no current "local mode" plumbing for the worker —
+* so deployed CF and `flue dev --target cloudflare` both currently render
+* the prod envelope. Threading a dev-mode signal through to the worker
+* fetch handler is left as a follow-up.
+*/
+function isDevMode() {
+	return typeof process !== "undefined" && process.env?.FLUE_MODE === "local";
+}
+function envelope(err) {
+	const out = { error: {
+		type: err.type,
+		message: err.message,
+		details: err.details
+	} };
+	if (isDevMode() && err.dev) out.error.dev = err.dev;
+	if (err.meta) out.error.meta = err.meta;
+	return out;
+}
+const GENERIC_INTERNAL = { error: {
+	type: "internal_error",
+	message: "An internal error occurred.",
+	details: "The server encountered an unexpected error while handling this request."
+} };
+/**
+* Render any thrown value into a `Response` with the canonical Flue error
+* envelope. Unknown / non-Flue errors are logged in full and rendered as a
+* generic 500 with no message leaked.
+*/
+function toHttpResponse(err) {
+	if (isFlueError(err)) {
+		const isHttp = err instanceof FlueHttpError;
+		const status = isHttp ? err.status : 500;
+		const headers = { "content-type": "application/json" };
+		if (isHttp && err.headers) Object.assign(headers, err.headers);
+		if (!isHttp) flueLog.error(err);
+		return new Response(JSON.stringify(envelope(err)), {
+			status,
+			headers
+		});
+	}
+	flueLog.error(err);
+	return new Response(JSON.stringify(GENERIC_INTERNAL), {
+		status: 500,
+		headers: { "content-type": "application/json" }
+	});
+}
+/**
+* Render any thrown value into a JSON string suitable for the `data:` line of
+* an SSE `error` event. Same envelope as `toHttpResponse`. Unknown / non-Flue
+* errors are logged and replaced with a generic envelope.
+*/
+function toSseData(err) {
+	if (isFlueError(err)) {
+		if (!(err instanceof FlueHttpError)) flueLog.error(err);
+		return JSON.stringify({
+			type: "error",
+			...envelope(err)
+		});
+	}
+	flueLog.error(err);
+	return JSON.stringify({
+		type: "error",
+		...GENERIC_INTERNAL
+	});
+}
+/**
+* Parse a request body as JSON. Returns `{}` for genuinely empty bodies
+* (Content-Length: 0 or missing) so that webhook agents which don't accept
+* a payload can be invoked without one.
+*
+* Throws `UnsupportedMediaTypeError` if a body is present without
+* `application/json` content-type, and `InvalidJsonError` if the body is
+* present but unparseable.
+*/
+async function parseJsonBody(request) {
+	const contentLengthHeader = request.headers.get("content-length");
+	const contentLength = contentLengthHeader === null ? null : Number(contentLengthHeader);
+	const contentType = request.headers.get("content-type");
+	if (contentLength === 0 || contentLengthHeader === null && contentType === null) return {};
+	if (!contentType || !contentType.toLowerCase().includes("application/json")) throw new UnsupportedMediaTypeError({ received: contentType });
+	let text;
+	try {
+		text = await request.clone().text();
+	} catch (err) {
+		throw new InvalidJsonError({ parseError: err instanceof Error ? err.message : String(err) });
+	}
+	if (text.trim() === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		throw new InvalidJsonError({ parseError: err instanceof Error ? err.message : String(err) });
+	}
+}
+function validateAgentRequest(opts) {
+	if (opts.method !== "POST") throw new MethodNotAllowedError({
+		method: opts.method,
+		allowed: ["POST"]
+	});
+	if (opts.name.trim() === "" || opts.id.trim() === "") throw new InvalidRequestError({ reason: "Webhook URLs must have the shape /agents/<name>/<id> with non-empty segments." });
+	if (!opts.registeredAgents.includes(opts.name)) throw new AgentNotFoundError({
+		name: opts.name,
+		available: opts.registeredAgents
+	});
+	if (!opts.allowNonWebhook && !opts.webhookAgents.includes(opts.name)) throw new AgentNotWebhookError({ name: opts.name });
+}
+
+//#endregion
+//#region src/runtime/handle-agent.ts
+/** Shared per-agent HTTP dispatcher for the Node and Cloudflare targets. */
+/**
+* Dispatch a single `/agents/:name/:id` request. The mode is chosen by
+* inspecting headers:
+*
+*   - `X-Webhook: true` → fire-and-forget. Returns 202 immediately; the
+*     handler runs in the background. Errors are logged server-side.
+*   - `Accept: text/event-stream` (and not webhook) → SSE streaming. Returns
+*     200 + text/event-stream. Events come from the FlueContext's event
+*     callback; final result is appended as `event: result`. Per-event errors
+*     surface as `event: error` envelopes.
+*   - Otherwise → sync. Returns 200 + JSON `{ result }`.
+*
+* Errors thrown BEFORE streaming starts (body parse, agent lookup) bubble
+* out as a `Response` via {@link toHttpResponse} — headers haven't been sent
+* yet, so a regular HTTP error is still possible. Errors thrown AFTER the
+* 200 + text/event-stream headers are on the wire (i.e. inside the agent
+* handler) get framed as in-stream `error` events instead.
+*
+* Caller is responsible for routing — this function assumes the request has
+* already been validated as a POST against a registered agent.
+*/
+async function handleAgentRequest(opts) {
+	const { request, agentName, id, handler, createContext } = opts;
+	const startWebhook = opts.startWebhook ?? defaultStartWebhook;
+	const runHandler = opts.runHandler ?? defaultRunHandler;
+	try {
+		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;
+		if (isWebhook) return runWebhookMode({
+			agentName,
+			id,
+			handler,
+			payload,
+			request,
+			createContext,
+			startWebhook
+		});
+		if (isSSE) return runSseMode({
+			id,
+			handler,
+			payload,
+			request,
+			createContext,
+			runHandler
+		});
+		return runSyncMode({
+			id,
+			handler,
+			payload,
+			request,
+			createContext,
+			runHandler
+		});
+	} catch (err) {
+		return toHttpResponse(err);
+	}
+}
+function runWebhookMode(opts) {
+	const { agentName, id, handler, payload, request, createContext, startWebhook } = opts;
+	const requestId = generateRequestId();
+	const ctx = createContext(id, payload, request);
+	const run = async () => {
+		try {
+			return await handler(ctx);
+		} finally {
+			ctx.setEventCallback(void 0);
+		}
+	};
+	startWebhook(requestId, run).then((result) => {
+		console.log("[flue] Webhook handler complete:", agentName, result !== void 0 ? 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" }
+	});
+}
+/**
+* Heartbeat interval for long-idle SSE streams. The actual cadence matters
+* less than the existence of *some* periodic payload — the heartbeat exists
+* to defeat intermediary timeouts (Node's default 300s requestTimeout, CDN
+* proxies, browser EventSource reconnect heuristics). 25s is the conventional
+* choice and matches what Hono's `streamSSE` defaults to.
+*/
+const SSE_HEARTBEAT_MS = 25e3;
+function runSseMode(opts) {
+	const { id, handler, payload, request, createContext, runHandler } = opts;
+	const { readable, writable } = new TransformStream();
+	const writer = writable.getWriter();
+	const encoder = new TextEncoder();
+	let eventId = 0;
+	let isIdle = false;
+	let closed = false;
+	const writeSSE = async (data, event) => {
+		if (closed) return;
+		const lines = [];
+		lines.push(`event: ${event}`);
+		lines.push(`id: ${eventId++}`);
+		lines.push(`data: ${typeof data === "string" ? data : JSON.stringify(data)}`);
+		lines.push("", "");
+		try {
+			await writer.write(encoder.encode(lines.join("\n")));
+		} catch {}
+	};
+	const writeHeartbeat = async () => {
+		if (closed) return;
+		try {
+			await writer.write(encoder.encode(": heartbeat\n\n"));
+		} catch {}
+	};
+	const heartbeat = setInterval(() => {
+		writeHeartbeat().catch(() => {});
+	}, SSE_HEARTBEAT_MS);
+	const ctx = createContext(id, payload, request);
+	ctx.setEventCallback((event) => {
+		if (event.type === "idle") isIdle = true;
+		writeSSE(event, event.type).catch(() => {});
+	});
+	(async () => {
+		try {
+			const result = await runHandler(ctx, handler);
+			if (!isIdle) await writeSSE({ type: "idle" }, "idle");
+			await writeSSE({
+				type: "result",
+				data: result !== void 0 ? result : null
+			}, "result");
+		} catch (err) {
+			await writeSSE(toSseData(err), "error");
+			if (!isIdle) await writeSSE({ type: "idle" }, "idle");
+		} finally {
+			clearInterval(heartbeat);
+			ctx.setEventCallback(void 0);
+			closed = true;
+			try {
+				await writer.close();
+			} catch {}
+		}
+	})();
+	return new Response(readable, { headers: {
+		"content-type": "text/event-stream",
+		"cache-control": "no-cache",
+		connection: "keep-alive"
+	} });
+}
+async function runSyncMode(opts) {
+	const { id, handler, payload, request, createContext, runHandler } = opts;
+	const ctx = createContext(id, payload, request);
+	try {
+		const result = await runHandler(ctx, handler);
+		return new Response(JSON.stringify({ result: result !== void 0 ? result : null }), { headers: { "content-type": "application/json" } });
+	} finally {
+		ctx.setEventCallback(void 0);
+	}
+}
+/**
+* Default webhook runner: invoke `run()` directly so the handler executes
+* in the current process. Used by the Node target. The Cloudflare target
+* overrides this with a `runFiber` wrapper for crash-recoverable execution
+* across DO hibernation.
+*/
+const defaultStartWebhook = (_requestId, run) => run();
+/**
+* Default foreground handler runner: invoke directly. Used by the Node
+* target. The Cloudflare target overrides this with a `keepAliveWhile`
+* wrapper.
+*/
+const defaultRunHandler = (ctx, handler) => handler(ctx);
+/**
+* Generate a UUID for webhook request correlation. `crypto.randomUUID()` is
+* available on both modern Node (≥18) and workerd, so no per-target shim is
+* needed.
+*/
+function generateRequestId() {
+	return crypto.randomUUID();
+}
+
+//#endregion
+//#region src/runtime/flue-app.ts
+/**
+* Public Hono sub-app exposing Flue's built-in agent route.
+*
+* Two consumers:
+*
+*   1. **User `app.ts` files.** Users mount this sub-app inside their own
+*      Hono app via `app.route('/', flue())`. The user owns the outer
+*      Hono and controls everything around Flue's routes (logging,
+*      auth, custom routes, framework-level error handlers).
+*
+*   2. **The default fallback when no `app.ts` exists.** {@link
+*      createDefaultFlueApp} wraps `flue()` in a thin outer Hono so the
+*      no-customization case ships the same routes as it always has.
+*
+* Only the agent route at `/agents/:name/:id` is exposed. `/health` and
+* `/agents` are NOT mounted — projects that want them add them in their
+* own `app.ts`. The magic surface stays minimal; users opt in to
+* whatever shape of liveness / introspection endpoint they actually
+* want.
+*
+* Targets diverge inside the agent route:
+*
+*   - **Node**: dispatches in-process via `handleAgentRequest` against
+*     the seeded handler map.
+*   - **Cloudflare**: forwards to `routeAgentRequest()` (provided by
+*     the seeded runtime), which reaches the per-agent Durable Object
+*     class. The DO's `onRequest` then calls `handleAgentRequest`
+*     itself with the CF-specific keepalive / fiber wrappers.
+*
+* The split is invisible to the user. They `import { flue } from
+* '@flue/sdk/app'` and mount it the same way regardless of target. See
+* {@link configureFlueRuntime} for the seeding contract that lets user
+* `app.ts` files call `flue()` at top level.
+*/
+/** Module-scoped runtime config seeded by the generated server entry. */
+let runtimeConfig;
+/**
+* Seed the runtime config consumed by {@link flue}. Called exactly
+* once at module load by the generated server entry. The Hono routes
+* returned by `flue()` read this config lazily — see the comment on
+* {@link runtimeConfig} for why timing relative to user `app.ts`
+* evaluation is fine.
+*
+* Not part of the public API — exposed via `@flue/sdk/internal` only
+* because the generated entry imports it from a stable bare specifier.
+*/
+function configureFlueRuntime(cfg) {
+	runtimeConfig = cfg;
+}
+/**
+* Public Hono sub-app mounting Flue's built-in agent route. Users
+* compose this into their own Hono via Hono's `app.route(path, subApp)`:
+*
+*     import { Hono } from 'hono';
+*     import { flue } from '@flue/sdk/app';
+*
+*     const app = new Hono();
+*     app.use('*', logger());
+*     app.get('/api/ping', (c) => c.json({ pong: true }));
+*     app.route('/', flue());
+*
+*     export default app;
+*
+* Each call to `flue()` returns a fresh Hono. Mounting it twice is
+* legal but pointless — both sub-apps read from the same seeded
+* runtime and produce identical responses.
+*
+* Importable from `@flue/sdk/app`.
+*/
+function flue() {
+	const app = new Hono();
+	app.all("/agents/:name/:id", agentRouteHandler);
+	app.onError((err) => toHttpResponse(err));
+	return app;
+}
+/**
+* Build the default outer Hono app used when no user `app.ts` is
+* present. Mounts `flue()` at root, renders canonical Flue envelopes
+* for unmatched paths and any thrown errors.
+*
+* Lives in the SDK rather than the generated entry so that user
+* projects on the Cloudflare target — whose `node_modules` does not
+* declare `hono` directly — don't have to add it themselves just to
+* keep the no-`app.ts` default behavior working. When a user does
+* write an `app.ts`, they own this composition and must `pnpm add
+* hono` (or equivalent) themselves.
+*/
+function createDefaultFlueApp() {
+	const app = new Hono();
+	app.route("/", flue());
+	app.notFound((c) => {
+		throw new RouteNotFoundError({
+			method: c.req.method,
+			path: new URL(c.req.url).pathname
+		});
+	});
+	app.onError((err) => toHttpResponse(err));
+	return app;
+}
+const agentRouteHandler = async (c) => {
+	const rt = runtimeConfig;
+	if (!rt) throw new Error("[flue] flue() route invoked before runtime was configured. This usually means flue() was used outside a Flue-built server entry.");
+	const name = c.req.param("name") ?? "";
+	const id = c.req.param("id") ?? "";
+	validateAgentRequest({
+		method: c.req.method,
+		name,
+		id,
+		registeredAgents: registeredAgentsFor(rt),
+		webhookAgents: rt.webhookAgents,
+		allowNonWebhook: rt.allowNonWebhook
+	});
+	if (rt.target === "node") {
+		const handler = rt.handlers[name];
+		return handleAgentRequest({
+			request: c.req.raw,
+			agentName: name,
+			id,
+			handler,
+			createContext: rt.createContext,
+			startWebhook: rt.startWebhook,
+			runHandler: rt.runHandler
+		});
+	}
+	const response = await rt.routeAgentRequest(c.req.raw, c.env);
+	if (response) return response;
+	throw new RouteNotFoundError({
+		method: c.req.method,
+		path: new URL(c.req.url).pathname
+	});
+};
+/**
+* Compute the set of agent names considered "registered" for purposes
+* of the agent route's name-validity check.
+*
+*   - Node: every entry in the handler map (including trigger-less
+*     agents — `allowNonWebhook` controls whether they're actually
+*     reachable).
+*   - Cloudflare: only webhook agents have generated DO classes, so
+*     non-webhook names have no valid landing target.
+*/
+function registeredAgentsFor(rt) {
+	if (rt.target === "node") return Object.keys(rt.handlers ?? {});
+	return rt.webhookAgents;
+}
+
+//#endregion
+export { handleAgentRequest as i, createDefaultFlueApp as n, flue as r, configureFlueRuntime as t };