@junejs/server 1.0.0-dev.10 → 1.0.0-dev.12

package/dist/agent-durable.d.ts

@@ -66,6 +66,7 @@ declare class AgentDurableObject {
   private readonly sink;
   private readonly model;
   private readonly tools;
+  private readonly channels;
   private readonly channelInstructions?;
   private readonly resources;
   private readonly services;

package/dist/agent-durable.js

@@ -1,5 +1,6 @@
+import { isolateLocal } from "./isolate-local.js";
 import { assertCoreRuntimeVersion } from "./core-version.js";
-import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
+import { DeliverUnsupportedError, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
 import { AgentSession, ResumeAuthorizationError, withSystem } from "@junejs/core/agent-runtime";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
@@ -80,6 +81,7 @@ var AgentDurableObject = class {
 	sink;
 	model;
 	tools;
+	channels;
 	channelInstructions;
 	resources;
 	services;
@@ -111,7 +113,8 @@ var AgentDurableObject = class {
 			}
 			defaultLog();
 		});
-		const channelTools = (def.channels ?? []).flatMap((c) => resolveChannel(c, def.env).tools?.() ?? []);
+		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) {
@@ -124,6 +127,7 @@ var AgentDurableObject = class {
 		this.sink = sink;
 		this.model = model;
 		this.tools = tools;
+		this.channels = channels;
 		this.channelInstructions = def.channelInstructions;
 	}
 	resolveSession(key) {
@@ -167,6 +171,13 @@ var AgentDurableObject = class {
 		if (req.method === "POST" && url.pathname.endsWith("/turn")) {
 			const { userText, turnId, event, trigger } = await req.json();
 			await ensureScope();
+			const wantsDeliver = url.searchParams.get("deliver") === "1";
+			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 });
+			}
 			let session;
 			let started;
 			try {
@@ -183,6 +194,25 @@ var AgentDurableObject = class {
 			} catch (err) {
 				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
 			}
+			if (wantsDeliver) {
+				const logRenderFailure = (err) => console.error(`[june] agent "${this.name}": delivered render for turn ${started.turnId} failed:`, err);
+				try {
+					const events = observeTurnEvents(session, started.turnId);
+					const target = {
+						channelId: event.channelId,
+						threadId: event.threadId,
+						recipientUserId: event.user?.id,
+						recipientTeamId: event.teamId
+					};
+					Promise.resolve().then(() => runInScope({
+						resources: this.resources,
+						services: this.services
+					}, () => deliverChannel.deliver(target, events, { session: this.sessionKey }))).catch(logRenderFailure);
+				} catch (err) {
+					logRenderFailure(err);
+				}
+				return Response.json({ turnId: started.turnId }, { status: 202 });
+			}
 			if (url.searchParams.get("detach") === "1") return Response.json({ turnId: started.turnId }, { status: 202 });
 			return new Response(sseTurnStream(session, started.turnId), { headers: SSE_HEADERS });
 		}
@@ -247,6 +277,49 @@ function sseTurnStream(session, turnId) {
 		}
 	});
 }
