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

package/dist/agent-durable.d.ts

@@ -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: {
+      message: 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

@@ -40,6 +40,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,6 +73,13 @@ const crossDoUnsupported = { session() {
 } };
 var AgentDurableObject = class {
 	session;
+	sessionKey;
+	name;
+	store;
+	sink;
+	model;
+	tools;
+	channelInstructions;
 	resources;
 	services;
 	constructor(state, def) {
@@ -73,6 +87,26 @@ var AgentDurableObject = class {
 		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.error.message}`);
+			if (def.onTurnError) try {
+				const out = def.onTurnError({
+					turnId: e.turnId,
+					error: e.error
+				});
+				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 +115,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 +179,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 });
 	}
 };
@@ -212,8 +289,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 +308,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 +341,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 +405,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

@@ -164,6 +164,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/package.json

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

package/src/agent-durable.ts

@@ -117,6 +117,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 +182,14 @@ 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. 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: { message: string } }) => void | Promise<void>;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -188,7 +207,20 @@ 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;
@@ -198,6 +230,40 @@ export class AgentDurableObject {
     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;
+      const defaultLog = () => console.error(`[june] agent "${name}" turn ${e.turnId} failed: ${e.error.message}`);
+      if (def.onTurnError) {
+        try {
+          const out = def.onTurnError({ turnId: e.turnId, error: e.error });
+          // 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 +275,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 +326,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 +387,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 });
   }
 }
@@ -352,10 +500,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 +546,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 +628,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

@@ -214,6 +214,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> => {