@junejs/server 1.0.0-dev.13 → 1.0.0-dev.17

package/src/agent-durable.ts

@@ -137,6 +137,28 @@ export class DoSessionStore implements SessionStore {
   tx<T>(fn: () => T): T {
     return this.storage.transactionSync(fn);
   }
+  // Session reset (#129): ARCHIVE messages/steps under the current generation (the audit
+  // trail — never deleted), clear the live tables, status → "new". The session key in
+  // agent_meta is deliberately untouched: the DO's identity survives its history. Archive
+  // tables + the generation counter are created lazily, so existing objects stay
+  // untouched until their first reset. seq keeps counting across generations (DELETE
+  // doesn't reset AUTOINCREMENT), so an archived (generation, seq) stays unique.
+  reset(): number {
+    return this.storage.transactionSync(() => {
+      const sql = this.sql;
+      sql.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (generation INTEGER, seq INTEGER, body TEXT)`);
+      sql.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (generation INTEGER, id TEXT, output TEXT)`);
+      const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'generation'").toArray();
+      const generation = rows.length ? Number(rows[0]!.v) : 0;
+      sql.exec("INSERT INTO agent_messages_archive (generation, seq, body) SELECT ?, seq, body FROM agent_messages", generation);
+      sql.exec("DELETE FROM agent_messages");
+      sql.exec("INSERT INTO agent_steps_archive (generation, id, output) SELECT ?, id, output FROM agent_steps", generation);
+      sql.exec("DELETE FROM agent_steps");
+      this.setStatus("new");
+      sql.exec("INSERT INTO agent_meta (k, v) VALUES ('generation', ?) ON CONFLICT(k) DO UPDATE SET v = ?", String(generation + 1), String(generation + 1));
+      return generation;
+    });
+  }
   unwrap<H = unknown>(): H {
     return this.sql as unknown as H;
   }