+function observeTurnEvents(session, turnId) {
+	const queue = [];
+	let terminal = false;
+	let notify;
+	const unsub = session.observe((e) => {
+		queue.push(e);
+		if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") terminal = true;
+		notify?.();
+	}, { turnId });
+	return { [Symbol.asyncIterator]() {
+		return {
+			async next() {
+				for (;;) {
+					const e = queue.shift();
+					if (e) return {
+						value: e,
+						done: false
+					};
+					if (terminal) {
+						unsub();
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+					await new Promise((resolve) => {
+						notify = resolve;
+					});
+					notify = void 0;
+				}
+			},
+			async return() {
+				unsub();
+				terminal = true;
+				queue.length = 0;
+				return {
+					value: void 0,
+					done: true
+				};
+			}
+		};
+	} };
+}
 async function sseTurnFinalText(res) {
 	const ct = res.headers.get("content-type") ?? "";
 	if (!res.body || !ct.includes("text/event-stream")) {
@@ -325,6 +398,18 @@ function durableAgentSurface(getNamespace, opts) {
 		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)), {
 		agent: {
@@ -335,7 +420,7 @@ function durableChannelSurface(getNamespace, opts) {
 			channels: [],
 			connections: []
 		},
-		services: opts.services?.(opts.env),
+		services: resolveServices(opts.services, opts.env, opts.agentName),
 		waitUntil: opts.waitUntil,
 		run: async (message, o) => {
 			const namespace = getNamespace();
@@ -358,6 +443,20 @@ function durableChannelSurface(getNamespace, opts) {
 			}
 			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", {
+				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)");

package/dist/isolate-local.d.ts

@@ -0,0 +1,6 @@
+//#region src/isolate-local.d.ts
+type IsolateLocal = <T>(key: string | symbol, make: () => T) => T;
+declare function makeIsolateLocalFallback(): IsolateLocal;
+declare const isolateLocal: IsolateLocal;
+//#endregion
+export { IsolateLocal, isolateLocal, makeIsolateLocalFallback };

package/dist/isolate-local.js

@@ -0,0 +1,12 @@
+import * as juneDb from "@junejs/db";
+//#region src/isolate-local.ts
+function makeIsolateLocalFallback() {
+	const values = /* @__PURE__ */ new Map();
+	return (key, make) => {
+		if (!values.has(key)) values.set(key, make());
+		return values.get(key);
+	};
+}
+const isolateLocal = juneDb.isolateLocal ?? makeIsolateLocalFallback();
+//#endregion
+export { isolateLocal, makeIsolateLocalFallback };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.10",
+  "version": "1.0.0-dev.12",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -125,14 +125,14 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@junejs/db": ">=0.0.34-dev.1",
+    "@junejs/db": ">=0.1.0-dev.2",
     "@momiji-rs/sparkdown": "^0.0.4",
     "lightningcss": "^1.27.0",
     "oxc-parser": "^0.137.0",
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.26",
+    "@junejs/core": ">=0.2.0-dev.27",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-server-dom-webpack": "19.2.7",

package/src/agent-durable.ts

@@ -34,6 +34,7 @@ import {
 import type { Resources } from "@junejs/core/resources";
 import {
   channelDispatch,
+  DeliverUnsupportedError,
   resolveChannel,
   type AgentDefinition,
   type Channel,
@@ -41,6 +42,7 @@ import {
   type ChannelFactory,
 } from "@junejs/core/agent-config";
 import { ensureScope, runInScope } from "@junejs/db";
+import { isolateLocal } from "./isolate-local";
 import { assertCoreRuntimeVersion } from "./core-version";
 
 // ── minimal structural Cloudflare surface (no @cloudflare/workers-types dep) ──
@@ -226,6 +228,7 @@ export class AgentDurableObject {
   private readonly sink: InProcEventSink;
   private readonly model: Model;
   private readonly tools: Tool[];
+  private readonly channels: Channel[];
   private readonly channelInstructions?: Record<string, string>;
   // Built from the DO's env in the constructor (this isolate), shared across turns —
   // env is stable per isolate, like bindWorkerResources memoizes per worker isolate.
@@ -276,8 +279,11 @@ export class AgentDurableObject {
     });
     // Merge the mounted channels' capability tools (built here from this DO's env, since a
     // tool's `run` closure can't cross the RPC). The cross-channel source gate on each tool
-    // keeps a Slack tool inert during a Crisp turn, so merging all of them is safe.
-    const channelTools = (def.channels ?? []).flatMap((c) => resolveChannel(c, def.env).tools?.() ?? []);
+    // keeps a Slack tool inert during a Crisp turn, so merging all of them is safe. The
+    // resolved channels are also RETAINED (this.channels): a delivered turn (/turn?deliver=1)
+    // renders its reply through the source channel's deliver() from inside this DO.
+    const channels = (def.channels ?? []).map((c) => resolveChannel(c, def.env));
+    const channelTools = channels.flatMap((c) => c.tools?.() ?? []);
     const tools: Tool[] = [...def.tools];
     const seen = new Set(tools.map((t) => t.spec.name));
     for (const t of channelTools) {
@@ -290,6 +296,7 @@ export class AgentDurableObject {
     this.sink = sink;
     this.model = model;
     this.tools = tools;
+    this.channels = channels;
     this.channelInstructions = def.channelInstructions;
   }
   // Resolve THE session for this DO: explicit key (from a routed request) → persisted
@@ -370,6 +377,26 @@ export class AgentDurableObject {
     if (req.method === "POST" && url.pathname.endsWith("/turn")) {
       const { userText, turnId, event, trigger } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger };
       await ensureScope();
+      // DELIVERED: like detach=1, the caller gets a 202 and goes away — but the reply is NOT
+      // dropped: this DO renders the turn's event stream through the source channel's own
+      // deliver() (the inbound renderer), under the DO's lifetime. Capability is checked
+      // BEFORE the turn starts — that ordering is DeliverUnsupportedError's contract at the
+      // surface: on a pre-start rejection the caller may fall back to consumer-side rendering
+      // without double-running the turn.
+      const wantsDeliver = url.searchParams.get("deliver") === "1";
+      let deliverChannel: Channel | undefined;
+      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 },
+          );
+        }
+      }
       // 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.
@@ -383,6 +410,35 @@ export class AgentDurableObject {
         // object's identity — a client-resolvable conflict, not a crash
         return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
       }
+      if (wantsDeliver) {
+        // Subscribe synchronously (same guarantee sseTurnStream relies on: start() scheduled
+        // the turn, no event can have emitted yet), then render under THIS DO's lifetime —
+        // the retained promise is pending work that keeps the DO alive, so a long turn's
+        // rendering survives however briefly the caller held its connection. The event is
+        // present (checked above); its author/thread are the reply target, exactly the
+        // surface the channel's inbound renderStream derives.
+        //
+        // Once start() has queued the turn, NOTHING here may escape: a throw would 500 the
+        // caller for a turn that runs anyway — the exact ambiguity delivered turns exist to
+        // remove. deliver() is app/third-party code that can throw synchronously before
+        // returning its promise, so it is deferred into the chain (the eager subscription
+        // above stays synchronous — that timing guarantee must not move); the try/catch
+        // backstops the subscription itself. Rendering failures have no live consumer —
+        // this log is their only surfacing path (the TURN's own failures already surface
+        // via the #76 sink subscription).
+        const logRenderFailure = (err: unknown) =>
+          console.error(`[june] agent "${this.name}": delivered render for turn ${started.turnId} failed:`, err);
+        try {
+          const events = observeTurnEvents(session, started.turnId);
+          const target = { channelId: event!.channelId, threadId: event!.threadId, recipientUserId: event!.user?.id, recipientTeamId: event!.teamId };
+          Promise.resolve()
+            .then(() => runInScope({ resources: this.resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey })))
+            .catch(logRenderFailure);
+        } catch (err) {
+          logRenderFailure(err);
+        }
+        return Response.json({ turnId: started.turnId }, { status: 202 });
+      }
       // DETACHED (#77): the turn is accepted — 202 now, no stream. It keeps running under
       // this DO's lifetime (alive while work is pending), so its duration is no longer
       // bounded by however long the CALLER can hold a connection (the edge waitUntil
@@ -457,6 +513,45 @@ function sseTurnStream(session: AgentSession, turnId: string): ReadableStream<Ui
   });
 }
 
