@junejs/server 1.0.0-dev.42 → 1.0.0-dev.47

package/src/agent-durable.ts

@@ -17,6 +17,7 @@
 
 import {
   AgentSession,
+  FatalToolError,
   grantAnswer,
   ResumeAuthorizationError,
   withSystem,
@@ -39,6 +40,7 @@ import {
 } from "@junejs/core/agent-runtime";
 import type { Principal } from "@junejs/core/context";
 import type { Resources } from "@junejs/core/resources";
+import { blobFileStore, type FileStore } from "@junejs/core/agent-files";
 import { observeTurnEvents } from "./turn-events";
 import {
   channelDispatch,
@@ -255,6 +257,10 @@ export type DoAgentDef = {
   // Receives this session's input announcements (#260) — run inside the request scope, so it
   // can write the app's cross-session index with the ambient db.
   onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+  // Where this session's tools store the files they produce (docs/rfc-agent-files.md), and
+  // where host-side delivery reads them back. Default: the `blob` of `resources` (an R2
+  // bucket), under agent-files/. Without either, a tool's ctx.files.put fails the turn.
+  files?: FileStore;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -300,6 +306,7 @@ export class AgentDurableObject {
   private readonly authorizeAnswer?: AuthorizeAnswer;
   private readonly onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
   private readonly storage: DurableStorage;
+  private readonly files: FileStore;
   // Consecutive failed announcement deliveries (#260) — sets the alarm retry's backoff.
   private announceFailures = 0;
   private resolveResources(): Promise<Resources> {
@@ -347,6 +354,15 @@ export class AgentDurableObject {
     this.onInputAnnouncement = def.onInputAnnouncement;
     this.storage = state.storage;
     const name = def.name ?? "agent";
+    // The blob resource opens with the rest of resources, lazily — the store is installed
+    // on the session before then, and only a tool that stores a file opens it.
+    this.files =
+      def.files ??
+      blobFileStore(async () => {
+        const blob = (await this.resolveResources()).blob;
+        if (!blob) throw new FatalToolError(`agent "${name}": no file store — declare a blob resource (DoAgentDef.resources) or pass DoAgentDef.files`);
+        return blob;
+      });
     // 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
@@ -459,6 +475,7 @@ export class AgentDurableObject {
     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);
+    this.session.files = this.files;
     // A held turn (#263) that asked for delivery is rendered through its source channel when
     // it finally runs — possibly in a later life of this object, which is why the ask rides
     // in the turn's hostContext and this hook is installed on every rebuild.
@@ -537,7 +554,7 @@ export class AgentDurableObject {
       const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
       const target = { channelId: event.channelId, threadId: event.threadId, recipientUserId: event.user?.id, recipientTeamId: event.teamId };
       this.ready()
-        .then((resources) => runInScope({ resources, services: this.services }, () => channel.deliver!(target, events, { session: this.sessionKey })))
+        .then((resources) => runInScope({ resources, services: this.services }, () => channel.deliver!(target, events, { session: this.sessionKey, files: this.files })))
         .catch(logRenderFailure)
         .finally(() => { void it.return?.(); });
     } catch (err) {
@@ -682,7 +699,7 @@ export class AgentDurableObject {
           const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
           const target = { channelId: event!.channelId, threadId: event!.threadId, recipientUserId: event!.user?.id, recipientTeamId: event!.teamId };
           Promise.resolve()
-            .then(() => runInScope({ resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey })))
+            .then(() => runInScope({ resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey, files: this.files })))
             .catch(logRenderFailure)
             .finally(() => { void it.return?.(); });
         } catch (err) {
@@ -770,7 +787,7 @@ export class AgentDurableObject {
           const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
           const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
           Promise.resolve()
-            .then(() => runInScope({ resources, services: this.services }, () => resumeChannel!.deliverResume!(target!, events, { session: this.sessionKey })))
+            .then(() => runInScope({ resources, services: this.services }, () => resumeChannel!.deliverResume!(target!, events, { session: this.sessionKey, files: this.files })))
             .catch(logRenderFailure)
             .finally(() => { void it.return?.(); });
         } catch (err) {
@@ -1079,6 +1096,9 @@ export function durableChannelSurface(
     // agentName must have one provider.
     services?: (env: unknown) => unknown;
     waitUntil?: (p: Promise<unknown>) => void;
+    // Where the channels read the files a turn attached (docs/rfc-agent-files.md) — the
+    // same storage the Durable Object's tools write, opened from this isolate's env.
+    files?: FileStore;
   },
 ): (req: Request) => Promise<Response | null> {
   const resolved = opts.channels.map((c) => resolveChannel(c, opts.env));
@@ -1088,6 +1108,7 @@ export function durableChannelSurface(
     agent: { name: opts.agentName, instructions: "", tools: [], skills: [], channels: [], connections: [] } satisfies AgentDefinition,
     services: resolveServices(opts.services, opts.env, opts.agentName),
     waitUntil: opts.waitUntil,
+    files: opts.files,
     run: async (message, o) => {
       const namespace = getNamespace();
       if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");

package/src/agent-native.ts

@@ -3,9 +3,9 @@
 // SessionStore = a session-scoped view over one shared synchronous SQLite handle
 // (bun:sqlite under Bun, node:sqlite under Node — the same handle openLocalSqlite
 // wraps as the async JuneDb, opened here directly because the durability tx must
-// be synchronous). Broadcaster = an in-process subscriber set. Turn serialization
+// be synchronous). EventSink = an in-process subscriber set. Turn serialization
 // comes from the AgentSession actor in core. On the edge target this same shape
-// is reimplemented over a Durable Object's ctx.storage.sql (build order step 5).
+// is reimplemented over a Durable Object's ctx.storage.sql (agent-durable.ts).
 
 import {
   AgentSession,
@@ -22,6 +22,7 @@ import {
   type Tool,
 } from "@junejs/core/agent-runtime";
 import { buildSystemPrompt, channelFetch, type AgentDefinition, type ChannelContext } from "@junejs/core/agent-config";
+import type { FileStore } from "@junejs/core/agent-files";
 import { openLocalSqliteSync, type SyncSqlite } from "./sqlite-driver";
 import { assertCoreRuntimeVersion } from "./core-version";
 import { observeTurnEvents } from "./turn-events";
@@ -141,6 +142,7 @@ class AnnouncementRetry {
   // Explicit fields (not parameter properties) — keep the shipped source erasable.
   private readonly flush: (agent: string, id: string) => void;
   private readonly state = new Map<string, { failures: number; timer?: ReturnType<typeof setTimeout> }>();
+  private stopped = false;
   constructor(flush: (agent: string, id: string) => void) {
     this.flush = flush;
   }
@@ -150,6 +152,7 @@ class AnnouncementRetry {
     this.state.delete(key);
   }
   failed(key: string, agent: string, id: string) {
+    if (this.stopped) return; // the runtime is closed: nothing retries into it
     const s = this.state.get(key) ?? { failures: 0 };
     this.state.set(key, s);
     if (s.timer) return; // one retry pending at a time
@@ -158,8 +161,20 @@ class AnnouncementRetry {
     s.timer = setTimeout(() => { s.timer = undefined; this.flush(agent, id); }, delay);
     (s.timer as { unref?: () => void }).unref?.();
   }
+  // Cancel every pending retry, for good (#317): unref only keeps a timer from holding the
+  // process open — it still fires while the process lives, into a runtime (and a db) that
+  // is gone.
+  stop() {
+    this.stopped = true;
+    for (const s of this.state.values()) if (s.timer) clearTimeout(s.timer);
+    this.state.clear();
+  }
 }
 
+// SQLite handles a runtime opened itself (createNativeRuntime), so close() closes those and
+// never one a caller passed in.
+const ownedDbs = new WeakSet<SyncSqlite>();
+
 // Install the announcement hook on a freshly built session and deliver what an earlier life
 // of it recorded but never delivered (#260). The flush never rejects; it logs — and a
 // failure schedules a retry.
@@ -207,6 +222,10 @@ export type NativeRuntimeOptions = {
   // 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;
+  // Where the sessions' tools store the files they produce (docs/rfc-agent-files.md), and
+  // where mountAgent's channels read them back to deliver. Absent: ctx.files.put fails the
+  // turn naming the missing configuration.
+  files?: FileStore;
 };
 
 // The native Runtime: a registry of agent definitions over one SQLite handle,
@@ -223,11 +242,14 @@ export class NativeRuntime implements Runtime {
   // Retries failed announcement deliveries (#260), across actor rebuilds.
   private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); });
   private readonly maxSessions: number;
+  private closing: Promise<void> | undefined; // set by close() (#317)
+  readonly files: FileStore | undefined;
 
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts: NativeRuntimeOptions = {}) {
     assertCoreRuntimeVersion("NativeRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
     this.db = db;
+    this.files = opts.files;
     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.
@@ -244,6 +266,9 @@ export class NativeRuntime implements Runtime {
   session(agent: string, id: string): AgentSession {
     const key = `${agent}:${id}`;
     const hit = this.actors.get(key);
+    // A closing runtime still serves the actors it has (their turns are finishing), but
+    // builds no new one.
+    if (!hit && this.closing) throw new Error(`NativeRuntime is closed: cannot open session "${key}"`);
     if (hit) {
       // most recently used → the tail (Map iteration order is insertion order)
       this.actors.delete(key);
@@ -254,7 +279,9 @@ export class NativeRuntime implements Runtime {
     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 = wireAnnouncements(new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+    const built = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+    built.files = this.files;
+    const session = wireAnnouncements(built, def, this.announceRetry);
     this.evictIdle();
     this.actors.set(key, { session, sink });
     return session;
@@ -276,6 +303,29 @@ export class NativeRuntime implements Runtime {
     }
   }
 
+  // Shut the runtime down (#317). Pending announcement retries are cancelled and no new
+  // session opens at once; then it waits until every actor is idle — a running turn or an
+  // announcement delivery in flight still writes the store after its hook or model call
+  // returns — before dropping the actors and closing the SQLite handle createNativeRuntime
+  // opened (a db passed to the constructor stays the caller's). So it resolves only after
+  // in-flight work finishes. Call it before discarding a runtime in a process that keeps
+  // running (a test suite, a host that swaps runtimes), or a retry fires later against a
+  // closed or deleted database. Safe to call twice: both calls resolve together.
+  close(): Promise<void> {
+    this.closing ??= (async () => {
+      this.announceRetry.stop();
+      while ([...this.actors.values()].some((a) => !a.session.idle())) {
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      this.actors.clear();
+      if (ownedDbs.has(this.db)) {
+        ownedDbs.delete(this.db);
+        this.db.close();
+      }
+    })();
+    return this.closing;
+  }
+
   // 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() {
@@ -295,9 +345,24 @@ export async function createNativeRuntime(
   path = ":memory:",
   opts: NativeRuntimeOptions = {},
 ): Promise<NativeRuntime> {
-  const runtime = new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
-  runtime.recoverAnnouncements(); // #260
-  return runtime;
+  const db = await openLocalSqliteSync(path);
+  ownedDbs.add(db);
+  let runtime: NativeRuntime | undefined;
+  try {
+    runtime = new NativeRuntime(agents, db, opts);
+    runtime.recoverAnnouncements(); // #260
+    return runtime;
+  } catch (err) {
+    // Nobody else holds this handle (a bad maxSessions, unreadable leftovers). A recovery
+    // that failed part-way may already have deliveries in flight, so go through close(),
+    // which waits for them before closing the db.
+    if (runtime) await runtime.close();
+    else {
+      ownedDbs.delete(db);
+      db.close();
+    }
+    throw err;
+  }
 }
 
 // ── memory backend — in-process, ephemeral (no DB, no disk) ───────────────────
@@ -340,26 +405,42 @@ export class MemoryRuntime implements Runtime {
   private stores = new Map<string, MemorySessionStore>();
   private readonly agents: Record<string, AgentDef>;
   private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); }); // #260
-  constructor(agents: Record<string, AgentDef>) {
+  private closed = false; // set by close() (#317)
+  readonly files: FileStore | undefined;
+  constructor(agents: Record<string, AgentDef>, opts: { files?: FileStore } = {}) {
     assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
+    this.files = opts.files;
   }
   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) {
+      if (this.closed) throw new Error(`MemoryRuntime is closed: cannot open session "${key}"`);
       const def = this.agents[agent];
       if (!def) throw new Error(`unknown agent: ${agent}`);
       const store = new MemorySessionStore();
       this.stores.set(key, store);
       // Same def handling as NativeRuntime: switching backend must not change behavior.
       const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = wireAnnouncements(new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions), def, this.announceRetry);
+      const built = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
+      built.files = this.files;
+      a = wireAnnouncements(built, def, this.announceRetry);
       this.actors.set(key, a);
     }
     return a;
   }
+  // Shut the runtime down (#317): cancel pending announcement retries and open no new
+  // session. The state is the actors themselves, so they are dropped too; with no store
+  // to close there is nothing to wait for — work still in flight finishes against its own
+  // in-memory store. Safe to call twice.
+  async close(): Promise<void> {
+    this.closed = true;
+    this.announceRetry.stop();
+    this.actors.clear();
+    this.stores.clear();
+  }
 }
 
 // The selectable agent-runtime backends. `native` (SQLite via june/host, durable
@@ -371,13 +452,16 @@ export type AgentBackend = "native" | "memory" | "durable";
 // Build an in-process runtime for the chosen backend. Throws for `durable` (that
 // target is the DO the worker constructs, not an in-process object) — so the
 // choice is explicit and a mis-selection fails loudly.
+// An in-process runtime: a Runtime the host owns, so it can shut it down (#317).
+export type InProcessRuntime = Runtime & { close(): Promise<void>; readonly files?: FileStore };
+
 export async function createAgentRuntime(
   agents: Record<string, AgentDef>,
-  opts: { backend?: AgentBackend; path?: string; maxSessions?: number } = {},
-): Promise<Runtime> {
+  opts: { backend?: AgentBackend; path?: string; maxSessions?: number; files?: FileStore } = {},
+): Promise<InProcessRuntime> {
   const backend = opts.backend ?? "native";
-  if (backend === "memory") return new MemoryRuntime(agents);
-  if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });
+  if (backend === "memory") return new MemoryRuntime(agents, { files: opts.files });
+  if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions, files: opts.files });
   throw new Error("backend 'durable' is the Cloudflare Durable Object target — construct AgentDurableObject in your worker, not via createAgentRuntime");
 }
 
@@ -414,7 +498,7 @@ function warnOnDrift(agent: AgentDefinition, runtime: Runtime) {
 export function mountAgent(
   agent: AgentDefinition,
   runtime: Runtime,
-  opts: { chatPath?: string; channels?: boolean; services?: unknown } = {},
+  opts: { chatPath?: string; channels?: boolean; services?: unknown; files?: FileStore } = {},
 ): {
   surface: (req: Request) => Promise<Response | null>;
   fetch: (req: Request) => Promise<Response | null>;
@@ -427,6 +511,8 @@ export function mountAgent(
   const ctx: ChannelContext = {
     agent,
     services: opts.services, // same DI bag reachable from channel hooks (parity with durableChannelSurface)
+    // The runtime's file store, so a channel can deliver the files the turn's tools stored.
+    files: opts.files ?? (runtime as { files?: FileStore }).files,
     run: (message, o) =>
       runtime.session(agent.name, o?.session ?? "default").turn({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger, replace: o?.replace }),
     // FIRE-AND-FORGET (#77): start() without awaiting the result. Native has no waitUntil

package/src/app.ts

@@ -25,14 +25,18 @@ import {
 } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
+import { blobFileStore, memoryFileStore } from "@junejs/core/agent-files";
+import type { JuneBlob } from "@junejs/core/resources";
 
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
+import { routeProblems, scanRoutes } from "./route-scan";
 import { createPipeline, type ExtraHandler, type LayoutComponent, type MiddlewareHandler, type Pipeline, type Resolved, type ResourceHandler } from "./pipeline";
 import { discoverAgent } from "./agent-discover";
-import { createAgentRuntime, mountAgent, toAgentDef } from "./agent-native";
+import { createAgentRuntime, mountAgent, toAgentDef, type InProcessRuntime } from "./agent-native";
 import { anthropic } from "@junejs/core/agent-models";
 import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
+import { localBlob } from "./blob";
 import {
   findClientEntry,
   bundleClientSplit,
@@ -65,6 +69,10 @@ export type JuneApp = {
   warmup(): Promise<void>;
   routePaths(): Promise<string[]>;
   earlyHints(): string[];
+  // Shut down what the app started (#317): the agent runtime built for an agent/
+  // directory — its pending announcement retries, its in-flight turns, its SQLite
+  // handle. Resolves once they finish. A no-op when no runtime was built.
+  close(): Promise<void>;
 };
 
 // Import a layout file's default export as a layout component (memoized), plus
@@ -226,6 +234,8 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
   // pipeline is built lazily on first fetch, memoized after.
   let pipelinePromise: Promise<Pipeline> | undefined;
   const getPipeline = (): Promise<Pipeline> => (pipelinePromise ??= buildPipeline());
+  // The agent runtime buildPipeline creates, kept so close() can shut it down (#317).
+  let agentRuntime: InProcessRuntime | undefined;
   async function buildPipeline(): Promise<Pipeline> {
     // Wire CSS Modules BEFORE any route import: the runtime interceptor must be
     // active so `import "x.module.css"` in a route resolves to the scoped map,
@@ -263,7 +273,16 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       const model = anthropic({ model: def.model });
       // 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 });
+      // Agent files (docs/rfc-agent-files.md) live in the app's blob resource; an app that
+      // declares none gets the local default directory. The memory backend keeps them in
+      // memory, like everything else it holds.
+      let blobOpened: Promise<JuneBlob> | undefined;
+      const files =
+        backend === "memory"
+          ? memoryFileStore()
+          : blobFileStore(() => (blobOpened ??= resources().then(async (r) => r.blob ?? (await localBlob().open()))));
+      const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend, files });
+      agentRuntime = rt;
       const mounted = mountAgent(def, rt, { chatPath: agent.runtime.chat.path, channels: agent.runtime.channels });
       agentSurface = (req) => mounted.surface(req);
       await mounted.startAll();
@@ -443,6 +462,13 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       return toPipeline();
     },
     async warmup() {
+      // What `june build` refuses (same-path files, a segment after an optional
+      // or catch-all), dev reports up front — it still serves what it can.
+      const problems = routeProblems(
+        [await scanRoutes(appDir), hasJuneRoutes ? await scanRoutes(juneRoutesDir) : []],
+        dirname(appDir),
+      );
+      if (problems) console.error(problems);
       const files = await routeFiles(appDir, { pageConvention: true });
       if (hasJuneRoutes) files.push(...(await routeFiles(juneRoutesDir, { pageConvention: true })));
       for (const file of files) {
@@ -453,5 +479,11 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
     },
     routePaths,
     earlyHints: () => config.earlyHints ?? [],
+    async close() {
+      // A pipeline still being built may be about to create the runtime: let it finish
+      // (its failure is the fetch's to report, not close()'s).
+      await pipelinePromise?.catch(() => {});
+      await agentRuntime?.close();
+    },
   };
 }

package/src/build.ts

@@ -300,6 +300,12 @@ export async function juneBuild(
   const resourceRoutesField = resources.length
     ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],`
     : "";
+  // .june/routes/ patterns rank after every app/ route (dev falls back to them).
+  // Only emitted when there are some, so bundles without them stay byte-identical.
+  const generatedPaths = routes.filter((r) => r.generated).map((r) => r.path);
+  const generatedRoutesField = generatedPaths.length
+    ? `\n  generatedRoutes: ${JSON.stringify(generatedPaths)},`
+    : "";
   // Only emitted when some route declares a boundary, so boundary-less bundles
   // stay byte-identical (additive manifest field, like resources).
   const layoutBoundariesField = boundaries.length
@@ -435,7 +441,7 @@ ${statics.join("\n")}
   },
   dynamicRoutes: [
 ${dynamics.join("\n")}
-  ],${resourceRoutesField}
+  ],${resourceRoutesField}${generatedRoutesField}
   layoutChains: {
 ${chains.join("\n")}
   },${layoutBoundariesField}

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

package/src/dev.ts

@@ -19,20 +19,41 @@ import { findGlobalCss, processCssCached, invalidateCss } from "./css";
 export type DevServerOptions = {
   appDir: string;
   port?: number;
+  // The address to bind. Default 127.0.0.1: the dev server is reachable from this
+  // machine only (MCP: "when running locally, servers SHOULD bind only to
+  // localhost"). "0.0.0.0" opens it to the LAN — `june dev --host`.
+  hostname?: string;
   host?: JuneHost;
 };
 
-export type DevServer = ServeHandle & { url: string };
+// The Host names a dev server answers /mcp and /api for (#308): localhost and its
+// subdomains, plus IP literals (always allowed — rebinding needs a domain name),
+// plus a named --host and whatever the config allows.
+// The URL to print and return: localhost for loopback or a wildcard bind (it
+// answers there too), else the one address bound — nothing listens on loopback then.
+export function devUrl(hostname: string, port: number): string {
+  if (["127.0.0.1", "0.0.0.0", "::", "localhost"].includes(hostname)) return `http://localhost:${port}`;
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`;
+}
+
+export function devAllowedHosts(configured: readonly string[] | undefined, hostname: string): string[] {
+  const hosts = new Set(["localhost", ".localhost", ...(configured ?? [])]);
+  if (!/^[\d.]+$|:/.test(hostname)) hosts.add(hostname.toLowerCase()); // a name, not 0.0.0.0 / an IP
+  return [...hosts];
+}
+
+// stop() also shuts the app down (its agent runtime, #317); await it to know that's done.
+export type DevServer = Omit<ServeHandle, "stop"> & { url: string; stop(force?: boolean): Promise<void> };
 
 // A taken default port must not be a dead end in dev — walk forward until a
 // port binds (the Vite convention). Probed with node:net, which both hosts
 // implement, so the host interface stays untouched.
-async function findFreePort(start: number, tries = 20): Promise<number> {
+async function findFreePort(start: number, hostname: string, tries = 20): Promise<number> {
   for (let p = start; p < start + tries; p++) {
     const free = await new Promise<boolean>((resolve) => {
       const probe = createNetServer();
       probe.once("error", () => resolve(false));
-      probe.listen(p, () => probe.close(() => resolve(true)));
+      probe.listen(p, hostname, () => probe.close(() => resolve(true)));
     });
     if (free) return p;
   }
@@ -42,10 +63,13 @@ async function findFreePort(start: number, tries = 20): Promise<number> {
 export async function startDevServer({
   appDir,
   port = 3000,
+  hostname = "127.0.0.1",
   host = defaultHost,
 }: DevServerOptions): Promise<DevServer> {
   await installAsyncContext();
-  const config = await loadJuneConfig(appDir);
+  const loaded = await loadJuneConfig(appDir);
+  // The DNS-rebinding check (#308): a local server is exactly what rebinding targets.
+  const config = { ...loaded, agent: { ...loaded.agent, allowedHosts: devAllowedHosts(loaded.agent?.allowedHosts, hostname) } };
 
   // Apply pending migrations before serving — dev auto-applies the SAFE ones; a
   // destructive one is reported and skipped (the server still starts, but the
@@ -57,7 +81,7 @@ export async function startDevServer({
   const app = createApp({ appDir, config });
   await app.warmup();
 
-  const freePort = await findFreePort(port);
+  const freePort = await findFreePort(port, hostname);
   if (freePort !== port) console.log(`[june] port ${port} is taken → using ${freePort}`);
   port = freePort;
 
@@ -65,6 +89,7 @@ export async function startDevServer({
   // dev/built parity) never sees it. See dev-reload.ts.
   const handle = host.serve(withLiveReload((req) => app.fetch(req)), {
     port,
+    hostname,
     earlyHints: () => app.earlyHints(),
   });
 
@@ -87,7 +112,15 @@ export async function startDevServer({
     void processCssCached(appDir).catch(() => {});
   }
 
-  const url = `http://localhost:${handle.port}`;
-  console.log(`june dev → ${url}  (host: ${host.name})`);
-  return { ...handle, url };
+  const url = devUrl(hostname, handle.port);
+  const lan = hostname === "127.0.0.1" ? "" : `  · listening on ${hostname}`;
+  console.log(`june dev → ${url}  (host: ${host.name})${lan}`);
+  return {
+    ...handle,
+    url,
+    async stop(force?: boolean) {
+      handle.stop(force);
+      await app.close();
+    },
+  };
 }

package/src/host.ts

@@ -42,7 +42,8 @@ export interface JuneHost {
   readonly name: "bun" | "node";
   serve(
     handler: (req: Request) => Promise<Response>,
-    opts: { port: number; earlyHints?: () => string[] },
+    // hostname: the address to bind. Absent = all interfaces (production, containers).
+    opts: { port: number; hostname?: string; earlyHints?: () => string[] },
   ): ServeHandle;
   // Spawn a module in a child runtime (the react-server Flight renderer, which
   // must run under a different module-resolution condition). Phase 4 supersedes
@@ -63,7 +64,7 @@ function bunHost(): JuneHost {
       // idleTimeout 0: Bun's 10s default kills quiet long-lived responses —
       // the dev live-reload SSE most visibly (the browser then reconnects,
       // reads it as a server restart, and reloads the page every 10s).
-      const server = Bun.serve({ port: opts.port, fetch: handler, idleTimeout: 0 });
+      const server = Bun.serve({ port: opts.port, hostname: opts.hostname, fetch: handler, idleTimeout: 0 });
       return { port: server.port ?? opts.port, stop: (force) => void server.stop(force) };
     },
     spawnModule(entry, args, opts) {
@@ -125,7 +126,7 @@ function nodeHost(): JuneHost {
           res.end("Internal Server Error");
         }
       });
-      server.listen(opts.port);
+      server.listen(opts.port, opts.hostname);
       return {
         get port() {
           const addr = server.address();

package/src/manifest.ts

@@ -63,6 +63,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const routes: Record<string, BrandedRoute> = {};
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
   const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
+  const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
   const layoutChains: Record<string, LayoutComponent[]> = {};
   const layoutBoundaries: Record<string, { index: number; key: string }> = {};
   const loadings: Record<string, LoadingComponent> = {};
@@ -115,6 +116,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     routes,
     dynamicRoutes,
     resourceRoutes,
+    ...(generatedRoutes.length ? { generatedRoutes } : {}),
     layoutChains,
     layoutBoundaries,
     loadings,

package/src/pipeline.ts

@@ -48,9 +48,10 @@ import {
   siteSkill,
   sitemapXml,
 } from "@junejs/core/discovery";
-import { mcpHandler, mcpServerIdentity, mcpTools } from "@junejs/core/mcp";
+import { mcpForbidden, mcpHandler, mcpServerIdentity, mcpTools, originRejection } from "@junejs/core/mcp";
 import {
   apiActionId,
+  apiForbidden,
   apiHandler,
   apiNamespaceResponse,
   isApiNamespace,
@@ -854,6 +855,14 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     }
   }
 
+  // Which browsers may call /mcp and /api (#308) — the config's allowlists.
+  const originPolicy = { allowedOrigins: agent.allowedOrigins, allowedHosts: agent.allowedHosts };
+  // Only a POST runs an action on /mcp or /api; any other method is a CORS
+  // preflight or a 405. A preflight carries no credentials, so a cookie-reading
+  // resolver could throw on it — never resolve identity for one.
+  const callerIdentity = async (request: Request) =>
+    request.method === "POST" && cfg.identity ? await cfg.identity(request) : undefined;
+
   async function handleRequest(request: Request): Promise<Response> {
       const url = new URL(request.url);
 
@@ -864,11 +873,16 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         // ambient `db` is the SAME resource the UI uses, and — via cfg.identity —
         // the same principal: requiresPrincipal actions and per-call connection
         // auth are live on this surface. ctx carries identity only — not resources.
-        const identity = cfg.identity ? await cfg.identity(request) : undefined;
+        // The origin policy first: a refused browser call must not reach the
+        // identity resolver (its I/O, or a throw that would turn 403 into 500).
+        const refused = originRejection(request, originPolicy);
+        if (refused !== undefined) return mcpForbidden(refused);
+        const identity = await callerIdentity(request);
         return mcpHandler(
           request,
           { request, ...identity },
           mcpServerIdentity(url.origin, { site: docConfig.site, agent }),
+          originPolicy,
         );
       }
       // The REST projection of the same actions: POST /api/<id> dispatches through
@@ -887,8 +901,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         }
         const actionId = apiActionId(url.pathname);
         if (actionId) {
-          const identity = cfg.identity ? await cfg.identity(request) : undefined;
-          return apiHandler(request, actionId, { request, ...identity });
+          const refused = originRejection(request, originPolicy);
+          if (refused !== undefined) return apiForbidden(request, refused);
+          const identity = await callerIdentity(request);
+          return apiHandler(request, actionId, { request, ...identity }, originPolicy);
         }
       }
       // The server card is read cross-origin by browser-based MCP clients; its