@@ -186,7 +208,11 @@ export type DoAgentDef = {
   // channel factories you mount on the worker, plus this DO's env.
   channels?: (Channel | ChannelFactory)[];
   env?: unknown;
-  resources?: Resources;
+  // A resolved bag, OR an env-driven — possibly async — provider
+  // (bindWorkerResources' shape): opening a D1 handle is async and a DO
+  // constructor cannot await, so a provider is resolved lazily at the first
+  // turn (once per DO instance) with this def's `env`.
+  resources?: Resources | ((env: unknown) => Promise<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
@@ -231,15 +257,25 @@ export class AgentDurableObject {
   private readonly tools: Tool[];
   private readonly channels: Channel[];
   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;
+  // A bag is used as-is; a provider (bindWorkerResources' shape) is resolved
+  // lazily at the first turn with the def's env — opening a D1 handle is async
+  // and this constructor cannot await. Resolved once, shared across turns (env
+  // is stable per isolate, like bindWorkerResources memoizes per worker isolate).
+  private readonly resourcesInput: DoAgentDef["resources"];
+  private resourcesOpened: Promise<Resources> | undefined;
+  private readonly doEnv: unknown;
   private readonly services: unknown;
+  private resolveResources(): Promise<Resources> {
+    return (this.resourcesOpened ??= Promise.resolve(
+      typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : (this.resourcesInput ?? {}),
+    ));
+  }
   constructor(state: DurableObjectState, def: DoAgentDef) {
     assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`); // #94: fail power-on, not mid-turn
     const store = new DoSessionStore(state.storage);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-    this.resources = def.resources ?? {};
+    this.resourcesInput = def.resources;
+    this.doEnv = def.env;
     this.services = def.services;
     const name = def.name ?? "agent";
     // Failure observability (#76): a turn that dies after the fast-ACK has no other
@@ -346,8 +382,9 @@ export class AgentDurableObject {
   // pipeline does; without it runInScope is a pass-through and ambient reads throw.
   async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<string> {
     await ensureScope();
+    const resources = await this.resolveResources();
     const session = this.resolveSession(input.session);
-    return runInScope({ resources: this.resources, services: this.services }, () => session.turn(input));
+    return runInScope({ 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
@@ -355,8 +392,14 @@ export class AgentDurableObject {
   // the default turn-failure log / onTurnError (#76).
   async start(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<{ turnId: string }> {
     await ensureScope();
+    const resources = await this.resolveResources();
     const session = this.resolveSession(input.session);
-    return runInScope({ resources: this.resources, services: this.services }, () => session.start(input));
+    return runInScope({ resources, services: this.services }, () => session.start(input));
+  }
+  // Session reset (#129) for custom shells — the direct sibling of the /reset route. No
+  // scope needed: reset touches only the store (no tools run).
+  reset(opts?: { session?: string }): Promise<{ previousSession: string; generation: number }> {
+    return this.resolveSession(opts?.session).reset();
   }
   // 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
@@ -378,6 +421,11 @@ export class AgentDurableObject {
     if (req.method === "POST" && url.pathname.endsWith("/turn")) {
       const { userText, turnId, event, trigger } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger };
       await ensureScope();
+      // CANCEL-AND-REPLACE (#129): supersede every unfinished turn on this session before
+      // queuing this one (debounce). A mode flag like deliver/detach, so it rides the query
+      // string and composes with both. A suspended session still 409s below — replace
+      // never cancels a parked approval.
+      const replace = url.searchParams.get("replace") === "1";
       // DELIVERED: like detach=1, the caller gets a 202 and goes away — but the reply is NOT
       // dropped: this DO renders the turn's event stream through the source channel's own
       // deliver() (the inbound renderer), under the DO's lifetime. Capability is checked
@@ -400,12 +448,14 @@ export class AgentDurableObject {
       }
       // 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.
+      // happens synchronously right after, before any event can emit. Resources resolve
+      // BEFORE this block — the section from start() to the subscription stays synchronous.
+      const resources = await this.resolveResources();
       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 }));
+        started = runInScope({ resources, services: this.services }, () => session.start({ userText, turnId, event, trigger, replace }));
       } 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
@@ -438,7 +488,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: this.resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey })))
+            .then(() => runInScope({ resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey })))
             .catch(logRenderFailure)
             .finally(() => { void it.return?.(); });
         } catch (err) {
@@ -483,10 +533,13 @@ export class AgentDurableObject {
           );
         }
       }
+      // Same discipline as /turn: resolve resources before the synchronous
+      // resume-then-subscribe section.
+      const resources = await this.resolveResources();
       let session: AgentSession;
       try {
         session = this.resolveSession(key);
-        runInScope({ resources: this.resources, services: this.services }, () => session.resume(turnId, inputId, input, { by }));
+        runInScope({ 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
@@ -506,7 +559,7 @@ export class AgentDurableObject {
           const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
           const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
           Promise.resolve()
-            .then(() => runInScope({ resources: this.resources, services: this.services }, () => resumeChannel!.deliverResume!(target!, events, { session: this.sessionKey })))
+            .then(() => runInScope({ resources, services: this.services }, () => resumeChannel!.deliverResume!(target!, events, { session: this.sessionKey })))
             .catch(logRenderFailure)
             .finally(() => { void it.return?.(); });
         } catch (err) {
@@ -516,6 +569,25 @@ export class AgentDurableObject {
       }
       return new Response(sseTurnStream(session, turnId), { headers: SSE_HEADERS });
     }
+    // SESSION RESET (#129): terminally retire this session's history — supersede unfinished
+    // turns, archive messages/steps under the current generation (the audit trail), and
+    // answer with the audit handle. The response waits for in-flight turns to unwind at
+    // their next checkpoint boundary (the reset op runs on the turn chain), which is fine:
+    // a DO stays alive while it has pending work.
+    if (req.method === "POST" && url.pathname.endsWith("/reset")) {
+      let session: AgentSession;
+      try {
+        session = this.resolveSession(key);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      try {
+        return Response.json(await session.reset());
+      } catch (err) {
+        // e.g. a store without reset() — a caller-resolvable refusal, not a crash
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+    }
     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().
@@ -528,7 +600,7 @@ export class AgentDurableObject {
       }
       return Response.json({ transcript: this.transcript() });
     }
-    return new Response("agent DO — POST /turn, POST /resume, or GET /transcript", { status: 404 });
+    return new Response("agent DO — POST /turn, POST /resume, POST /reset, or GET /transcript", { status: 404 });
   }
 }
 
@@ -556,9 +628,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`));
-        // 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(); }
+        // terminal for the STREAM: completed, failed, cancelled, 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 === "turn.cancelled" || e.type === "input.requested") { stop(); controller.close(); }
       }, { turnId });
     },
     cancel() { stop(); },