+// The IN-PROCESS sibling of sseTurnStream: one turn's TurnEvents as an AsyncIterable, for a
+// consumer living in the SAME isolate as the session (a delivered render). Subscribes eagerly
+// at call time — not at first iteration — so the sseTurnStream timing guarantee carries over
+// (call this synchronously after start(), before any event can emit); events landing before
+// the consumer catches up are buffered. Ends after the turn's terminal event (completed,
+// failed, or input.requested — a park ends this stream; a later /resume is a new one), and an
+// early consumer exit (for-await break/return) unsubscribes rather than buffering forever.
+function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent> {
+  const queue: TurnEvent[] = [];
+  let terminal = false;
+  let notify: (() => void) | undefined;
+  const unsub = session.observe((e) => {
+    queue.push(e);
+    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") terminal = true;
+    notify?.();
+  }, { turnId });
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next(): Promise<IteratorResult<TurnEvent>> {
+          for (;;) {
+            const e = queue.shift();
+            if (e) return { value: e, done: false };
+            if (terminal) { unsub(); return { value: undefined, done: true }; }
+            await new Promise<void>((resolve) => { notify = resolve; });
+            notify = undefined;
+          }
+        },
+        async return(): Promise<IteratorResult<TurnEvent>> {
+          unsub();
+          terminal = true;
+          queue.length = 0;
+          return { value: undefined, done: true };
+        },
+      };
+    },
+  };
+}
+
 // 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.
