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

package/dist/client-bundle.js

@@ -1,5 +1,5 @@
-import { rolldownCssModulesPlugin } from "./css-modules.js";
 import { jsxTransform } from "./tsconfig-jsx.js";
+import { rolldownCssModulesPlugin } from "./css-modules.js";
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AdapterCapabilities, AdapterEmitContext, AdapterEntry, JuneAdapter, ResourcePlan, deno, staticSite, vercel, workers } from "./adapter.js";
+import { AGENT_MODULE_FILE, AgentDirScan, emitAgentModule, findAgentDir, generateAgentModule, scanAgentDir } from "./agent-compile.js";
 import { CreateAppOptions, JuneApp, createApp } from "./app.js";
 import { R2Bucket, localBlob, r2 } from "./blob.js";
 import { a as Pipeline, d as createPipeline, n as LayoutComponent, o as PipelineConfig, s as Resolved, u as RouteResolver } from "./pipeline-cCR6MGNK.js";
@@ -24,4 +25,4 @@ import { Negotiated, negotiate } from "./negotiate.js";
 import { blob, currentServices, db, kv } from "@junejs/db";
 import { ServicesConfig, defineServices } from "@junejs/core/config";
 import { I18nConfig, LOCALE_COOKIE, LocaleConfig, LocaleMatch, dirForLang, localeDir, localeHref, matchPinnedLocale, negotiateLocale, parseAcceptLanguage, resolveRequestLocale } from "@junejs/core/i18n";