@@ -578,7 +650,7 @@ function observeTurnEvents(session: AgentSession, turnId: string): AsyncIterable
   let notify: (() => void) | undefined;
   const unsub = session.observe((e) => {
     queue.push(e);
-    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "input.requested") terminal = true;
+    if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") terminal = true;
     notify?.();
   }, { turnId });
   return {
@@ -627,6 +699,7 @@ export async function sseTurnFinalText(res: Response): Promise<string> {
       const e = JSON.parse(line.slice(5).trim()) as TurnEvent;
       if (e.type === "turn.completed") return e.text;
       if (e.type === "turn.failed") throw new Error(e.error.message, { cause: e.error }); // full TurnError rides along
+      if (e.type === "turn.cancelled") throw new Error(`turn ${e.turnId} was cancelled (${e.reason})`);
     }
     if (done) break;
   }
@@ -827,7 +900,7 @@ export function durableChannelSurface(
         namespace,
         opts.agentName,
         o?.session ?? "default",
-        new Request("https://do/turn", { method: "POST", body: serializeTurn(message, o) }),
+        new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
       );
       // /turn streams SSE; the simple path collapses it to the final text.
       return sseTurnFinalText(res);
@@ -843,7 +916,7 @@ export function durableChannelSurface(
         namespace,
         opts.agentName,
         o?.session ?? "default",
-        new Request("https://do/turn?detach=1", { method: "POST", body: serializeTurn(message, o) }),
+        new Request(`https://do/turn?detach=1${o?.replace ? "&replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
       );
       if (res.status !== 202) {
         const detail = (await res.text()).slice(0, 200);
@@ -864,7 +937,7 @@ export function durableChannelSurface(
         namespace,
         opts.agentName,
         o?.session ?? "default",
-        new Request("https://do/turn?deliver=1", { method: "POST", body: serializeTurn(message, o) }),
+        new Request(`https://do/turn?deliver=1${o?.replace ? "&replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
       );
       if (res.status === 501) {
         throw new DeliverUnsupportedError(`runDelivered: ${((await res.json().catch(() => undefined)) as { error?: string } | undefined)?.error ?? "the turn host cannot deliver this turn"}`);
@@ -883,7 +956,7 @@ export function durableChannelSurface(
         namespace,
         opts.agentName,
         o?.session ?? "default",
-        new Request("https://do/turn", { method: "POST", body: serializeTurn(message, o) }),
+        new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
       );
       yield* sseTurnEvents(res);
     },
@@ -924,6 +997,24 @@ export function durableChannelSurface(
       }
       return (await res.json()) as { turnId: string };
     },
+    // SESSION RESET (#129): retire the session's history on its DO. The response carries
+    // the audit handle ({ previousSession, generation }); a 409 (store without reset(),
+    // key mismatch) surfaces as an ordinary error — there is no fallback to invent.
+    resetSession: async (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/reset", { method: "POST" }),
+      );
+      if (!res.ok) {
+        const detail = (await res.text()).slice(0, 200);
+        throw new Error(`resetSession: reset was not accepted (status ${res.status}): ${detail}`);
+      }
+      return (await res.json()) as { previousSession: string; generation: number };
+    },
   };
   return channelDispatch(resolved, ctx);
 }

package/src/agent-native.ts