@@ -605,6 +700,43 @@ export function durableAgentSurface(
 // fails in the background — surfaced via the channel's onError IF one is configured,
 // otherwise swallowed (runBackground never rejects). The app is expected to bind
 // env.AGENT when it mounts channels. Returns null for unclaimed requests.
+// The services bag, memoized per (env object, agentName).
+//
+// Why that key. `env` identity is what makes the memo survive: a worker builds
+// the surface inside `fetch`, so the only thing stable across requests is the
+// env object the host hands in — and NOT the provider function, which the
+// documented shape (`services: (e) => makeServices(e)`) recreates on every
+// fetch. But env alone is too coarse: two surfaces mounted in one worker over
+// the same env would then share whichever bag was built first, making the
+// result depend on mount order. `agentName` is the surface's own stable
+// identity, so it partitions them. (One agent must therefore have ONE services
+// provider — mounting the same agentName twice with different providers is
+// incoherent and keeps the first bag.)
+//
+// Held in an isolateLocal so duplicate module instances (workspace symlinks)
+// share one cache; the outer WeakMap is keyed by env so a host handing out
+// fresh env objects gets fresh bags instead of a leak. A non-object env (tests
+// passing a primitive) skips memoization rather than throwing.
+function resolveServices(
+  factory: ((env: unknown) => unknown) | undefined,
+  env: unknown,
+  agentName: string,
+): unknown {
+  if (!factory) return undefined;
+  if (typeof env !== "object" || env === null) return factory(env);
+  const cache = isolateLocal(
+    "june.durableChannelSurface.services",
+    () => new WeakMap<object, Map<string, unknown>>(),
+  );
+  let perAgent = cache.get(env);
+  if (!perAgent) {
+    perAgent = new Map<string, unknown>();
+    cache.set(env, perAgent);
+  }
+  if (!perAgent.has(agentName)) perAgent.set(agentName, factory(env));
+  return perAgent.get(agentName);
+}
+
 export function durableChannelSurface(
   getNamespace: () => DurableObjectNamespace | undefined,
   opts: {
@@ -614,7 +746,17 @@ export function durableChannelSurface(
     // The app's services factory — the SAME one AgentDurableObject uses — resolved HERE
     // (worker isolate) and exposed to channel hooks as ctx.services. Channel hooks run at
     // the edge, outside the DO, so they can't read the DO's ambient currentServices(); this
-    // gives them the same DI bag. Resolved once per surface construction.
+    // gives them the same DI bag.
+    //
+    // Called once per (env object, agentName) — NOT once per surface. A worker
+    // typically constructs the surface inside `fetch` (env only exists inside an
+    // invocation), so resolving per construction rebuilt every client on every
+    // request and any cache the bag held could never hit. Memoizing on env
+    // identity fixes that; see resolveServices above for why the key is env ×
+    // agentName and not the provider function. Practical consequences: the
+    // provider must be a function of `env` alone, it runs again whenever the
+    // host hands in a different env object (a new isolate, or a test), and one
+    // agentName must have one provider.
     services?: (env: unknown) => unknown;
     waitUntil?: (p: Promise<unknown>) => void;
   },
@@ -624,7 +766,7 @@ export function durableChannelSurface(
     // A minimal but complete AgentDefinition — channels only read ctx.agent.name; the
     // full def isn't present in the worker (tools/model live in the DO).
     agent: { name: opts.agentName, instructions: "", tools: [], skills: [], channels: [], connections: [] } satisfies AgentDefinition,
-    services: opts.services?.(opts.env),
+    services: resolveServices(opts.services, opts.env, opts.agentName),
     waitUntil: opts.waitUntil,
     run: async (message, o) => {
       const namespace = getNamespace();
@@ -657,6 +799,30 @@ export function durableChannelSurface(
       }
       return (await res.json()) as { turnId: string };
     },
+    // DELIVERED: runDetached's reply-bearing sibling — the DO runs the turn AND renders its
+    // reply through the source channel's deliver() under its OWN lifetime, so a reply-bearing
+    // turn escapes the edge waitUntil ceiling exactly as a shadow turn does. A 501 means the
+    // DO refused BEFORE starting the turn (the channel isn't wired there / has no deliver) —
+    // surfaced as DeliverUnsupportedError, the one rejection a channel may answer with a
+    // consumer-side rendering fallback without double-running the turn.
+    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", { method: "POST", body: serializeTurn(message, o) }),
+      );
+      if (res.status === 501) {
+        throw new DeliverUnsupportedError(`runDelivered: ${((await res.json().catch(() => undefined)) as { error?: string } | undefined)?.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()) as { turnId: string };
+    },
     // 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();

package/src/isolate-local.ts

@@ -0,0 +1,33 @@
+// isolate-local.ts — read @junejs/db's `isolateLocal` WITHOUT a named import.
+//
+// Same hazard core-version.ts exists for: a NAMED import of an export the
+// resolved copy doesn't have dies at module LINK time with an unhelpful
+// SyntaxError, before any of our own diagnostics can run. `isolateLocal` is new
+// in @junejs/db 0.1.0-dev.2, and a version range cannot save us here — the
+// floor has to stay satisfiable by the workspace's own db (which is the very
+// version that lacks it), and `bun pm pack` rewrites a `workspace:*` dep to
+// whatever version it resolves, which can be OLDER still.
+//
+// So: namespace import + optional read, with a local fallback. Unlike the core
+// runtime contract, this one does NOT warrant throwing — isolate-scoped
+// memoization is a lifetime optimization, not a correctness contract. The
+// fallback memoizes in this module instance, so callers keep their cache; the
+// only thing lost against an older db is sharing one value across DUPLICATE
+// copies of the module (workspace symlinks), which costs a missed cache hit,
+// never a wrong answer.
+import * as juneDb from "@junejs/db";
+
+export type IsolateLocal = <T>(key: string | symbol, make: () => T) => T;
+
+// Exported for tests: the ambient read below can only ever see the workspace's
+// own (matching) db, so the degraded path needs a direct handle to be provable.
+export function makeIsolateLocalFallback(): IsolateLocal {
+  const values = new Map<string | symbol, unknown>();
+  return <T>(key: string | symbol, make: () => T): T => {
+    if (!values.has(key)) values.set(key, make());
+    return values.get(key) as T;
+  };
+}
+
+export const isolateLocal: IsolateLocal =
+  (juneDb as { isolateLocal?: IsolateLocal }).isolateLocal ?? makeIsolateLocalFallback();