-export { type AdapterCapabilities, type AdapterEmitContext, type AdapterEntry, type BuildResult, type ContentEntry, type CreateAppOptions, type D1Database, type D1Exec, type DeployResult, type DevServer, type DevServerOptions, type I18nConfig, type JuneAdapter, type JuneApp, type JuneDb, type JuneHost, LOCALE_COOKIE, type LayoutComponent, type LocaleConfig, type LocaleMatch, type MatchOptions, type MigrateResult, type Migration, type Negotiated, type Pipeline, type PipelineConfig, type R2Bucket, type Resolved, type ResourceFlags, type ResourcePlan, type RouteMatch, type RouteResolver, type RouteTreeMatch, type RunResult, type SegmentMatch, type ServeHandle, type ServicesConfig, type SpawnedModule, type WorkerEnv, type WorkerManifest, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, defineServices, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };
+export { AGENT_MODULE_FILE, type AdapterCapabilities, type AdapterEmitContext, type AdapterEntry, type AgentDirScan, type BuildResult, type ContentEntry, type CreateAppOptions, type D1Database, type D1Exec, type DeployResult, type DevServer, type DevServerOptions, type I18nConfig, type JuneAdapter, type JuneApp, type JuneDb, type JuneHost, LOCALE_COOKIE, type LayoutComponent, type LocaleConfig, type LocaleMatch, type MatchOptions, type MigrateResult, type Migration, type Negotiated, type Pipeline, type PipelineConfig, type R2Bucket, type Resolved, type ResourceFlags, type ResourcePlan, type RouteMatch, type RouteResolver, type RouteTreeMatch, type RunResult, type SegmentMatch, type ServeHandle, type ServicesConfig, type SpawnedModule, type WorkerEnv, type WorkerManifest, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, defineServices, deno, dirForLang, emitAgentModule, entry, findAgentDir, freezeConfig, generateAgentModule, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanAgentDir, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { deno, staticSite, vercel, workers } from "./adapter.js";
+import { AGENT_MODULE_FILE, emitAgentModule, findAgentDir, generateAgentModule, scanAgentDir } from "./agent-compile.js";
 import { listRoutes, matchRoute, matchRouteTree, resolveNotFound } from "./router.js";
 import { negotiate } from "./negotiate.js";
 import { createPipeline } from "./pipeline.js";
@@ -24,4 +25,4 @@ import { memoryKv, redisKv } from "./kv.js";
 import { blob, currentServices, db, kv } from "@junejs/db";
 import { defineServices } from "@junejs/core/config";
 import { LOCALE_COOKIE, dirForLang, localeDir, localeHref, matchPinnedLocale, negotiateLocale, parseAcceptLanguage, resolveRequestLocale } from "@junejs/core/i18n";
-export { LOCALE_COOKIE, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, defineServices, deno, dirForLang, entry, freezeConfig, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };
+export { AGENT_MODULE_FILE, LOCALE_COOKIE, bindWorkerResources, blob, blockedMessage, buildManifest, classify, collection, createApp, createPipeline, createWorker, currentServices, d1, db, defineServices, deno, dirForLang, emitAgentModule, entry, findAgentDir, freezeConfig, generateAgentModule, generateContent, host, installAsyncContext, juneBuild, juneDeploy, kv, listRoutes, loadJuneConfig, localBlob, localeDir, localeHref, matchPinnedLocale, matchRoute, matchRouteTree, memoizeResources, memoryKv, migrate, migrateApp, migrateD1, mysql, negotiate, negotiateLocale, parseAcceptLanguage, postgres, r2, readMigrations, redisKv, resolveD1Database, resolveNotFound, resolveRequestLocale, scanAgentDir, scanRoutes, sqlite, startDevServer, staticSite, turso, typesApp, vercel, workers, wranglerD1 };

package/dist/tsconfig-jsx.d.ts

@@ -1,4 +1,5 @@
 //#region src/tsconfig-jsx.d.ts
+declare const stripJsonc: (s: string) => string;
 /** Read the app's tsconfig.json and return compilerOptions.jsxImportSource.
  *  Follows one level of `extends` so apps that inherit from a base tsconfig
  *  (e.g. "@kurajs/docs/tsconfig.kura.json") are handled correctly.
@@ -12,4 +13,4 @@ declare function jsxTransform(appRoot: string): Promise<{
   importSource?: string;
 }>;
 //#endregion
-export { appJsxImportSource, jsxTransform };
+export { appJsxImportSource, jsxTransform, stripJsonc };

package/dist/tsconfig-jsx.js

@@ -32,4 +32,4 @@ async function jsxTransform(appRoot) {
 	};
 }
 //#endregion
-export { appJsxImportSource, jsxTransform };
+export { appJsxImportSource, jsxTransform, stripJsonc };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.14",
+  "version": "1.0.0-dev.17",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,12 @@
       "types": "./dist/agent-discover.d.ts",
       "default": "./dist/agent-discover.js"
     },
+    "./agent-compile": {
+      "source": "./src/agent-compile.ts",
+      "bun": "./src/agent-compile.ts",
+      "types": "./dist/agent-compile.d.ts",
+      "default": "./dist/agent-compile.js"
+    },
     "./db": {
       "source": "./src/db.ts",
       "bun": "./src/db.ts",
@@ -132,13 +138,14 @@
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.32",
+    "@junejs/core": ">=0.2.0-dev.33",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-server-dom-webpack": "19.2.7",
     "pg": "^8.0.0",
     "mysql2": "^3.0.0",
-    "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0"
+    "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0",
+    "@anthropic-ai/sdk": ">=0.60.0"
   },
   "peerDependenciesMeta": {
     "react-server-dom-webpack": {
@@ -152,6 +159,9 @@
     },
     "@libsql/client": {
       "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
     }
   },
   "repository": {

package/src/adapter.ts

@@ -7,10 +7,11 @@
 // `workers()` is the zero-config default (this file, no import). Other targets
 // are explicit `deploy: { adapter: vercel() }` from their own package.
 import { existsSync } from "node:fs";
-import { cp, copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { cp, copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 import type { JuneConfig } from "@junejs/core/config";
+import { stripJsonc } from "./tsconfig-jsx";
 
 export type AdapterCapabilities = {
   runtime: "edge" | "node" | "serverless" | "native" | "static";
@@ -20,6 +21,9 @@ export type AdapterCapabilities = {
   persistentConnections: boolean;
   // Who serves prerendered static files: the platform CDN, the server, or none.
   assets: "platform" | "server" | "none";
+  // Durable Objects (the per-session agent actor). Only workers() today; the
+  // build skips the durable-agent mount (with a notice) when absent.
+  durableObjects?: boolean;
 };
 
 // What the adapter contributes to the generated worker entry: extra imports and
@@ -37,6 +41,11 @@ export type ResourcePlan = {
   // A declared `db` → a D1 binding named `binding`. The runtime provider
   // (bindWorkerResources) reads env[binding]; keep in sync (default "DB").
   db?: { binding: string; databaseName: string };
+  // A durable agent (an app/agent directory on a DO-capable target) → the DO
+  // namespace binding createWorker reads (env.AGENT) and the class the
+  // generated entry exports. workers() emits durable_objects + the SQLite-class
+  // migration from it.
+  agent?: { binding: string; className: string };
 };
 
 export type AdapterEmitContext = {
@@ -77,13 +86,60 @@ export interface JuneAdapter {
   emit(ctx: AdapterEmitContext): Promise<void>;
 }
 
+// Whether an app-owned wrangler config actually BINDS the generated DO class
+// under the binding name createWorker reads (env.AGENT) — not merely mentions
+// the class (a migrations entry does that too, and a binding under another
+// name never reaches the chat route). JSONC is parsed for the real
+// durable_objects.bindings entry; TOML is scanned per
+// [[durable_objects.bindings]] table with comments stripped, so a
+// commented-out binding never counts. The TOML scan covers wrangler's
+// canonical table form; an exotic inline-table config may draw a spurious
+// (advisory) warning, never a suppressed one. Pure — unit-tested directly.
+export function hasDurableBinding(text: string, file: string, binding: string, className: string): boolean {
+  if (file.endsWith(".toml")) {
+    // Strip comments: '#' to end of line, unless inside a double-quoted string.
+    const lines = text.split("\n").map((line) => {
+      let inString = false;
+      for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === '"' && line[i - 1] !== "\\") inString = !inString;
+        else if (ch === "#" && !inString) return line.slice(0, i);
+      }
+      return line;
+    });
+    let inBindings = false;
+    let name: string | undefined;
+    let cls: string | undefined;
+    const matches = () => name === binding && cls === className;
+    for (const line of lines) {
+      const t = line.trim();
+      if (t.startsWith("[")) {
+        if (inBindings && matches()) return true; // the table that just ended bound it
+        inBindings = /^\[\[\s*durable_objects\.bindings\s*\]\]$/.test(t);
+        name = cls = undefined;
+        continue;
+      }
+      if (!inBindings) continue;
+      const kv = t.match(/^(name|class_name)\s*=\s*"([^"]*)"/);
+      if (kv) kv[1] === "name" ? (name = kv[2]) : (cls = kv[2]);
+    }
+    return inBindings && matches();
+  }
+  try {
+    const parsed = JSON.parse(stripJsonc(text)) as { durable_objects?: { bindings?: { name?: string; class_name?: string }[] } };
+    return (parsed.durable_objects?.bindings ?? []).some((b) => b.name === binding && b.class_name === className);
+  } catch {
+    return text.includes(className); // unparsable — loose fallback, never crash the build
+  }
+}
+
 // The built-in default. Reproduces exactly what build.ts emitted inline:
 // withAssets(pipeline) as the entry, and a wrangler.jsonc with the assets
 // binding (run_worker_first) + optional custom domain.
 export function workers(opts?: { name?: string; domain?: string }): JuneAdapter {
   return {
     name: "workers",
-    capabilities: { runtime: "edge", persistentConnections: true, assets: "platform" },
+    capabilities: { runtime: "edge", persistentConnections: true, assets: "platform", durableObjects: true },
     conditions: ["source", "workerd", "edge", "import", "default"],
     // workers-og is a workerd-native WASM package: rolldown cannot bundle its
     // .wasm assets (wrangler's own bundler applies the CompiledWasm rule). Mark
@@ -100,7 +156,23 @@ export function workers(opts?: { name?: string; domain?: string }): JuneAdapter
 
     async emit({ appRoot, outDir, hasAssets, config, plan, defaultName }) {
       // An app that manages its own wrangler config wins — don't overwrite it.
-      if (existsSync(join(appRoot, "wrangler.toml")) || existsSync(join(appRoot, "wrangler.jsonc"))) {
+      // But a durable agent NEEDS its DO binding: warn when the app-owned config
+      // doesn't BIND the generated class under the name createWorker reads
+      // (hasDurableBinding above — a migrations-only mention, a binding under
+      // another name, or a commented-out table must all still warn), instead of
+      // silently shipping a worker whose chat surface 404s.
+      const own = ["wrangler.toml", "wrangler.jsonc"].map((f) => join(appRoot, f)).find(existsSync);
+      if (own) {
+        if (plan.agent) {
+          const cls = plan.agent.className;
+          const bound = hasDurableBinding(await readFile(own, "utf8"), own, plan.agent.binding, cls);
+          if (!bound) {
+            const snippet = own.endsWith(".toml")
+              ? `[[durable_objects.bindings]]\nname = "${plan.agent.binding}"\nclass_name = "${cls}"\n\n[[migrations]]\ntag = "v1"\nnew_sqlite_classes = ["${cls}"]`
+              : `"durable_objects": { "bindings": [{ "name": "${plan.agent.binding}", "class_name": "${cls}" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["${cls}"] }]`;
+            console.warn(`[june build] durable agent built, but ${basename(own)} doesn't bind it — add:\n${snippet}`);
+          }
+        }
         return;
       }
       const deployCfg = config.deploy;
@@ -133,6 +205,15 @@ export function workers(opts?: { name?: string; domain?: string }): JuneAdapter
                   ],
                 }
               : {}),
+            // The durable agent: one SQLite-backed DO class = the per-session
+            // AgentSession actor (its ctx.storage.sql is the durable loop's
+            // synchronous store). The binding name is what createWorker reads.
+            ...(plan.agent
+              ? {
+                  durable_objects: { bindings: [{ name: plan.agent.binding, class_name: plan.agent.className }] },
+                  migrations: [{ tag: "v1", new_sqlite_classes: [plan.agent.className] }],
+                }
+              : {}),
             // config deploy.domain → a Workers custom domain; without it the
             // regenerated file would silently drop a hand-attached domain.
             ...(opts?.domain ?? deployCfg?.domain

package/src/agent-compile.ts

@@ -0,0 +1,245 @@
+// agent-compile.ts — compile an agent/ directory into a static module
+// (_agent.gen.ts) so the SAME directory convention mounts where filesystem
+// discovery cannot run: workerd has no fs, so discoverAgent (dynamic import +
+// readFile) is native-only. The generated module is plain erasable TypeScript —
+// static imports of tools/channels/connections, markdown inlined as string
+// literals — bundleable by wrangler or Rolldown, importable under Node type
+// stripping and bun test alike. No [[rules]] Text hack, no md loader plugins,
+// no hand-maintained tool registry.
+//
+// Mirrors the content freeze (content.ts): a pure emitter (emitAgentModule)
+// over a plain scan (scanAgentDir), with a thin fs wrapper
+// (generateAgentModule) — the emitter is unit-testable without touching disk.
+// Assembly logic is NOT duplicated here: the generated module exports the raw
+// AgentModule shape, and both runtimes assemble it through
+// @junejs/core/agent-config (assembleAgent natively, assembleDurable in a DO
+// shell). Skill files are inlined raw and parsed at module init via core's
+// parseSkill, so a parser improvement never requires regeneration.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+import { stripJsonc } from "./tsconfig-jsx";
+
+export const AGENT_MODULE_FILE = "_agent.gen.ts";
+
+// The raw scan of an agent directory: file paths for code (imported statically
+// by the emitted module), file contents for prose (inlined as literals).
+export type AgentDirScan = {
+  dir: string;
+  // basename fallback when agent.ts is absent (mirrors discoverAgent).
+  name: string;
+  hasConfig: boolean;
+  instructions: string | null;
+  tools: string[]; // relative specifiers, e.g. "./tools/create_order.ts"
+  skills: { name: string; raw: string }[];
+  channels: string[]; // "./channels/slack.ts"
+  channelOverlays: { source: string; raw: string }[]; // channels/<source>.md
+  connections: string[]; // "./connections/teachify.ts"
+};
+
+// `_`-prefixed files are private by convention — most importantly the generated
+// module itself, which must never be scanned back in. Sorted for determinism.
+function list(dir: string, ext: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(ext) && !e.name.startsWith("_"))
+    .map((e) => e.name)
+    .sort();
+}
+
+// Scan an agent directory (fs only — no dynamic imports; the point is to defer
+// module loading to the bundler). Returns null when the directory holds nothing
+// agent-shaped, so callers can probe candidate paths cheaply.
+export function scanAgentDir(dir: string): AgentDirScan | null {
+  if (!existsSync(dir)) return null;
+  const instructionsFile = join(dir, "instructions.md");
+  const scan: AgentDirScan = {
+    dir,
+    name: basename(dir),
+    hasConfig: existsSync(join(dir, "agent.ts")),
+    instructions: existsSync(instructionsFile) ? readFileSync(instructionsFile, "utf8") : null,
+    tools: list(join(dir, "tools"), ".ts").map((f) => `./tools/${f}`),
+    skills: list(join(dir, "skills"), ".md").map((f) => ({
+      name: basename(f, ".md"),
+      raw: readFileSync(join(dir, "skills", f), "utf8"),
+    })),
+    channels: list(join(dir, "channels"), ".ts").map((f) => `./channels/${f}`),
+    channelOverlays: list(join(dir, "channels"), ".md").map((f) => ({
+      source: basename(f, ".md"),
+      raw: readFileSync(join(dir, "channels", f), "utf8"),
+    })),
+    connections: list(join(dir, "connections"), ".ts").map((f) => `./connections/${f}`),
+  };
+  const empty =
+    !scan.hasConfig &&
+    scan.instructions === null &&
+    !scan.tools.length &&
+    !scan.skills.length &&
+    !scan.channels.length &&
+    !scan.channelOverlays.length &&
+    !scan.connections.length;
+  return empty ? null : scan;
+}
+
+// A stable, readable import identifier from a file specifier: "./tools/create_order.ts"
+// → "tool_create_order". Collisions (foo-bar vs foo_bar) get a numeric suffix.
+function identFor(prefix: string, spec: string, taken: Set<string>): string {
+  const stem = basename(spec).replace(/\.ts$/, "").replace(/[^A-Za-z0-9]/g, "_");
+  let id = `${prefix}_${stem}`;
+  for (let i = 2; taken.has(id); i++) id = `${prefix}_${stem}_${i}`;
+  taken.add(id);
+  return id;
+}
+
+export type EmitOptions = {
+  // Keep ".ts" on relative import specifiers. Required by consumers that run
+  // the module under Node's native type stripping (Node never resolves
+  // extensionless imports); rejected (TS5097) by tsconfigs without
+  // allowImportingTsExtensions. generateAgentModule sniffs the consumer's
+  // tsconfig; pass explicitly to override.
+  tsExtensions?: boolean;
+};
+
+// Emit the module source for a scan. Pure — the golden test pins this output.
+export function emitAgentModule(scan: AgentDirScan, opts?: EmitOptions): string {
+  const spec = (s: string) => JSON.stringify(opts?.tsExtensions ? s : s.replace(/\.ts$/, ""));
+  const taken = new Set<string>();
+  const imports: string[] = [];
+  const toolIds = scan.tools.map((s) => {
+    const id = identFor("tool", s, taken);
+    imports.push(`import ${id} from ${spec(s)};`);
+    return id;
+  });
+  const channelIds = scan.channels.map((s) => {
+    const id = identFor("channel", s, taken);
+    imports.push(`import ${id} from ${spec(s)};`);
+    return { key: basename(s, ".ts"), id };
+  });
+  const connectionIds = scan.connections.map((s) => {
+    const id = identFor("connection", s, taken);
+    imports.push(`import ${id} from ${spec(s)};`);
+    return id;
+  });
+  if (scan.hasConfig) imports.push(`import config from ${spec("./agent.ts")};`);
+
+  const lines: string[] = [
+    "// AUTO-GENERATED by June — do not edit. Compiled from this agent/ directory so",
+    "// the definition mounts without filesystem discovery (workerd has no fs).",
+    "// Regenerate with `june gen` after adding, removing, or editing agent files.",
+    ...imports,
+    scan.skills.length
+      ? `import { parseSkill, type AgentModule } from "@junejs/core/agent-config";`
+      : `import type { AgentModule } from "@junejs/core/agent-config";`,
+    "",
+  ];
+  if (!scan.hasConfig) lines.push(`const config = { name: ${JSON.stringify(scan.name)} };`, "");
+
+  lines.push(
+    "export const agentModule: AgentModule = {",
+    "  config,",
+    `  instructions: ${JSON.stringify(scan.instructions ?? "")},`,
+    `  tools: [${toolIds.join(", ")}],`,
+    scan.skills.length
+      ? `  skills: [\n${scan.skills.map((s) => `    parseSkill(${JSON.stringify(s.name)}, ${JSON.stringify(s.raw)}),`).join("\n")}\n  ],`
+      : "  skills: [],",
+    channelIds.length
+      ? `  channels: { ${channelIds.map((c) => `${JSON.stringify(c.key)}: ${c.id}`).join(", ")} },`
+      : "  channels: {},",
+    scan.channelOverlays.length
+      ? `  channelInstructions: {\n${scan.channelOverlays.map((o) => `    ${JSON.stringify(o.source)}: ${JSON.stringify(o.raw)},`).join("\n")}\n  },`
+      : "  channelInstructions: {},",
+    `  connections: [${connectionIds.join(", ")}],`,
+    "};",
+    "export default agentModule;",
+    "",
+  );
+  return lines.join("\n");
+}
+
+// Locate the agent directory for a project root: a June app keeps it at
+// app/<dir> (the app.ts convention); a wrangler-first worker keeps it at
+// <root>/<dir>. `dirName` follows june.config's agent.runtime.dir (default
+// "agent").
+export function findAgentDir(root: string, dirName = "agent"): string | null {
+  for (const candidate of [join(root, "app", dirName), join(root, dirName)]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// Whether the consumer's tsconfig keeps ".ts" on import specifiers
+// (allowImportingTsExtensions): the nearest tsconfig.json walking up from the
+// agent dir, parsed as JSONC (same stripJsonc as tsconfig-jsx.ts — a commented-
+// out option must not count) and resolved through `extends` (relative, bare
+// package specifiers, and the TS 5 array form; own options win, later array
+// entries beat earlier ones). Explicit opts.tsExtensions overrides the sniff.
+type TsconfigLite = { extends?: string | string[]; compilerOptions?: { allowImportingTsExtensions?: boolean } };
+
+function readTsconfig(path: string): TsconfigLite | undefined {
+  try {
+    return JSON.parse(stripJsonc(readFileSync(path, "utf8"))) as TsconfigLite;
+  } catch {
+    return undefined; // absent or unparsable — treat as "not declared"
+  }
+}
+
+// Resolve an `extends` specifier from the extending config's directory: relative
+// paths directly, bare specifiers through the nearest node_modules walking up.
+// tsc appends ".json" when the target has no extension — mirror that.
+function resolveExtends(fromDir: string, spec: string): string | undefined {
+  const withJson = (p: string) => (existsSync(p) ? p : !p.endsWith(".json") && existsSync(`${p}.json`) ? `${p}.json` : undefined);
+  if (spec.startsWith(".")) return withJson(resolve(fromDir, spec));
+  for (let d = fromDir; ; ) {
+    const candidate = withJson(join(d, "node_modules", spec));
+    if (candidate) return candidate;
+    const parent = dirname(d);
+    if (parent === d) return undefined;
+    d = parent;
+  }
+}
+
+function resolveAllowTsExtensions(path: string, depth: number): boolean | undefined {
+  if (depth > 8) return undefined; // extends cycles/degenerate chains — give up
+  const tc = readTsconfig(path);
+  if (!tc) return undefined;
+  const own = tc.compilerOptions?.allowImportingTsExtensions;
+  if (own !== undefined) return own;
+  // TS extends-array semantics: later entries override earlier ones.
+  const bases = typeof tc.extends === "string" ? [tc.extends] : [...(tc.extends ?? [])].reverse();
+  for (const spec of bases) {
+    const base = resolveExtends(dirname(path), spec);
+    const inherited = base ? resolveAllowTsExtensions(base, depth + 1) : undefined;
+    if (inherited !== undefined) return inherited;
+  }
+  return undefined;
+}
+
+function sniffTsExtensions(dir: string): boolean {
+  for (let d = dir; ; ) {
+    const candidate = join(d, "tsconfig.json");
+    if (existsSync(candidate)) return resolveAllowTsExtensions(candidate, 0) ?? false;
+    const parent = dirname(d);
+    if (parent === d) return false;
+    d = parent;
+  }
+}
+
+// Generate <dir>/_agent.gen.ts. With `check: true` nothing is written — `stale`
+// reports whether the file on disk differs from what would be generated (the CI
+// gate; `june gen && git diff --exit-code` works too). Returns null when the
+// directory holds nothing agent-shaped.
+export function generateAgentModule(
+  dir: string,
+  opts?: { check?: boolean } & EmitOptions,
+): { file: string; code: string; stale: boolean; written: boolean } | null {
+  const scan = scanAgentDir(dir);
+  if (!scan) return null;
+  const code = emitAgentModule(scan, { tsExtensions: opts?.tsExtensions ?? sniffTsExtensions(dir) });
+  const file = join(dir, AGENT_MODULE_FILE);
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : null;
+  const stale = existing !== code;
+  if (opts?.check) return { file, code, stale, written: false };
+  if (stale) writeFileSync(file, code);
+  return { file, code, stale, written: stale };
+}

package/src/agent-discover.ts

@@ -8,12 +8,15 @@
 //     tools/*.ts       → each default-exports a defineAction (a tool)
 //     skills/*.md      → each a procedure, loaded on demand (progressive disclosure)
 //     channels/*.ts    → each default-exports a Channel (an inbound edge)
+//     channels/*.md    → source-keyed system overlay for the same-named channel
 //     connections/*.ts → each default-exports a Connection (an outbound tool source)
 //
 // There is no central registry to keep in sync — the directory IS the manifest.
 // Because tools are `defineAction`s, the SAME directory is also an MCP server and
 // a `.agent` manifest (surfaces land in a later step). fs lives here in the host
-// package; the pure assembly is @junejs/core/agent-config's defineAgent().
+// package; the pure assembly is @junejs/core/agent-config's assembleAgent() — the
+// SAME entry point a compiled agent module (agent-compile.ts, the edge path) goes
+// through, so native discovery and the generated module cannot drift.
 
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
@@ -21,52 +24,32 @@ import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import type { AnyAction } from "@junejs/core/agent";
-import { defineAgent, resolveChannel, type AgentConfigFile, type AgentDefinition, type Channel, type ChannelFactory, type Skill } from "@junejs/core/agent-config";
-import { connectAll, type Connection } from "@junejs/core/connections";
+import { assembleAgent, parseSkill, type AgentConfigFile, type AgentDefinition, type AgentModule, type Channel, type ChannelFactory, type Skill } from "@junejs/core/agent-config";
+import type { Connection } from "@junejs/core/connections";
 
+// `_`-prefixed files are private by convention (mirrors the app/ router) — most
+// importantly the generated `_agent.gen.ts` itself, which must never be scanned
+// back in as a tool/channel.
 async function scan(dir: string, ext: string): Promise<string[]> {
   if (!existsSync(dir)) return [];
   const entries = await readdir(dir, { withFileTypes: true });
   return entries
-    .filter((e) => e.isFile() && extname(e.name) === ext)
+    .filter((e) => e.isFile() && extname(e.name) === ext && !e.name.startsWith("_"))
     .map((e) => join(dir, e.name))
     .sort();
 }
 
-// Optional YAML-ish frontmatter: --- \n key: value \n --- \n body. Falls back to
-// the first non-empty line (minus a leading "# ") as the description.
-function parseSkill(name: string, text: string): Skill {
-  if (text.startsWith("---")) {
-    const end = text.indexOf("\n---", 3);
-    if (end !== -1) {
-      const front = text.slice(3, end);
-      const body = text.slice(end + 4).replace(/^\s*\n/, "");
-      const meta: Record<string, string> = {};
-      for (const line of front.split("\n")) {
-        const m = line.match(/^\s*(\w+)\s*:\s*(.+?)\s*$/);
-        if (m) meta[m[1]!] = m[2]!;
-      }
-      return { name: meta.name ?? name, description: meta.description ?? "", body };
-    }
-  }
-  const firstLine = text.split("\n").find((l) => l.trim()) ?? "";
-  return { name, description: firstLine.replace(/^#\s*/, ""), body: text };
-}
-
-// Discover an agent from its directory, returning the assembled AgentDefinition
-// (tools already adapted from defineActions; read_skill added if any skills
-// exist). Mount it on a runtime with createNativeRuntime({ [agent.name]: { model,
-// tools: agent.tools } }).
-export async function discoverAgent(dir: string): Promise<AgentDefinition> {
+// Read an agent directory into its raw, unassembled shape (fs + dynamic import —
+// native only). The pure sibling for the edge is agent-compile.ts, which emits
+// the same AgentModule as static code.
+export async function discoverAgentModule(dir: string): Promise<AgentModule> {
   const configFile = join(dir, "agent.ts");
   const config: AgentConfigFile = existsSync(configFile)
     ? ((await import(pathToFileURL(configFile).href)).default as AgentConfigFile)
     : { name: basename(dir) };
 
   const instructionsFile = join(dir, "instructions.md");
-  const instructions = existsSync(instructionsFile)
-    ? await readFile(instructionsFile, "utf8")
-    : (config.instructions ?? "");
+  const instructions = existsSync(instructionsFile) ? await readFile(instructionsFile, "utf8") : "";
 
   const tools: AnyAction[] = [];
   for (const f of await scan(join(dir, "tools"), ".ts")) {
@@ -80,34 +63,36 @@ export async function discoverAgent(dir: string): Promise<AgentDefinition> {
   }
 
   // A channel module default-exports a Channel OR a `(env) => Channel` factory (the
-  // form workerd needs — secrets live in env, not at module scope). On native, env is
-  // process.env (present at load), so resolve here; the plain form stays supported.
-  const channels: Channel[] = [];
+  // form workerd needs — secrets live in env, not at module scope). Resolution is
+  // assembleAgent's job (native: process.env; a DO: its own env) — keep raw here.
+  const channels: Record<string, Channel | ChannelFactory> = {};
   for (const f of await scan(join(dir, "channels"), ".ts")) {
     const mod = await import(pathToFileURL(f).href);
-    if (mod.default) channels.push(resolveChannel(mod.default as Channel | ChannelFactory, process.env));
+    if (mod.default) channels[basename(f, ".ts")] = mod.default as Channel | ChannelFactory;
   }
 
-  // connections/*.ts — outbound: wire external MCP/OpenAPI servers, turning their
-  // operations into `<connection>__<tool>` defineActions that join `tools`.
-  const connectionDefs: Connection[] = [];
+  // channels/<source>.md — a system overlay applied when a turn's inbound event
+  // source matches the file's basename (see AgentDefinition.channelInstructions).
+  const channelInstructions: Record<string, string> = {};
+  for (const f of await scan(join(dir, "channels"), ".md")) {
+    channelInstructions[basename(f, ".md")] = await readFile(f, "utf8");
+  }
+
+  // connections/*.ts — outbound: definitions of external MCP/OpenAPI servers;
+  // assembleAgent wires them (connectAll) where the agent actually runs.
+  const connections: Connection[] = [];
   for (const f of await scan(join(dir, "connections"), ".ts")) {
     const mod = await import(pathToFileURL(f).href);
-    if (mod.default) connectionDefs.push(mod.default as Connection);
+    if (mod.default) connections.push(mod.default as Connection);
   }
-  const { actions: connectionActions, report: connections } = connectionDefs.length
-    ? await connectAll(connectionDefs)
-    : { actions: [], report: [] };
-  tools.push(...connectionActions);
 
-  return defineAgent({
-    name: config.name,
-    model: config.model,
-    description: config.description,
-    instructions,
-    tools,
-    skills,
-    channels,
-    connections,
-  });
+  return { config, instructions, tools, skills, channels, channelInstructions, connections };
+}
+
+// Discover an agent from its directory, returning the assembled AgentDefinition
+// (tools already adapted from defineActions; read_skill added if any skills
+// exist). Mount it on a runtime with createNativeRuntime({ [agent.name]: { model,
+// tools: agent.tools } }).
+export async function discoverAgent(dir: string): Promise<AgentDefinition> {
+  return assembleAgent(await discoverAgentModule(dir), process.env);
 }