@@ -79,6 +79,26 @@ class SqliteSessionStore implements SessionStore {
       throw e;
     }
   }
+  // Session reset (#129): ARCHIVE this session's messages/steps under the current
+  // generation (audit trail — never deleted), clear the live rows, status → "new".
+  // Archive tables + the generation counter are created lazily here, so existing
+  // databases stay untouched until the first reset.
+  reset(): number {
+    return this.tx(() => {
+      this.db.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (session_id TEXT, generation INTEGER, seq INTEGER, body TEXT)`);
+      this.db.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (session_id TEXT, generation INTEGER, id TEXT, output TEXT)`);
+      this.db.exec(`CREATE TABLE IF NOT EXISTS agent_session_generations (session_id TEXT PRIMARY KEY, generation INTEGER)`);
+      const r = this.db.query("SELECT generation FROM agent_session_generations WHERE session_id = ?").get(this.sid) as { generation: number } | undefined;
+      const generation = r?.generation ?? 0;
+      this.db.query("INSERT INTO agent_messages_archive (session_id, generation, seq, body) SELECT session_id, ?, seq, body FROM agent_messages WHERE session_id = ?").run(generation, this.sid);
+      this.db.query("DELETE FROM agent_messages WHERE session_id = ?").run(this.sid);
+      this.db.query("INSERT INTO agent_steps_archive (session_id, generation, id, output) SELECT session_id, ?, id, output FROM agent_steps WHERE session_id = ?").run(generation, this.sid);
+      this.db.query("DELETE FROM agent_steps WHERE session_id = ?").run(this.sid);
+      this.db.query("INSERT INTO agent_sessions (session_id, status) VALUES (?, 'new') ON CONFLICT(session_id) DO UPDATE SET status = 'new'").run(this.sid);
+      this.db.query("INSERT INTO agent_session_generations (session_id, generation) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET generation = ?").run(this.sid, generation + 1, generation + 1);
+      return generation;
+    });
+  }
   unwrap<H = unknown>(): H { return this.db as unknown as H; }
 }
 
@@ -139,6 +159,10 @@ class MemorySessionStore implements SessionStore {
   private msgs: Msg[] = [];
   private steps = new Map<string, unknown>();
   private status = "new";
+  private generation = 0;
+  // Retired generations (#129) — kept for the audit contract even in memory, so the
+  // backend behaves like the durable tiers within one process lifetime.
+  private readonly archives: { generation: number; msgs: Msg[]; steps: Map<string, unknown> }[] = [];
   appendMessage(m: Msg) { this.msgs.push(m); }
   messages(): Msg[] { return this.msgs.slice(); }
   hasOpeningMessage(turnId: string): boolean { return this.msgs.some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId); }
@@ -148,6 +172,14 @@ class MemorySessionStore implements SessionStore {
   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
+  reset(): number {
+    const generation = this.generation++;
+    this.archives.push({ generation, msgs: this.msgs, steps: this.steps });
+    this.msgs = [];
+    this.steps = new Map();
+    this.status = "new";
+    return generation;
+  }
   unwrap<H = unknown>(): H { return undefined as unknown as H; }
 }
 
@@ -216,12 +248,16 @@ 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, trigger: o?.trigger }),
+      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
     // 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 }),
+      runtime.session(agent.name, o?.session ?? "default").start({ turnId: o?.turnId, userText: message, event: o?.event, trigger: o?.trigger, replace: o?.replace }),
+    // 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.
+    resetSession: (o) => runtime.session(agent.name, o?.session ?? "default").reset(),
   };
   const channels = channelFetch(agent, ctx);
   const surface = async (req: Request): Promise<Response | null> => {

package/src/build.ts

@@ -32,6 +32,7 @@ import { localeHref } from "@junejs/core/i18n";
 import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
 import { workers, vercel, deno, staticSite, type JuneAdapter, type ResourcePlan } from "./adapter";
 import type { DocumentConfig } from "@junejs/core/document";
+import { generateAgentModule } from "./agent-compile";
 import { generateContentModule } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
 import { findMiddlewareFile } from "./router";
@@ -441,6 +442,20 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     if (typeof mod.default === "function") extra = mod.default as ExtraHandler;
   }
 
