@junejs/server 0.1.2 → 0.2.0

package/dist/agent-durable.js

@@ -1,5 +1,10 @@
-import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
-import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
+import { observeTurnEvents } from "./turn-events.js";
+import { isolateLocal } from "./isolate-local.js";
+import { assertCoreRuntimeVersion } from "./core-version.js";
+import { DeliverUnsupportedError, actionToTool, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
+import { AgentSession, FatalToolError, ResumeAuthorizationError, grantAnswer, withSystem } from "@junejs/core/agent-runtime";
+import { blobFileStore } from "@junejs/core/agent-files";
+import { connectAll } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
 var DoSessionStore = class {
@@ -20,8 +25,8 @@ var DoSessionStore = class {
 	messages() {
 		return this.sql.exec("SELECT body FROM agent_messages ORDER BY seq").toArray().map((r) => JSON.parse(r.body));
 	}
-	hasUserTurn(turnId) {
-		return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+	hasOpeningMessage(turnId) {
+		return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
 	}
 	getStep(id) {
 		const rows = this.sql.exec("SELECT output FROM agent_steps WHERE id = ?", id).toArray();
@@ -30,6 +35,9 @@ var DoSessionStore = class {
 	putStep(id, output) {
 		this.sql.exec("INSERT INTO agent_steps (id, output) VALUES (?, ?)", id, JSON.stringify(output));
 	}
+	delStep(id) {
+		this.sql.exec("DELETE FROM agent_steps WHERE id = ?", id);
+	}
 	getStatus() {
 		const rows = this.sql.exec("SELECT v FROM agent_meta WHERE k = 'status'").toArray();
 		return rows.length ? rows[0].v : "new";
@@ -37,19 +45,43 @@ var DoSessionStore = class {
 	setStatus(s) {
 		this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('status', ?) ON CONFLICT(k) DO UPDATE SET v = ?", s, s);
 	}
+	getSessionKey() {
+		const rows = this.sql.exec("SELECT v FROM agent_meta WHERE k = 'session_key'").toArray();
+		return rows.length ? rows[0].v : void 0;
+	}
+	setSessionKey(key) {
+		this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('session_key', ?) ON CONFLICT(k) DO UPDATE SET v = ?", key, key);
+	}
 	tx(fn) {
 		return this.storage.transactionSync(fn);
 	}
+	reset(inTx) {
+		return this.storage.transactionSync(() => {
+			const sql = this.sql;
+			sql.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (generation INTEGER, seq INTEGER, body TEXT)`);
+			sql.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (generation INTEGER, id TEXT, output TEXT)`);
+			const rows = this.sql.exec("SELECT v FROM agent_meta WHERE k = 'generation'").toArray();
+			const generation = rows.length ? Number(rows[0].v) : 0;
+			sql.exec("INSERT INTO agent_messages_archive (generation, seq, body) SELECT ?, seq, body FROM agent_messages", generation);
+			sql.exec("DELETE FROM agent_messages");
+			sql.exec("INSERT INTO agent_steps_archive (generation, id, output) SELECT ?, id, output FROM agent_steps", generation);
+			sql.exec("DELETE FROM agent_steps");
+			this.setStatus("new");
+			sql.exec("INSERT INTO agent_meta (k, v) VALUES ('generation', ?) ON CONFLICT(k) DO UPDATE SET v = ?", String(generation + 1), String(generation + 1));
+			inTx?.();
+			return generation;
+		});
+	}
 	unwrap() {
 		return this.sql;
 	}
 };
-var InProcBroadcaster = class {
+var InProcEventSink = class {
 	subs = /* @__PURE__ */ new Set();
-	publish(turnId) {
+	emit(e) {
 		this.subs.forEach((cb) => {
 			try {
-				cb(turnId);
+				cb(e);
 			} catch {}
 		});
 	}
@@ -63,40 +95,493 @@ const crossDoUnsupported = { session() {
 } };
 var AgentDurableObject = class {
 	session;
-	resources;
+	sessionKey;
+	name;
+	store;
+	sink;
+	model;
+	tools;
+	channels;
+	channelInstructions;
+	resourcesInput;
+	resourcesOpened;
+	connectionsInput;
+	connectionsOpened;
+	doEnv;
 	services;
+	authorizeAnswer;
+	onInputAnnouncement;
+	storage;
+	files;
+	announceFailures = 0;
+	resolveResources() {
+		return this.resourcesOpened ??= Promise.resolve(typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : this.resourcesInput ?? {});
+	}
+	resolveConnections() {
+		return this.connectionsOpened ??= (async () => {
+			if (!this.connectionsInput?.length) return;
+			const { actions, report } = await connectAll(this.connectionsInput);
+			for (const r of report) if (r.error) console.error(`[june] agent "${this.name}": connection "${r.name}" (${r.url}) failed: ${r.error}`);
+			const seen = new Set(this.tools.map((t) => t.spec.name));
+			for (const a of actions) {
+				const tool = actionToTool(a);
+				if (seen.has(tool.spec.name)) throw new Error(`AgentDurableObject(${this.name}): duplicate tool name "${tool.spec.name}" from a connection — rename so dispatch is unambiguous.`);
+				seen.add(tool.spec.name);
+				this.tools.push(tool);
+			}
+		})();
+	}
+	async ready() {
+		const [resources] = await Promise.all([this.resolveResources(), this.resolveConnections()]);
+		return resources;
+	}
 	constructor(state, def) {
+		assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`);
 		const store = new DoSessionStore(state.storage);
 		const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-		this.resources = def.resources ?? {};
+		this.resourcesInput = def.resources;
+		this.connectionsInput = def.connections;
+		this.doEnv = def.env;
 		this.services = def.services;
-		this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, def.tools, crossDoUnsupported);
+		this.authorizeAnswer = def.authorizeAnswer;
+		this.onInputAnnouncement = def.onInputAnnouncement;
+		this.storage = state.storage;
+		const name = def.name ?? "agent";
+		this.files = def.files ?? blobFileStore(async () => {
+			const blob = (await this.resolveResources()).blob;
+			if (!blob) throw new FatalToolError(`agent "${name}": no file store — declare a blob resource (DoAgentDef.resources) or pass DoAgentDef.files`);
+			return blob;
+		});
+		const sink = new InProcEventSink();
+		sink.subscribe((e) => {
+			if (e.type === "turn.started") this.armWatchdog();
+		});
+		sink.subscribe((e) => {
+			if (e.type !== "turn.failed") return;
+			const defaultLog = () => console.error(`[june] agent "${name}" turn ${e.turnId} failed${e.step ? ` at ${e.step}` : ""}: ${e.error.stack ?? e.error.message}${e.error.causeChain?.length ? `\ncaused by: ${e.error.causeChain.join(" ← ")}` : ""}`);
+			if (def.onTurnError) try {
+				const out = def.onTurnError({
+					turnId: e.turnId,
+					error: e.error,
+					phase: e.phase,
+					step: e.step
+				});
+				if (out && typeof out.then === "function") out.then(void 0, (hookErr) => {
+					console.error(`[june] agent "${name}": onTurnError hook rejected:`, hookErr);
+					defaultLog();
+				});
+				return;
+			} catch (hookErr) {
+				console.error(`[june] agent "${name}": onTurnError hook threw:`, hookErr);
+			}
+			defaultLog();
+		});
+		const channels = (def.channels ?? []).map((c) => resolveChannel(c, def.env));
+		const channelTools = channels.flatMap((c) => c.tools?.() ?? []);
+		const tools = [...def.tools];
+		const seen = new Set(tools.map((t) => t.spec.name));
+		for (const t of channelTools) {
+			if (seen.has(t.spec.name)) throw new Error(`AgentDurableObject(${def.name ?? "agent"}): duplicate tool name "${t.spec.name}" from a channel — rename so dispatch is unambiguous.`);
+			seen.add(t.spec.name);
+			tools.push(t);
+		}
+		this.name = name;
+		this.store = store;
+		this.sink = sink;
+		this.model = model;
+		this.tools = tools;
+		this.channels = channels;
+		this.channelInstructions = def.channelInstructions;
+		if (def.channelInstructions) {
+			const names = new Set(channels.map((c) => c.name));
+			for (const source of Object.keys(def.channelInstructions)) if (!names.has(source)) console.warn(`[june] agent "${name}": surface policy "${source}" matches no channel wired into this DO (${[...names].join(", ") || "none"}) — it will never fire.`);
+		}
+	}
+	resolveSession(key) {
+		if (key !== void 0) assertSessionKey(key);
+		if (this.session) {
+			if (key !== void 0 && this.sessionKey !== key) throw new Error(this.sessionKey === "self" ? `agent "${this.name}": request session "${key}" arrived, but this session is bound to the placeholder "self" (first used without a real key) — carry the key on every path (route through durableFetch, or pass turn({ session }) on the direct API)` : `agent "${this.name}": request session "${key}" does not match this object's session "${this.sessionKey}" — one DO is one session; address each session by its own key (durableFetch, or turn({ session }) on the direct API)`);
+			return this.session;
+		}
+		const stored = this.store.getSessionKey();
+		if (key !== void 0 && stored !== void 0 && key !== stored) throw new Error(`agent "${this.name}": request session "${key}" does not match this object's session "${stored}" — one DO is one session; address each session by its own key (durableFetch, or turn({ session }) on the direct API)`);
+		const resolved = key ?? stored ?? "self";
+		if (key !== void 0 && key !== "self" && stored === void 0) this.store.setSessionKey(key);
+		this.sessionKey = resolved;
+		this.session = new AgentSession(this.name, resolved, this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions);
+		this.session.files = this.files;
+		this.session.onDequeue = (heldTurnId, held) => {
+			if (held.hostContext?.deliver && held.event) this.deliverHeld(this.session, heldTurnId, held.event);
+		};
+		const announce = this.onInputAnnouncement;
+		if (announce) {
+			this.session.onAnnounce = async (a) => {
+				await ensureScope();
+				const resources = await this.ready();
+				try {
+					await runInScope({
+						resources,
+						services: this.services
+					}, () => announce(a));
+				} catch (err) {
+					this.scheduleAlarm(Math.min(5e3 * 2 ** this.announceFailures, 3e5));
+					this.announceFailures++;
+					throw err;
+				}
+				this.announceFailures = 0;
+			};
+			this.session.flushAnnouncements();
+		}
+		return this.session;
+	}
+	async alarm() {
+		if (!this.onInputAnnouncement) return;
+		await this.resolveSession().flushAnnouncements();
+	}
+	armWatchdog() {
+		if (this.onInputAnnouncement) this.scheduleAlarm(6e4);
+	}
+	scheduleAlarm(inMs) {
+		const failed = (err) => console.error(`[june] agent "${this.name}": could not schedule the announcement alarm — delivery waits for the next announcement, turn or rebuild:`, err);
+		try {
+			Promise.resolve(this.storage.setAlarm?.(Date.now() + inMs)).catch(failed);
+		} catch (err) {
+			failed(err);
+		}
+	}
+	deliverHeld(session, turnId, event) {
+		const logRenderFailure = (err) => console.error(`[june] agent "${this.name}": delivered render for held turn ${turnId} failed:`, err);
+		try {
+			const channel = this.channels.find((c) => c.name === event.source);
+			if (!channel?.deliver) {
+				logRenderFailure(/* @__PURE__ */ new Error(`no deliver()-capable channel named "${event.source}" is wired into this DO — the held turn runs, but its reply is not rendered`));
+				return;
+			}
+			const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
+			const events = { [Symbol.asyncIterator]: () => it };
+			const target = {
+				channelId: event.channelId,
+				threadId: event.threadId,
+				recipientUserId: event.user?.id,
+				recipientTeamId: event.teamId
+			};
+			this.ready().then((resources) => runInScope({
+				resources,
+				services: this.services
+			}, () => channel.deliver(target, events, {
+				session: this.sessionKey,
+				files: this.files
+			}))).catch(logRenderFailure).finally(() => {
+				it.return?.();
+			});
+		} catch (err) {
+			logRenderFailure(err);
+		}
 	}
 	async turn(input) {
 		await ensureScope();
+		const resources = await this.ready();
+		const session = this.resolveSession(input.session);
 		return runInScope({
-			resources: this.resources,
+			resources,
 			services: this.services
-		}, () => this.session.turn(input));
+		}, () => session.turn(input));
+	}
+	async start(input) {
+		await ensureScope();
+		const resources = await this.ready();
+		const session = this.resolveSession(input.session);
+		return runInScope({
+			resources,
+			services: this.services
+		}, () => session.start(input));
+	}
+	note(input) {
+		const { session, ...note } = input;
+		return this.resolveSession(session).note(note);
+	}
+	reset(opts) {
+		const session = this.resolveSession(opts?.session);
+		this.armWatchdog();
+		return session.reset();
 	}
 	transcript() {
-		return this.session.transcript();
+		if (this.session) return this.session.transcript();
+		if (this.store.getSessionKey() !== void 0) return this.resolveSession().transcript();
+		return new AgentSession(this.name, "self", this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions).transcript();
 	}
 	async fetch(req) {
 		const url = new URL(req.url);
+		const key = req.headers.get("x-june-session") ?? void 0;
 		if (req.method === "POST" && url.pathname.endsWith("/turn")) {
-			const { userText, turnId } = await req.json();
-			return Response.json({ text: await this.turn({
-				userText,
-				turnId
-			}) });
+			const { userText, turnId, event, trigger, ifSuspended } = await req.json();
+			await ensureScope();
+			const replace = url.searchParams.get("replace") === "1";
+			const wantsDeliver = url.searchParams.get("deliver") === "1";
+			const detached = url.searchParams.get("detach") === "1";
+			if (ifSuspended === "queue" && !wantsDeliver && !detached) return Response.json({ error: `ifSuspended "queue" needs deliver=1 or detach=1: a held turn runs later, when no one is streaming it` }, { status: 400 });
+			if (ifSuspended === "queue" && replace) return Response.json({ error: `ifSuspended "queue" and replace=1 cannot be combined — replacing would drop held turns that were accepted` }, { status: 400 });
+			let deliverChannel;
+			if (wantsDeliver) {
+				if (!event?.channelId) return Response.json({ error: "deliver=1 needs an inbound event (event.channelId names the reply target)" }, { status: 400 });
+				deliverChannel = this.channels.find((c) => c.name === event.source);
+				if (!deliverChannel?.deliver) return Response.json({ error: `agent "${this.name}": no deliver()-capable channel named "${event.source}" is wired into this DO (DoAgentDef.channels) — the turn was NOT started` }, { status: 501 });
+			}
+			const resources = await this.ready();
+			let session;
+			let started;
+			try {
+				session = this.resolveSession(key);
+				this.armWatchdog();
+				started = runInScope({
+					resources,
+					services: this.services
+				}, () => session.start({
+					userText,
+					turnId,
+					event,
+					trigger,
+					replace,
+					ifSuspended,
+					hostContext: wantsDeliver ? { deliver: true } : void 0
+				}));
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			if (started.queued) return Response.json({
+				turnId: started.turnId,
+				queued: true
+			}, { status: 202 });
+			if (wantsDeliver) {
+				const logRenderFailure = (err) => console.error(`[june] agent "${this.name}": delivered render for turn ${started.turnId} failed:`, err);
+				try {
+					const it = observeTurnEvents(session, started.turnId)[Symbol.asyncIterator]();
+					const events = { [Symbol.asyncIterator]: () => it };
+					const target = {
+						channelId: event.channelId,
+						threadId: event.threadId,
+						recipientUserId: event.user?.id,
+						recipientTeamId: event.teamId
+					};
+					Promise.resolve().then(() => runInScope({
+						resources,
+						services: this.services
+					}, () => deliverChannel.deliver(target, events, {
+						session: this.sessionKey,
+						files: this.files
+					}))).catch(logRenderFailure).finally(() => {
+						it.return?.();
+					});
+				} catch (err) {
+					logRenderFailure(err);
+				}
+				return Response.json({ turnId: started.turnId }, { status: 202 });
+			}
+			if (detached) return Response.json({ turnId: started.turnId }, { status: 202 });
+			return new Response(sseTurnStream(session, started.turnId), { headers: SSE_HEADERS });
 		}
-		if (url.pathname.endsWith("/transcript")) return Response.json({ transcript: this.transcript() });
-		return new Response("agent DO — POST /turn or GET /transcript", { status: 404 });
+		if (req.method === "POST" && url.pathname.endsWith("/resume")) {
+			const { turnId, inputId, input, by, principal, source, target } = await req.json();
+			await ensureScope();
+			const wantsDeliver = url.searchParams.get("deliver") === "1";
+			let resumeChannel;
+			if (wantsDeliver) {
+				if (!source || !target?.channelId || !target.messageTs) return Response.json({ error: "resume deliver=1 needs `source` (the channel name) and `target` (channelId + messageTs of the prompt message)" }, { status: 400 });
+				resumeChannel = this.channels.find((c) => c.name === source);
+				if (!resumeChannel?.deliverResume) return Response.json({ error: `agent "${this.name}": no deliverResume()-capable channel named "${source}" is wired into this DO (DoAgentDef.channels) — the answer was NOT applied` }, { status: 501 });
+			}
+			const resources = await this.ready();
+			let session;
+			try {
+				session = this.resolveSession(key);
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			let granted;
+			try {
+				granted = await runInScope({
+					resources,
+					services: this.services
+				}, () => grantAnswer(session, {
+					turnId,
+					inputId,
+					by,
+					principal
+				}, this.authorizeAnswer));
+			} catch (err) {
+				console.error(`[june] agent "${this.name}": authorizeAnswer failed for input "${inputId}" of turn ${turnId}:`, err);
+				return Response.json({ error: `authorizeAnswer failed: ${err instanceof Error ? err.message : String(err)} — the answer was NOT applied` }, { status: 500 });
+			}
+			this.armWatchdog();
+			try {
+				runInScope({
+					resources,
+					services: this.services
+				}, () => session.resume(turnId, inputId, input, {
+					by,
+					granted
+				}));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
+			}
+			if (wantsDeliver) {
+				const logRenderFailure = (err) => console.error(`[june] agent "${this.name}": delivered resume render for turn ${turnId} failed:`, err);
+				try {
+					const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
+					const events = { [Symbol.asyncIterator]: () => it };
+					Promise.resolve().then(() => runInScope({
+						resources,
+						services: this.services
+					}, () => resumeChannel.deliverResume(target, events, {
+						session: this.sessionKey,
+						files: this.files
+					}))).catch(logRenderFailure).finally(() => {
+						it.return?.();
+					});
+				} catch (err) {
+					logRenderFailure(err);
+				}
+				return Response.json({ turnId }, { status: 202 });
+			}
+			return new Response(sseTurnStream(session, turnId), { headers: SSE_HEADERS });
+		}
+		if (req.method === "POST" && url.pathname.endsWith("/reset")) {
+			let session;
+			try {
+				session = this.resolveSession(key);
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			this.armWatchdog();
+			try {
+				return Response.json(await session.reset());
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+		}
+		if (req.method === "POST" && url.pathname.endsWith("/note")) {
+			let input;
+			try {
+				input = await req.json();
+			} catch {
+				return Response.json({ error: "note: the body must be JSON { by, kind, text }" }, { status: 400 });
+			}
+			let session;
+			try {
+				session = this.resolveSession(key);
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			try {
+				return Response.json(await session.note(input));
+			} catch (err) {
+				if (err instanceof TypeError) return Response.json({ error: err.message }, { status: 400 });
+				throw err;
+			}
+		}
+		if (url.pathname.endsWith("/transcript")) {
+			if (key !== void 0) try {
+				return Response.json({ transcript: this.resolveSession(key).transcript() });
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			return Response.json({ transcript: this.transcript() });
+		}
+		return new Response("agent DO — POST /turn, POST /resume, POST /reset, POST /note, or GET /transcript", { status: 404 });
 	}
 };
+const SSE_HEADERS = {
+	"content-type": "text/event-stream",
+	"cache-control": "no-store"
+};
+function sseTurnStream(session, turnId) {
+	const enc = new TextEncoder();
+	let unsub;
+	let heartbeat;
+	const stop = () => {
+		unsub?.();
+		clearInterval(heartbeat);
+	};
+	return new ReadableStream({
+		start(controller) {
+			heartbeat = setInterval(() => {
+				try {
+					controller.enqueue(enc.encode(":hb\n\n"));
+				} catch {
+					clearInterval(heartbeat);
+				}
+			}, 2e4);
+			unsub = session.observe((e) => {
+				controller.enqueue(enc.encode(`data: ${JSON.stringify(e)}\n\n`));
+				if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") {
+					stop();
+					controller.close();
+				}
+			}, { turnId });
+		},
+		cancel() {
+			stop();
+		}
+	});
+}
+async function sseTurnFinalText(res) {
+	const ct = res.headers.get("content-type") ?? "";
+	if (!res.body || !ct.includes("text/event-stream")) {
+		const detail = res.body ? (await res.text()).slice(0, 200) : "no body";
+		throw new Error(`turn stream: expected an SSE response, got ${ct || "no content-type"} (status ${res.status}): ${detail}`);
+	}
+	const reader = res.body.getReader();
+	const dec = new TextDecoder();
+	let buf = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (value) buf += dec.decode(value, { stream: true });
+		let i;
+		while ((i = buf.indexOf("\n\n")) >= 0) {
+			const line = buf.slice(0, i).split("\n").find((l) => l.startsWith("data:"));
+			buf = buf.slice(i + 2);
+			if (!line) continue;
+			const e = JSON.parse(line.slice(5).trim());
+			if (e.type === "turn.completed") return e.text;
+			if (e.type === "turn.failed") throw new Error(e.error.message, { cause: e.error });
+			if (e.type === "turn.cancelled") throw new Error(`turn ${e.turnId} was cancelled (${e.reason})`);
+		}
+		if (done) break;
+	}
+	throw new Error("turn stream ended without a terminal event");
+}
+async function* sseTurnEvents(res) {
+	const ct = res.headers.get("content-type") ?? "";
+	if (!res.body || !ct.includes("text/event-stream")) {
+		const detail = res.body ? (await res.text()).slice(0, 200) : "no body";
+		throw new Error(`turn stream: expected an SSE response, got ${ct || "no content-type"} (status ${res.status}): ${detail}`);
+	}
+	const reader = res.body.getReader();
+	const dec = new TextDecoder();
+	let buf = "";
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (value) buf += dec.decode(value, { stream: true });
+		let i;
+		while ((i = buf.indexOf("\n\n")) >= 0) {
+			const line = buf.slice(0, i).split("\n").find((l) => l.startsWith("data:"));
+			buf = buf.slice(i + 2);
+			if (line) yield JSON.parse(line.slice(5).trim());
+		}
+		if (done) break;
+	}
+}
+const SESSION_HEADER = "x-june-session";
+const SESSION_KEY_RE = /^[\x20-\x7E]+$/;
+function assertSessionKey(session) {
+	if (typeof session !== "string" || !SESSION_KEY_RE.test(session)) throw new Error(`invalid session key ${JSON.stringify(session)} — a session key must be a non-empty printable-ASCII string (it rides an HTTP header and the DO name)`);
+}
 function durableFetch(namespace, agent, session, req) {
-	return namespace.get(namespace.idFromName(`${agent}:${session}`)).fetch(req);
+	assertSessionKey(session);
+	const headers = new Headers(req.headers);
+	headers.set(SESSION_HEADER, session);
+	return namespace.get(namespace.idFromName(`${agent}:${session}`)).fetch(new Request(req, { headers }));
 }
 function durableAgentSurface(getNamespace, opts) {
 	const chatPath = opts.chatPath ?? "/message";
@@ -106,14 +591,34 @@ function durableAgentSurface(getNamespace, opts) {
 		const namespace = getNamespace();
 		if (!namespace) return null;
 		const { message, session } = await req.json();
-		return durableFetch(namespace, opts.agentName, session ?? "default", new Request("https://do/turn", {
+		if (session !== void 0) try {
+			assertSessionKey(session);
+		} catch (err) {
+			return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 400 });
+		}
+		const res = await durableFetch(namespace, opts.agentName, session ?? "default", new Request("https://do/turn", {
 			method: "POST",
 			body: JSON.stringify({ userText: message })
 		}));
+		if (req.headers.get("accept")?.includes("text/event-stream")) return res;
+		return Response.json({ text: await sseTurnFinalText(res) });
 	};
 }
+function resolveServices(factory, env, agentName) {
+	if (!factory) return void 0;
+	if (typeof env !== "object" || env === null) return factory(env);
+	const cache = isolateLocal("june.durableChannelSurface.services", () => /* @__PURE__ */ new WeakMap());
+	let perAgent = cache.get(env);
+	if (!perAgent) {
+		perAgent = /* @__PURE__ */ new Map();
+		cache.set(env, perAgent);
+	}
+	if (!perAgent.has(agentName)) perAgent.set(agentName, factory(env));
+	return perAgent.get(agentName);
+}
 function durableChannelSurface(getNamespace, opts) {
-	return channelDispatch(opts.channels.map((c) => resolveChannel(c, opts.env)), {
+	const resolved = opts.channels.map((c) => resolveChannel(c, opts.env));
+	const ctx = {
 		agent: {
 			name: opts.agentName,
 			instructions: "",
@@ -122,20 +627,130 @@ function durableChannelSurface(getNamespace, opts) {
 			channels: [],
 			connections: []
 		},
+		services: resolveServices(opts.services, opts.env, opts.agentName),
 		waitUntil: opts.waitUntil,
+		files: opts.files,
 		run: async (message, o) => {
 			const namespace = getNamespace();
 			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
-			const { text } = await (await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request("https://do/turn", {
+			return sseTurnFinalText(await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, {
+				method: "POST",
+				body: serializeTurn(message, o)
+			})));
+		},
+		runDetached: async (message, o) => {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			const res = await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request(`https://do/turn?detach=1${o?.replace ? "&replace=1" : ""}`, {
+				method: "POST",
+				body: serializeTurn(message, o)
+			}));
+			if (res.status !== 202) {
+				const detail = (await res.text()).slice(0, 200);
+				throw new Error(`runDetached: turn was not accepted (status ${res.status}): ${detail}`);
+			}
+			return await res.json();
+		},
+		runDelivered: async (message, o) => {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			const res = await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request(`https://do/turn?deliver=1${o?.replace ? "&replace=1" : ""}`, {
+				method: "POST",
+				body: serializeTurn(message, o)
+			}));
+			if (res.status === 501) throw new DeliverUnsupportedError(`runDelivered: ${(await res.json().catch(() => void 0))?.error ?? "the turn host cannot deliver this turn"}`);
+			if (res.status !== 202) {
+				const detail = (await res.text()).slice(0, 200);
+				throw new Error(`runDelivered: delivered turn was not accepted (status ${res.status}): ${detail}`);
+			}
+			return await res.json();
+		},
+		runStream: async function* (message, o) {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			yield* sseTurnEvents(await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, {
+				method: "POST",
+				body: serializeTurn(message, o)
+			})));
+		},
+		resumeStream: async function* (o) {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			yield* sseTurnEvents(await durableFetch(namespace, opts.agentName, o.session ?? "default", new Request("https://do/resume", {
 				method: "POST",
-				body: JSON.stringify({
-					userText: message,
-					turnId: o?.turnId
-				})
-			}))).json();
-			return text;
+				body: serializeResume(o)
+			})));
+		},
+		resumeDelivered: async (o) => {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			const res = await durableFetch(namespace, opts.agentName, o.session ?? "default", new Request("https://do/resume?deliver=1", {
+				method: "POST",
+				body: serializeResume(o)
+			}));
+			if (res.status === 501) throw new DeliverUnsupportedError(`resumeDelivered: ${(await res.json().catch(() => void 0))?.error ?? "the turn host cannot deliver this continuation"}`);
+			if (res.status !== 202) {
+				const detail = (await res.text()).slice(0, 200);
+				throw new Error(`resumeDelivered: resume was not accepted (status ${res.status}): ${detail}`);
+			}
+			return await res.json();
+		},
+		resetSession: async (o) => {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			const res = await durableFetch(namespace, opts.agentName, o?.session ?? "default", new Request("https://do/reset", { method: "POST" }));
+			if (!res.ok) {
+				const detail = (await res.text()).slice(0, 200);
+				throw new Error(`resetSession: reset was not accepted (status ${res.status}): ${detail}`);
+			}
+			return await res.json();
 		}
-	});
+	};
+	return channelDispatch(resolved, ctx);
+}
+function serializeResume(o) {
+	try {
+		return JSON.stringify({
+			turnId: o.turnId,
+			inputId: o.inputId,
+			input: o.input,
+			by: o.by,
+			principal: o.principal,
+			source: o.source,
+			target: o.target
+		});
+	} catch (err) {
+		const culprit = ["input", "principal"].find((field) => {
+			try {
+				JSON.stringify(o[field]);
+				return false;
+			} catch {
+				return true;
+			}
+		}) ?? "payload";
+		throw new Error(`resume: ${culprit} is not JSON-serializable (${err.message}) — a resume must round-trip to the DO`);
+	}
+}
+function serializeTurn(userText, o) {
+	const payload = {
+		userText,
+		turnId: o?.turnId,
+		event: o?.event,
+		trigger: o?.trigger,
+		ifSuspended: o?.ifSuspended
+	};
+	try {
+		return JSON.stringify(payload);
+	} catch {
+		const event = o?.event ? {
+			...o.event,
+			raw: void 0
+		} : void 0;
+		return JSON.stringify({
+			...payload,
+			event
+		});
+	}
 }
 //#endregion
-export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableChannelSurface, durableFetch };
+export { AgentDurableObject, DoSessionStore, SESSION_HEADER, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };