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

package/dist/agent-durable.d.ts

@@ -1,5 +1,5 @@
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
-import { InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnEvent } from "@junejs/core/agent-runtime";
+import { InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnError, TurnEvent, TurnFailurePhase } from "@junejs/core/agent-runtime";
 import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
 type SqlStorageValue = ArrayBuffer | string | number | null;
@@ -36,6 +36,8 @@ declare class DoSessionStore implements SessionStore {
   delStep(id: string): void;
   getStatus(): string;
   setStatus(s: string): void;
+  getSessionKey(): string | undefined;
+  setSessionKey(key: string): void;
   tx<T>(fn: () => T): T;
   unwrap<H = unknown>(): H;
 }
@@ -49,23 +51,48 @@ type DoAgentDef = {
   env?: unknown;
   resources?: Resources;
   services?: unknown;
+  onTurnError?: (failure: {
+    turnId: string;
+    error: TurnError;
+    phase?: TurnFailurePhase;
+    step?: string;
+  }) => void | Promise<void>;
 };
 declare class AgentDurableObject {
   private session;
+  private sessionKey;
+  private readonly name;
+  private readonly store;
+  private readonly sink;
+  private readonly model;
+  private readonly tools;
+  private readonly channelInstructions?;
   private readonly resources;
   private readonly services;
   constructor(state: DurableObjectState, def: DoAgentDef);
+  private resolveSession;
   turn(input: {
     turnId?: string;
     userText: string;
     event?: InboundEvent;
     trigger?: ProactiveTrigger;
+    session?: string;
   }): Promise<string>;
+  start(input: {
+    turnId?: string;
+    userText: string;
+    event?: InboundEvent;
+    trigger?: ProactiveTrigger;
+    session?: string;
+  }): Promise<{
+    turnId: 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 const SESSION_HEADER = "x-june-session";
 declare function durableFetch(namespace: DurableObjectNamespace, agent: string, session: string, req: Request): Promise<Response>;
 declare function durableAgentSurface(getNamespace: () => DurableObjectNamespace | undefined, opts: {
   agentName: string;
@@ -79,4 +106,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, sseTurnEvents, sseTurnFinalText };
+export { AgentDurableObject, DoAgentDef, DoSessionStore, DurableObjectNamespace, DurableObjectState, DurableObjectStub, DurableStorage, SESSION_HEADER, SqlStorage, SqlStorageCursor, SqlStorageValue, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };

package/dist/agent-durable.js

@@ -1,3 +1,4 @@
+import { assertCoreRuntimeVersion } from "./core-version.js";
 import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
 import { AgentSession, ResumeAuthorizationError, withSystem } from "@junejs/core/agent-runtime";
 import { ensureScope, runInScope } from "@junejs/db";
@@ -40,6 +41,13 @@ 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);
 	}
@@ -66,13 +74,43 @@ const crossDoUnsupported = { session() {
 } };
 var AgentDurableObject = class {
 	session;
+	sessionKey;
+	name;
+	store;
+	sink;
+	model;
+	tools;
+	channelInstructions;
 	resources;
 	services;
 	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.services = def.services;
+		const name = def.name ?? "agent";
+		const sink = new InProcEventSink();
+		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 channelTools = (def.channels ?? []).flatMap((c) => resolveChannel(c, def.env).tools?.() ?? []);
 		const tools = [...def.tools];
 		const seen = new Set(tools.map((t) => t.spec.name));
@@ -81,29 +119,62 @@ var AgentDurableObject = class {
 			seen.add(t.spec.name);
 			tools.push(t);
 		}
-		this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcEventSink(), model, tools, crossDoUnsupported, def.channelInstructions);
+		this.name = name;
+		this.store = store;
+		this.sink = sink;
+		this.model = model;
+		this.tools = tools;
+		this.channelInstructions = def.channelInstructions;
+	}
+	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);
+		return this.session;
 	}
 	async turn(input) {
 		await ensureScope();
+		const session = this.resolveSession(input.session);
 		return runInScope({
 			resources: this.resources,
 			services: this.services
-		}, () => this.session.turn(input));
+		}, () => session.turn(input));
+	}
+	async start(input) {
+		await ensureScope();
+		const session = this.resolveSession(input.session);
+		return runInScope({
+			resources: this.resources,
+			services: this.services
+		}, () => session.start(input));
 	}
 	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, event, trigger } = await req.json();
 			await ensureScope();
+			let session;
 			let started;
 			try {
+				session = this.resolveSession(key);
 				started = runInScope({
 					resources: this.resources,
 					services: this.services
-				}, () => this.session.start({
+				}, () => session.start({
 					userText,
 					turnId,
 					event,
@@ -112,23 +183,33 @@ var AgentDurableObject = class {
 			} 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 (url.searchParams.get("detach") === "1") return Response.json({ turnId: started.turnId }, { status: 202 });
+			return new Response(sseTurnStream(session, started.turnId), { headers: SSE_HEADERS });
 		}
 		if (req.method === "POST" && url.pathname.endsWith("/resume")) {
 			const { turnId, inputId, input, by } = await req.json();
 			await ensureScope();
+			let session;
 			try {
+				session = this.resolveSession(key);
 				runInScope({
 					resources: this.resources,
 					services: this.services
-				}, () => this.session.resume(turnId, inputId, input, { by }));
+				}, () => 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 });
+			return new Response(sseTurnStream(session, turnId), { headers: SSE_HEADERS });
+		}
+		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() });
 		}
-		if (url.pathname.endsWith("/transcript")) return Response.json({ transcript: this.transcript() });
 		return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
 	}
 };
@@ -185,7 +266,7 @@ async function sseTurnFinalText(res) {
 			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 (e.type === "turn.failed") throw new Error(e.error.message, { cause: e.error });
 		}
 		if (done) break;
 	}
@@ -212,8 +293,16 @@ async function* sseTurnEvents(res) {
 		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";
@@ -223,6 +312,11 @@ function durableAgentSurface(getNamespace, opts) {
 		const namespace = getNamespace();
 		if (!namespace) return null;
 		const { message, session } = await req.json();
+		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 })
@@ -251,6 +345,19 @@ function durableChannelSurface(getNamespace, opts) {
 				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", {
+				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();
+		},
 		runStream: async function* (message, o) {
 			const namespace = getNamespace();
 			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
@@ -302,4 +409,4 @@ function serializeTurn(userText, o) {
 	}
 }
 //#endregion
-export { AgentDurableObject, DoSessionStore, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };
+export { AgentDurableObject, DoSessionStore, SESSION_HEADER, durableAgentSurface, durableChannelSurface, durableFetch, sseTurnEvents, sseTurnFinalText };

package/dist/agent-native.js

@@ -1,3 +1,4 @@
+import { assertCoreRuntimeVersion } from "./core-version.js";
 import { openLocalSqliteSync } from "./sqlite-driver.js";
 import { channelFetch } from "@junejs/core/agent-config";
 import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
