@flue/sdk 0.4.1 → 0.5.0

package/dist/{flue-app-DeTOZjPs.mjs → flue-app-SjL4I83Y.mjs}

@@ -1,3 +1,4 @@
+import { u as generateRunId } from "./providers-BjEEoKLy.mjs";
 import { Hono } from "hono";
 
 //#region src/errors.ts
@@ -221,6 +222,28 @@ var RouteNotFoundError = class extends FlueHttpError {
 		});
 	}
 };
+var RunNotFoundError = class extends FlueHttpError {
+	constructor({ runId }) {
+		super({
+			type: "run_not_found",
+			message: `Run "${runId}" was not found.`,
+			details: "Verify the run id is correct and still within retention.",
+			dev: "",
+			status: 404
+		});
+	}
+};
+var RunStoreUnavailableError = class extends FlueHttpError {
+	constructor() {
+		super({
+			type: "run_store_unavailable",
+			message: "Run history is not available in this runtime.",
+			details: "This endpoint requires the generated runtime to be configured with a run store.",
+			dev: "",
+			status: 501
+		});
+	}
+};
 var InvalidRequestError = class extends FlueHttpError {
 	constructor({ reason }) {
 		super({
@@ -334,25 +357,6 @@ function toHttpResponse(err) {
 	});
 }
 /**
-* 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.
@@ -385,6 +389,16 @@ function validateAgentRequest(opts) {
 		method: opts.method,
 		allowed: ["POST"]
 	});
+	validateAgentIdentity(opts);
+}
+function validateAgentRunRequest(opts) {
+	if (opts.method !== "GET") throw new MethodNotAllowedError({
+		method: opts.method,
+		allowed: ["GET"]
+	});
+	validateAgentIdentity(opts);
+}
+function validateAgentIdentity(opts) {
 	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,
@@ -395,7 +409,6 @@ function validateAgentRequest(opts) {
 
 //#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:
@@ -418,9 +431,10 @@ function validateAgentRequest(opts) {
 * already been validated as a POST against a registered agent.
 */
 async function handleAgentRequest(opts) {
-	const { request, agentName, id, handler, createContext } = opts;
+	const { request, agentName, id, handler, createContext, runStore, runSubscribers } = opts;
 	const startWebhook = opts.startWebhook ?? defaultStartWebhook;
 	const runHandler = opts.runHandler ?? defaultRunHandler;
+	const runId = generateRunId();
 	try {
 		const payload = await parseJsonBody(request);
 		const accept = request.headers.get("accept") || "";
@@ -429,77 +443,92 @@ async function handleAgentRequest(opts) {
 		if (isWebhook) return runWebhookMode({
 			agentName,
 			id,
+			runId,
 			handler,
 			payload,
 			request,
 			createContext,
-			startWebhook
+			startWebhook,
+			runStore,
+			runSubscribers
 		});
 		if (isSSE) return runSseMode({
+			agentName,
 			id,
+			runId,
 			handler,
 			payload,
 			request,
 			createContext,
-			runHandler
+			runHandler,
+			runStore,
+			runSubscribers
 		});
 		return runSyncMode({
+			agentName,
 			id,
+			runId,
 			handler,
 			payload,
 			request,
 			createContext,
-			runHandler
+			runHandler,
+			runStore,
+			runSubscribers
 		});
 	} catch (err) {
-		return toHttpResponse(err);
+		const response = toHttpResponse(err);
+		response.headers.set("X-Flue-Run-Id", runId);
+		return response;
 	}
 }
-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) => {
+async function runWebhookMode(opts) {
+	const { agentName, id, runId, handler, payload, request, createContext, startWebhook, runStore, runSubscribers } = opts;
+	const lifecycle = await createRunLifecycle({
+		agentName,
+		id,
+		runId,
+		payload,
+		request,
+		createContext,
+		runStore,
+		runSubscribers
+	});
+	const { ctx } = lifecycle;
+	const run = async () => withRunLifecycle(lifecycle, () => handler(ctx));
+	startWebhook(runId, 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
+		runId
 	}), {
 		status: 202,
-		headers: { "content-type": "application/json" }
+		headers: {
+			"content-type": "application/json",
+			"X-Flue-Run-Id": runId
+		}
 	});
 }
 /**
-* 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.
+* Shared heartbeat interval for SSE streams.
 */
-const SSE_HEARTBEAT_MS = 25e3;
+const SSE_HEARTBEAT_MS = 15e3;
 function runSseMode(opts) {
-	const { id, handler, payload, request, createContext, runHandler } = opts;
+	const { agentName, id, runId, handler, payload, request, createContext, runHandler, runStore, runSubscribers } = 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) => {
+	const writeSSE = async (data, eventType) => {
 		if (closed) return;
+		const eventIndex = getEventIndex(data) ?? 0;
 		const lines = [];
-		lines.push(`event: ${event}`);
-		lines.push(`id: ${eventId++}`);
+		lines.push(`event: ${eventType}`);
+		lines.push(`id: ${eventIndex}`);
 		lines.push(`data: ${typeof data === "string" ? data : JSON.stringify(data)}`);
 		lines.push("", "");
 		try {
@@ -515,23 +544,31 @@ function runSseMode(opts) {
 	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 () => {
+		const lifecycle = await createRunLifecycle({
+			agentName,
+			id,
+			runId,
+			payload,
+			request,
+			createContext,
+			runStore,
+			runSubscribers
+		});
+		const { ctx } = lifecycle;
+		ctx.setEventCallback((event) => {
+			if (event.type === "idle") isIdle = true;
+			writeSSE(event, event.type).catch(() => {});
+		});
 		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 {
+			await withRunLifecycle(lifecycle, async () => {
+				try {
+					return await runHandler(ctx, handler);
+				} finally {
+					if (!isIdle) ctx.emitEvent({ type: "idle" });
+				}
+			});
+		} catch {} finally {
 			clearInterval(heartbeat);
 			ctx.setEventCallback(void 0);
 			closed = true;
@@ -543,77 +580,413 @@ function runSseMode(opts) {
 	return new Response(readable, { headers: {
 		"content-type": "text/event-stream",
 		"cache-control": "no-cache",
-		connection: "keep-alive"
+		connection: "keep-alive",
+		"X-Flue-Run-Id": runId
 	} });
 }
 async function runSyncMode(opts) {
-	const { id, handler, payload, request, createContext, runHandler } = opts;
-	const ctx = createContext(id, payload, request);
+	const { agentName, id, runId, handler, payload, request, createContext, runHandler, runStore, runSubscribers } = opts;
+	const lifecycle = await createRunLifecycle({
+		agentName,
+		id,
+		runId,
+		payload,
+		request,
+		createContext,
+		runStore,
+		runSubscribers
+	});
+	const { ctx } = lifecycle;
 	try {
-		const result = await runHandler(ctx, handler);
-		return new Response(JSON.stringify({ result: result !== void 0 ? result : null }), { headers: { "content-type": "application/json" } });
+		const result = await withRunLifecycle(lifecycle, () => runHandler(ctx, handler));
+		return new Response(JSON.stringify({
+			result: result === void 0 ? null : result,
+			_meta: { runId }
+		}), { headers: {
+			"content-type": "application/json",
+			"X-Flue-Run-Id": runId
+		} });
 	} finally {
 		ctx.setEventCallback(void 0);
 	}
 }
+async function createRunLifecycle(options) {
+	const startedAtMs = Date.now();
+	const startedAt = new Date(startedAtMs).toISOString();
+	const ctx = options.createContext(options.id, options.runId, options.payload, options.request);
+	await safeRunStore("createRun", () => options.runStore?.createRun({
+		runId: options.runId,
+		instanceId: options.id,
+		agentName: options.agentName,
+		startedAt,
+		payload: options.payload
+	}));
+	return {
+		...options,
+		ctx,
+		startedAt,
+		startedAtMs
+	};
+}
+/**
+* Wrap all invocation modes with the same run-start/run-end envelope.
+*/
+async function withRunLifecycle(lifecycle, body) {
+	const unsubscribeFanout = subscribeRunFanout(lifecycle);
+	emitRunStart(lifecycle);
+	try {
+		const result = await body();
+		await emitRunEnd(lifecycle, {
+			result,
+			isError: false
+		});
+		return result;
+	} catch (error) {
+		await emitRunEnd(lifecycle, {
+			isError: true,
+			error
+		});
+		throw error;
+	} finally {
+		unsubscribeFanout();
+	}
+}
+function emitRunStart(lifecycle) {
+	lifecycle.ctx.emitEvent({
+		type: "run_start",
+		runId: lifecycle.runId,
+		instanceId: lifecycle.id,
+		agentName: lifecycle.agentName,
+		startedAt: lifecycle.startedAt,
+		payload: lifecycle.payload
+	});
+}
+/**
+* Emit `run_end` and finalize the run.
+*
+* Terminal ordering matters for `/runs/:runId/stream`: append `run_end`
+* before marking the run terminal, then publish and close subscribers.
+*/
+async function emitRunEnd(lifecycle, input) {
+	const endedAtMs = Date.now();
+	const endedAt = new Date(endedAtMs).toISOString();
+	const durationMs = endedAtMs - lifecycle.startedAtMs;
+	const result = input.isError ? void 0 : input.result;
+	const error = input.isError ? serializeError(input.error) : void 0;
+	const normalizedResult = result === void 0 ? null : result;
+	const { runStore, runSubscribers, runId } = lifecycle;
+	const decorated = lifecycle.ctx.emitEvent({
+		type: "run_end",
+		runId,
+		result: normalizedResult,
+		isError: input.isError,
+		error,
+		durationMs
+	});
+	await safeRunStore("appendEvent(run_end)", () => runStore?.appendEvent(runId, decorated));
+	runSubscribers?.publish(runId, decorated);
+	await safeRunStore("endRun", () => runStore?.endRun({
+		runId,
+		endedAt,
+		isError: input.isError,
+		durationMs,
+		result,
+		error
+	}));
+	runSubscribers?.complete(runId);
+}
+/**
+* Persist non-terminal events before publishing them to live subscribers.
+* `run_end` is handled separately by {@link emitRunEnd}.
+*/
+function subscribeRunFanout(lifecycle) {
+	const { ctx, runStore, runSubscribers, runId } = lifecycle;
+	if (!runStore && !runSubscribers) return () => {};
+	let chain = Promise.resolve();
+	return ctx.subscribeEvent((event) => {
+		if (event.type === "run_end") return;
+		chain = chain.then(() => fanOutEvent(runStore, runSubscribers, runId, event));
+	});
+}
+async function fanOutEvent(runStore, runSubscribers, runId, event) {
+	if (runStore) try {
+		await runStore.appendEvent(runId, event);
+	} catch (error) {
+		console.error("[flue:run-store] appendEvent failed:", error);
+	}
+	runSubscribers?.publish(runId, event);
+}
+async function safeRunStore(label, fn) {
+	try {
+		await fn();
+	} catch (error) {
+		console.error(`[flue:run-store] ${label} failed:`, error);
+	}
+}
+function serializeError(error) {
+	if (error instanceof Error) return {
+		name: error.name,
+		message: error.message
+	};
+	return error;
+}
+function getEventIndex(data) {
+	if (typeof data !== "object" || data === null) return void 0;
+	const value = data.eventIndex;
+	return typeof value === "number" ? value : 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();
+const defaultStartWebhook = (_runId, 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);
+
+//#endregion
+//#region src/runtime/handle-run-routes.ts
+/** Run-history HTTP endpoints shared by the Node and Cloudflare targets. */
+const EVENTS_DEFAULT_LIMIT = 100;
+const EVENTS_MAX_LIMIT = 1e3;
+/** Buffer cap for events published while a live stream is replaying history. */
+const REPLAY_BUFFER_CAP = 1e3;
+async function handleRunRouteRequest(opts) {
+	const store = opts.runStore;
+	if (!store) throw new RunStoreUnavailableError();
+	switch (opts.action) {
+		case "get": return getRun(store, requireRunId(opts.runId), opts.agentName, opts.id);
+		case "events": return getRunEvents(opts.request, store, requireRunId(opts.runId), opts.agentName, opts.id);
+		case "stream": return streamRunEvents(opts.request, store, opts.runSubscribers, requireRunId(opts.runId), opts.agentName, opts.id);
+	}
+}
+async function getRun(store, runId, agentName, instanceId) {
+	return json(await getRunForInstance(store, runId, agentName, instanceId));
+}
+async function getRunEvents(request, store, runId, agentName, instanceId) {
+	await getRunForInstance(store, runId, agentName, instanceId);
+	const url = new URL(request.url);
+	const after = parseEventIndex(url.searchParams.get("after"));
+	const types = parseTypes(url.searchParams.get("types"));
+	const limit = parseLimit(url.searchParams.get("limit"), EVENTS_DEFAULT_LIMIT, EVENTS_MAX_LIMIT);
+	let events = await store.getEvents(runId, after === void 0 ? void 0 : after + 1);
+	if (types) events = events.filter((event) => types.has(event.type));
+	return json({ events: events.slice(0, limit) });
+}
+/**
+* Replay durable history, then tail live events for active runs.
+* Subscribe-before-replay avoids dropping events produced during the
+* store read; eventIndex dedup handles overlap.
+*/
+async function streamRunEvents(request, store, subscribers, runId, agentName, instanceId) {
+	const run = await getRunForInstance(store, runId, agentName, instanceId);
+	const lastEventId = parseLastEventId(request.headers.get("last-event-id"));
+	const fromIndex = lastEventId === void 0 ? void 0 : lastEventId + 1;
+	if (isTerminal(run)) return sseResponse(encodeSseEvents(await store.getEvents(runId, fromIndex)));
+	if (!subscribers) throw new Error("[flue] Active run streaming requires a run subscriber registry, but none was configured for this target. Wire one through HandleRunRouteOptions.runSubscribers.");
+	return streamReplayThenTail({
+		store,
+		subscribers,
+		runId,
+		fromIndex
+	});
+}
+function streamReplayThenTail(opts) {
+	const { store, subscribers, runId, fromIndex } = opts;
+	const encoder = new TextEncoder();
+	let buffer = [];
+	let bufferOverflowed = false;
+	let replayDone = false;
+	let lastSentIndex = fromIndex === void 0 ? void 0 : fromIndex - 1;
+	let closed = false;
+	let onLiveEvent;
+	let onClose;
+	const subscriberListener = (event) => {
+		if (closed) return;
+		if (!replayDone) {
+			if (buffer.length >= REPLAY_BUFFER_CAP) {
+				bufferOverflowed = true;
+				return;
+			}
+			buffer.push(event);
+			return;
+		}
+		onLiveEvent?.(event);
+	};
+	const unsubscribe = subscribers.subscribe(runId, subscriberListener);
+	return sseResponse(new ReadableStream({
+		start(controller) {
+			const heartbeat = setInterval(() => {
+				if (closed) return;
+				try {
+					controller.enqueue(encoder.encode(": heartbeat\n\n"));
+				} catch {}
+			}, SSE_HEARTBEAT_MS);
+			const close = () => {
+				if (closed) return;
+				closed = true;
+				clearInterval(heartbeat);
+				unsubscribe();
+				try {
+					controller.close();
+				} catch {}
+			};
+			onClose = close;
+			const write = (event) => {
+				if (closed) return;
+				try {
+					controller.enqueue(encoder.encode(encodeSseEvent(event)));
+				} catch {
+					close();
+					return;
+				}
+				if (typeof event.eventIndex === "number") lastSentIndex = event.eventIndex;
+				if (event.type === "run_end") close();
+			};
+			onLiveEvent = write;
+			(async () => {
+				try {
+					await runReplayPhase({
+						store,
+						runId,
+						fromIndex,
+						write,
+						getBuffer: () => buffer,
+						drainBuffer: () => {
+							const drained = buffer;
+							buffer = [];
+							return drained;
+						},
+						getBufferOverflowed: () => bufferOverflowed,
+						resetBufferOverflowed: () => {
+							bufferOverflowed = false;
+						},
+						getLastSentIndex: () => lastSentIndex,
+						markReplayDone: () => {
+							replayDone = true;
+						}
+					});
+				} catch (error) {
+					if (closed) return;
+					try {
+						controller.enqueue(encoder.encode(encodeSseError(error, lastSentIndex)));
+					} catch {}
+					close();
+				}
+			})();
+		},
+		cancel() {
+			closed = true;
+			onClose?.();
+		}
+	}));
+}
+async function runReplayPhase(opts) {
+	const { store, runId, fromIndex, write, drainBuffer, getBufferOverflowed, resetBufferOverflowed, getLastSentIndex, markReplayDone } = opts;
+	const replay = await store.getEvents(runId, fromIndex);
+	for (const event of replay) write(event);
+	while (getBufferOverflowed()) {
+		resetBufferOverflowed();
+		const lastSent = getLastSentIndex();
+		const refetchFrom = lastSent === void 0 ? void 0 : lastSent + 1;
+		const refetched = await store.getEvents(runId, refetchFrom);
+		for (const event of refetched) write(event);
+	}
+	const buffered = drainBuffer();
+	for (const event of buffered) {
+		const lastSent = getLastSentIndex();
+		if (typeof event.eventIndex === "number" && lastSent !== void 0 && event.eventIndex <= lastSent) continue;
+		write(event);
+	}
+	markReplayDone();
+}
+async function getRunForInstance(store, runId, agentName, instanceId) {
+	const run = await store.getRun(runId);
+	if (!run) throw new RunNotFoundError({ runId });
+	if (run.agentName !== agentName || run.instanceId !== instanceId) throw new RunNotFoundError({ runId });
+	return run;
+}
+function isTerminal(run) {
+	return run.status === "completed" || run.status === "errored";
+}
+function encodeSseEvents(events) {
+	return events.map(encodeSseEvent).join("");
+}
+function encodeSseEvent(event) {
+	const id = typeof event.eventIndex === "number" ? event.eventIndex : 0;
+	return [
+		`event: ${event.type}`,
+		`id: ${id}`,
+		`data: ${JSON.stringify(event)}`,
+		"",
+		""
+	].join("\n");
+}
+function encodeSseError(error, lastSentIndex) {
+	const data = { message: error instanceof Error ? error.message : String(error) };
+	return [
+		`event: error`,
+		`id: ${lastSentIndex ?? 0}`,
+		`data: ${JSON.stringify(data)}`,
+		"",
+		""
+	].join("\n");
+}
+function sseResponse(body) {
+	return new Response(body, { headers: {
+		"content-type": "text/event-stream",
+		"cache-control": "no-cache",
+		connection: "keep-alive"
+	} });
+}
+function requireRunId(runId) {
+	if (!runId) throw new InvalidRequestError({ reason: "Run id is required for this endpoint." });
+	return runId;
+}
+function parseTypes(value) {
+	if (!value) return void 0;
+	const types = value.split(",").map((type) => type.trim()).filter(Boolean);
+	return types.length > 0 ? new Set(types) : void 0;
+}
+function parseLimit(value, defaultLimit, maxLimit) {
+	if (!value) return defaultLimit;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return defaultLimit;
+	return Math.min(parsed, maxLimit);
+}
+function parseEventIndex(value) {
+	if (!value) return void 0;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return void 0;
+	return parsed;
+}
 /**
-* 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.
+* `Last-Event-ID` is the standard SSE reconnect header. Browsers send the
+* last `id:` field they saw; the server uses it to resume from that point.
+* Malformed values are ignored — equivalent to no header.
 */
-function generateRequestId() {
-	return crypto.randomUUID();
+function parseLastEventId(value) {
+	if (!value) return void 0;
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return void 0;
+	return parsed;
+}
+function json(data) {
+	return new Response(JSON.stringify(data), { headers: { "content-type": "application/json" } });
 }
 
 //#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.
-*/
+const RUN_ROUTES = [
+	["/agents/:name/:id/runs/:runId", "get"],
+	["/agents/:name/:id/runs/:runId/events", "events"],
+	["/agents/:name/:id/runs/:runId/stream", "stream"]
+];
 /** Module-scoped runtime config seeded by the generated server entry. */
 let runtimeConfig;
 /**
@@ -652,6 +1025,7 @@ function configureFlueRuntime(cfg) {
 function flue() {
 	const app = new Hono();
 	app.all("/agents/:name/:id", agentRouteHandler);
+	for (const [routePath, action] of RUN_ROUTES) app.all(routePath, runRouteHandler(action));
 	app.onError((err) => toHttpResponse(err));
 	return app;
 }
@@ -701,7 +1075,9 @@ const agentRouteHandler = async (c) => {
 			handler,
 			createContext: rt.createContext,
 			startWebhook: rt.startWebhook,
-			runHandler: rt.runHandler
+			runHandler: rt.runHandler,
+			runStore: rt.runStore,
+			runSubscribers: rt.runSubscribers
 		});
 	}
 	const response = await rt.routeAgentRequest(c.req.raw, c.env);
@@ -711,6 +1087,38 @@ const agentRouteHandler = async (c) => {
 		path: new URL(c.req.url).pathname
 	});
 };
+function runRouteHandler(action) {
+	return 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") ?? "";
+		const runId = c.req.param("runId") || void 0;
+		validateAgentRunRequest({
+			method: c.req.method,
+			name,
+			id,
+			registeredAgents: registeredAgentsFor(rt),
+			webhookAgents: rt.webhookAgents,
+			allowNonWebhook: rt.allowNonWebhook
+		});
+		if (rt.target === "node") return handleRunRouteRequest({
+			request: c.req.raw,
+			runStore: rt.runStore,
+			runSubscribers: rt.runSubscribers,
+			agentName: name,
+			id,
+			runId,
+			action
+		});
+		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.
@@ -727,4 +1135,4 @@ function registeredAgentsFor(rt) {
 }
 
 //#endregion
-export { handleAgentRequest as i, createDefaultFlueApp as n, flue as r, configureFlueRuntime as t };
+export { handleAgentRequest as a, handleRunRouteRequest as i, createDefaultFlueApp as n, flue as r, configureFlueRuntime as t };