@junejs/server 1.0.0-dev.20 → 1.0.0-dev.24

package/dist/agent-durable.js

@@ -1,3 +1,4 @@
+import { observeTurnEvents } from "./turn-events.js";
 import { isolateLocal } from "./isolate-local.js";
 import { assertCoreRuntimeVersion } from "./core-version.js";
 import { DeliverUnsupportedError, actionToTool, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
@@ -373,49 +374,6 @@ function sseTurnStream(session, turnId) {
 		}
 	});
 }
-function observeTurnEvents(session, turnId) {
-	const queue = [];
-	let terminal = false;
-	let notify;
-	const unsub = session.observe((e) => {
-		queue.push(e);
-		if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
-		notify?.();
-	}, { turnId });
-	return { [Symbol.asyncIterator]() {
-		return {
-			async next() {
-				for (;;) {
-					const e = queue.shift();
-					if (e) return {
-						value: e,
-						done: false
-					};
-					if (terminal) {
-						unsub();
-						return {
-							value: void 0,
-							done: true
-						};
-					}
-					await new Promise((resolve) => {
-						notify = resolve;
-					});
-					notify = void 0;
-				}
-			},
-			async return() {
-				unsub();
-				terminal = true;
-				queue.length = 0;
-				return {
-					value: void 0,
-					done: true
-				};
-			}
-		};
-	} };
-}
 async function sseTurnFinalText(res) {
 	const ct = res.headers.get("content-type") ?? "";
 	if (!res.body || !ct.includes("text/event-stream")) {

package/dist/agent-native.d.ts

@@ -1,32 +1,42 @@
 import { SyncSqlite } from "./sqlite-driver.js";
 import { AgentDefinition, ChannelContext } from "@junejs/core/agent-config";
-import { AgentSession, Model, Runtime, Tool } from "@junejs/core/agent-runtime";
+import { AgentSession, ChannelPolicy, Model, Runtime, Tool } from "@junejs/core/agent-runtime";
 //#region src/agent-native.d.ts
 type AgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
-  channelInstructions?: Record<string, string>;
+  channelInstructions?: Record<string, string | ChannelPolicy>;
+};
+declare function toAgentDef(agent: AgentDefinition, model: Model): AgentDef;
+type NativeRuntimeOptions = {
+  maxSessions?: number;
 };
 declare class NativeRuntime implements Runtime {
   private actors;
   private readonly agents;
   private readonly db;
-  constructor(agents: Record<string, AgentDef>, db: SyncSqlite);
+  private readonly maxSessions;
+  constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts?: NativeRuntimeOptions);
+  agentDef(name: string): AgentDef | undefined;
   session(agent: string, id: string): AgentSession;
+  get sessionCount(): number;
+  private evictIdle;
 }
