@junejs/server 0.1.2-dev.2 → 0.1.2-dev.4

package/dist/agent-durable.d.ts

@@ -1,5 +1,5 @@
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
-import { InboundEvent, Model, Msg, SessionStore, Tool } from "@junejs/core/agent-runtime";
+import { InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnEvent } from "@junejs/core/agent-runtime";
 import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
 type SqlStorageValue = ArrayBuffer | string | number | null;
@@ -30,9 +30,10 @@ declare class DoSessionStore implements SessionStore {
   private get sql();
   appendMessage(m: Msg): void;
   messages(): Msg[];
-  hasUserTurn(turnId: string): boolean;
+  hasOpeningMessage(turnId: string): boolean;
   getStep(id: string): unknown | undefined;
   putStep(id: string, output: unknown): void;
+  delStep(id: string): void;
   getStatus(): string;
   setStatus(s: string): void;
   tx<T>(fn: () => T): T;
@@ -58,10 +59,13 @@ declare class AgentDurableObject {
     turnId?: string;
     userText: string;
     event?: InboundEvent;
+    trigger?: ProactiveTrigger;
   }): Promise<string>;
   transcript(): import("@junejs/core/agent-runtime").Turn[];
   fetch(req: Request): Promise<Response>;
 }
+declare function sseTurnFinalText(res: Response): Promise<string>;
+declare function sseTurnEvents(res: Response): AsyncIterable<TurnEvent>;
 declare function durableFetch(namespace: DurableObjectNamespace, agent: string, session: string, req: Request): Promise<Response>;
 declare function durableAgentSurface(getNamespace: () => DurableObjectNamespace | undefined, opts: {
   agentName: string;
@@ -75,4 +79,4 @@ declare function durableChannelSurface(getNamespace: () => DurableObjectNamespac
   waitUntil?: (p: Promise<unknown>) => void;
 }): (req: Request) => Promise<Response | null>;
 //#endregion
-export { AgentDurableObject, DoAgentDef, DoSessionStore, DurableObjectNamespace, DurableObjectState, DurableObjectStub, DurableStorage, SqlStorage, SqlStorageCursor, SqlStorageValue, durableAgentSurface, durableChannelSurface, durableFetch };
+export { AgentDurableObject, DoAgentDef, DoSessionStore, DurableObjectNamespace, DurableObjectState, DurableObjectStub, DurableStorage, SqlStorage, SqlStorageCursor, SqlStorageValue, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };

package/dist/agent-durable.js

@@ -1,5 +1,5 @@
 import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
-import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
+import { AgentSession, ResumeAuthorizationError, withSystem } from "@junejs/core/agent-runtime";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
 var DoSessionStore = class {
@@ -20,8 +20,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 +30,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";
@@ -44,12 +47,12 @@ var DoSessionStore = class {
 		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 {}
 		});
 	}
@@ -78,7 +81,7 @@ var AgentDurableObject = class {
 			seen.add(t.spec.name);
 			tools.push(t);
 		}
-		this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, tools, crossDoUnsupported, def.channelInstructions);
+		this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcEventSink(), model, tools, crossDoUnsupported, def.channelInstructions);
 	}
 	async turn(input) {
 		await ensureScope();
@@ -93,17 +96,122 @@ var AgentDurableObject = class {
 	async fetch(req) {
 		const url = new URL(req.url);
 		if (req.method === "POST" && url.pathname.endsWith("/turn")) {
-			const { userText, turnId, event } = await req.json();
-			return Response.json({ text: await this.turn({
-				userText,
-				turnId,
-				event
-			}) });
+			const { userText, turnId, event, trigger } = await req.json();
+			await ensureScope();
+			let started;
+			try {
+				started = runInScope({
+					resources: this.resources,
+					services: this.services
+				}, () => this.session.start({
+					userText,
+					turnId,
+					event,
+					trigger
+				}));
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			return new Response(sseTurnStream(this.session, started.turnId), { headers: SSE_HEADERS });
+		}
+		if (req.method === "POST" && url.pathname.endsWith("/resume")) {
+			const { turnId, inputId, input, by } = await req.json();
+			await ensureScope();
+			try {
+				runInScope({
+					resources: this.resources,
+					services: this.services
+				}, () => this.session.resume(turnId, inputId, input, { by }));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
+			}
+			return new Response(sseTurnStream(this.session, 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 });
+		return new Response("agent DO — POST /turn, POST /resume, 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 === "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);
+		}
+		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;
+	}
+}
 function durableFetch(namespace, agent, session, req) {
 	return namespace.get(namespace.idFromName(`${agent}:${session}`)).fetch(req);
 }
@@ -115,10 +223,12 @@ 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", {
+		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 durableChannelSurface(getNamespace, opts) {
@@ -136,19 +246,47 @@ function durableChannelSurface(getNamespace, opts) {
 		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", {
+				method: "POST",
+				body: serializeTurn(message, o)
+			})));
+		},
+		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", {
 				method: "POST",
 				body: serializeTurn(message, o)
