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

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, 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;
@@ -62,6 +62,8 @@ declare class AgentDurableObject {
   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 +77,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

@@ -44,12 +44,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 +78,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();
@@ -94,16 +94,101 @@ var AgentDurableObject = class {
 		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({
+			await ensureScope();
+			const started = runInScope({
+				resources: this.resources,
+				services: this.services
+			}, () => this.session.start({
 				userText,
 				turnId,
 				event
-			}) });
+			}));
+			return new Response(sseTurnStream(this.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 });
 	}
 };
+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") {
+					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 +200,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,11 +223,18 @@ 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;
+			})));
 		}
 	});
 }
@@ -164,4 +258,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

@@ -51,12 +51,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 +81,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;
@@ -135,7 +135,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.1.2-dev.2",
+  "version": "0.1.2-dev.3",
   "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.5",
     "@junejs/db": ">=0.0.34-dev.0",
     "@momiji-rs/sparkdown": "^0.0.4",
     "lightningcss": "^1.27.0",

package/src/agent-durable.ts

@@ -18,7 +18,8 @@
 import {
   AgentSession,
   withSystem,
-  type Broadcaster,
+  type EventSink,
+  type TurnEvent,
   type Model,
   type Msg,
   type Runtime,
@@ -119,10 +120,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 +204,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
@@ -219,19 +220,109 @@ export class AgentDurableObject {
   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 }) });
+      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.
+      const started = runInScope({ resources: this.resources, services: this.services }, () => this.session.start({ userText, turnId, event }));
+      return new Response(sseTurnStream(this.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 });
   }
 }
 
+// ── 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`));
+        if (e.type === "turn.completed" || e.type === "turn.failed") { 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;
+  }
+}
+
 // Worker-side routing: address a session's DO by (agent, session) and forward the
 // request to it. `env.AGENT` is the DO namespace binding.
 export function durableFetch(namespace: DurableObjectNamespace, agent: string, session: string, req: Request): Promise<Response> {
@@ -257,13 +348,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 +418,20 @@ 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);
     },
   };
   return channelDispatch(resolved, ctx);

package/src/agent-native.ts

@@ -10,7 +10,8 @@
 import {
   AgentSession,
   withSystem,
-  type Broadcaster,
+  type EventSink,
+  type TurnEvent,
   type Model,
   type Msg,
   type Runtime,
@@ -77,10 +78,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 +108,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;
@@ -159,7 +160,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;