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

package/dist/agent-durable.d.ts

@@ -1,5 +1,5 @@
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
-import { InboundEvent, Model, Msg, SessionStore, Tool, TurnEvent } from "@junejs/core/agent-runtime";
+import { InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnEvent } from "@junejs/core/agent-runtime";
 import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
 type SqlStorageValue = ArrayBuffer | string | number | null;
@@ -30,11 +30,14 @@ declare class DoSessionStore implements SessionStore {
   private get sql();
   appendMessage(m: Msg): void;
   messages(): Msg[];
-  hasUserTurn(turnId: string): boolean;
+  hasOpeningMessage(turnId: string): boolean;
   getStep(id: string): unknown | undefined;
   putStep(id: string, output: unknown): void;
+  delStep(id: string): void;
   getStatus(): string;
   setStatus(s: string): void;
+  getSessionKey(): string | undefined;
+  setSessionKey(key: string): void;
   tx<T>(fn: () => T): T;
   unwrap<H = unknown>(): H;
 }
@@ -48,22 +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;
@@ -77,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,5 +1,5 @@
 import { channelDispatch, resolveChannel } from "@junejs/core/agent-config";
-import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
+import { AgentSession, ResumeAuthorizationError, withSystem } from "@junejs/core/agent-runtime";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
 var DoSessionStore = class {
@@ -20,8 +20,8 @@ var DoSessionStore = class {
 	messages() {
 		return this.sql.exec("SELECT body FROM agent_messages ORDER BY seq").toArray().map((r) => JSON.parse(r.body));
 	}
-	hasUserTurn(turnId) {
-		return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+	hasOpeningMessage(turnId) {
+		return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
 	}
 	getStep(id) {
 		const rows = this.sql.exec("SELECT output FROM agent_steps WHERE id = ?", id).toArray();
@@ -30,6 +30,9 @@ var DoSessionStore = class {
 	putStep(id, output) {
 		this.sql.exec("INSERT INTO agent_steps (id, output) VALUES (?, ?)", id, JSON.stringify(output));
 	}
+	delStep(id) {
+		this.sql.exec("DELETE FROM agent_steps WHERE id = ?", id);
+	}
 	getStatus() {
 		const rows = this.sql.exec("SELECT v FROM agent_meta WHERE k = 'status'").toArray();
 		return rows.length ? rows[0].v : "new";
@@ -37,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);
 	}
@@ -63,6 +73,13 @@ const crossDoUnsupported = { session() {
 } };
 var AgentDurableObject = class {
 	session;
+	sessionKey;
+	name;
+	store;
+	sink;
+	model;
+	tools;
+	channelInstructions;
 	resources;
 	services;
 	constructor(state, def) {
@@ -70,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));
@@ -78,35 +115,98 @@ 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
+		}, () => session.turn(input));
+	}
+	async start(input) {
+		await ensureScope();
+		const session = this.resolveSession(input.session);
 		return runInScope({
 			resources: this.resources,
 			services: this.services
-		}, () => this.session.turn(input));
+		}, () => 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 } = await req.json();
+			const { userText, turnId, event, trigger } = await req.json();
 			await ensureScope();
-			const started = runInScope({
-				resources: this.resources,
-				services: this.services
-			}, () => this.session.start({
-				userText,
-				turnId,
-				event
-			}));
-			return new Response(sseTurnStream(this.session, started.turnId), { headers: SSE_HEADERS });
+			let session;
+			let started;
+			try {
+				session = this.resolveSession(key);
+				started = runInScope({
+					resources: this.resources,
+					services: this.services
+				}, () => session.start({
+					userText,
+					turnId,
+					event,
+					trigger
+				}));
+			} catch (err) {
+				return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+			}
+			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 (url.pathname.endsWith("/transcript")) return Response.json({ transcript: this.transcript() });
-		return new Response("agent DO — POST /turn or GET /transcript", { status: 404 });
+		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
+				}, () => 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(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() });
+		}
+		return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
 	}
 };
 const SSE_HEADERS = {
@@ -132,7 +232,7 @@ function sseTurnStream(session, turnId) {
 			}, 2e4);
 			unsub = session.observe((e) => {
 				controller.enqueue(enc.encode(`data: ${JSON.stringify(e)}\n\n`));
-				if (e.type === "turn.completed" || e.type === "turn.failed") {
+				if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") {
 					stop();
 					controller.close();
 				}
@@ -189,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";
@@ -200,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 })
@@ -228,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)");
@@ -235,14 +361,35 @@ function durableChannelSurface(getNamespace, opts) {
 				method: "POST",
 				body: serializeTurn(message, o)
 			})));
