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

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,10 +789,52 @@ 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";`);
+  }
+  // Assembled BEFORE createWorker: the manifest consumes the channels (worker-
+  // side webhook routing) and the DO class consumes the full definition.
+  const agentPreamble = agentModule ? `\nconst __agentDef = assembleDurable(__agentModule);\n` : "";
+  const agentNameField = agentModule ? `\n  agentName: __agentModule.config.name,\n  agentChannels: __agentDef.channels,` : "";
+  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.
+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")}
-${dataLayerBoot}
+${dataLayerBoot}${agentPreamble}
 const pipeline = createWorker({
   routes: {
 ${statics.join("\n")}
@@ -741,12 +849,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 +881,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 +1070,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")

package/src/worker.ts

@@ -17,10 +17,19 @@ import type { DocumentConfig } from "@junejs/core/document";
 import type { I18nConfig } from "@junejs/core/i18n";
 import type { Resources } from "@junejs/core/resources";
 
+import type { Channel, ChannelFactory } from "@junejs/core/agent-config";
+
 import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved, type ResolvedResource, type ResourceHandler } from "./pipeline";
-import { durableAgentSurface, type DurableObjectNamespace } from "./agent-durable";
+import { durableAgentSurface, durableChannelSurface, type DurableObjectNamespace } from "./agent-durable";
 import { contentTypeFor, RESERVED_PREFIX, safeRelativePath } from "./static-files";
 
+// The slice of workerd's ExecutionContext the worker threads through: webhook
+// channels ACK fast and finish their work (post the reply out-of-band) on
+// waitUntil — without it a floating promise can be killed when the isolate is
+// reclaimed. Optional end to end; a host without it (tests, other targets)
+// simply doesn't extend the invocation.
+export type WorkerExecutionContext = { waitUntil?(p: Promise<unknown>): void };
+
 export type WorkerManifest = {
   // Static paths → route definitions ("/", "/users", ...).
   routes: Record<string, BrandedRoute>;
@@ -45,6 +54,13 @@ export type WorkerManifest = {
   // by the build when an agent/ directory exists; absent → no durable agent on
   // the edge. The DO namespace binding is `env.AGENT`.
   agentName?: string;
+  // The agent's channels (Channel or `(env) => Channel` factories, from the
+  // compiled agent module) — mounted as webhook routes on the worker via
+  // durableChannelSurface when agent.runtime.channels is on. The SAME factories
+  // are also wired into the DO (DoAgentDef.channels) by the generated entry, so
+  // capability tools and host-side delivery work; this field is the WORKER half
+  // (verify the webhook, run the turn on the DO, reply on waitUntil).
+  agentChannels?: (Channel | ChannelFactory)[];
   // Locale routing config, frozen from june.config.ts `i18n`. The locales table
   // is plain data; a `resolveLocale` hook survives the in-process freeze (parity
   // test) but not JSON codegen — worker hook support lands with the codegen pass.
@@ -111,7 +127,7 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
 
 export function createWorker(
   manifest: WorkerManifest,
-): { fetch(request: Request, env?: unknown): Promise<Response> } {
+): { fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response> } {
   const dynamic: Compiled[] = (manifest.dynamicRoutes ?? []).map((d) => ({
     ...compilePattern(d.pattern),
     def: d.def,
@@ -134,8 +150,14 @@ export function createWorker(
 
   // The worker's env (D1/KV/R2 bindings) arrives per fetch and is stable across
   // requests in an isolate; we capture the latest and hand it to the env-aware
-  // provider, which memoizes the opened handles on first call.
+  // provider, which memoizes the opened handles on first call. That "latest"
+  // pattern is safe ONLY for per-isolate-stable values — concurrent fetches
+  // interleave at await points, so anything per-INVOCATION (the execution
+  // context, and env used at a specific moment) must come from request-scoped
+  // storage instead: `requestLocals`, keyed by the Request identity that flows
+  // unchanged from fetch() through the pipeline to the agent surface.
   let currentEnv: unknown;
+  const requestLocals = new WeakMap<Request, { env: unknown; ctx?: WorkerExecutionContext }>();
   const provider = manifest.resources;
 
   // App services: the build sets a raw `(env) => services` factory here; memoize it per
@@ -144,18 +166,43 @@ export function createWorker(
   const servicesProvider = manifest.services;
   let servicesCache: { v: unknown } | undefined;
 
-  // Durable agent (edge): route the chat endpoint to the per-session DO bound at
-  // env.AGENT. Built only when the app has an agent (manifest.agentName) and the
-  // runtime is enabled; the surface is inert (null → fall through) until env.AGENT
-  // is present, so a worker without the DO binding is unaffected.
+  // Durable agent (edge): route the chat endpoint — and the agent's channel
+  // webhooks — to the per-session DO bound at env.AGENT. Built only when the app
+  // has an agent (manifest.agentName) and the runtime is enabled; the surface is
+  // inert (null → fall through) until env.AGENT is present, so a worker without
+  // the DO binding is unaffected.
   const agentSurface =
     manifest.agent.runtime.enabled && manifest.agentName
       ? (() => {
-          const route = durableAgentSurface(
-            () => (currentEnv as { AGENT?: DurableObjectNamespace } | undefined)?.AGENT,
-            { agentName: manifest.agentName, chatPath: manifest.agent.runtime.chat.path },
-          );
-          return (req: Request) => route(req);
+          const agentName = manifest.agentName;
+          const wantChannels = manifest.agent.runtime.channels !== false && (manifest.agentChannels?.length ?? 0) > 0;
+          return async (req: Request): Promise<Response | null> => {
+            // REQUEST-scoped, not isolate-scoped: the pipeline awaits between
+            // fetch() and this call, so a concurrent fetch may have run since —
+            // a module-level "current request" variable here would hand this
+            // webhook ANOTHER request's env (wrong AGENT namespace, factories
+            // resolved against foreign secrets) and register its background
+            // work on another invocation's waitUntil. Everything below reads
+            // THIS request's locals.
+            const locals = requestLocals.get(req);
+            const ns = () => (locals?.env as { AGENT?: DurableObjectNamespace } | undefined)?.AGENT;
+            const chat = durableAgentSurface(ns, { agentName, chatPath: manifest.agent.runtime.chat.path });
+            const chatRes = await chat(req);
+            if (chatRes) return chatRes;
+            if (!wantChannels) return null;
+            // Constructed per request — cheap by design: resolveChannel is a
+            // call, and resolveServices memoizes the app services bag per
+            // (env, agentName), exactly for this construction pattern (see
+            // durableChannelSurface's services doc).
+            const channels = durableChannelSurface(ns, {
+              agentName,
+              channels: manifest.agentChannels!,
+              env: locals?.env,
+              services: servicesProvider,
+              waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx),
+            });
+            return channels(req);
+          };
         })()
       : undefined;
 
@@ -224,8 +271,9 @@ export function createWorker(
   });
 
   return {
-    fetch(request, env) {
-      currentEnv = env;
+    fetch(request, env, ctx) {
+      currentEnv = env; // per-isolate-stable consumers only (resources/services)
+      requestLocals.set(request, { env, ctx }); // per-invocation consumers (agent surface)
       return pipeline.fetch(request);
     },
   };
@@ -241,16 +289,16 @@ export function createWorker(
 // dynamic routes reach the pipeline. With no ASSETS binding (no prerender), this
 // is a transparent pass-through to the pipeline.
 type AssetEnv = { ASSETS?: { fetch(request: Request): Promise<Response> } };
-type FetchPipeline = { fetch(request: Request, env?: unknown): Promise<Response> };
+type FetchPipeline = { fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response> };
 
 const estimateTokens = (s: string) => String(Math.ceil(s.length / 4));
 
 export function withAssets(
   pipeline: FetchPipeline,
   opts: { link?: string | null } = {},
-): { fetch(request: Request, env?: AssetEnv): Promise<Response> } {
+): { fetch(request: Request, env?: AssetEnv, ctx?: WorkerExecutionContext): Promise<Response> } {
   return {
-    async fetch(request, env) {
+    async fetch(request, env, ctx) {
       const assets = env?.ASSETS;
       const url = new URL(request.url);
       const isPagePath = !/\.[a-z0-9]+$/i.test(url.pathname); // no file extension
@@ -296,7 +344,7 @@ export function withAssets(
 
       // 3. Dynamic routes → the render pipeline (already sets Link + negotiates).
       // Env flows through so the pipeline's resources get the D1/KV/R2 bindings.
-      return pipeline.fetch(request, env);
+      return pipeline.fetch(request, env, ctx);
     },
   };
 }