+  // The durable agent's DO address (createWorker routes the chat endpoint by
+  // it). Set whenever an agent/ directory exists — the surface is inert without
+  // an env.AGENT binding, so in-process consumers (prerender, the parity test)
+  // are unaffected.
+  let agentName: string | undefined;
+  const agentDir = join(appDir, frozen.agent.runtime.dir);
+  if (frozen.agent.runtime.enabled && existsSync(agentDir)) {
+    const cfgFile = join(agentDir, "agent.ts");
+    const cfg = existsSync(cfgFile)
+      ? ((await import(pathToFileURL(cfgFile).href)).default as { name?: string } | undefined)
+      : undefined;
+    agentName = cfg?.name ?? basename(agentDir);
+  }
+
   return {
     routes,
     dynamicRoutes,
@@ -450,6 +465,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     loadings,
     document: frozen.document,
     agent: frozen.agent,
+    agentName,
     i18n: frozen.i18n,
     earlyHints: frozen.earlyHints,
     extra,
@@ -521,6 +537,52 @@ export async function juneBuild(
     config: fullConfig,
   });
 
+  // ---- durable agent (the F7 mount): compile app/agent → _agent.gen.ts ------
+  // The generated entry mounts the compiled module statically (fs discovery
+  // can't run on workerd) and exports the per-session Durable Object class.
+  // Only a target with Durable Objects can host the session actor — elsewhere
+  // the agent surface is skipped with a notice, and an app without an agent/
+  // directory emits a byte-identical entry (the parity guarantee).
+  const agentDir = join(appDir, frozen.agent.runtime.dir);
+  let agentModule: { file: string } | null = null;
+  if (frozen.agent.runtime.enabled) {
+    const generated = generateAgentModule(agentDir);
+    if (generated && adapter.capabilities.durableObjects) {
+      agentModule = generated;
+    } else if (generated) {
+      console.warn(
+        `[june build] app/${frozen.agent.runtime.dir}/ found, but the ${adapter.name}() target has no Durable Objects — the durable agent is not mounted.`,
+      );
+    }
+  }
+  if (agentModule) {
+    // The generated DO's model is Claude, and workerd has no runtime module
+    // resolution — the SDK must be a real dependency of the app so the entry's
+    // STATIC import bundles it (@junejs/core treats it as an optional peer; the
+    // adapter's own lazy import can never be bundled). Fail the build with the
+    // fix, never ship a worker whose first model turn dies on a bare import.
+    // An explicit node_modules walk, not a resolver API: the check must behave
+    // identically on every host (Bun.resolveSync missed a symlinked scoped
+    // package on Linux CI that it found on macOS), and Rolldown does its own
+    // resolution at bundle time anyway — this is a preflight, not the resolver.
+    const sdkResolvable = (fromDir: string): boolean => {
+      // Absolute first: with a relative root (juneBuild(".")), dirname(".") is
+      // still "." and the walk would stop before reaching a hoisted parent.
+      for (let d = resolve(fromDir); ; ) {
+        if (existsSync(join(d, "node_modules", "@anthropic-ai", "sdk", "package.json"))) return true;
+        const parent = dirname(d);
+        if (parent === d) return false;
+        d = parent;
+      }
+    };
+    if (!sdkResolvable(appRoot)) {
+      throw new Error(
+        `app/${frozen.agent.runtime.dir}/ mounts a durable agent whose model is Claude — ` +
+          `add the SDK to the app so it bundles for workerd: bun add @anthropic-ai/sdk`,
+      );
+    }
+  }
+
   // Compile the global stylesheet ONCE and content-hash it: the built worker and
   // prerendered HTML link `/global.<hash>.css`, served immutable (cache forever,
   // a content change ships a new URL → no revalidation, no stale window). Dev