-			}))).json();
-			return text;
+			})));
+		},
+		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: serializeResume(o)
+			})));
 		}
 	});
 }
+function serializeResume(o) {
+	try {
+		return JSON.stringify({
+			turnId: o.turnId,
+			inputId: o.inputId,
+			input: o.input,
+			by: o.by
+		});
+	} catch (err) {
+		throw new Error(`resumeStream: input is not JSON-serializable (${err.message}) — a resume answer must round-trip to the DO`);
+	}
+}
 function serializeTurn(userText, o) {
 	const payload = {
 		userText,
 		turnId: o?.turnId,
-		event: o?.event
+		event: o?.event,
+		trigger: o?.trigger
 	};
 	try {
 		return JSON.stringify(payload);
@@ -164,4 +302,4 @@ function serializeTurn(userText, o) {
 	}
 }
 //#endregion
-export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableChannelSurface, durableFetch };
+export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };

package/dist/agent-native.js

@@ -20,8 +20,8 @@ var SqliteSessionStore = class {
 	messages() {
 		return this.db.query("SELECT body FROM agent_messages WHERE session_id = ? ORDER BY seq").all(this.sid).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 r = this.db.query("SELECT output FROM agent_steps WHERE session_id = ? AND id = ?").get(this.sid, id);
@@ -30,6 +30,9 @@ var SqliteSessionStore = class {
 	putStep(id, output) {
 		this.db.query("INSERT INTO agent_steps (session_id, id, output) VALUES (?, ?, ?)").run(this.sid, id, JSON.stringify(output));
 	}
+	delStep(id) {
+		this.db.query("DELETE FROM agent_steps WHERE session_id = ? AND id = ?").run(this.sid, id);
+	}
 	getStatus() {
 		return this.db.query("SELECT status FROM agent_sessions WHERE session_id = ?").get(this.sid)?.status ?? "new";
 	}
@@ -51,12 +54,12 @@ var SqliteSessionStore = class {
 		return this.db;
 	}
 };
-var InProcBroadcaster = class {
+var InProcEventSink = class {
 	subs = /* @__PURE__ */ new Set();
-	publish(turnId) {
+	emit(e) {
 		this.subs.forEach((cb) => {
 			try {
-				cb(turnId);
+				cb(e);
 			} catch {}
 		});
 	}
@@ -81,7 +84,7 @@ var NativeRuntime = class {
 			const def = this.agents[agent];
 			if (!def) throw new Error(`unknown agent: ${agent}`);
 			const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-			a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcBroadcaster(), model, def.tools, this, def.channelInstructions);
+			a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcEventSink(), model, def.tools, this, def.channelInstructions);
 			this.actors.set(key, a);
 		}
 		return a;
@@ -100,8 +103,8 @@ var MemorySessionStore = class {
 	messages() {
 		return this.msgs.slice();
 	}
-	hasUserTurn(turnId) {
-		return this.msgs.some((m) => m.role === "user" && m.turnId === turnId);
+	hasOpeningMessage(turnId) {
+		return this.msgs.some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
 	}
 	getStep(id) {
 		return this.steps.has(id) ? this.steps.get(id) : void 0;
@@ -109,6 +112,9 @@ var MemorySessionStore = class {
 	putStep(id, output) {
 		this.steps.set(id, output);
 	}
+	delStep(id) {
+		this.steps.delete(id);
+	}
 	getStatus() {
 		return this.status;
 	}
@@ -135,7 +141,7 @@ var MemoryRuntime = class {
 			if (!def) throw new Error(`unknown agent: ${agent}`);
 			const store = new MemorySessionStore();
 			this.stores.set(key, store);
-			a = new AgentSession(agent, id, store, new InProcBroadcaster(), def.model, def.tools, this);
+			a = new AgentSession(agent, id, store, new InProcEventSink(), def.model, def.tools, this);
 			this.actors.set(key, a);
 		}
 		return a;
@@ -156,7 +162,8 @@ function mountAgent(agent, runtime, opts = {}) {
 		run: (message, o) => runtime.session(agent.name, o?.session ?? "default").turn({
 			turnId: o?.turnId,
 			userText: message,
-			event: o?.event
+			event: o?.event,
+			trigger: o?.trigger
 		})
 	};
 	const channels = channelFetch(agent, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.1.2-dev.2",
+  "version": "0.1.2-dev.4",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -125,7 +125,7 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@junejs/core": ">=0.1.1-dev.4",
+    "@junejs/core": ">=0.1.1-dev.8",
     "@junejs/db": ">=0.0.34-dev.0",
     "@momiji-rs/sparkdown": "^0.0.4",
     "lightningcss": "^1.27.0",

package/src/agent-durable.ts

@@ -17,13 +17,16 @@
 
 import {
   AgentSession,
+  ResumeAuthorizationError,
   withSystem,
-  type Broadcaster,
+  type EventSink,
+  type TurnEvent,
   type Model,
   type Msg,
   type Runtime,
   type InboundEvent,
   type SessionStore,
+  type ProactiveTrigger,
   type Tool,
 } from "@junejs/core/agent-runtime";
 import type { Resources } from "@junejs/core/resources";
@@ -94,8 +97,8 @@ export class DoSessionStore implements SessionStore {
   messages(): Msg[] {
     return this.sql.exec<{ body: string }>("SELECT body FROM agent_messages ORDER BY seq").toArray().map((r) => JSON.parse(r.body));
   }
-  hasUserTurn(turnId: string): boolean {
-    return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+  hasOpeningMessage(turnId: string): boolean {
+    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
   }
   getStep(id: string): unknown | undefined {
     const rows = this.sql.exec<{ output: string }>("SELECT output FROM agent_steps WHERE id = ?", id).toArray();
@@ -104,6 +107,9 @@ export class DoSessionStore implements SessionStore {
   putStep(id: string, output: unknown) {
     this.sql.exec("INSERT INTO agent_steps (id, output) VALUES (?, ?)", id, JSON.stringify(output));
   }
+  delStep(id: string) {
+    this.sql.exec("DELETE FROM agent_steps WHERE id = ?", id);
+  }
   getStatus(): string {
     const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'status'").toArray();
     return rows.length ? rows[0]!.v : "new";
@@ -119,10 +125,10 @@ export class DoSessionStore implements SessionStore {
   }
 }
 
-class InProcBroadcaster implements Broadcaster {
-  private subs = new Set<(t: string) => void>();
-  publish(turnId: string) { this.subs.forEach((cb) => { try { cb(turnId); } catch { /* a bad subscriber must not break publish */ } }); }
-  subscribe(cb: (t: string) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
+class InProcEventSink implements EventSink {
+  private subs = new Set<(e: TurnEvent) => void>();
+  emit(e: TurnEvent) { this.subs.forEach((cb) => { try { cb(e); } catch { /* a bad subscriber must not break emit */ } }); }
+  subscribe(cb: (e: TurnEvent) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
 }
 
 // A DO can't run in-process subagents; a subagent there is a sibling DO (cross-DO
@@ -203,7 +209,7 @@ export class AgentDurableObject {
       seen.add(t.spec.name);
       tools.push(t);
     }
-    this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, tools, crossDoUnsupported, def.channelInstructions);
+    this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcEventSink(), model, tools, crossDoUnsupported, def.channelInstructions);
   }
   // Run the whole turn inside a request scope seeded from this DO's env, so ambient
   // `db`/`kv`/`blob` and `currentServices()` resolve inside a tool exactly as in a
@@ -212,23 +218,137 @@ export class AgentDurableObject {
   // Juno's batch-loader registry) can't leak across turns on a long-lived DO.
   // ensureScope() lazily wires node:async_hooks (workerd via nodejs_compat), as the
   // pipeline does; without it runInScope is a pass-through and ambient reads throw.
-  async turn(input: { turnId?: string; userText: string; event?: InboundEvent }): Promise<string> {
+  async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger }): Promise<string> {
     await ensureScope();
     return runInScope({ resources: this.resources, services: this.services }, () => this.session.turn(input));
   }
   transcript() {
     return this.session.transcript();
   }
-  // Default HTTP surface: POST …/turn runs a durable turn; GET …/transcript reads
-  // the log. The app can call turn()/transcript() directly instead.
+  // Default HTTP surface: POST …/turn STREAMS the turn's TurnEvents as SSE (start the
+  // turn in-scope, then stream from the session sink); GET …/transcript reads the log.
+  // The app can call turn()/transcript() directly instead (turn() awaits the final text).
   async fetch(req: Request): Promise<Response> {
     const url = new URL(req.url);
     if (req.method === "POST" && url.pathname.endsWith("/turn")) {
-      const { userText, turnId, event } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent };
-      return Response.json({ text: await this.turn({ userText, turnId, event }) });
+      const { userText, turnId, event, trigger } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger };
+      await ensureScope();
+      // start() schedules the turn on the chain WITHIN the scope, so it runs with ambient
+      // db/services (ALS propagates to the .then continuation registered here); subscribing
+      // happens synchronously right after, before any event can emit.
+      let started: { turnId: string };
+      try {
+        started = runInScope({ resources: this.resources, services: this.services }, () => this.session.start({ userText, turnId, event, trigger }));
+      } catch (err) {
+        // e.g. the session is suspended awaiting input — a client-resolvable conflict, not a crash
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      return new Response(sseTurnStream(this.session, started.turnId), { headers: SSE_HEADERS });
+    }
+    // Provide the input a suspended turn is waiting on and stream its continuation as SSE.
+    // NOTE: this default surface passes `by` straight from the body — the engine treats it as a
+    // VERIFIED identity, so the app must authenticate it upstream (e.g. take the user id from a
+    // signature-checked Slack interaction payload), never expose this endpoint raw to clients.
+    if (req.method === "POST" && url.pathname.endsWith("/resume")) {
+      const { turnId, inputId, input, by } = (await req.json()) as { turnId: string; inputId: string; input: unknown; by?: string };
+      await ensureScope();
+      try {
+        runInScope({ resources: this.resources, services: this.services }, () => this.session.resume(turnId, inputId, input, { by }));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // 403: the resumer may not answer; 409: not suspended / wrong turn / wrong input id
+        return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
+      }
+      return new Response(sseTurnStream(this.session, 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 });
+    return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
+  }
+}
+
+// ── SSE transport for the turn event stream (crosses the worker→DO isolate) ───
+// The DO streams a turn's TurnEvents as text/event-stream; the worker either pipes
+// that straight to a browser (live chat) or collapses it to the final text (channels).
+// no-store (not no-cache): an intermediary must NOT store chat/user content at all, and it
+// matches the repo's other SSE surface (dev-reload).
+const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-store" };
+
+// A ReadableStream of SSE frames from a session's live event stream, scoped to one turn
+// and closed on its terminal event. Subscribes synchronously (no replay needed — we start
+// the turn then subscribe before any event can emit). A `:hb` comment heartbeat keeps the
+// connection alive across long model/tool gaps (a silent SSE stream gets culled by idle
+// timeouts on hosts/proxies) — cleared on terminal close and on cancel.
+function sseTurnStream(session: AgentSession, turnId: string): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  let unsub: (() => void) | undefined;
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  const stop = () => { unsub?.(); clearInterval(heartbeat); };
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      heartbeat = setInterval(() => {
+        try { controller.enqueue(enc.encode(":hb\n\n")); } catch { clearInterval(heartbeat); }
+      }, 20_000);
+      unsub = session.observe((e) => {
+        controller.enqueue(enc.encode(`data: ${JSON.stringify(e)}\n\n`));
+        // terminal for the STREAM: completed, failed, OR suspended (input.requested → the turn
+        // parked; the stream ends and a later /resume opens a fresh continuation stream).
+        if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") { stop(); controller.close(); }
+      }, { turnId });
+    },
+    cancel() { stop(); },
+  });
+}
+
+// Consume an SSE turn stream to its terminal state: the final text, or throw on failure.
+// The non-streaming path (channels, a JSON chat response) uses this. Guards a non-SSE /
+// body-less upstream response (a misroute or an error) into a clear error, not a TypeError.
+export async function sseTurnFinalText(res: Response): Promise<string> {
+  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: number;
+    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()) as TurnEvent;
+      if (e.type === "turn.completed") return e.text;
+      if (e.type === "turn.failed") throw new Error(e.error.message);
+    }
+    if (done) break;
+  }
+  throw new Error("turn stream ended without a terminal event");
+}
+
+// Parse an SSE turn response into the stream of TurnEvents (skipping `:hb` heartbeats).
+// The streaming consumer (a channel's render path) iterates this to drive live UI.
+export async function* sseTurnEvents(res: Response): AsyncIterable<TurnEvent> {
+  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: number;
+    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()) as TurnEvent;
+    }
+    if (done) break;
   }
 }
 
@@ -257,13 +377,17 @@ export function durableAgentSurface(
     const namespace = getNamespace();
     if (!namespace) return null; // no DO binding → not mounted here
     const { message, session } = (await req.json()) as { message: string; session?: string };
-    // Forward to the session's DO on its /turn contract (AgentDurableObject.fetch).
-    return durableFetch(
+    // Forward to the session's DO on its /turn contract — which now STREAMS SSE. A client
+    // that asks for the stream (Accept: text/event-stream) gets live TurnEvents piped
+    // through; otherwise collapse to the final { text } (the prior JSON contract).
+    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) });
   };
 }
 