+		},
+		resumeStream: async function* (o) {
+			const namespace = getNamespace();
+			if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+			yield* sseTurnEvents(await durableFetch(namespace, opts.agentName, o.session ?? "default", new Request("https://do/resume", {
+				method: "POST",
+				body: serializeResume(o)
+			})));
 		}
 	});
 }
+function serializeResume(o) {
+	try {
+		return JSON.stringify({
+			turnId: o.turnId,
+			inputId: o.inputId,
+			input: o.input,
+			by: o.by
+		});
+	} catch (err) {
+		throw new Error(`resumeStream: input is not JSON-serializable (${err.message}) — a resume answer must round-trip to the DO`);
+	}
+}
 function serializeTurn(userText, o) {
 	const payload = {
 		userText,
 		turnId: o?.turnId,
-		event: o?.event
+		event: o?.event,
+		trigger: o?.trigger
 	};
 	try {
 		return JSON.stringify(payload);
@@ -258,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

@@ -20,8 +20,8 @@ var SqliteSessionStore = class {
 	messages() {
 		return this.db.query("SELECT body FROM agent_messages WHERE session_id = ? ORDER BY seq").all(this.sid).map((r) => JSON.parse(r.body));
 	}
-	hasUserTurn(turnId) {
-		return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+	hasOpeningMessage(turnId) {
+		return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
 	}
 	getStep(id) {
 		const r = this.db.query("SELECT output FROM agent_steps WHERE session_id = ? AND id = ?").get(this.sid, id);
@@ -30,6 +30,9 @@ var SqliteSessionStore = class {
 	putStep(id, output) {
 		this.db.query("INSERT INTO agent_steps (session_id, id, output) VALUES (?, ?, ?)").run(this.sid, id, JSON.stringify(output));
 	}
+	delStep(id) {
+		this.db.query("DELETE FROM agent_steps WHERE session_id = ? AND id = ?").run(this.sid, id);
+	}
 	getStatus() {
 		return this.db.query("SELECT status FROM agent_sessions WHERE session_id = ?").get(this.sid)?.status ?? "new";
 	}
@@ -100,8 +103,8 @@ var MemorySessionStore = class {
 	messages() {
 		return this.msgs.slice();
 	}
-	hasUserTurn(turnId) {
-		return this.msgs.some((m) => m.role === "user" && m.turnId === turnId);
+	hasOpeningMessage(turnId) {
+		return this.msgs.some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
 	}
 	getStep(id) {
 		return this.steps.has(id) ? this.steps.get(id) : void 0;
@@ -109,6 +112,9 @@ var MemorySessionStore = class {
 	putStep(id, output) {
 		this.steps.set(id, output);
 	}
+	delStep(id) {
+		this.steps.delete(id);
+	}
 	getStatus() {
 		return this.status;
 	}
@@ -156,7 +162,14 @@ function mountAgent(agent, runtime, opts = {}) {
 		run: (message, o) => runtime.session(agent.name, o?.session ?? "default").turn({
 			turnId: o?.turnId,
 			userText: message,
-			event: o?.event
+			event: o?.event,
+			trigger: o?.trigger
+		}),
+		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.3",
+  "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.5",
+    "@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

@@ -17,6 +17,7 @@
 
 import {
   AgentSession,
+  ResumeAuthorizationError,
   withSystem,
   type EventSink,
   type TurnEvent,
@@ -25,6 +26,7 @@ import {
   type Runtime,
   type InboundEvent,
   type SessionStore,
+  type ProactiveTrigger,
   type Tool,
 } from "@junejs/core/agent-runtime";
 import type { Resources } from "@junejs/core/resources";
@@ -95,8 +97,8 @@ export class DoSessionStore implements SessionStore {
   messages(): Msg[] {
     return this.sql.exec<{ body: string }>("SELECT body FROM agent_messages ORDER BY seq").toArray().map((r) => JSON.parse(r.body));
   }
-  hasUserTurn(turnId: string): boolean {
-    return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+  hasOpeningMessage(turnId: string): boolean {
+    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
   }
   getStep(id: string): unknown | undefined {
     const rows = this.sql.exec<{ output: string }>("SELECT output FROM agent_steps WHERE id = ?", id).toArray();
@@ -105,6 +107,9 @@ export class DoSessionStore implements SessionStore {
   putStep(id: string, output: unknown) {
     this.sql.exec("INSERT INTO agent_steps (id, output) VALUES (?, ?)", id, JSON.stringify(output));
   }
+  delStep(id: string) {
+    this.sql.exec("DELETE FROM agent_steps WHERE id = ?", id);
+  }
   getStatus(): string {
     const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'status'").toArray();
     return rows.length ? rows[0]!.v : "new";
@@ -112,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);
   }
@@ -166,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
@@ -183,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;
@@ -193,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.
@@ -204,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
@@ -213,29 +326,91 @@ export class AgentDurableObject {
   // Juno's batch-loader registry) can't leak across turns on a long-lived DO.
   // ensureScope() lazily wires node:async_hooks (workerd via nodejs_compat), as the
   // pipeline does; without it runInScope is a pass-through and ambient reads throw.
-  async turn(input: { turnId?: string; userText: string; event?: InboundEvent }): Promise<string> {
+  async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<string> {
+    await ensureScope();
+    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();
-    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.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 } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent };
+      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.
-      const started = runInScope({ resources: this.resources, services: this.services }, () => this.session.start({ userText, turnId, event }));
-      return new Response(sseTurnStream(this.session, started.turnId), { headers: SSE_HEADERS });
+      let session: AgentSession;
+      let started: { turnId: string };
+      try {
+        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, 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 });
+      }
+      // 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
+    // VERIFIED identity, so the app must authenticate it upstream (e.g. take the user id from a
+    // signature-checked Slack interaction payload), never expose this endpoint raw to clients.
+    if (req.method === "POST" && url.pathname.endsWith("/resume")) {
+      const { turnId, inputId, input, by } = (await req.json()) as { turnId: string; inputId: string; input: unknown; by?: string };
+      await ensureScope();
+      let session: AgentSession;
+      try {
+        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 / key mismatch
+        return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
+      }
+      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 or GET /transcript", { status: 404 });
+    return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
   }
 }
 
@@ -263,7 +438,9 @@ function sseTurnStream(session: AgentSession, turnId: string): ReadableStream<Ui
       }, 20_000);
       unsub = session.observe((e) => {
         controller.enqueue(enc.encode(`data: ${JSON.stringify(e)}\n\n`));
-        if (e.type === "turn.completed" || e.type === "turn.failed") { stop(); controller.close(); }
+        // terminal for the STREAM: completed, failed, OR suspended (input.requested → the turn
+        // parked; the stream ends and a later /resume opens a fresh continuation stream).
+        if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") { stop(); controller.close(); }
       }, { turnId });
     },
     cancel() { stop(); },
@@ -323,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
@@ -348,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).
@@ -421,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();
@@ -433,6 +659,18 @@ export function durableChannelSurface(
       );
       yield* sseTurnEvents(res);
     },
+    // Resume a parked turn on its session's DO and stream the continuation.
+    resumeStream: async function* (o) {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o.session ?? "default",
+        new Request("https://do/resume", { method: "POST", body: serializeResume(o) }),
+      );
+      yield* sseTurnEvents(res);
+    },
   };
   return channelDispatch(resolved, ctx);
 }
@@ -443,8 +681,22 @@ export function durableChannelSurface(
 // run the turn, so on a serialization failure we drop it rather than let an
 // unserializable payload take down turn forwarding entirely. (raw is optional on
 // InboundEvent precisely because it may not survive this boundary.)
-function serializeTurn(userText: string, o?: { turnId?: string; event?: InboundEvent }): string {
-  const payload = { userText, turnId: o?.turnId, event: o?.event };
+// Serialize a /resume RPC body. `input` is `unknown` — the human's answer — so a
+// (third-party) host could hand us something JSON.stringify chokes on (BigInt, circular).
+// Unlike serializeTurn's `raw`, `input` is essential: silently dropping it would resume the
+// turn with the wrong answer. So fail loudly with a clear message rather than corrupt the resume.
+function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string }): string {
+  try {
+    return JSON.stringify({ turnId: o.turnId, inputId: o.inputId, input: o.input, by: o.by });
+  } catch (err) {
+    throw new Error(`resumeStream: input is not JSON-serializable (${(err as Error).message}) — a resume answer must round-trip to the DO`);
+  }
+}
+
+// `trigger` is ProactiveTrigger — plain strings by construction — so only event.raw can make
+// the stringify throw; the fallback that strips it stays sufficient.
+function serializeTurn(userText: string, o?: { turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger }): string {
+  const payload = { userText, turnId: o?.turnId, event: o?.event, trigger: o?.trigger };
   try {
     return JSON.stringify(payload);
   } catch {

package/src/agent-native.ts

@@ -46,8 +46,8 @@ class SqliteSessionStore implements SessionStore {
     return (this.db.query("SELECT body FROM agent_messages WHERE session_id = ? ORDER BY seq").all(this.sid) as { body: string }[])
       .map((r) => JSON.parse(r.body));
   }
-  hasUserTurn(turnId: string): boolean {
-    return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+  hasOpeningMessage(turnId: string): boolean {
+    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
   }
   getStep(id: string): unknown | undefined {
     const r = this.db.query("SELECT output FROM agent_steps WHERE session_id = ? AND id = ?").get(this.sid, id) as { output: string } | undefined;
@@ -56,6 +56,9 @@ class SqliteSessionStore implements SessionStore {
   putStep(id: string, output: unknown) {
     this.db.query("INSERT INTO agent_steps (session_id, id, output) VALUES (?, ?, ?)").run(this.sid, id, JSON.stringify(output));
   }
+  delStep(id: string) {
+    this.db.query("DELETE FROM agent_steps WHERE session_id = ? AND id = ?").run(this.sid, id);
+  }
   getStatus(): string {
     return (this.db.query("SELECT status FROM agent_sessions WHERE session_id = ?").get(this.sid) as { status: string } | undefined)?.status ?? "new";
   }
@@ -136,9 +139,10 @@ class MemorySessionStore implements SessionStore {
   private status = "new";
   appendMessage(m: Msg) { this.msgs.push(m); }
   messages(): Msg[] { return this.msgs.slice(); }
-  hasUserTurn(turnId: string): boolean { return this.msgs.some((m) => m.role === "user" && m.turnId === turnId); }
+  hasOpeningMessage(turnId: string): boolean { return this.msgs.some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId); }
   getStep(id: string): unknown | undefined { return this.steps.has(id) ? this.steps.get(id) : undefined; }
   putStep(id: string, output: unknown) { this.steps.set(id, output); }
+  delStep(id: string) { this.steps.delete(id); }
   getStatus(): string { return this.status; }
   setStatus(s: string) { this.status = s; }
   tx<T>(fn: () => T): T { return fn(); } // no rollback: an in-memory store is not a durability tier
@@ -209,7 +213,12 @@ export function mountAgent(
     agent,
     services: opts.services, // same DI bag reachable from channel hooks (parity with durableChannelSurface)
     run: (message, o) =>
-      runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event }),
+      runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger }),
+    // 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> => {