@@ -691,11 +753,15 @@ export async function juneBuild(
   } else if (hasResources) {
     imports.push(`import { bindWorkerResources } from "@junejs/server/resources";`);
   }
-  const resourcesField = tursoDb
-    ? `\n  resources: memoizeResources({ db: turso() }),`
+  // One expression, TWO instances: the pipeline (createWorker) and the durable
+  // agent's DO each open their own provider — the DO is a separate isolate whose
+  // env must not be captured by the worker-side memoization.
+  const resourcesExpr = tursoDb
+    ? `memoizeResources({ db: turso() })`
     : hasResources
-      ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
-      : "";
+      ? `bindWorkerResources(${JSON.stringify(resourceFlags)})`
+      : null;
+  const resourcesField = resourcesExpr ? `\n  resources: ${resourcesExpr},` : "";
 
   // Opt-in Tier-3 data layer: import its installDataLayer from the declared module
   // and call it at worker boot — the prod twin of the dev host's dataLayer.install()
@@ -723,6 +789,46 @@ export async function juneBuild(
   }
   const servicesField = servicesModule ? `\n  services: __appServices,` : "";
 
+  // Durable agent: import the compiled agent module + the DO shell pieces, set
+  // agentName on the manifest (what activates createWorker's chat routing), and
+  // export the DO class the adapter's wrangler binding names. cloudflare:workers
+  // is a workerd runtime module — external to the bundle (see the predicate below).
+  if (agentModule) {
+    imports.push(`import __agentModule from ${JSON.stringify(importPath(genDir, agentModule.file))};`);
+    imports.push(`import { assembleDurable } from "@junejs/core/agent-config";`);
+    imports.push(`import { anthropic } from "@junejs/core/agent-models";`);
+    imports.push(`import { AgentDurableObject } from "@junejs/server/agent-durable";`);
+    imports.push(`import { DurableObject } from "cloudflare:workers";`);
+    // STATIC so Rolldown bundles the SDK (the adapter's own import is a
+    // non-literal lazy specifier — deliberately unbundleable); injected via
+    // anthropic({ client }), which skips that lazy path entirely.
+    imports.push(`import Anthropic from "@anthropic-ai/sdk";`);
+  }
+  const agentNameField = agentModule ? `\n  agentName: __agentModule.config.name,` : "";
+  const doClass = agentModule
+    ? `
+// The durable agent: one Durable Object per session, the compiled agent/
+// directory as its definition — adapted tools (+ read_skill when skills exist),
+// the assembled system prompt, channel factories resolved with the DO's own
+// env, and the app's declared resources opened from THIS isolate's env (lazily,
+// at the first turn — the same ambient db a tool sees in native dev). Model:
+// Anthropic over a statically bundled client (workerd cannot resolve a bare
+// import at runtime), keyed by the ANTHROPIC_API_KEY secret — a missing secret
+// surfaces as the SDK's own clear construction error on the first agent request.
+const __agentDef = assembleDurable(__agentModule);
+export class JuneAgentDO extends DurableObject {
+  #agent = new AgentDurableObject(this.ctx, {
+    ...__agentDef,
+    model: anthropic({ model: __agentModule.config.model, client: new Anthropic({ apiKey: (this.env as { ANTHROPIC_API_KEY?: string }).ANTHROPIC_API_KEY }) }),
+    env: this.env,${resourcesExpr ? `\n    resources: ${resourcesExpr},` : ""}${servicesModule ? "\n    services: __appServices(this.env)," : ""}
+  });
+  fetch(req: Request): Promise<Response> {
+    return this.#agent.fetch(req);
+  }
+}
+`
+    : "";
+
   const entry = `// AUTO-GENERATED by \`june build\` — do not edit. Regenerate: june build .
 ${adapterEntry.imports.join("\n")}
 ${imports.join("\n")}
@@ -741,12 +847,12 @@ ${chains.join("\n")}
 ${loadings.join("\n")}
   },
   document: ${JSON.stringify(frozen.document, null, 2).replace(/\n/g, "\n  ")},
-  agent: ${JSON.stringify(frozen.agent)},${frozen.i18n ? `\n  i18n: ${JSON.stringify(frozen.i18n)},` : ""}
+  agent: ${JSON.stringify(frozen.agent)},${agentNameField}${frozen.i18n ? `\n  i18n: ${JSON.stringify(frozen.i18n)},` : ""}
   earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}${resourcesField}${servicesField}
 });
 
 ${adapterEntry.wrap("pipeline")}
-`;
+${doClass}`;
   const entryFile = join(genDir, "worker-entry.tsx");
   await writeFile(entryFile, entry);
 
@@ -773,6 +879,8 @@ ${adapterEntry.wrap("pipeline")}
     external: (id: string) => {
       // Bun built-ins exist only at Bun runtime, never in the workerd graph (see isBunSpecifier).
       if (isBunSpecifier(id)) return true;
+      // workerd runtime modules (the durable-agent entry imports cloudflare:workers).
+      if (id.startsWith("cloudflare:")) return true;
       // Binary assets stay external — wrangler's CompiledWasm/Data rules own them.
       if (/\.(wasm|ttf|otf|woff2?|png|jpe?g|avif|webp)$/.test(id)) return true;
       // Merge: adapter.buildExternal (target-specific, e.g. workers-og for the
@@ -960,16 +1068,23 @@ ${adapterEntry.wrap("pipeline")}
   const defaultName = workerName(pkgName ?? basename(appRoot));
   // A declared D1-backed db (sqlite/d1) → a D1 binding named DB (the name
   // bindWorkerResources reads). turso() connects from env, not a binding — no plan.
-  const plan: ResourcePlan =
-    resourcesCfg?.db && resourcesCfg.db.kind !== "turso"
+  const plan: ResourcePlan = {
+    ...(resourcesCfg?.db && resourcesCfg.db.kind !== "turso"
       ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
-      : {};
+      : {}),
+    // The durable agent's DO binding — the name createWorker reads (env.AGENT)
+    // and the class the generated entry exports.
+    ...(agentModule ? { agent: { binding: "AGENT", className: "JuneAgentDO" } } : {}),
+  };
   await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName, publicFiles });
   if (plan.db) {
     console.log(
       `  ↳ d1 binding "${plan.db.binding}" emitted — set database_id in wrangler.jsonc (wrangler d1 create ${plan.db.databaseName})`,
     );
   }
+  if (plan.agent) {
+    console.log(`  ↳ durable agent mounted (${plan.agent.className} → env.${plan.agent.binding}; chat at ${frozen.agent.runtime.chat.path})`);
+  }
 
   return {
     outFile,

package/src/index.ts

@@ -91,6 +91,14 @@ export {
   freezeConfig,
   type BuildResult,
 } from "./build";
+export {
+  generateAgentModule,
+  findAgentDir,
+  scanAgentDir,
+  emitAgentModule,
+  AGENT_MODULE_FILE,
+  type AgentDirScan,
+} from "./agent-compile";
 export { juneDeploy, type DeployResult } from "./deploy";
 export { migrateD1, wranglerD1, resolveD1Database, type D1Exec } from "./d1-migrate";
 export { startDevServer, type DevServer, type DevServerOptions } from "./dev";

package/src/tsconfig-jsx.ts

@@ -9,8 +9,8 @@ import { join } from "node:path";
 // tsconfig.json is JSONC by convention (comments + trailing commas are idiomatic), and a strict
 // JSON.parse failure here silently degrades to "not declared" → the conflict warning reappears.
 // Strip comments (`//` only at line-start/after-whitespace so "https://…" in strings survives)
-// and trailing commas before parsing.
-const stripJsonc = (s: string): string =>
+// and trailing commas before parsing. Shared: agent-compile's tsconfig sniff parses the same way.
+export const stripJsonc = (s: string): string =>
   s
     .replace(/\/\*[\s\S]*?\*\//g, "")
     .replace(/(^|\s)\/\/.*$/gm, "$1")