@@ -323,8 +447,32 @@ export function durableChannelSurface(
         o?.session ?? "default",
         new Request("https://do/turn", { method: "POST", body: serializeTurn(message, o) }),
       );
-      const { text } = (await res.json()) as { text: string };
-      return text;
+      // /turn streams SSE; the simple path collapses it to the final text.
+      return sseTurnFinalText(res);
+    },
+    // The LIVE path: hand the channel the TurnEvent stream so it can render as the turn runs.
+    runStream: async function* (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", { method: "POST", body: serializeTurn(message, o) }),
+      );
+      yield* sseTurnEvents(res);
+    },
+    // Resume a parked turn on its session's DO and stream the continuation.
+    resumeStream: async function* (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", { method: "POST", body: serializeResume(o) }),
+      );
+      yield* sseTurnEvents(res);
     },
   };
   return channelDispatch(resolved, ctx);
@@ -336,8 +484,22 @@ export function durableChannelSurface(
 // run the turn, so on a serialization failure we drop it rather than let an
 // unserializable payload take down turn forwarding entirely. (raw is optional on
 // InboundEvent precisely because it may not survive this boundary.)
-function serializeTurn(userText: string, o?: { turnId?: string; event?: InboundEvent }): string {
-  const payload = { userText, turnId: o?.turnId, event: o?.event };
+// Serialize a /resume RPC body. `input` is `unknown` — the human's answer — so a
+// (third-party) host could hand us something JSON.stringify chokes on (BigInt, circular).
+// Unlike serializeTurn's `raw`, `input` is essential: silently dropping it would resume the
+// turn with the wrong answer. So fail loudly with a clear message rather than corrupt the resume.
+function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string }): string {
+  try {
+    return JSON.stringify({ turnId: o.turnId, inputId: o.inputId, input: o.input, by: o.by });
+  } catch (err) {
+    throw new Error(`resumeStream: input is not JSON-serializable (${(err as Error).message}) — a resume answer must round-trip to the DO`);
+  }
+}
+
+// `trigger` is ProactiveTrigger — plain strings by construction — so only event.raw can make
+// the stringify throw; the fallback that strips it stays sufficient.
+function serializeTurn(userText: string, o?: { turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger }): string {
+  const payload = { userText, turnId: o?.turnId, event: o?.event, trigger: o?.trigger };
   try {
     return JSON.stringify(payload);
   } catch {

package/src/agent-native.ts

@@ -10,7 +10,8 @@
 import {
   AgentSession,
   withSystem,
-  type Broadcaster,
+  type EventSink,
+  type TurnEvent,
   type Model,
   type Msg,
   type Runtime,
@@ -45,8 +46,8 @@ class SqliteSessionStore implements SessionStore {
     return (this.db.query("SELECT body FROM agent_messages WHERE session_id = ? ORDER BY seq").all(this.sid) as { body: string }[])
       .map((r) => JSON.parse(r.body));
   }
-  hasUserTurn(turnId: string): boolean {
-    return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+  hasOpeningMessage(turnId: string): boolean {
+    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
   }
   getStep(id: string): unknown | undefined {
     const r = this.db.query("SELECT output FROM agent_steps WHERE session_id = ? AND id = ?").get(this.sid, id) as { output: string } | undefined;
@@ -55,6 +56,9 @@ class SqliteSessionStore implements SessionStore {
   putStep(id: string, output: unknown) {
     this.db.query("INSERT INTO agent_steps (session_id, id, output) VALUES (?, ?, ?)").run(this.sid, id, JSON.stringify(output));
   }
+  delStep(id: string) {
+    this.db.query("DELETE FROM agent_steps WHERE session_id = ? AND id = ?").run(this.sid, id);
+  }
   getStatus(): string {
     return (this.db.query("SELECT status FROM agent_sessions WHERE session_id = ?").get(this.sid) as { status: string } | undefined)?.status ?? "new";
   }
@@ -77,10 +81,10 @@ class SqliteSessionStore implements SessionStore {
   unwrap<H = unknown>(): H { return this.db as unknown as H; }
 }
 
-class InProcBroadcaster implements Broadcaster {
-  private subs = new Set<(t: string) => void>();
-  publish(turnId: string) { this.subs.forEach((cb) => { try { cb(turnId); } catch { /* a bad subscriber must not break publish */ } }); }
-  subscribe(cb: (t: string) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
+class InProcEventSink implements EventSink {
+  private subs = new Set<(e: TurnEvent) => void>();
+  emit(e: TurnEvent) { this.subs.forEach((cb) => { try { cb(e); } catch { /* a bad subscriber must not break emit */ } }); }
+  subscribe(cb: (e: TurnEvent) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
 }
 
 // `instructions` (the agent's system prompt) is injected into the model per turn
@@ -107,7 +111,7 @@ export class NativeRuntime implements Runtime {
       const def = this.agents[agent];
       if (!def) throw new Error(`unknown agent: ${agent}`);
       const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcBroadcaster(), model, def.tools, this, def.channelInstructions);
+      a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcEventSink(), model, def.tools, this, def.channelInstructions);
       this.actors.set(key, a);
     }
     return a;
@@ -135,9 +139,10 @@ class MemorySessionStore implements SessionStore {
   private status = "new";
   appendMessage(m: Msg) { this.msgs.push(m); }
   messages(): Msg[] { return this.msgs.slice(); }
-  hasUserTurn(turnId: string): boolean { return this.msgs.some((m) => m.role === "user" && m.turnId === turnId); }
+  hasOpeningMessage(turnId: string): boolean { return this.msgs.some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId); }
   getStep(id: string): unknown | undefined { return this.steps.has(id) ? this.steps.get(id) : undefined; }
   putStep(id: string, output: unknown) { this.steps.set(id, output); }
+  delStep(id: string) { this.steps.delete(id); }
   getStatus(): string { return this.status; }
   setStatus(s: string) { this.status = s; }
   tx<T>(fn: () => T): T { return fn(); } // no rollback: an in-memory store is not a durability tier
@@ -159,7 +164,7 @@ export class MemoryRuntime implements Runtime {
       if (!def) throw new Error(`unknown agent: ${agent}`);
       const store = new MemorySessionStore();
       this.stores.set(key, store);
-      a = new AgentSession(agent, id, store, new InProcBroadcaster(), def.model, def.tools, this);
+      a = new AgentSession(agent, id, store, new InProcEventSink(), def.model, def.tools, this);
       this.actors.set(key, a);
     }
     return a;
@@ -208,7 +213,7 @@ export function mountAgent(
     agent,
     services: opts.services, // same DI bag reachable from channel hooks (parity with durableChannelSurface)
     run: (message, o) =>
-      runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event }),
+      runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger }),
   };
   const channels = channelFetch(agent, ctx);
   const surface = async (req: Request): Promise<Response | null> => {