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

package/dist/agent-compile.d.ts

@@ -5,6 +5,10 @@ type AgentDirScan = {
   name: string;
   hasConfig: boolean;
   instructions: string | null;
+  surfaceVariants: {
+    source: string;
+    raw: string;
+  }[];
   tools: string[];
   skills: {
     name: string;

package/dist/agent-compile.js

@@ -15,6 +15,10 @@ function scanAgentDir(dir) {
 		name: basename(dir),
 		hasConfig: existsSync(join(dir, "agent.ts")),
 		instructions: existsSync(instructionsFile) ? readFileSync(instructionsFile, "utf8") : null,
+		surfaceVariants: readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/)).filter((m) => m !== null).sort((a, b) => a[1].localeCompare(b[1])).map((m) => ({
+			source: m[1],
+			raw: readFileSync(join(dir, m[0]), "utf8")
+		})),
 		tools: list(join(dir, "tools"), ".ts").map((f) => `./tools/${f}`),
 		skills: list(join(dir, "skills"), ".md").map((f) => ({
 			name: basename(f, ".md"),
@@ -27,7 +31,7 @@ function scanAgentDir(dir) {
 		})),
 		connections: list(join(dir, "connections"), ".ts").map((f) => `./connections/${f}`)
 	};
-	return !scan.hasConfig && scan.instructions === null && !scan.tools.length && !scan.skills.length && !scan.channels.length && !scan.channelOverlays.length && !scan.connections.length ? null : scan;
+	return !scan.hasConfig && scan.instructions === null && !scan.tools.length && !scan.skills.length && !scan.channels.length && !scan.surfaceVariants.length && !scan.channelOverlays.length && !scan.connections.length ? null : scan;
 }
 function identFor(prefix, spec, taken) {
 	const stem = basename(spec).replace(/\.ts$/, "").replace(/[^A-Za-z0-9]/g, "_");
@@ -68,7 +72,7 @@ function emitAgentModule(scan, opts) {
 		""
 	];
 	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;", "");
+	lines.push("export const agentModule: AgentModule = {", "  config,", `  instructions: ${JSON.stringify(scan.instructions ?? "")},`, scan.surfaceVariants.length ? `  surfaceInstructions: {\n${scan.surfaceVariants.map((v) => `    ${JSON.stringify(v.source)}: ${JSON.stringify(v.raw)},`).join("\n")}\n  },` : "  surfaceInstructions: {},", `  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");
 }
 function findAgentDir(root, dirName = "agent") {
@@ -118,6 +122,8 @@ function sniffTsExtensions(dir) {
 function generateAgentModule(dir, opts) {
 	const scan = scanAgentDir(dir);
 	if (!scan) return null;
+	for (const o of scan.channelOverlays) console.warn(`[june] deprecated: channels/${o.source}.md — move it to instructions.${o.source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`);
+	for (const e of readdirSync(dir, { withFileTypes: true })) if (e.isFile() && /^instructions\..+\.md$/.test(e.name) && !/^instructions\.[a-z0-9_-]+\.md$/.test(e.name)) console.warn(`[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`);
 	const code = emitAgentModule(scan, { tsExtensions: opts?.tsExtensions ?? sniffTsExtensions(dir) });
 	const file = join(dir, AGENT_MODULE_FILE);
 	const stale = (existsSync(file) ? readFileSync(file, "utf8") : null) !== code;

package/dist/agent-discover.js

@@ -13,6 +13,13 @@ async function discoverAgentModule(dir) {
 	const config = existsSync(configFile) ? (await import(pathToFileURL(configFile).href)).default : { name: basename(dir) };
 	const instructionsFile = join(dir, "instructions.md");
 	const instructions = existsSync(instructionsFile) ? await readFile(instructionsFile, "utf8") : "";
+	const surfaceInstructions = {};
+	if (existsSync(dir)) for (const e of await readdir(dir, { withFileTypes: true })) {
+		if (!e.isFile() || !/^instructions\..+\.md$/.test(e.name)) continue;
+		const m = e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/);
+		if (m) surfaceInstructions[m[1]] = await readFile(join(dir, e.name), "utf8");
+		else console.warn(`[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`);
+	}
 	const tools = [];
 	for (const f of await scan(join(dir, "tools"), ".ts")) {
 		const mod = await import(pathToFileURL(f).href);
@@ -26,7 +33,11 @@ async function discoverAgentModule(dir) {
 		if (mod.default) channels[basename(f, ".ts")] = mod.default;
 	}
 	const channelInstructions = {};
-	for (const f of await scan(join(dir, "channels"), ".md")) channelInstructions[basename(f, ".md")] = await readFile(f, "utf8");
+	for (const f of await scan(join(dir, "channels"), ".md")) {
+		const source = basename(f, ".md");
+		console.warn(`[june] deprecated: channels/${source}.md — move it to instructions.${source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`);
+		channelInstructions[source] = await readFile(f, "utf8");
+	}
 	const connections = [];
 	for (const f of await scan(join(dir, "connections"), ".ts")) {
 		const mod = await import(pathToFileURL(f).href);
@@ -35,6 +46,7 @@ async function discoverAgentModule(dir) {
 	return {
 		config,
 		instructions,
+		surfaceInstructions,
 		tools,
 		skills,
 		channels,

package/dist/agent-durable.d.ts

@@ -1,5 +1,6 @@
 import { Channel, ChannelFactory } from "@junejs/core/agent-config";
-import { InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnError, TurnEvent, TurnFailurePhase } from "@junejs/core/agent-runtime";
+import { ChannelPolicy, InboundEvent, Model, Msg, ProactiveTrigger, SessionStore, Tool, TurnError, TurnEvent, TurnFailurePhase } from "@junejs/core/agent-runtime";
+import { Connection } from "@junejs/core/connections";
 import { Resources } from "@junejs/core/resources";
 //#region src/agent-durable.d.ts
 type SqlStorageValue = ArrayBuffer | string | number | null;
@@ -47,10 +48,11 @@ type DoAgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
-  channelInstructions?: Record<string, string>;
+  channelInstructions?: Record<string, string | ChannelPolicy>;
   channels?: (Channel | ChannelFactory)[];
   env?: unknown;
   resources?: Resources | ((env: unknown) => Promise<Resources> | Resources);
+  connections?: Connection[];
   services?: unknown;
   onTurnError?: (failure: {
     turnId: string;
@@ -71,9 +73,13 @@ declare class AgentDurableObject {
   private readonly channelInstructions?;
   private readonly resourcesInput;
   private resourcesOpened;
+  private readonly connectionsInput;
+  private connectionsOpened;
   private readonly doEnv;
   private readonly services;
   private resolveResources;
+  private resolveConnections;
+  private ready;
   constructor(state: DurableObjectState, def: DoAgentDef);
   private resolveSession;
   turn(input: {

package/dist/agent-durable.js

@@ -1,7 +1,8 @@
 import { isolateLocal } from "./isolate-local.js";
 import { assertCoreRuntimeVersion } from "./core-version.js";
-import { DeliverUnsupportedError, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
+import { DeliverUnsupportedError, actionToTool, channelDispatch, resolveChannel } from "@junejs/core/agent-config";
 import { AgentSession, ResumeAuthorizationError, withSystem } from "@junejs/core/agent-runtime";
+import { connectAll } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
 //#region src/agent-durable.ts
 var DoSessionStore = class {
@@ -101,16 +102,37 @@ var AgentDurableObject = class {
 	channelInstructions;
 	resourcesInput;
 	resourcesOpened;
+	connectionsInput;
+	connectionsOpened;
 	doEnv;
 	services;
 	resolveResources() {
 		return this.resourcesOpened ??= Promise.resolve(typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : this.resourcesInput ?? {});
 	}
+	resolveConnections() {
+		return this.connectionsOpened ??= (async () => {
+			if (!this.connectionsInput?.length) return;
+			const { actions, report } = await connectAll(this.connectionsInput);
+			for (const r of report) if (r.error) console.error(`[june] agent "${this.name}": connection "${r.name}" (${r.url}) failed: ${r.error}`);
+			const seen = new Set(this.tools.map((t) => t.spec.name));
+			for (const a of actions) {
+				const tool = actionToTool(a);
+				if (seen.has(tool.spec.name)) throw new Error(`AgentDurableObject(${this.name}): duplicate tool name "${tool.spec.name}" from a connection — rename so dispatch is unambiguous.`);
+				seen.add(tool.spec.name);
+				this.tools.push(tool);
+			}
+		})();
+	}
+	async ready() {
+		const [resources] = await Promise.all([this.resolveResources(), this.resolveConnections()]);
+		return resources;
+	}
 	constructor(state, def) {
 		assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`);
 		const store = new DoSessionStore(state.storage);
 		const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
 		this.resourcesInput = def.resources;
+		this.connectionsInput = def.connections;
 		this.doEnv = def.env;
 		this.services = def.services;
 		const name = def.name ?? "agent";
@@ -151,6 +173,10 @@ var AgentDurableObject = class {
 		this.tools = tools;
 		this.channels = channels;
 		this.channelInstructions = def.channelInstructions;
+		if (def.channelInstructions) {
+			const names = new Set(channels.map((c) => c.name));
+			for (const source of Object.keys(def.channelInstructions)) if (!names.has(source)) console.warn(`[june] agent "${name}": surface policy "${source}" matches no channel wired into this DO (${[...names].join(", ") || "none"}) — it will never fire.`);
+		}
 	}
 	resolveSession(key) {
 		if (key !== void 0) assertSessionKey(key);
@@ -168,7 +194,7 @@ var AgentDurableObject = class {
 	}
 	async turn(input) {
 		await ensureScope();
-		const resources = await this.resolveResources();
+		const resources = await this.ready();
 		const session = this.resolveSession(input.session);
 		return runInScope({
 			resources,
@@ -177,7 +203,7 @@ var AgentDurableObject = class {
 	}
 	async start(input) {
 		await ensureScope();
-		const resources = await this.resolveResources();
+		const resources = await this.ready();
 		const session = this.resolveSession(input.session);
 		return runInScope({
 			resources,
@@ -206,7 +232,7 @@ var AgentDurableObject = class {
 				deliverChannel = this.channels.find((c) => c.name === event.source);
 				if (!deliverChannel?.deliver) return Response.json({ error: `agent "${this.name}": no deliver()-capable channel named "${event.source}" is wired into this DO (DoAgentDef.channels) — the turn was NOT started` }, { status: 501 });
 			}
-			const resources = await this.resolveResources();
+			const resources = await this.ready();
 			let session;
 			let started;
 			try {
@@ -259,7 +285,7 @@ var AgentDurableObject = class {
 				resumeChannel = this.channels.find((c) => c.name === source);
 				if (!resumeChannel?.deliverResume) return Response.json({ error: `agent "${this.name}": no deliverResume()-capable channel named "${source}" is wired into this DO (DoAgentDef.channels) — the answer was NOT applied` }, { status: 501 });
 			}
-			const resources = await this.resolveResources();
+			const resources = await this.ready();
 			let session;
 			try {
 				session = this.resolveSession(key);

package/dist/build.js

@@ -452,7 +452,8 @@ async function juneBuild(appRoot, options = {}) {
 		imports.push(`import { DurableObject } from "cloudflare:workers";`);
 		imports.push(`import Anthropic from "@anthropic-ai/sdk";`);
 	}
-	const agentNameField = agentModule ? `\n  agentName: __agentModule.config.name,` : "";
+	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),
@@ -462,7 +463,6 @@ async function juneBuild(appRoot, options = {}) {
 // 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,
@@ -477,7 +477,7 @@ export class JuneAgentDO extends DurableObject {
 	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")}

package/dist/worker.d.ts

@@ -1,4 +1,5 @@
 import { l as ResourceHandler, n as LayoutComponent, r as LoadingComponent, t as ExtraHandler } from "./pipeline-cCR6MGNK.js";
+import { Channel, ChannelFactory } from "@junejs/core/agent-config";
 import { BrandedRoute } from "@junejs/core/route";
 import { AgentConfig } from "@junejs/core/config";
 import React from "react";
@@ -6,6 +7,9 @@ import { DocumentConfig } from "@junejs/core/document";
 import { I18nConfig } from "@junejs/core/i18n";
 import { Resources } from "@junejs/core/resources";
 //#region src/worker.d.ts
+type WorkerExecutionContext = {
+  waitUntil?(p: Promise<unknown>): void;
+};
 type WorkerManifest = {
   routes: Record<string, BrandedRoute>;
   dynamicRoutes?: Array<{
@@ -25,6 +29,7 @@ type WorkerManifest = {
   document: DocumentConfig;
   agent: AgentConfig;
   agentName?: string;
+  agentChannels?: (Channel | ChannelFactory)[];
   i18n?: I18nConfig;
   earlyHints?: string[];
   htmlCacheControl?: string;
@@ -36,7 +41,7 @@ type WorkerManifest = {
   services?: (env?: unknown) => unknown;
 };
 declare function createWorker(manifest: WorkerManifest): {
-  fetch(request: Request, env?: unknown): Promise<Response>;
+  fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response>;
 };
 type AssetEnv = {
   ASSETS?: {
@@ -44,13 +49,13 @@ type AssetEnv = {
   };
 };
 type FetchPipeline = {
-  fetch(request: Request, env?: unknown): Promise<Response>;
+  fetch(request: Request, env?: unknown, ctx?: WorkerExecutionContext): Promise<Response>;
 };
 declare function withAssets(pipeline: FetchPipeline, opts?: {
   link?: string | null;
 }): {
-  fetch(request: Request, env?: AssetEnv): Promise<Response>;
+  fetch(request: Request, env?: AssetEnv, ctx?: WorkerExecutionContext): Promise<Response>;
 };
 declare function withDenoAssets(pipeline: FetchPipeline): (request: Request) => Promise<Response>;
 //#endregion
-export { WorkerManifest, createWorker, withAssets, withDenoAssets };
+export { WorkerExecutionContext, WorkerManifest, createWorker, withAssets, withDenoAssets };

package/dist/worker.js

@@ -1,4 +1,4 @@
-import { durableAgentSurface } from "./agent-durable.js";
+import { durableAgentSurface, durableChannelSurface } from "./agent-durable.js";
 import { createPipeline } from "./pipeline.js";
 import { RESERVED_PREFIX, contentTypeFor, safeRelativePath } from "./static-files.js";
 //#region src/worker.ts
@@ -61,15 +61,30 @@ function createWorker(manifest) {
 	const loadingFor = (key) => manifest.loadings?.[key];
 	const boundaryFor = (key) => manifest.layoutBoundaries?.[key] ?? null;
 	let currentEnv;
+	const requestLocals = /* @__PURE__ */ new WeakMap();
 	const provider = manifest.resources;
 	const servicesProvider = manifest.services;
 	let servicesCache;
 	const agentSurface = manifest.agent.runtime.enabled && manifest.agentName ? (() => {
-		const route = durableAgentSurface(() => currentEnv?.AGENT, {
-			agentName: manifest.agentName,
-			chatPath: manifest.agent.runtime.chat.path
-		});
-		return (req) => route(req);
+		const agentName = manifest.agentName;
+		const wantChannels = manifest.agent.runtime.channels !== false && (manifest.agentChannels?.length ?? 0) > 0;
+		return async (req) => {
+			const locals = requestLocals.get(req);
+			const ns = () => (locals?.env)?.AGENT;
+			const chatRes = await durableAgentSurface(ns, {
+				agentName,
+				chatPath: manifest.agent.runtime.chat.path
+			})(req);
+			if (chatRes) return chatRes;
+			if (!wantChannels) return null;
+			return durableChannelSurface(ns, {
+				agentName,
+				channels: manifest.agentChannels,
+				env: locals?.env,
+				services: servicesProvider,
+				waitUntil: locals?.ctx?.waitUntil?.bind(locals.ctx)
+			})(req);
+		};
 	})() : void 0;
 	const pipeline = createPipeline({
 		docConfig: manifest.document,
@@ -130,14 +145,18 @@ function createWorker(manifest) {
 			return null;
 		}
 	});
-	return { fetch(request, env) {
+	return { fetch(request, env, ctx) {
 		currentEnv = env;
+		requestLocals.set(request, {
+			env,
+			ctx
+		});
 		return pipeline.fetch(request);
 	} };
 }
 const estimateTokens = (s) => String(Math.ceil(s.length / 4));
 function withAssets(pipeline, opts = {}) {
-	return { async fetch(request, env) {
+	return { async fetch(request, env, ctx) {
 		const assets = env?.ASSETS;
 		const url = new URL(request.url);
 		const isPagePath = !/\.[a-z0-9]+$/i.test(url.pathname);
@@ -177,7 +196,7 @@ function withAssets(pipeline, opts = {}) {
 				return a;
 			}
 		}
-		return pipeline.fetch(request, env);
+		return pipeline.fetch(request, env, ctx);
 	} };
 }
 function withDenoAssets(pipeline) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "1.0.0-dev.17",
+  "version": "1.0.0-dev.19",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -138,7 +138,7 @@
     "rolldown": "^1.1.0"
   },
   "peerDependencies": {
-    "@junejs/core": ">=0.2.0-dev.33",
+    "@junejs/core": ">=0.2.0-dev.36",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-server-dom-webpack": "19.2.7",

package/src/agent-compile.ts

@@ -31,6 +31,8 @@ export type AgentDirScan = {
   name: string;
   hasConfig: boolean;
   instructions: string | null;
+  // instructions.<source>.md at the agent root — per-surface variants (#149).
+  surfaceVariants: { source: string; raw: string }[];
   tools: string[]; // relative specifiers, e.g. "./tools/create_order.ts"
   skills: { name: string; raw: string }[];
   channels: string[]; // "./channels/slack.ts"
@@ -59,6 +61,12 @@ export function scanAgentDir(dir: string): AgentDirScan | null {
     name: basename(dir),
     hasConfig: existsSync(join(dir, "agent.ts")),
     instructions: existsSync(instructionsFile) ? readFileSync(instructionsFile, "utf8") : null,
+    surfaceVariants: readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile())
+      .map((e) => e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/))
+      .filter((m): m is RegExpMatchArray => m !== null)
+      .sort((a, b) => a[1]!.localeCompare(b[1]!))
+      .map((m) => ({ source: m[1]!, raw: readFileSync(join(dir, m[0]!), "utf8") })),
     tools: list(join(dir, "tools"), ".ts").map((f) => `./tools/${f}`),
     skills: list(join(dir, "skills"), ".md").map((f) => ({
       name: basename(f, ".md"),
@@ -77,6 +85,7 @@ export function scanAgentDir(dir: string): AgentDirScan | null {
     !scan.tools.length &&
     !scan.skills.length &&
     !scan.channels.length &&
+    !scan.surfaceVariants.length &&
     !scan.channelOverlays.length &&
     !scan.connections.length;
   return empty ? null : scan;
@@ -139,6 +148,9 @@ export function emitAgentModule(scan: AgentDirScan, opts?: EmitOptions): string
     "export const agentModule: AgentModule = {",
     "  config,",
     `  instructions: ${JSON.stringify(scan.instructions ?? "")},`,
+    scan.surfaceVariants.length
+      ? `  surfaceInstructions: {\n${scan.surfaceVariants.map((v) => `    ${JSON.stringify(v.source)}: ${JSON.stringify(v.raw)},`).join("\n")}\n  },`
+      : "  surfaceInstructions: {},",
     `  tools: [${toolIds.join(", ")}],`,
     scan.skills.length
       ? `  skills: [\n${scan.skills.map((s) => `    parseSkill(${JSON.stringify(s.name)}, ${JSON.stringify(s.raw)}),`).join("\n")}\n  ],`
@@ -235,6 +247,20 @@ export function generateAgentModule(
 ): { file: string; code: string; stale: boolean; written: boolean } | null {
   const scan = scanAgentDir(dir);
   if (!scan) return null;
+  for (const o of scan.channelOverlays) {
+    console.warn(
+      `[june] deprecated: channels/${o.source}.md — move it to instructions.${o.source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`,
+    );
+  }
+  // A variant-shaped file the grammar doesn't parse yet must never be silently
+  // inert (the same failure class this whole convention exists to kill).
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.isFile() && /^instructions\..+\.md$/.test(e.name) && !/^instructions\.[a-z0-9_-]+\.md$/.test(e.name)) {
+      console.warn(
+        `[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`,
+      );
+    }
+  }
   const code = emitAgentModule(scan, { tsExtensions: opts?.tsExtensions ?? sniffTsExtensions(dir) });
   const file = join(dir, AGENT_MODULE_FILE);
   const existing = existsSync(file) ? readFileSync(file, "utf8") : null;

package/src/agent-discover.ts

@@ -3,13 +3,14 @@
 // An agent is a DIRECTORY, not a config object. Location determines function:
 //
 //   agent/
-//     agent.ts         → default-exports a plain config { name, model?, description? }
-//     instructions.md  → system prompt
-//     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)
+//     agent.ts                  → default-exports a plain config { name, model?, surfaces? }
+//     instructions.md           → base system prompt
+//     instructions.<source>.md  → per-surface instruction variant (#149)
+//     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 — pure transport)
+//     channels/*.md             → DEPRECATED overlay location (warned; use instructions.<source>.md)
+//     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
@@ -51,6 +52,26 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
   const instructionsFile = join(dir, "instructions.md");
   const instructions = existsSync(instructionsFile) ? await readFile(instructionsFile, "utf8") : "";
 
+  // instructions.<source>.md — the agent's per-surface instruction variants
+  // (#149): applied to turns arriving through that source, composed per
+  // config.surfaces (append by default, "replace" to stand alone).
+  const surfaceInstructions: Record<string, string> = {};
+  if (existsSync(dir)) {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      if (!e.isFile() || !/^instructions\..+\.md$/.test(e.name)) continue;
+      const m = e.name.match(/^instructions\.([a-z0-9_-]+)\.md$/);
+      if (m) {
+        surfaceInstructions[m[1]!] = await readFile(join(dir, e.name), "utf8");
+      } else {
+        // A variant-shaped file the grammar doesn't parse yet (e.g. a locale
+        // suffix, instructions.slack.zh-TW.md) must never be SILENTLY inert.
+        console.warn(
+          `[june] ${e.name}: unrecognized instructions variant — only single-segment sources (instructions.<source>.md) are parsed today; locale variants are a planned follow-up (junebuild/june#149). This file is ignored.`,
+        );
+      }
+    }
+  }
+
   const tools: AnyAction[] = [];
   for (const f of await scan(join(dir, "tools"), ".ts")) {
     const mod = await import(pathToFileURL(f).href);
@@ -71,11 +92,16 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
     if (mod.default) channels[basename(f, ".ts")] = mod.default as Channel | ChannelFactory;
   }
 
-  // channels/<source>.md — a system overlay applied when a turn's inbound event
-  // source matches the file's basename (see AgentDefinition.channelInstructions).
+  // channels/<source>.md — the DEPRECATED overlay convention (#149): behavior
+  // prose belongs at the agent level (instructions.<source>.md), not beside
+  // transport code. Still honored for one dev-series, loudly.
   const channelInstructions: Record<string, string> = {};
   for (const f of await scan(join(dir, "channels"), ".md")) {
-    channelInstructions[basename(f, ".md")] = await readFile(f, "utf8");
+    const source = basename(f, ".md");
+    console.warn(
+      `[june] deprecated: channels/${source}.md — move it to instructions.${source}.md at the agent root (per-surface behavior is agent-level; see junebuild/june#149).`,
+    );
+    channelInstructions[source] = await readFile(f, "utf8");
   }
 
   // connections/*.ts — outbound: definitions of external MCP/OpenAPI servers;
@@ -86,7 +112,7 @@ export async function discoverAgentModule(dir: string): Promise<AgentModule> {
     if (mod.default) connections.push(mod.default as Connection);
   }
 
-  return { config, instructions, tools, skills, channels, channelInstructions, connections };
+  return { config, instructions, surfaceInstructions, tools, skills, channels, channelInstructions, connections };
 }
 
 // Discover an agent from its directory, returning the assembled AgentDefinition

package/src/agent-durable.ts

@@ -19,6 +19,7 @@ import {
   AgentSession,
   ResumeAuthorizationError,
   withSystem,
+  type ChannelPolicy,
   type EventSink,
   type TurnEvent,
   type Model,
@@ -35,6 +36,7 @@ import type { Resources } from "@junejs/core/resources";
 import {
   channelDispatch,
   DeliverUnsupportedError,
+  actionToTool,
   resolveChannel,
   type AgentDefinition,
   type Channel,
@@ -42,6 +44,7 @@ import {
   type ChannelFactory,
   type ResumeDeliveryTarget,
 } from "@junejs/core/agent-config";
+import { connectAll, type Connection } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
 import { isolateLocal } from "./isolate-local";
 import { assertCoreRuntimeVersion } from "./core-version";
@@ -198,9 +201,12 @@ export type DoAgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
-  // Per-channel-source system overlays (see AgentDefinition.channelInstructions) — the
-  // shared agent branches by real inbound source, no userText marker.
-  channelInstructions?: Record<string, string>;
+  // Per-channel-source turn policies (see AgentDefinition.channelInstructions):
+  // an overlay string, or a ChannelPolicy carrying overlay/overlayMode/denyTools
+  // (#149 — derived from agent-level instructions.<source>.md + surfaces config
+  // by assembleDurable). The shared agent branches by real inbound source, no
+  // userText marker.
+  channelInstructions?: Record<string, string | ChannelPolicy>;
   // Channels whose CAPABILITY tools should be available to this session's turns. Their
   // tools are built HERE, in the DO isolate, from `env` — because a channel's tool `run`
   // is a closure (over the bot token, etc.) that can't cross the worker→DO RPC. This is
@@ -213,6 +219,12 @@ export type DoAgentDef = {
   // 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);
+  // Outbound connection DEFINITIONS (external MCP/OpenAPI servers). Wiring them
+  // is network I/O (connectAll), which a DO constructor cannot await — resolved
+  // lazily at the first turn, their tools merged into the agent's tool set
+  // before any session is constructed. The native equivalent happens at
+  // assembly (assembleAgent → connectAll).
+  connections?: Connection[];
   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
@@ -256,13 +268,15 @@ export class AgentDurableObject {
   private readonly model: Model;
   private readonly tools: Tool[];
   private readonly channels: Channel[];
-  private readonly channelInstructions?: Record<string, string>;
+  private readonly channelInstructions?: Record<string, string | ChannelPolicy>;
   // 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 connectionsInput: Connection[] | undefined;
+  private connectionsOpened: Promise<void> | undefined;
   private readonly doEnv: unknown;
   private readonly services: unknown;
   private resolveResources(): Promise<Resources> {
@@ -270,11 +284,40 @@ export class AgentDurableObject {
       typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : (this.resourcesInput ?? {}),
     ));
   }
+  // Wire outbound connections once (network I/O the constructor can't await):
+  // their tools merge into this.tools BEFORE any session is constructed — the
+  // ready() callers hoist this ahead of resolveSession. A failed connection is
+  // reported and skipped (connectAll never throws), matching native assembly.
+  private resolveConnections(): Promise<void> {
+    return (this.connectionsOpened ??= (async () => {
+      if (!this.connectionsInput?.length) return;
+      const { actions, report } = await connectAll(this.connectionsInput);
+      for (const r of report) {
+        if (r.error) console.error(`[june] agent "${this.name}": connection "${r.name}" (${r.url}) failed: ${r.error}`);
+      }
+      const seen = new Set(this.tools.map((t) => t.spec.name));
+      for (const a of actions) {
+        const tool = actionToTool(a);
+        if (seen.has(tool.spec.name)) {
+          throw new Error(`AgentDurableObject(${this.name}): duplicate tool name "${tool.spec.name}" from a connection — rename so dispatch is unambiguous.`);
+        }
+        seen.add(tool.spec.name);
+        this.tools.push(tool);
+      }
+    })());
+  }
+  // Everything a turn needs opened BEFORE its synchronous scope-and-subscribe
+  // section: resources (possibly an async provider) and outbound connections.
+  private async ready(): Promise<Resources> {
+    const [resources] = await Promise.all([this.resolveResources(), this.resolveConnections()]);
+    return resources;
+  }
   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.resourcesInput = def.resources;
+    this.connectionsInput = def.connections;
     this.doEnv = def.env;
     this.services = def.services;
     const name = def.name ?? "agent";
@@ -335,6 +378,18 @@ export class AgentDurableObject {
     this.tools = tools;
     this.channels = channels;
     this.channelInstructions = def.channelInstructions;
+    // Orphan-policy check (#149): assembly can't validate surface keys against
+    // factory channels (they resolve only here, with env) — so warn now, once,
+    // when a policy's source matches no resolved channel. A policy that never
+    // fires is the old silent failure; a warning is its floor.
+    if (def.channelInstructions) {
+      const names = new Set(channels.map((c) => c.name));
+      for (const source of Object.keys(def.channelInstructions)) {
+        if (!names.has(source)) {
+          console.warn(`[june] agent "${name}": surface policy "${source}" matches no channel wired into this DO (${[...names].join(", ") || "none"}) — it will never fire.`);
+        }
+      }
+    }
   }
   // Resolve THE session for this DO: explicit key (from a routed request) → persisted
   // key (a prior life learned it) → "self". A key that contradicts the persisted or
@@ -382,7 +437,7 @@ 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 resources = await this.ready();
     const session = this.resolveSession(input.session);
     return runInScope({ resources, services: this.services }, () => session.turn(input));
   }
@@ -392,7 +447,7 @@ 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 resources = await this.ready();
     const session = this.resolveSession(input.session);
     return runInScope({ resources, services: this.services }, () => session.start(input));
   }
@@ -450,7 +505,7 @@ export class AgentDurableObject {
       // db/services (ALS propagates to the .then continuation registered here); subscribing
       // 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();
+      const resources = await this.ready();
       let session: AgentSession;
       let started: { turnId: string };
       try {
@@ -535,7 +590,7 @@ export class AgentDurableObject {
       }
       // Same discipline as /turn: resolve resources before the synchronous
       // resume-then-subscribe section.
-      const resources = await this.resolveResources();
+      const resources = await this.ready();
       let session: AgentSession;
       try {
         session = this.resolveSession(key);

package/src/build.ts

@@ -804,7 +804,10 @@ export async function juneBuild(
     // anthropic({ client }), which skips that lazy path entirely.
     imports.push(`import Anthropic from "@anthropic-ai/sdk";`);
   }
-  const agentNameField = agentModule ? `\n  agentName: __agentModule.config.name,` : "";
+  // 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/
@@ -815,7 +818,6 @@ export async function juneBuild(
 // 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,
@@ -832,7 +834,7 @@ export class JuneAgentDO extends DurableObject {
   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")}

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);
     },
   };
 }