-declare function createNativeRuntime(agents: Record<string, AgentDef>, path?: string): Promise<NativeRuntime>;
+declare function createNativeRuntime(agents: Record<string, AgentDef>, path?: string, opts?: NativeRuntimeOptions): Promise<NativeRuntime>;
 declare class MemoryRuntime implements Runtime {
   private actors;
   private stores;
   private readonly agents;
   constructor(agents: Record<string, AgentDef>);
+  agentDef(name: string): AgentDef | undefined;
   session(agent: string, id: string): AgentSession;
 }
 type AgentBackend = "native" | "memory" | "durable";
 declare function createAgentRuntime(agents: Record<string, AgentDef>, opts?: {
   backend?: AgentBackend;
   path?: string;
+  maxSessions?: number;
 }): Promise<Runtime>;
 declare function mountAgent(agent: AgentDefinition, runtime: Runtime, opts?: {
   chatPath?: string;
@@ -39,4 +49,4 @@ declare function mountAgent(agent: AgentDefinition, runtime: Runtime, opts?: {
   ctx: ChannelContext;
 };
 //#endregion
-export { AgentBackend, AgentDef, MemoryRuntime, NativeRuntime, createAgentRuntime, createNativeRuntime, mountAgent };
+export { AgentBackend, AgentDef, MemoryRuntime, NativeRuntime, NativeRuntimeOptions, createAgentRuntime, createNativeRuntime, mountAgent, toAgentDef };

package/dist/agent-native.js

@@ -1,11 +1,13 @@
+import { observeTurnEvents } from "./turn-events.js";
 import { assertCoreRuntimeVersion } from "./core-version.js";
 import { openLocalSqliteSync } from "./sqlite-driver.js";
-import { channelFetch } from "@junejs/core/agent-config";
+import { buildSystemPrompt, channelFetch } from "@junejs/core/agent-config";
 import { AgentSession, withSystem } from "@junejs/core/agent-runtime";
 //#region src/agent-native.ts
 function initSchema(db) {
 	db.exec(`CREATE TABLE IF NOT EXISTS agent_sessions (session_id TEXT PRIMARY KEY, status TEXT)`);
 	db.exec(`CREATE TABLE IF NOT EXISTS agent_messages (seq INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, body TEXT)`);
+	db.exec(`CREATE INDEX IF NOT EXISTS agent_messages_session ON agent_messages (session_id, seq)`);
 	db.exec(`CREATE TABLE IF NOT EXISTS agent_steps (session_id TEXT, id TEXT, output TEXT, PRIMARY KEY (session_id, id))`);
 }
 var SqliteSessionStore = class {
@@ -22,7 +24,7 @@ var SqliteSessionStore = class {
 		return this.db.query("SELECT body FROM agent_messages WHERE session_id = ? ORDER BY seq").all(this.sid).map((r) => JSON.parse(r.body));
 	}
 	hasOpeningMessage(turnId) {
-		return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
+		return this.db.query("SELECT 1 FROM agent_messages WHERE session_id = ? AND json_extract(body, '$.turnId') = ? AND json_extract(body, '$.role') IN ('user', 'trigger') LIMIT 1").get(this.sid, turnId) != null;
 	}
 	getStep(id) {
 		const r = this.db.query("SELECT output FROM agent_steps WHERE session_id = ? AND id = ?").get(this.sid, id);
@@ -83,32 +85,68 @@ var InProcEventSink = class {
 		this.subs.add(cb);
 		return () => this.subs.delete(cb);
 	}
+	get size() {
+		return this.subs.size;
+	}
 };
+function toAgentDef(agent, model) {
+	return {
+		model,
+		tools: agent.tools,
+		instructions: buildSystemPrompt(agent),
+		...agent.channelInstructions ? { channelInstructions: agent.channelInstructions } : {}
+	};
+}
 var NativeRuntime = class {
 	actors = /* @__PURE__ */ new Map();
 	agents;
 	db;
-	constructor(agents, db) {
+	maxSessions;
+	constructor(agents, db, opts = {}) {
 		assertCoreRuntimeVersion("NativeRuntime");
 		this.agents = agents;
 		this.db = db;
+		const max = opts.maxSessions ?? 1e3;
+		if (!(Number.isInteger(max) && max >= 1) && max !== Infinity) throw new RangeError(`NativeRuntime: maxSessions must be an integer >= 1 (or Infinity for no cap), got ${max}`);
+		this.maxSessions = max;
 		initSchema(db);
 	}
+	agentDef(name) {
+		return this.agents[name];
+	}
 	session(agent, id) {
 		const key = `${agent}:${id}`;
-		let a = this.actors.get(key);
-		if (!a) {
-			const def = this.agents[agent];
-			if (!def) throw new Error(`unknown agent: ${agent}`);
-			const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-			a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcEventSink(), model, def.tools, this, def.channelInstructions);
-			this.actors.set(key, a);
+		const hit = this.actors.get(key);
+		if (hit) {
+			this.actors.delete(key);
+			this.actors.set(key, hit);
+			return hit.session;
+		}
+		const def = this.agents[agent];
+		if (!def) throw new Error(`unknown agent: ${agent}`);
+		const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+		const sink = new InProcEventSink();
+		const session = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+		this.evictIdle();
+		this.actors.set(key, {
+			session,
+			sink
+		});
+		return session;
+	}
+	get sessionCount() {
+		return this.actors.size;
+	}
+	evictIdle() {
+		if (this.actors.size < this.maxSessions) return;
+		for (const [key, a] of this.actors) {
+			if (this.actors.size < this.maxSessions) break;
+			if (a.session.idle() && a.sink.size === 0) this.actors.delete(key);
 		}
-		return a;
 	}
 };
-async function createNativeRuntime(agents, path = ":memory:") {
-	return new NativeRuntime(agents, await openLocalSqliteSync(path));
+async function createNativeRuntime(agents, path = ":memory:", opts = {}) {
+	return new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
 }
 var MemorySessionStore = class {
 	msgs = [];
@@ -165,6 +203,9 @@ var MemoryRuntime = class {
 		assertCoreRuntimeVersion("MemoryRuntime");
 		this.agents = agents;
 	}
+	agentDef(name) {
+		return this.agents[name];
+	}
 	session(agent, id) {
 		const key = `${agent}:${id}`;
 		let a = this.actors.get(key);
@@ -173,7 +214,8 @@ var MemoryRuntime = class {
 			if (!def) throw new Error(`unknown agent: ${agent}`);
 			const store = new MemorySessionStore();
 			this.stores.set(key, store);
-			a = new AgentSession(agent, id, store, new InProcEventSink(), def.model, def.tools, this);
+			const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+			a = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
 			this.actors.set(key, a);
 		}
 		return a;
@@ -182,12 +224,23 @@ var MemoryRuntime = class {
 async function createAgentRuntime(agents, opts = {}) {
 	const backend = opts.backend ?? "native";
 	if (backend === "memory") return new MemoryRuntime(agents);
-	if (backend === "native") return createNativeRuntime(agents, opts.path);
+	if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });
 	throw new Error("backend 'durable' is the Cloudflare Durable Object target — construct AgentDurableObject in your worker, not via createAgentRuntime");
 }
+function warnOnDrift(agent, runtime) {
+	const def = runtime.agentDef?.(agent.name);
+	if (!def) return;
+	const names = (tools) => tools.map((t) => t.spec.name).sort();
+	const want = names(agent.tools), have = names(def.tools);
+	if (want.join("\0") !== have.join("\0")) {
+		const missing = want.filter((n) => !have.includes(n)), extra = have.filter((n) => !want.includes(n));
+		console.warn(`[june] mountAgent("${agent.name}"): the runtime's tools differ from the agent definition's` + (missing.length ? ` — missing from the runtime: ${missing.join(", ")}` : "") + (extra.length ? ` — only in the runtime: ${extra.join(", ")}` : "") + `. Build the runtime entry with toAgentDef(agent, model) so both come from one definition.`);
+	}
+}
 function mountAgent(agent, runtime, opts = {}) {
 	const chatPath = opts.chatPath ?? "/message";
 	const channelsOn = opts.channels ?? true;
+	warnOnDrift(agent, runtime);
 	const ctx = {
 		agent,
 		services: opts.services,
@@ -205,6 +258,22 @@ function mountAgent(agent, runtime, opts = {}) {
 			trigger: o?.trigger,
 			replace: o?.replace
 		}),
+		runStream: async function* (message, o) {
+			const session = runtime.session(agent.name, o?.session ?? "default");
+			const { turnId } = session.start({
+				turnId: o?.turnId,
+				userText: message,
+				event: o?.event,
+				trigger: o?.trigger,
+				replace: o?.replace
+			});
+			yield* observeTurnEvents(session, turnId);
+		},
+		resumeStream: async function* (o) {
+			const session = runtime.session(agent.name, o.session ?? "default");
+			const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by });
+			yield* observeTurnEvents(session, turnId);
+		},
 		resetSession: (o) => runtime.session(agent.name, o?.session ?? "default").reset()
 	};
 	const channels = channelFetch(agent, ctx);
@@ -226,4 +295,4 @@ function mountAgent(agent, runtime, opts = {}) {
 	};
 }
 //#endregion
-export { MemoryRuntime, NativeRuntime, createAgentRuntime, createNativeRuntime, mountAgent };
+export { MemoryRuntime, NativeRuntime, createAgentRuntime, createNativeRuntime, mountAgent, toAgentDef };

package/dist/app.js

@@ -1,5 +1,5 @@
 import { discoverAgent } from "./agent-discover.js";
-import { createAgentRuntime, mountAgent } from "./agent-native.js";
+import { createAgentRuntime, mountAgent, toAgentDef } from "./agent-native.js";
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles } from "./router.js";
 import { createPipeline } from "./pipeline.js";
 import { resolveBoundary } from "./segment.js";
@@ -13,7 +13,6 @@ import { existsSync, lstatSync, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { buildSystemPrompt } from "@junejs/core/agent-config";
 import { routeFromModule } from "@junejs/core/route";
 import { resolveAgent, resolveClientRouter, resolveSpeculationRules } from "@junejs/core/config";
 import { runWithTrace } from "@junejs/core/instrumentation";
@@ -125,11 +124,7 @@ function createApp({ appDir: appDirInput, config = {} }) {
 			const def = await discoverAgent(agentDir);
 			const backend = agent.runtime.backend === "durable" ? "native" : agent.runtime.backend;
 			const model = anthropic({ model: def.model });
-			const mounted = mountAgent(def, await createAgentRuntime({ [def.name]: {
-				model,
-				tools: def.tools,
-				instructions: buildSystemPrompt(def)
-			} }, { backend }), {
+			const mounted = mountAgent(def, await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend }), {
 				chatPath: agent.runtime.chat.path,
 				channels: agent.runtime.channels
 			});

package/dist/core-version.js

@@ -1,6 +1,6 @@
 import * as coreRuntime from "@junejs/core/agent-runtime";
 //#region src/core-version.ts
-const EXPECTED_CORE_RUNTIME_API = 1;
+const EXPECTED_CORE_RUNTIME_API = 2;
 function assertCoreRuntimeVersion(surface) {
 	checkCoreRuntimeVersion(surface, coreRuntime.RUNTIME_API_VERSION);
 }

package/dist/turn-events.d.ts

@@ -0,0 +1,5 @@
+import { AgentSession, TurnEvent } from "@junejs/core/agent-runtime";
+//#region src/turn-events.d.ts
+declare function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent>;
+//#endregion
+export { observeTurnEvents };

package/dist/turn-events.js

@@ -0,0 +1,46 @@
+//#region src/turn-events.ts
+function observeTurnEvents(session, turnId) {
+	const queue = [];
+	let terminal = false;
+	let notify;
+	const unsub = session.observe((e) => {
+		queue.push(e);
+		if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
+		notify?.();
+	}, { turnId });
+	return { [Symbol.asyncIterator]() {
+		return {
+			async next() {
+				for (;;) {
+					const e = queue.shift();
+					if (e) return {
+						value: e,
+						done: false
+					};
+					if (terminal) {
+						unsub();
+						return {
+							value: void 0,
+							done: true
+						};
+					}
+					await new Promise((resolve) => {
+						notify = resolve;
+					});
+					notify = void 0;
+				}
+			},
+			async return() {
+				unsub();
+				terminal = true;
+				queue.length = 0;
+				return {
+					value: void 0,
+					done: true
+				};
+			}
+		};
+	} };
+}
+//#endregion
+export { observeTurnEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.20",
+  "version": "1.0.0-dev.24",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -138,7 +138,7 @@
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.38",
+    "@junejs/core": ">=0.2.0-dev.44",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-server-dom-webpack": "19.2.7",

package/src/agent-discover.ts

@@ -120,8 +120,8 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
 
 // Discover an agent from its directory, returning the assembled AgentDefinition
 // (tools already adapted from defineActions; read_skill added if any skills
-// exist). Mount it on a runtime with createNativeRuntime({ [agent.name]: { model,
-// tools: agent.tools } }).
+// exist). Mount it on a runtime with createNativeRuntime({ [agent.name]:
+// toAgentDef(agent, model) }).
 export async function discoverAgent(dir: string): Promise<AgentDefinition> {
   return assembleAgent(await discoverAgentModule(dir), process.env);
 }

package/src/agent-durable.ts

@@ -33,6 +33,7 @@ import {
   type TurnFailurePhase,
 } from "@junejs/core/agent-runtime";
 import type { Resources } from "@junejs/core/resources";
+import { observeTurnEvents } from "./turn-events";
 import {
   channelDispatch,
   DeliverUnsupportedError,
@@ -692,45 +693,6 @@ function sseTurnStream(session: AgentSession, turnId: string): ReadableStream<Ui
   });
 }
 
-// The IN-PROCESS sibling of sseTurnStream: one turn's TurnEvents as an AsyncIterable, for a
-// consumer living in the SAME isolate as the session (a delivered render). Subscribes eagerly
-// at call time — not at first iteration — so the sseTurnStream timing guarantee carries over
-// (call this synchronously after start(), before any event can emit); events landing before
-// the consumer catches up are buffered. Ends after the turn's terminal event (completed,
-// failed, or input.requested — a park ends this stream; a later /resume is a new one), and an
-// early consumer exit (for-await break/return) unsubscribes rather than buffering forever.
-function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent> {
-  const queue: TurnEvent[] = [];
-  let terminal = false;
-  let notify: (() => void) | undefined;
-  const unsub = session.observe((e) => {
-    queue.push(e);
-    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
-    notify?.();
-  }, { turnId });
-  return {
-    [Symbol.asyncIterator]() {
-      return {
-        async next(): Promise<IteratorResult<TurnEvent>> {
-          for (;;) {
-            const e = queue.shift();
-            if (e) return { value: e, done: false };
-            if (terminal) { unsub(); return { value: undefined, done: true }; }
-            await new Promise<void>((resolve) => { notify = resolve; });
-            notify = undefined;
-          }
-        },
-        async return(): Promise<IteratorResult<TurnEvent>> {
-          unsub();
-          terminal = true;
-          queue.length = 0;
-          return { value: undefined, done: true };
-        },
-      };
-    },
-  };
-}
-
 // Consume an SSE turn stream to its terminal state: the final text, or throw on failure.
 // The non-streaming path (channels, a JSON chat response) uses this. Guards a non-SSE /
 // body-less upstream response (a misroute or an error) into a clear error, not a TypeError.

package/src/agent-native.ts

@@ -10,6 +10,7 @@
 import {
   AgentSession,
   withSystem,
+  type ChannelPolicy,
   type EventSink,
   type TurnEvent,
   type Model,
@@ -18,13 +19,17 @@ import {
   type SessionStore,
   type Tool,
 } from "@junejs/core/agent-runtime";
-import { channelFetch, type AgentDefinition, type ChannelContext } from "@junejs/core/agent-config";
+import { buildSystemPrompt, channelFetch, type AgentDefinition, type ChannelContext } from "@junejs/core/agent-config";
 import { openLocalSqliteSync, type SyncSqlite } from "./sqlite-driver";
 import { assertCoreRuntimeVersion } from "./core-version";
+import { observeTurnEvents } from "./turn-events";
 
 function initSchema(db: SyncSqlite) {
   db.exec(`CREATE TABLE IF NOT EXISTS agent_sessions (session_id TEXT PRIMARY KEY, status TEXT)`);
   db.exec(`CREATE TABLE IF NOT EXISTS agent_messages (seq INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, body TEXT)`);
+  // Every store read is scoped to one session; without this index each one scanned the
+  // messages of ALL sessions in the file (#168). IF NOT EXISTS: existing DBs gain it.
+  db.exec(`CREATE INDEX IF NOT EXISTS agent_messages_session ON agent_messages (session_id, seq)`);
   // NOTE: PRIMARY KEY (session_id, id) — never id alone. The store view scopes
   // every query by session, so a step id can't leak across sessions.
   db.exec(`CREATE TABLE IF NOT EXISTS agent_steps (session_id TEXT, id TEXT, output TEXT, PRIMARY KEY (session_id, id))`);
@@ -47,8 +52,11 @@ 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));
   }
+  // Asked once per turn start: probe for the one row instead of parsing the transcript.
   hasOpeningMessage(turnId: string): boolean {
-    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
+    return this.db
+      .query("SELECT 1 FROM agent_messages WHERE session_id = ? AND json_extract(body, '$.turnId') = ? AND json_extract(body, '$.role') IN ('user', 'trigger') LIMIT 1")
+      .get(this.sid, turnId) != null; // bun:sqlite misses with null, node:sqlite with undefined
   }
   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;
@@ -106,37 +114,96 @@ class InProcEventSink implements EventSink {
   private subs = new Set<(e: TurnEvent) => void>();
   emit(e: TurnEvent) { this.subs.forEach((cb) => { try { cb(e); } catch { /* a bad subscriber must not break emit */ } }); }
   subscribe(cb: (e: TurnEvent) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
+  get size(): number { return this.subs.size; }
 }
 
 // `instructions` (the agent's system prompt) is injected into the model per turn
 // by the runtime (withSystem) — single-sourced on the def, not baked into `model`.
-export type AgentDef = { model: Model; tools: Tool[]; instructions?: string; channelInstructions?: Record<string, string> };
+export type AgentDef = { model: Model; tools: Tool[]; instructions?: string; channelInstructions?: Record<string, string | ChannelPolicy> };
+
+// The runtime-side def for an assembled AgentDefinition (#173): the tools (channel
+// capability tools and read_skill included), the system prompt (instructions + the
+// skill index) and the per-surface policies all come from the ONE definition that
+// mountAgent mounts, so the engine and the channels can't drift apart. Only the model
+// is the host's choice.
+//   createNativeRuntime({ [agent.name]: toAgentDef(agent, anthropic({ … })) })
+export function toAgentDef(agent: AgentDefinition, model: Model): AgentDef {
+  return {
+    model,
+    tools: agent.tools,
+    instructions: buildSystemPrompt(agent),
+    ...(agent.channelInstructions ? { channelInstructions: agent.channelInstructions } : {}),
+  };
+}
+
+export type NativeRuntimeOptions = {
+  // Soft cap on memoized session actors (#174), default 1000. Past it, the least recently
+  // used IDLE actors (no turn running or queued, no reset pending, no live subscriber) are
+  // dropped; their state is in SQLite, so the next session() rebuilds them transparently.
+  // Busy actors are never dropped, so the count can exceed the cap while they run.
+  maxSessions?: number;
+};
 
 // The native Runtime: a registry of agent definitions over one SQLite handle,
-// handing out (and memoizing) an AgentSession actor per (agent, id).
+// handing out (and memoizing) an AgentSession actor per (agent, id). The memo is an
+// LRU bounded by maxSessions — with slackChannel every thread is a session, so an
+// unbounded memo grew by one actor per thread for the life of the process.
+// Callers must not hold an AgentSession across an await and start turns on it later:
+// if it was evicted meanwhile, a fresh actor for the same session would run turns
+// unserialized with it. Call session() at the point of use (mountAgent does).
 export class NativeRuntime implements Runtime {
-  private actors = new Map<string, AgentSession>();
+  private actors = new Map<string, { session: AgentSession; sink: InProcEventSink }>();
   private readonly agents: Record<string, AgentDef>;
   private readonly db: SyncSqlite;
+  private readonly maxSessions: number;
 
-  constructor(agents: Record<string, AgentDef>, db: SyncSqlite) {
+  constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts: NativeRuntimeOptions = {}) {
     assertCoreRuntimeVersion("NativeRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
     this.db = db;
+    const max = opts.maxSessions ?? 1000;
+    // At least one actor is always retained (the one being handed out), so a cap below 1
+    // means nothing, and NaN would compare false and evict every idle actor on each miss.
+    // Infinity is allowed: an explicit "no cap".
+    if (!(Number.isInteger(max) && max >= 1) && max !== Infinity) {
+      throw new RangeError(`NativeRuntime: maxSessions must be an integer >= 1 (or Infinity for no cap), got ${max}`);
+    }
+    this.maxSessions = max;
     initSchema(db);
   }
 
+  agentDef(name: string): AgentDef | undefined { return this.agents[name]; }
+
   session(agent: string, id: string): AgentSession {
     const key = `${agent}:${id}`;
-    let a = this.actors.get(key);
-    if (!a) {
-      const def = this.agents[agent];
-      if (!def) throw new Error(`unknown agent: ${agent}`);
-      const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), new InProcEventSink(), model, def.tools, this, def.channelInstructions);
-      this.actors.set(key, a);
+    const hit = this.actors.get(key);
+    if (hit) {
+      // most recently used → the tail (Map iteration order is insertion order)
+      this.actors.delete(key);
+      this.actors.set(key, hit);
+      return hit.session;
+    }
+    const def = this.agents[agent];
+    if (!def) throw new Error(`unknown agent: ${agent}`);
+    const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+    const sink = new InProcEventSink();
+    const session = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+    this.evictIdle();
+    this.actors.set(key, { session, sink });
+    return session;
+  }
+
+  // Number of memoized actors (observability / tests).
+  get sessionCount(): number { return this.actors.size; }
+
+  // Drop least recently used idle actors until one more fits under the cap. Runs before
+  // the new actor is inserted, so the actor being handed out is never a candidate.
+  private evictIdle() {
+    if (this.actors.size < this.maxSessions) return;
+    for (const [key, a] of this.actors) {
+      if (this.actors.size < this.maxSessions) break;
+      if (a.session.idle() && a.sink.size === 0) this.actors.delete(key);
     }
-    return a;
   }
 }
 
@@ -146,14 +213,16 @@ export class NativeRuntime implements Runtime {
 export async function createNativeRuntime(
   agents: Record<string, AgentDef>,
   path = ":memory:",
+  opts: NativeRuntimeOptions = {},
 ): Promise<NativeRuntime> {
-  return new NativeRuntime(agents, await openLocalSqliteSync(path));
+  return new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
 }
 
 // ── memory backend — in-process, ephemeral (no DB, no disk) ───────────────────
 // The lightest "no Durable Object, no persistence" option: great for dev, tests,
 // and stateless previews. Same engine + seams; state is a Map that dies with the
-// process. (For durability pick `native` on a long-running host or the Durable
+// process — and is never evicted (the actor IS the state), so it grows with every
+// session: not for a long-running host with unbounded sessions. (For durability pick `native` on a long-running host or the Durable
 // Object target on the edge.)
 class MemorySessionStore implements SessionStore {
   private msgs: Msg[] = [];
@@ -191,6 +260,7 @@ export class MemoryRuntime implements Runtime {
     assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
   }
+  agentDef(name: string): AgentDef | undefined { return this.agents[name]; }
   session(agent: string, id: string): AgentSession {
     const key = `${agent}:${id}`;
     let a = this.actors.get(key);
@@ -199,7 +269,9 @@ export class MemoryRuntime implements Runtime {
       if (!def) throw new Error(`unknown agent: ${agent}`);
       const store = new MemorySessionStore();
       this.stores.set(key, store);
-      a = new AgentSession(agent, id, store, new InProcEventSink(), def.model, def.tools, this);
+      // Same def handling as NativeRuntime: switching backend must not change behavior.
+      const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
+      a = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
       this.actors.set(key, a);
     }
     return a;
@@ -217,16 +289,39 @@ export type AgentBackend = "native" | "memory" | "durable";
 // choice is explicit and a mis-selection fails loudly.
 export async function createAgentRuntime(
   agents: Record<string, AgentDef>,
-  opts: { backend?: AgentBackend; path?: string } = {},
+  opts: { backend?: AgentBackend; path?: string; maxSessions?: number } = {},
 ): Promise<Runtime> {
   const backend = opts.backend ?? "native";
   if (backend === "memory") return new MemoryRuntime(agents);
-  if (backend === "native") return createNativeRuntime(agents, opts.path);
+  if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });
   throw new Error("backend 'durable' is the Cloudflare Durable Object target — construct AgentDurableObject in your worker, not via createAgentRuntime");
 }
 
-// Mount a discovered agent on a runtime. Builds the ChannelContext whose `run`
-// bridges to a durable turn, and exposes:
+// #173: the engine runs the runtime's AgentDef, the channels see the AgentDefinition —
+// declared separately by hand, they drift silently (a tool the model can't call, a
+// channel capability tool the engine never got). Say so once at mount. Only the
+// in-process runtimes expose their def; tools compare by name.
+function warnOnDrift(agent: AgentDefinition, runtime: Runtime) {
+  const def = (runtime as { agentDef?: (name: string) => AgentDef | undefined }).agentDef?.(agent.name);
+  if (!def) return;
+  const names = (tools: Tool[]) => tools.map((t) => t.spec.name).sort();
+  const want = names(agent.tools), have = names(def.tools);
+  if (want.join("\0") !== have.join("\0")) {
+    const missing = want.filter((n) => !have.includes(n)), extra = have.filter((n) => !want.includes(n));
+    console.warn(
+      `[june] mountAgent("${agent.name}"): the runtime's tools differ from the agent definition's` +
+        (missing.length ? ` — missing from the runtime: ${missing.join(", ")}` : "") +
+        (extra.length ? ` — only in the runtime: ${extra.join(", ")}` : "") +
+        `. Build the runtime entry with toAgentDef(agent, model) so both come from one definition.`,
+    );
+  }
+}
+
+// Mount a discovered agent on a runtime. Builds the ChannelContext the channels drive
+// turns through — run, runDetached, runStream, resumeStream and resetSession, each over
+// the runtime's in-process session. Not provided: runDelivered/resumeDelivered, which
+// exist to escape the edge waitUntil ceiling (a native host has none; channels fall back
+// to runStream/resumeStream without them). Exposes:
 //   • surface(req) — the composable agent surface for June's router: a framework
 //     chat endpoint at `chatPath` (POST {message, session?} → a turn) PLUS the
 //     discovered channels; returns null when the request isn't an agent route.
@@ -244,6 +339,7 @@ export function mountAgent(
 } {
   const chatPath = opts.chatPath ?? "/message";
   const channelsOn = opts.channels ?? true;
+  warnOnDrift(agent, runtime);
   const ctx: ChannelContext = {
     agent,
     services: opts.services, // same DI bag reachable from channel hooks (parity with durableChannelSurface)
@@ -254,6 +350,22 @@ export function mountAgent(
     // 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, replace: o?.replace }),
+    // LIVE (#169): the turn's event stream, so a channel renders as the turn runs —
+    // slackChannel({ stream: true }) edits in place here exactly as on the edge, instead of
+    // silently degrading to one post at the end. Lazy like the DO's (the turn starts on the
+    // first pull); start()/resume() and the subscription run with nothing awaited between,
+    // so no event can emit unobserved.
+    runStream: async function* (message, o) {
+      const session = runtime.session(agent.name, o?.session ?? "default");
+      const { turnId } = session.start({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger, replace: o?.replace });
+      yield* observeTurnEvents(session, turnId);
+    },
+    // HITL: answer a parked turn and stream its continuation (the approval-button path).
+    resumeStream: async function* (o) {
+      const session = runtime.session(agent.name, o.session ?? "default");
+      const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by });
+      yield* observeTurnEvents(session, turnId);
+    },
     // SESSION RESET (#129): same seam as durableChannelSurface — the in-process runtimes'
     // stores implement archival, so a channel written against ctx.resetSession behaves
     // identically on both targets.

package/src/app.ts

@@ -28,8 +28,7 @@ import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
 import { createPipeline, type ExtraHandler, type LayoutComponent, type MiddlewareHandler, type Pipeline, type Resolved, type ResourceHandler } from "./pipeline";
 import { discoverAgent } from "./agent-discover";
-import { createAgentRuntime, mountAgent } from "./agent-native";
-import { buildSystemPrompt } from "@junejs/core/agent-config";
+import { createAgentRuntime, mountAgent, toAgentDef } from "./agent-native";
 import { anthropic } from "@junejs/core/agent-models";
 import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
@@ -237,10 +236,9 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       // instructions live on the def (single source); the runtime injects them
       // into the model per turn via withSystem — no need to bake into anthropic().
       const model = anthropic({ model: def.model });
-      const rt = await createAgentRuntime(
-        { [def.name]: { model, tools: def.tools, instructions: buildSystemPrompt(def) } },
-        { backend },
-      );
+      // toAgentDef: tools, prompt AND the per-surface policies (#149) from the one
+      // definition — channelInstructions was previously dropped on this path (#173).
+      const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend });
       const mounted = mountAgent(def, rt, { chatPath: agent.runtime.chat.path, channels: agent.runtime.channels });
       agentSurface = (req) => mounted.surface(req);
       await mounted.startAll();

package/src/core-version.ts

@@ -15,7 +15,7 @@ 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;
+const EXPECTED_CORE_RUNTIME_API = 2;
 
 export function assertCoreRuntimeVersion(surface: string): void {
   checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);

package/src/turn-events.ts

@@ -0,0 +1,43 @@
+// turn-events.ts — one turn's live TurnEvents as an AsyncIterable, for a consumer in the
+// SAME process as the session: the Durable Object's delivered renders (agent-durable.ts)
+// and the native host's ChannelContext.runStream/resumeStream (agent-native.ts).
+
+import type { AgentSession, TurnEvent } from "@junejs/core/agent-runtime";
+
+// Subscribes eagerly at call time — not at first iteration — so the sseTurnStream timing
+// guarantee carries over (call this synchronously after start()/resume(), before any event
+// can emit); events landing before the consumer catches up are buffered. Ends after the
+// turn's terminal event (completed, failed, cancelled, or input.requested — a park ends
+// this stream; a later resume is a new one), and an early consumer exit (for-await
+// break/return) unsubscribes rather than buffering forever.
+export function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable<TurnEvent> {
+  const queue: TurnEvent[] = [];
+  let terminal = false;
+  let notify: (() => void) | undefined;
+  const unsub = session.observe((e) => {
+    queue.push(e);
+    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
+    notify?.();
+  }, { turnId });
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next(): Promise<IteratorResult<TurnEvent>> {
+          for (;;) {
+            const e = queue.shift();
+            if (e) return { value: e, done: false };
+            if (terminal) { unsub(); return { value: undefined, done: true }; }
+            await new Promise<void>((resolve) => { notify = resolve; });
+            notify = undefined;
+          }
+        },
+        async return(): Promise<IteratorResult<TurnEvent>> {
+          unsub();
+          terminal = true;
+          queue.length = 0;
+          return { value: undefined, done: true };
+        },
+      };
+    },
+  };
+}