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

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();