@@ -73,6 +74,7 @@ var NativeRuntime = class {
 	agents;
 	db;
 	constructor(agents, db) {
+		assertCoreRuntimeVersion("NativeRuntime");
 		this.agents = agents;
 		this.db = db;
 		initSchema(db);
@@ -131,6 +133,7 @@ var MemoryRuntime = class {
 	stores = /* @__PURE__ */ new Map();
 	agents;
 	constructor(agents) {
+		assertCoreRuntimeVersion("MemoryRuntime");
 		this.agents = agents;
 	}
 	session(agent, id) {
@@ -164,6 +167,12 @@ function mountAgent(agent, runtime, opts = {}) {
 			userText: message,
 			event: o?.event,
 			trigger: o?.trigger
+		}),
+		runDetached: async (message, o) => runtime.session(agent.name, o?.session ?? "default").start({
+			turnId: o?.turnId,
+			userText: message,
+			event: o?.event,
+			trigger: o?.trigger
 		})
 	};
 	const channels = channelFetch(agent, ctx);

package/dist/core-version.d.ts

@@ -0,0 +1,5 @@
+//#region src/core-version.d.ts
+declare function assertCoreRuntimeVersion(surface: string): void;
+declare function checkCoreRuntimeVersion(surface: string, actual: number | undefined, expected?: number): void;
+//#endregion
+export { assertCoreRuntimeVersion, checkCoreRuntimeVersion };

package/dist/core-version.js

@@ -0,0 +1,12 @@
+import * as coreRuntime from "@junejs/core/agent-runtime";
+//#region src/core-version.ts
+const EXPECTED_CORE_RUNTIME_API = 1;
+function assertCoreRuntimeVersion(surface) {
+	checkCoreRuntimeVersion(surface, coreRuntime.RUNTIME_API_VERSION);
+}
+function checkCoreRuntimeVersion(surface, actual, expected = EXPECTED_CORE_RUNTIME_API) {
+	if (actual === expected) return;
+	throw new Error(`${surface}: @junejs/server is built against @junejs/core runtime API v${expected}, but the @junejs/core it resolved provides ${actual === void 0 ? "no RUNTIME_API_VERSION (a pre-0.1.1-dev.16 core)" : `v${actual}`} — two copies of @junejs/core are likely installed (one nested under @junejs/server). Align the app's @junejs/core with @junejs/server's peer range, then reinstall/dedupe so one copy remains.`);
+}
+//#endregion
+export { assertCoreRuntimeVersion, checkCoreRuntimeVersion };

package/package.json

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

package/src/agent-durable.ts

@@ -28,6 +28,8 @@ import {
   type SessionStore,
   type ProactiveTrigger,
   type Tool,
+  type TurnError,
+  type TurnFailurePhase,
 } from "@junejs/core/agent-runtime";
 import type { Resources } from "@junejs/core/resources";
 import {
@@ -39,6 +41,7 @@ import {
   type ChannelFactory,
 } from "@junejs/core/agent-config";
 import { ensureScope, runInScope } from "@junejs/db";
+import { assertCoreRuntimeVersion } from "./core-version";
 
 // ── minimal structural Cloudflare surface (no @cloudflare/workers-types dep) ──
 // SqlStorage row values are exactly what workerd's SQLite returns. Mirroring
@@ -117,6 +120,17 @@ export class DoSessionStore implements SessionStore {
   setStatus(s: string) {
     this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('status', ?) ON CONFLICT(k) DO UPDATE SET v = ?", s, s);
   }
+  // The externally-assigned session key (#75). A DO cannot read its own idFromName
+  // name, so the key arrives on the first routed request and is persisted here —
+  // surviving hibernation/eviction, where the constructor re-runs with no request
+  // in hand. Not part of core's SessionStore contract: only the DO seam needs it.
+  getSessionKey(): string | undefined {
+    const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'session_key'").toArray();
+    return rows.length ? rows[0]!.v : undefined;
+  }
+  setSessionKey(key: string) {
+    this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('session_key', ?) ON CONFLICT(k) DO UPDATE SET v = ?", key, key);
+  }
   tx<T>(fn: () => T): T {
     return this.storage.transactionSync(fn);
   }
@@ -171,6 +185,17 @@ export type DoAgentDef = {
   env?: unknown;
   resources?: Resources;
   services?: unknown;
+  // Called on every turn.failed for this session — the app's seam for routing turn
+  // failures to its own telemetry (Sentry, a ledger, …). Providing it REPLACES the
+  // default console.error; if the hook throws (or an async hook rejects), the default
+  // log fires anyway (both errors), so a failure is never silent. `error` carries the
+  // full serialized failure (stack, cause chain — see TurnError, #96), and phase/step
+  // name the engine step that was in flight — for a DETACHED turn this hook is the
+  // only failure-surfacing path, so nothing may be flattened before it fires. It
+  // happens to run inside the failed turn's request scope today (turn.failed is
+  // emitted mid-turn and ALS propagates), but that is NOT contract — don't rely on
+  // ambient db/services; close over what you need.
+  onTurnError?: (failure: { turnId: string; error: TurnError; phase?: TurnFailurePhase; step?: string }) => void | Promise<void>;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -188,16 +213,67 @@ export type DoAgentDef = {
 //     fetch(req) { return this.agent.fetch(req); }
 //   }
 export class AgentDurableObject {
-  private session: AgentSession;
+  // The AgentSession is constructed LAZILY (#75): the DO is keyed externally by
+  // idFromName(`${agent}:${session}`) but cannot read its own name, so the true
+  // session key only exists on a routed request (the SESSION_HEADER durableFetch
+  // sets). First keyed request wins and persists the key (agent_meta) so it
+  // survives hibernation; key-less paths fall back to the persisted key, then
+  // "self" (the pre-#75 behavior, kept for backward compatibility).
+  private session: AgentSession | undefined;
+  private sessionKey: string | undefined;
+  private readonly name: string;
+  private readonly store: DoSessionStore;
+  private readonly sink: InProcEventSink;
+  private readonly model: Model;
+  private readonly tools: Tool[];
+  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.
   private readonly resources: Resources;
   private readonly services: unknown;
   constructor(state: DurableObjectState, def: DoAgentDef) {
+    assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`); // #94: fail power-on, not mid-turn
     const store = new DoSessionStore(state.storage);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
     this.resources = def.resources ?? {};
     this.services = def.services;
+    const name = def.name ?? "agent";
+    // Failure observability (#76): a turn that dies after the fast-ACK has no other
+    // observable surface on the edge — the webhook already 200'd and runBackground
+    // swallows the rejection unless the channel wired onError. Subscribing HERE (the
+    // session sink) covers every turn path — turn(), /turn, /resume — with one seam.
+    // Default: console.error, which wrangler tail surfaces. An app onTurnError takes
+    // over reporting; if IT throws, fall back to the default so nothing goes silent.
+    // (InProcEventSink already guards emit against a throwing subscriber.)
+    const sink = new InProcEventSink();
+    sink.subscribe((e) => {
+      if (e.type !== "turn.failed") return;
+      // The stack already opens with the message; log it INSTEAD of the message line
+      // when present so wrangler tail shows one coherent trace, not the message twice.
+      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 });
+          // An async hook (e.g. `await sendToSentry(...)`) types as void but returns a
+          // Promise — a rejection there must hit the same fallback as a sync throw, or
+          // the failure goes silent again (plus an unhandled rejection). No waitUntil
+          // keeper is needed here: unlike a Worker, a DO stays active while it has
+          // pending work/IO, and DurableObjectState.waitUntil is documented as a no-op —
+          // this .then subscription is what retains the promise.
+          if (out && typeof (out as Promise<void>).then === "function") {
+            (out as Promise<void>).then(undefined, (hookErr) => {
+              console.error(`[june] agent "${name}": onTurnError hook rejected:`, hookErr);
+              defaultLog();
+            });
+          }
+          return;
+        } catch (hookErr) {
+          console.error(`[june] agent "${name}": onTurnError hook threw:`, hookErr);
+        }
+      }
+      defaultLog();
+    });
     // 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.
@@ -209,7 +285,49 @@ export class AgentDurableObject {
       seen.add(t.spec.name);
       tools.push(t);
     }
-    this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcEventSink(), model, tools, crossDoUnsupported, def.channelInstructions);
+    this.name = name;
+    this.store = store;
+    this.sink = sink;
+    this.model = model;
+    this.tools = tools;
+    this.channelInstructions = def.channelInstructions;
+  }
+  // Resolve THE session for this DO: explicit key (from a routed request) → persisted
+  // key (a prior life learned it) → "self". A key that contradicts the persisted or
+  // live identity is a mis-route (or a key-less path was used first) — fail loudly:
+  // silently proceeding is exactly the per-conversation data corruption #75 hit.
+  private resolveSession(key?: string): AgentSession {
+    // Every entry point shares the session-key contract (turn({ session }) and hand-rolled
+    // SESSION_HEADER values included, not just durableFetch): an invalid key persisted here
+    // would bind an identity no routed request could ever address — an orphaned session.
+    if (key !== undefined) assertSessionKey(key);
+    // Live fast path — no storage read once the session exists: this method is the only
+    // writer of the persisted key, so within one life it cannot diverge from the live one.
+    if (this.session) {
+      if (key !== undefined && 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 !== undefined && stored !== undefined && 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";
+    // "self" is deliberately NOT persisted — even when a caller passes it EXPLICITLY: it
+    // is a placeholder ("no identity externally assigned yet"), not an identity. Within
+    // one life a keyed request after a "self" binding is refused above — two concurrently
+    // active paths disagreeing is a live bug. But across eviction a keyed request ADOPTS
+    // the legacy transcript: that asymmetry IS the migration path from pre-keyed
+    // deployments, where a persisted "self" would 409 every keyed request forever.
+    if (key !== undefined && key !== "self" && stored === undefined) 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);
+    return this.session;
   }
   // 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
@@ -218,32 +336,59 @@ 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; trigger?: ProactiveTrigger }): Promise<string> {
+  async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<string> {
     await ensureScope();
-    return runInScope({ resources: this.resources, services: this.services }, () => this.session.turn(input));
+    const session = this.resolveSession(input.session);
+    return runInScope({ resources: this.resources, services: this.services }, () => session.turn(input));
   }
+  // Fire-and-forget for custom shells (#77): resolves once the turn is durably ACCEPTED;
+  // it then runs under the DO's own lifetime (a DO stays alive while it has pending
+  // work), not the caller's. No live consumer sees the result — failures surface via
+  // the default turn-failure log / onTurnError (#76).
+  async start(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<{ turnId: string }> {
+    await ensureScope();
+    const session = this.resolveSession(input.session);
+    return runInScope({ resources: this.resources, services: this.services }, () => session.start(input));
+  }
+  // Read-only: folds the durable log. When an identity exists (live, or persisted from a
+  // prior life) the session resolves and caches like any other path. Only a read on a
+  // NEVER-keyed object stays non-committal — caching there would bake "self" in as the
+  // identity and 409 a later keyed turn — so it folds through an ephemeral AgentSession.
   transcript() {
-    return this.session.transcript();
+    if (this.session) return this.session.transcript();
+    if (this.store.getSessionKey() !== undefined) return this.resolveSession().transcript();
+    return new AgentSession(this.name, "self", this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions).transcript();
   }
   // 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);
+    // The session key durableFetch stamped on the routed request (#75); absent on a
+    // hand-rolled fetch → the pre-#75 "self" fallback keeps old callers working.
+    const key = req.headers.get(SESSION_HEADER) ?? undefined;
     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();
       // 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 session: AgentSession;
       let started: { turnId: string };
       try {
-        started = runInScope({ resources: this.resources, services: this.services }, () => this.session.start({ userText, turnId, event, trigger }));
+        session = this.resolveSession(key);
+        started = runInScope({ resources: this.resources, services: this.services }, () => session.start({ userText, turnId, event, trigger }));
       } catch (err) {
-        // e.g. the session is suspended awaiting input — a client-resolvable conflict, not a crash
+        // e.g. the session is suspended awaiting input, or the key mis-matches this
+        // object's identity — 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 });
+      // 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
+      // ceiling). Nobody consumes the result; failures surface via the #76 log/hook.
+      if (url.searchParams.get("detach") === "1") return Response.json({ turnId: started.turnId }, { status: 202 });
+      return new Response(sseTurnStream(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
@@ -252,16 +397,29 @@ export class AgentDurableObject {
     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();
+      let session: AgentSession;
       try {
-        runInScope({ resources: this.resources, services: this.services }, () => this.session.resume(turnId, inputId, input, { by }));
+        session = this.resolveSession(key);
+        runInScope({ resources: this.resources, services: this.services }, () => 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
+        // 403: the resumer may not answer; 409: not suspended / wrong turn / wrong input id / key mismatch
         return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
       }
-      return new Response(sseTurnStream(this.session, turnId), { headers: SSE_HEADERS });
+      return new Response(sseTurnStream(session, turnId), { headers: SSE_HEADERS });
+    }
+    if (url.pathname.endsWith("/transcript")) {
+      // A keyed read still conflict-checks (and may commit the key — it is authentic,
+      // idFromName routed it here); a key-less read stays non-committal via transcript().
+      if (key !== undefined) {
+        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() });
     }
-    if (url.pathname.endsWith("/transcript")) return Response.json({ transcript: this.transcript() });
     return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
   }
 }
@@ -321,7 +479,7 @@ export async function sseTurnFinalText(res: Response): Promise<string> {
       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 (e.type === "turn.failed") throw new Error(e.error.message, { cause: e.error }); // full TurnError rides along
     }
     if (done) break;
   }
@@ -352,10 +510,31 @@ export async function* sseTurnEvents(res: Response): AsyncIterable<TurnEvent> {
   }
 }
 
+// The header durableFetch stamps the session key on (#75). A DO cannot read its own
+// idFromName name, so this is how the externally-assigned session identity crosses
+// into the object — exported so a custom shell that bypasses durableFetch can set it.
+export const SESSION_HEADER = "x-june-session";
+
+// A session key rides an HTTP header (SESSION_HEADER) and the DO name (idFromName) —
+// reject values that can't: CR/LF would be header injection, and Headers.set throws a
+// bare TypeError on control/non-ASCII bytes, turning a bad client value into an opaque
+// 500 deep inside durableFetch. Non-empty printable ASCII is the contract.
+const SESSION_KEY_RE = /^[\x20-\x7E]+$/;
+function assertSessionKey(session: string) {
+  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)`);
+  }
+}
+
 // Worker-side routing: address a session's DO by (agent, session) and forward the
-// request to it. `env.AGENT` is the DO namespace binding.
+// request to it. `env.AGENT` is the DO namespace binding. The session key rides a
+// header (not the body): one seam covers /turn, /resume, and /transcript without
+// touching any body contract, and an older DO simply ignores it.
 export function durableFetch(namespace: DurableObjectNamespace, agent: string, session: string, req: Request): Promise<Response> {
-  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 }));
 }
 
 // The EDGE agent surface for June's router: route the chat endpoint to the
@@ -377,6 +556,15 @@ 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 };
+    // `session` is CLIENT input here — an un-headerable value must be a clear 400, not
+    // the opaque 500 assertSessionKey would become this deep in the worker.
+    if (session !== undefined) {
+      try {
+        assertSessionKey(session);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 400 });
+      }
+    }
     // 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).
@@ -450,6 +638,25 @@ export function durableChannelSurface(
       // /turn streams SSE; the simple path collapses it to the final text.
       return sseTurnFinalText(res);
     },
+    // FIRE-AND-FORGET (#77): POST /turn?detach=1 — the DO 202s once the turn is accepted
+    // and runs it under its OWN lifetime. This is how a shadow/observe hook (onEvent →
+    // assessment turn, reply dropped) escapes the edge waitUntil ceiling that killed
+    // 24–38s turns in production: nothing holds the edge open while the turn runs.
+    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", { 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()) 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/agent-native.ts

@@ -20,6 +20,7 @@ import {
 } from "@junejs/core/agent-runtime";
 import { channelFetch, type AgentDefinition, type ChannelContext } from "@junejs/core/agent-config";
 import { openLocalSqliteSync, type SyncSqlite } from "./sqlite-driver";
+import { assertCoreRuntimeVersion } from "./core-version";
 
 function initSchema(db: SyncSqlite) {
   db.exec(`CREATE TABLE IF NOT EXISTS agent_sessions (session_id TEXT PRIMARY KEY, status TEXT)`);
@@ -99,6 +100,7 @@ export class NativeRuntime implements Runtime {
   private readonly db: SyncSqlite;
 
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite) {
+    assertCoreRuntimeVersion("NativeRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
     this.db = db;
     initSchema(db);
@@ -154,6 +156,7 @@ export class MemoryRuntime implements Runtime {
   private stores = new Map<string, MemorySessionStore>();
   private readonly agents: Record<string, AgentDef>;
   constructor(agents: Record<string, AgentDef>) {
+    assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
   }
   session(agent: string, id: string): AgentSession {
@@ -214,6 +217,11 @@ export function mountAgent(
     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, trigger: o?.trigger }),
+    // FIRE-AND-FORGET (#77): start() without awaiting the result. Native has no waitUntil
+    // ceiling (Node keeps floating promises alive), but the seam is the same so a channel
+    // written against ctx.runDetached behaves identically on both targets.
+    runDetached: async (message, o) =>
+      runtime.session(agent.name, o?.session ?? "default").start({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger }),
   };
   const channels = channelFetch(agent, ctx);
   const surface = async (req: Request): Promise<Response | null> => {

package/src/core-version.ts

@@ -0,0 +1,34 @@
+// core-version.ts — the #94 belt-and-braces: fail at POWER-ON when the @junejs/core
+// copy this server resolved is not the one it was built for.
+//
+// The primary fix is @junejs/core being a peerDependency (the app's single resolution
+// always wins), but a nested second copy can still appear (npm legacy peer handling,
+// a stale lockfile, a transitive pin). When it does, the failure without this check
+// is far from the cause and mid-turn ("sink.emit is not a function", first seen in
+// crisp-agent production); with it, construction throws with both versions named.
+//
+// Namespace import + optional read on purpose: a PRE-#94 core has no
+// RUNTIME_API_VERSION export, and a named import of a missing export would die at
+// module link time with an unhelpful SyntaxError — exactly the confusion this
+// module exists to remove.
+import * as coreRuntime from "@junejs/core/agent-runtime";
+
+// The contract number this server tree is built against. Bump in lockstep with
+// core's RUNTIME_API_VERSION whenever the server↔core runtime contract changes.
+const EXPECTED_CORE_RUNTIME_API = 1;
+
+export function assertCoreRuntimeVersion(surface: string): void {
+  checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);
+}
+
+// The pure check, split out so the mismatch paths are unit-testable (the ambient
+// read above can only ever see the workspace's own — matching — core).
+export function checkCoreRuntimeVersion(surface: string, actual: number | undefined, expected: number = EXPECTED_CORE_RUNTIME_API): void {
+  if (actual === expected) return;
+  throw new Error(
+    `${surface}: @junejs/server is built against @junejs/core runtime API v${expected}, ` +
+      `but the @junejs/core it resolved provides ${actual === undefined ? "no RUNTIME_API_VERSION (a pre-0.1.1-dev.16 core)" : `v${actual}`} — ` +
+      `two copies of @junejs/core are likely installed (one nested under @junejs/server). ` +
+      `Align the app's @junejs/core with @junejs/server's peer range, then reinstall/dedupe so one copy remains.`,
+  );
+}